Admin encoding workflow

Ce guide s'adresse à l'encodeur : la personne qui transforme le seed brut Bandai (nom, coût, power) en données structurées exploitables par le moteur IA et le validateur de deck.

Vue d'ensemble

Le workflow vit dans /admin/encoding-queue. Chaque carte traverse 3 états explicites :

Le passage encoded → published exige que effectSummary.en soit non vide (règle IP : nos mots, jamais le texte Bandai verbatim).

Encoder une carte

1. /admin/encoding-queue → trie par releasedAt DESC (les sets récents OP15/OP16 d'abord).

2. Clic Encoder → sur une ligne en pending.

3. Remplir :

   • Keywords : cocher ce qui s'applique (rush, blocker, on_play, …).
   • Effects : un bloc par effet. Pour chaque bloc :
     • Trigger : quand l'effet se déclenche (on_play, when_attacking, permanent, …).
     • Cost : ressource consommée (rest_self, trash_n_cards, don_x2, …).
     • Action : ce que l'effet fait (draw_n_cards, ko_target, give_power_target, …).
     • Target : cible (leader_opp, character_self, all_characters, …).
     • Params : JSON libre pour les valeurs numériques ({"amount": 2}, {"power": 1000}).
   • Summary :
     • EN (obligatoire à la publication) : 1 phrase paraphrasée. Pas le texte Bandai. Limite 280 caractères.
     • FR / JP : traductions optionnelles.

4. Sauver brouillon (Ctrl+S) : carte passe en encoded, tu peux reprendre plus tard.

5. Publier (Ctrl+Enter) : valide Zod + bascule en published.

Raccourcis clavier

Rejeter une carte

Pour les doublons scrape, fausses cartes, ou erreurs seed à investiguer.

1. Sur la page de la carte, Reject.
2. Saisir une raison non-vide dans le prompt (conservée dans adminAuditLog).
3. La carte passe en rejected. Reste invisible côté public.

Voir le JSON debug

Toggle JSON en haut de la page. Affiche le payload final effectsEncoded en read-only. Utile pour vérifier la cohérence avant publication.

FAQ

Que faire si une carte a un effet ambigu ?

Cas typiques :

• Effet conditionnel ("if your leader is …") : encode l'effet principal, mets la condition dans params ou dans le résumé EN.
• Effet inédit (un keyword Bandai qu'on n'a jamais vu) :
  1. Ouvre une PR séparée feat(effect-vocab): add <key> qui ajoute la valeur dans convex/cards/effectVocabulary.ts.
  2. Reviens sur la carte une fois la PR mergée.
• Effet ambivalent (peut s'interpréter de 2 façons) : choisis l'interprétation la plus restrictive, documente l'autre dans le résumé.

Une carte est bannie / restrictée — dois-je dépublier ?

Non. La carte reste published (catalogue) ; sa legality.status passe à banned ou restricted via la page /admin/ban-list. Les decks contenant la carte deviennent automatiquement isValid: false et l'owner reçoit un email (feature 04 propagation).

J'ai publié, puis je veux modifier l'encodage

Le workflow V1 ne permet pas d'éditer une carte published. Si l'erreur est grave :

1. Reject la carte (audit row).
2. Re-seed la carte côté script (les données factuelles : nom, coût, power viennent du seed, pas de l'encodeur).
3. La carte re-passe en pending. Re-encode.

Plus tard une feature "édition de cartes publiées" pourra arriver.

Ça plante quand je publie

Cas connus :

• "effectSummary.en is required" : remplis le résumé EN. Si tu veux juste sauver un brouillon : utilise Sauver brouillon (pas Publish).
• "Unknown vocab value" : tu as tapé une valeur de trigger / cost / action / target qui n'existe pas. Le form a un dropdown, ne tape jamais à la main.
• Erreur Zod cryptée : retoogle "Voir le JSON" pour inspecter le payload, le path Zod dans le message t'indique le champ fautif.

Comment marche pnpm admin:grant ?

Pour promouvoir un utilisateur au rôle admin sur la plateforme. Le premier admin doit être créé en CLI parce que personne n'est encore admin pour cliquer dans l'UI.

CONVEX_DEPLOY_KEY="<key>" pnpm admin:grant alice@example.com
# ou pour révoquer
CONVEX_DEPLOY_KEY="<key>" pnpm admin:grant alice@example.com --revoke