colibre/docs/superpowers/specs/2026-07-01-subscriptions-handle-history-design.md

Handle d'abonnement personnalisé + historique des abonnements — design

• Contexte : suite de 2026-06-25-frisbii-abonnements-design.md
• Date : 2026-07-01

Objectif

Remplacer le paramètre generate_handle: true (Frisbii génère le handle de l'abonnement) par un handle choisi par colibre, préfixé abo, unique. Générer ce handle nécessite de pouvoir consulter l'historique des abonnements d'un utilisateur — ce qui n'est pas possible avec le schéma actuel de subscriptions, qui n'a qu'une ligne par utilisateur (user_id PRIMARY KEY), écrasée à chaque nouvelle souscription. Ce design scinde donc subscriptions en un historique multi-lignes et introduit une table séparée pour l'état cumulatif de l'utilisateur (votes, essai), en plus du changement de handle.

Décisions clés

1. Format du handle : abo-{user_id}-{N}, N incrémental par utilisateur (ex. abo-42-1, puis abo-42-2 en cas de résiliation puis réabonnement). Calculé en scannant les handles déjà utilisés par cet utilisateur dans subscriptions (LIKE 'abo-{user_id}-%') et en prenant le suffixe max + 1.
2. subscriptions devient un historique multi-lignes (une ligne par tentative d'abonnement Frisbii), id auto-incrémenté comme clé primaire, user_id non-unique.
3. Nouvelle table subscriber_state (1 ligne par utilisateur) pour l'état cumulatif indépendant du cycle de vie d'un abonnement particulier (trial_used, votes_balance, votes_last_credited_at) — ces colonnes n'ont pas de sens sur une ligne d'historique précise. Alternative écartée : les ajouter à users (mélangerait identité et logique d'abonnement/billing dans auth/db.py, qui doit rester focalisé sur l'identité).
4. Le handle est écrit par colibre à la création, pas par le webhook. Contrairement au comportement actuel (Frisbii génère le handle, on l'apprend via le webhook), colibre choisit abo-{user_id}-{N} et l'enregistre dans subscriptions.frisbii_subscription_handle avant d'appeler l'API Frisbii. Le webhook ne fait plus que lire/matcher sur ce handle (get_by_handle), jamais l'écrire.
   • Ordre retenu : écrire chez nous d'abord, appeler Frisbii ensuite. En cas d'échec de l'appel Frisbii, on se retrouve avec une ligne locale pending→failed dont le handle n'a jamais existé côté Frisbii — c'est inoffensif (voir décision 5). L'ordre inverse (Frisbii d'abord) est plus risqué : un succès Frisbii suivi d'un échec d'écriture locale laisserait un abonnement réel et potentiellement payant chez Frisbii sans aucune trace côté colibre, avec un risque de collision de handle au prochain essai.
5. Statut failed pour distinguer un échec propre côté Frisbii (juste après create_pending) d'un abonnement réellement pending chez Frisbii (session créée, paiement pas encore confirmé). Sans ce statut, l'écran /compte/abonnement affiche _active_view dès qu'une ligne existe pour l'utilisateur (peu importe le statut), ce qui bloquerait indéfiniment le bouton « S'abonner » derrière un écran « Ajouter une méthode de paiement » pour un abonnement fantôme, et « Me désabonner » échouerait aussi (handle inconnu de Frisbii). La ligne failed reste en base (pas de suppression) pour que abo-{user_id}-{N} ne réutilise jamais ce suffixe — protection utile en cas d'échec réseau ambigu (timeout ne garantit pas que la requête n'a pas été traitée côté Frisbii).
6. Chaque tentative de souscription crée une nouvelle ligne (pas de réutilisation d'une ligne pending existante). Chaque clic sur « S'abonner » qui atteint create_subscription_session crée un véritable nouvel objet abonnement chez Frisbii ; réutiliser une ligne locale reviendrait à réutiliser un handle déjà proposé à Frisbii pour un objet différent.

Schéma

CREATE TABLE subscriptions (
    id                           INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id                      INTEGER NOT NULL,
    frisbii_customer_handle      TEXT,
    frisbii_subscription_handle  TEXT,
    plan                         TEXT,
    prix_ht                      REAL,
    status                       TEXT,   -- 'pending' | 'trial' | 'active' | 'cancelled' | 'expired' | 'failed'
    current_period_end           TEXT,
    created_at                   TEXT NOT NULL,
    updated_at                   TEXT NOT NULL,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);
CREATE INDEX idx_subscriptions_user ON subscriptions(user_id);
CREATE UNIQUE INDEX idx_subscriptions_handle ON subscriptions(frisbii_subscription_handle);

CREATE TABLE subscriber_state (
    user_id                 INTEGER PRIMARY KEY,
    trial_used              INTEGER NOT NULL DEFAULT 0,
    votes_balance           INTEGER NOT NULL DEFAULT 0,
    votes_last_credited_at  TEXT,
    updated_at              TEXT NOT NULL,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

Migration

ALTER TABLE ne permet ni de retirer user_id comme clé primaire ni de répartir des colonnes vers une nouvelle table. Migration par reconstruction de table, sur le modèle de _rebuild_users_password_nullable dans src/auth/db.py:86 : fonction Python dédiée (pas une entrée de la liste générique _MIGRATIONS, qui n'exécute qu'une instruction SQL simple), guard d'idempotence sur PRAGMA table_info(subscriptions) (absence de la colonne id), transaction unique :

1. CREATE TABLE subscriptions_new (nouveau schéma).
2. INSERT INTO subscriptions_new (...) SELECT user_id, frisbii_customer_handle, ... FROM subscriptions (les anciennes lignes deviennent l'historique, un id frais leur est attribué).
3. INSERT INTO subscriber_state (user_id, trial_used, votes_balance, votes_last_credited_at, updated_at) SELECT ... FROM subscriptions (depuis l'ancienne table, avant le DROP).
4. DROP TABLE subscriptions, ALTER TABLE subscriptions_new RENAME TO subscriptions, recréation des index.

Appelée depuis subscriptions/db.py:init_schema(), PRAGMA foreign_keys = OFF pendant le DROP/RENAME (cascade), comme dans le précédent auth.

API subscriptions/db.py

• get_by_user → get_current(user_id) -> Row | None : dernière ligne (ORDER BY id DESC LIMIT 1). Remplace tous les usages actuels de « l'abonnement de l'utilisateur ».
• get_by_customer → customer_known(customer_handle) -> bool : test d'existence seul (un frisbii_customer_handle peut apparaître sur plusieurs lignes d'historique).
• get_by_handle(subscription_handle) -> Row | None (nouveau) : résout la ligne exacte à mettre à jour depuis un webhook.
• _next_handle(user_id) -> str (nouveau, privé) :

  def _next_handle(user_id: int) -> str:
      prefix = f"abo-{user_id}-"
      rows = get_conn().execute(
          "SELECT frisbii_subscription_handle FROM subscriptions "
          "WHERE user_id = ? AND frisbii_subscription_handle LIKE ?",
          (user_id, f"{prefix}%"),
      ).fetchall()
      n = max(
          (int(r[0][len(prefix):]) for r in rows if r[0][len(prefix):].isdigit()),
          default=0,
      )
      return f"{prefix}{n + 1}"
  

• create_pending(user_id, customer_handle, plan, prix_ht=None) -> tuple[str, int] : génère le handle via _next_handle, INSERT une nouvelle ligne (status='pending', frisbii_subscription_handle déjà renseigné), renvoie (handle, subscription_id).
• mark_failed(subscription_id) -> None (nouveau) : UPDATE subscriptions SET status='failed', updated_at=? WHERE id=?. Pas de logique de crédit de votes (rien n'a jamais été actif), contrairement à set_cancelled.
• update_from_webhook(subscription_handle, status, current_period_end) : signature simplifiée (retrait de customer_handle), cible la ligne via get_by_handle. trial_used déplacé vers subscriber_state.
• set_cancelled(subscription_id, current_period_end) : opère par id de ligne (plus par user_id) — routes.cancel() récupère déjà la ligne via get_current, lui passe row["id"].
• has_active_subscription, has_used_trial, credit_pending, spend_vote, next_recharge_at, freeze_votes_cursor : signatures inchangées, mais relus/écrits sur subscriber_state pour le solde/l'essai. credit_pending reste la seule fonction à toucher aux deux tables (lit le statut courant sur subscriptions via get_current, écrit le solde sur subscriber_state). has_used_trial/les fonctions de vote tolèrent l'absence de ligne subscriber_state (première interaction de l'utilisateur : valeurs par défaut, pas d'erreur).

client.py

create_subscription_session reçoit un paramètre handle: str obligatoire ; remplace "generate_handle": True par "handle": handle dans le corps de la requête POST /v1/subscription.

routes.py

• subscribe() : appelle db.create_pending(...) → (handle, subscription_id), passe handle à client.create_subscription_session(..., handle=handle). Dans le except client.FrisbiiError, appelle db.mark_failed(subscription_id) avant de rediriger vers ?error=frisbii.
• cancel() : récupère la ligne via get_current, passe row["id"] à set_cancelled.
• webhook() : garde existant basé sur customer_known(customer) ; appelle update_from_webhook(sub_handle, status, current_period_end) (sans customer_handle).

compte_abonnement.py

layout() : if row is not None: → if row is not None and row["status"] != "failed": pour qu'une ligne failed ne bloque plus l'affichage de _plan_cards (retour au formulaire de souscription).

Sites d'appel à migrer

get_by_user/get_by_customer sont utilisés dans : src/pages/compte_roadmap.py, src/pages/_compte_shell.py, src/pages/compte_abonnement.py, src/auth/routes.py — renommage mécanique vers get_current. tests/subscriptions/test_db.py et test_routes.py nécessitent une réécriture significative (nouvelles signatures, statut failed, table subscriber_state).

Hors périmètre (YAGNI)

• Nettoyage automatique des lignes pending/failed orphelines (essais de souscription abandonnés ou échoués). Inoffensif : ne bloque pas la réinscription, ne crée pas de collision de handle. Pas de cron de réconciliation pour l'instant — cohérent avec la décision « pas de réconciliation périodique automatique » du design initial.
• Scoping des colonnes des SELECT * dans subscriptions/db.py / auth/db.py (évoqué en discussion, explicitement écarté de cette tâche).
• Vérifier une vraie méthode de paiement (Frisbii) avant d'afficher le bandeau « Ajouter une méthode de paiement » dans _active_view pour status == "pending". Aujourd'hui le bandeau s'affiche pour tout pending, y compris juste après un ajout de méthode de paiement via /subscriptions/add-payment si le webhook n'a pas encore fait passer le statut à trial/active. client.get_customer_payment_methods existe déjà pour ça. Orthogonal à ce design (ne dépend d'aucune décision ci-dessus) — traité comme tâche de suivi séparée, avec son propre petit design (gestion d'erreur API, message si paiement déjà présent mais webhook en retard).