# Changer de méthode de paiement (issue #108) — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Permettre à un·e abonné·e en essai ou actif de changer sa carte bancaire depuis `/compte/abonnement`, via la page hébergée Frisbii dédiée (`hosted_page_links.payment_info` de l'objet subscription).

**Architecture:** Une fonction client Frisbii récupère l'abonnement et construit l'URL de la page hébergée avec `accept_url`/`cancel_url`. Une route Flask (symétrique à `/subscriptions/add-payment` et `/subscriptions/cancel`) sert de point d'entrée POST et redirige (303) vers cette URL. Un bouton sur `/compte/abonnement` déclenche cette route ; les retours (`?carte=succes`/`?carte=annule`) affichent un message dans `_feedback()`.

**Tech Stack:** Python, Flask, Dash + Dash Bootstrap Components, httpx (déjà en place dans `src/subscriptions/client.py`), pytest + monkeypatch pour les tests.

## Global Constraints

- Le bouton n'apparaît que pour `row["status"] in ("trial", "active")` — pas `pending` (garde son bouton "Ajouter une méthode de paiement" existant), pas `cancelled` (rien à facturer, chemin logique = reprendre un abonnement).
- Réutiliser `client.get_subscription` déjà existant (`src/subscriptions/client.py:136`), ne pas dupliquer l'appel HTTP.
- Suivre le pattern CSRF + `html.Form` POST déjà utilisé pour "Me désabonner" / "Ajouter une méthode de paiement" dans `src/pages/compte/abonnement.py`.
- Aucun nouveau webhook/callback : Frisbii associe la nouvelle méthode de paiement à l'abonnement de son côté.

---

### Task 1: `client.get_payment_info_url`

**Files:**

- Modify: `src/subscriptions/client.py`
- Test: `tests/subscriptions/test_client.py`

**Interfaces:**

- Consumes: `get_subscription(subscription_handle: str) -> dict` (déjà défini à `src/subscriptions/client.py:136`), qui retourne le JSON brut de `GET /v1/subscription/{handle}` — notamment `hosted_page_links: {"payment_info": "<url>"}`.
- Produces: `get_payment_info_url(sub_handle: str, accept_url: str, cancel_url: str) -> str`, utilisé par la route du Task 2.

- [ ] **Step 1: Write the failing test**

Ajouter à la fin de `tests/subscriptions/test_client.py` :

```python
def test_get_payment_info_url_appends_query_params(fake_httpx):
    fake_httpx["queue"].append(
        fake_httpx["Response"](
            200,
            {
                "handle": "abo-1-1",
                "hosted_page_links": {
                    "payment_info": "https://checkout.reepay.com/#/subscription/pay/en_GB/x/abo-1-1"
                },
            },
        )
    )
    url = client.get_payment_info_url(
        "abo-1-1", "https://app/compte/abonnement?carte=succes",
        "https://app/compte/abonnement?carte=annule",
    )
    assert url.startswith(
        "https://checkout.reepay.com/#/subscription/pay/en_GB/x/abo-1-1"
    )
    assert "accept_url=https%3A%2F%2Fapp%2Fcompte%2Fabonnement%3Fcarte%3Dsucces" in url
    assert "cancel_url=https%3A%2F%2Fapp%2Fcompte%2Fabonnement%3Fcarte%3Dannule" in url


def test_get_payment_info_url_merges_existing_query_string(fake_httpx):
    fake_httpx["queue"].append(
        fake_httpx["Response"](
            200,
            {
                "handle": "abo-1-2",
                "hosted_page_links": {
                    "payment_info": "https://checkout.reepay.com/pay/abo-1-2?locale=fr"
                },
            },
        )
    )
    url = client.get_payment_info_url("abo-1-2", "https://app/ok", "https://app/ko")
    assert "locale=fr" in url
    assert "accept_url=https%3A%2F%2Fapp%2Fok" in url
    assert "cancel_url=https%3A%2F%2Fapp%2Fko" in url
```

- [ ] **Step 2: Run test to verify it fails**

Run: `uv run pytest tests/subscriptions/test_client.py -k payment_info_url -v`
Expected: FAIL with `AttributeError: module 'src.subscriptions.client' has no attribute 'get_payment_info_url'`

- [ ] **Step 3: Write minimal implementation**

Dans `src/subscriptions/client.py`, ajouter l'import en haut du fichier (avec les autres imports) :

```python
from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
```

Puis, juste après `get_subscription` (après la ligne `return _call("GET", f"/v1/subscription/{subscription_handle}")`) :

```python
def get_payment_info_url(sub_handle: str, accept_url: str, cancel_url: str) -> str:
    sub = get_subscription(sub_handle)
    url = sub["hosted_page_links"]["payment_info"]
    parts = urlsplit(url)
    query = dict(parse_qsl(parts.query))
    query["accept_url"] = accept_url
    query["cancel_url"] = cancel_url
    return urlunsplit(parts._replace(query=urlencode(query)))
```

- [ ] **Step 4: Run test to verify it passes**

Run: `uv run pytest tests/subscriptions/test_client.py -k payment_info_url -v`
Expected: PASS (2 tests)

- [ ] **Step 5: Run the full client test file to check no regression**

Run: `uv run pytest tests/subscriptions/test_client.py -v`
Expected: All PASS

- [ ] **Step 6: Commit**

```bash
git add src/subscriptions/client.py tests/subscriptions/test_client.py
git commit -m "feat(abonnement): client.get_payment_info_url pour le changement de carte Frisbii"
```

---

### Task 2: Route `POST /subscriptions/change-payment-method`

**Files:**

- Modify: `src/subscriptions/routes.py`
- Test: `tests/subscriptions/test_routes.py`

**Interfaces:**

- Consumes: `client.get_payment_info_url(sub_handle, accept_url, cancel_url) -> str` (Task 1) ; `db.get_current(user_id) -> sqlite3.Row | None` (déjà existant, colonne `frisbii_subscription_handle`) ; `client.FrisbiiError` (déjà existant).
- Produces: route Flask `POST /subscriptions/change-payment-method`, utilisée par le bouton du Task 3. Redirige (303) vers l'URL Frisbii en cas de succès, 400 si pas d'abonnement, redirect 302 vers `/compte/abonnement?error=frisbii` en cas d'erreur API.

- [ ] **Step 1: Write the failing tests**

Ajouter à la fin de `tests/subscriptions/test_routes.py` :

```python
def test_change_payment_method_redirects_to_hosted_url(logged_in_client, monkeypatch):
    client, uid = logged_in_client
    handle, _ = db.create_pending(uid, "colibre-%d" % uid, "simple")
    db.update_from_webhook(handle, "active", "2099-01-01T00:00:00+00:00")
    monkeypatch.setattr(
        frisbii_client,
        "get_payment_info_url",
        lambda h, accept_url, cancel_url: f"https://pay.test/{h}?a={accept_url}&c={cancel_url}",
    )
    resp = client.post("/subscriptions/change-payment-method")
    assert resp.status_code == 303
    assert resp.headers["Location"].startswith(f"https://pay.test/{handle}")
    assert "carte%3Dsucces" in resp.headers["Location"] or "carte=succes" in resp.headers["Location"]
    assert "carte%3Dannule" in resp.headers["Location"] or "carte=annule" in resp.headers["Location"]


def test_change_payment_method_without_subscription(logged_in_client):
    client, _ = logged_in_client
    resp = client.post("/subscriptions/change-payment-method")
    assert resp.status_code == 400


def test_change_payment_method_api_error_redirects(logged_in_client, monkeypatch):
    client, uid = logged_in_client
    handle, _ = db.create_pending(uid, "colibre-%d" % uid, "simple")
    db.update_from_webhook(handle, "active", "2099-01-01T00:00:00+00:00")

    def boom(h, accept_url, cancel_url):
        raise frisbii_client.FrisbiiError(500, "boom")

    monkeypatch.setattr(frisbii_client, "get_payment_info_url", boom)
    resp = client.post("/subscriptions/change-payment-method")
    assert resp.status_code == 302
    assert "error=frisbii" in resp.headers["Location"]


def test_change_payment_method_requires_login(sub_app):
    resp = sub_app.test_client().post("/subscriptions/change-payment-method")
    assert resp.status_code in (302, 401)
```

- [ ] **Step 2: Run tests to verify they fail**

Run: `uv run pytest tests/subscriptions/test_routes.py -k change_payment_method -v`
Expected: FAIL — `test_change_payment_method_without_subscription` gets a 404 (route doesn't exist yet) instead of 400, others fail similarly.

- [ ] **Step 3: Write minimal implementation**

Dans `src/subscriptions/routes.py`, ajouter la route juste après `add_payment_callback()` (avant `cancel()`) :

```python
@subscriptions_bp.route("/subscriptions/change-payment-method", methods=["POST"])
@login_required
def change_payment_method():
    base = os.getenv("APP_BASE_URL", "")
    row = db.get_current(current_user.id)
    if row is None or not row["frisbii_subscription_handle"]:
        return "Aucun abonnement actif", 400
    try:
        url = client.get_payment_info_url(
            row["frisbii_subscription_handle"],
            f"{base}/compte/abonnement?carte=succes",
            f"{base}/compte/abonnement?carte=annule",
        )
    except client.FrisbiiError:
        logger.exception("Échec de récupération du lien de paiement Frisbii")
        return redirect("/compte/abonnement?error=frisbii")
    return redirect(url, code=303)
```

- [ ] **Step 4: Run tests to verify they pass**

Run: `uv run pytest tests/subscriptions/test_routes.py -k change_payment_method -v`
Expected: PASS (4 tests)

- [ ] **Step 5: Run the full routes test file to check no regression**

Run: `uv run pytest tests/subscriptions/test_routes.py -v`
Expected: All PASS

- [ ] **Step 6: Commit**

```bash
git add src/subscriptions/routes.py tests/subscriptions/test_routes.py
git commit -m "feat(abonnement): route /subscriptions/change-payment-method"
```

---

### Task 3: Bouton et messages de retour sur `/compte/abonnement`

**Files:**

- Modify: `src/pages/compte/abonnement.py`
- Test: `tests/subscriptions/test_compte_abonnement.py`

**Interfaces:**

- Consumes: rien de nouveau — utilise `_csrf_input()` déjà défini dans ce fichier (`src/pages/compte/abonnement.py:18`).
- Produces: `_active_view(row)` inclut désormais le bouton pour `status in ("trial", "active")` ; `_feedback(query)` gère `query.get("carte")`.

- [ ] **Step 1: Write the failing tests**

Ajouter à la fin de `tests/subscriptions/test_compte_abonnement.py` :

```python
def test_active_view_shows_change_payment_method_for_active():
    from src.pages.compte import abonnement as compte_abonnement

    row = {
        "plan": "simple",
        "status": "active",
        "current_period_end": "2099-01-01T00:00:00+00:00",
    }
    text = str(compte_abonnement._active_view(row))
    assert "Changer de méthode de paiement" in text
    assert "/subscriptions/change-payment-method" in text


def test_active_view_shows_change_payment_method_for_trial():
    from src.pages.compte import abonnement as compte_abonnement

    row = {
        "plan": "simple",
        "status": "trial",
        "current_period_end": "2099-01-01T00:00:00+00:00",
    }
    assert "Changer de méthode de paiement" in str(
        compte_abonnement._active_view(row)
    )


def test_active_view_hides_change_payment_method_for_cancelled():
    from src.pages.compte import abonnement as compte_abonnement

    row = {
        "plan": "simple",
        "status": "cancelled",
        "current_period_end": "2099-01-01T00:00:00+00:00",
    }
    assert "Changer de méthode de paiement" not in str(
        compte_abonnement._active_view(row)
    )


def test_active_view_hides_change_payment_method_for_pending():
    from src.pages.compte import abonnement as compte_abonnement

    row = {"plan": "simple", "status": "pending", "current_period_end": None}
    text = str(compte_abonnement._active_view(row))
    assert "Changer de méthode de paiement" not in text
    assert "Ajouter une méthode de paiement" in text


def test_feedback_carte_succes():
    from src.pages.compte import abonnement as compte_abonnement

    text = str(compte_abonnement._feedback({"carte": "succes"}))
    assert "Méthode de paiement mise à jour." in text


def test_feedback_carte_annule():
    from src.pages.compte import abonnement as compte_abonnement

    text = str(compte_abonnement._feedback({"carte": "annule"}))
    assert "Modification annulée." in text
```

- [ ] **Step 2: Run tests to verify they fail**

Run: `uv run pytest tests/subscriptions/test_compte_abonnement.py -v`
Expected: FAIL — the 6 new tests fail (button/messages absent), the 8 pre-existing tests in this file still PASS.

- [ ] **Step 3: Write minimal implementation**

Dans `src/pages/compte/abonnement.py`, modifier `_active_view` : remplacer le bloc

```python
    if row["status"] in ("pending", "trial", "active"):
        blocks.append(
            html.Button(
                "Me désabonner",
                id="resiliation-trigger",
                n_clicks=0,
                className="btn btn-outline-danger mt-3",
            )
        )

    return html.Div(blocks)
```

par :

```python
    if row["status"] in ("trial", "active"):
        blocks.append(
            html.Form(
                method="POST",
                action="/subscriptions/change-payment-method",
                children=[
                    _csrf_input(),
                    html.Button(
                        "Changer de méthode de paiement",
                        type="submit",
                        className="btn btn-outline-secondary mt-3 me-2",
                    ),
                ],
                style={"display": "inline-block"},
            )
        )

    if row["status"] in ("pending", "trial", "active"):
        blocks.append(
            html.Button(
                "Me désabonner",
                id="resiliation-trigger",
                n_clicks=0,
                className="btn btn-outline-danger mt-3",
            )
        )

    return html.Div(blocks)
```

Puis modifier `_feedback` : remplacer

```python
    if query.get("error") == "frisbii":
        out.append(
            dbc.Alert(
                "Une erreur est survenue avec le service de paiement.", color="primary"
            )
        )
    return out
```

par :

```python
    if query.get("carte") == "succes":
        out.append(dbc.Alert("Méthode de paiement mise à jour.", color="success"))
    if query.get("carte") == "annule":
        out.append(dbc.Alert("Modification annulée.", color="secondary"))
    if query.get("error") == "frisbii":
        out.append(
            dbc.Alert(
                "Une erreur est survenue avec le service de paiement.", color="primary"
            )
        )
    return out
```

- [ ] **Step 4: Run tests to verify they pass**

Run: `uv run pytest tests/subscriptions/test_compte_abonnement.py -v`
Expected: All 14 tests PASS (8 pre-existing + 6 new)

- [ ] **Step 5: Run the full subscriptions test suite to check no regression**

Run: `uv run pytest tests/subscriptions/ -v`
Expected: All PASS

- [ ] **Step 6: Commit**

```bash
git add src/pages/compte/abonnement.py tests/subscriptions/test_compte_abonnement.py
git commit -m "feat(abonnement): bouton changer de méthode de paiement sur /compte/abonnement"
```

---

### Task 4: Vérification manuelle en local

**Files:** aucun (vérification uniquement)

- [ ] **Step 1: Lancer l'app en local**

Run: `uv run run.py`

- [ ] **Step 2: Créer un abonnement actif de test et vérifier l'affichage du bouton**

Se connecter, créer un abonnement (trial ou active selon état de la base de test), aller sur `/compte/abonnement`, vérifier que le bouton "Changer de méthode de paiement" est visible, et absent une fois l'abonnement résilié (statut `cancelled`).

- [ ] **Step 3: Vérifier le clic (sans compte Frisbii réel si `FRISBII_API_KEY` n'est pas configurée en local)**

Si `FRISBII_API_KEY` n'est pas renseignée, le clic déclenchera une `FrisbiiError` (requête échouée) → vérifier la redirection vers `/compte/abonnement?error=frisbii` et l'affichage du message d'erreur existant. Si une clé de test Frisbii est disponible, vérifier la redirection réelle vers la page hébergée et le retour via `?carte=succes`/`?carte=annule`.

- [ ] **Step 4: Run full test suite**

Run: `uv run pytest`
Expected: All PASS

Pas de commit pour cette tâche (vérification uniquement).