Documentation

Appearance

Rollback — intégration One Piece ​

Procédure si l'ajout de One Piece (mai 2026) casse quelque chose en prod et qu'il faut revenir à l'état Pokémon-only.

Date : 2026-05-06.

Ce qui a été shippé ​

Trois PRs sur snag-tcg/tcg-collector-backend, mergées sur main le 2026-05-05 :

#TypeQuoiDate
96featSource d'ingest OPTCG API + dispatch INGEST_TCG=onepiece2026-05-05
97featEnrichissement /scan-compat pour les TCG non-Pokémon (lookup /cards/:id)2026-05-05
98docsCatch-up CHANGELOG.md initial2026-05-05

Note 2026-05-06 (suite). Après le revert de #99, un plan en plusieurs phases a été lancé : Phase A (#103, table card_embeddings_lab + endpoint /scan-lab), Phase B (#105, schéma variant-aware cards.base_id + cards.variant), Phase C (#107, ingest OP variant-aware avec assignVariantIds). Voir Plan — validation pgvector via /scan-lab.

Effets de bord en runtime cumulés (post Phase C) :

  • Postgres : 2 967 lignes dans cards (tcg='onepiece') — 2 135 base + 832 variantes (674 v2 / 120 v3 / 34 v4 / 4 v5). 20 lignes dans sets. ~2 727 lignes dans card_images (1 999 base + 728 nouvelles variantes).
  • Disque : ~1 159 MB sous data/images/OP-*/, data/images/EB-*/, data/images/PRB-*/ (819 MB base + 340 MB variantes).
  • Image tcg-vision-api:latest rebuildée avec le _fetch_backend_card de #97 (suffix-strip regex _pN only — Phase C n'a pas modifié tcg-vision puisqu'on construit notre propre stack en parallèle).

Vérifier l'état actuel avant de toucher à quoi que ce soit ​

bash
cd tcg-collector-backend
sudo docker ps --filter name=tcg --format 'table {{.Names}}\t{{.Status}}'
sudo docker compose --env-file .env -f docker/compose.yml exec -T postgres \
  psql -U tcg -d tcg -c "SELECT tcg, COUNT(*) FROM cards GROUP BY tcg;"

Attendu en état "OP shippé" (post Phase C) :

   tcg    | count
----------+-------
 onepiece |  2967
 pokemon  | 23159

Rollback partiel — désactiver l'enrichissement OP côté scan (rapide, non destructif) ​

Si tcg-vision /scan-compat retourne des erreurs sur des scans OP, on peut court-circuiter PR #97 sans toucher aux autres :

bash
# Désactive le lookup backend pour les TCG non-Pokémon
# → /scan-compat retombe sur le comportement legacy (cardDetails: null)
# → Pokémon continue de marcher comme avant
echo "BACKEND_API_URL=" >> .env  # ou éditer la valeur existante
sudo docker compose --env-file .env -f docker/compose.yml up -d tcg-vision

Aucune perte de données. Pour réactiver : remettre BACKEND_API_URL=http://api:3000 dans .env et redémarrer.

Rollback partiel — bloquer l'ingest OP futur (rapide, non destructif) ​

Si on veut empêcher de futurs runs INGEST_TCG=onepiece mais garder ce qui est déjà en DB :

bash
# Rien à faire — le défaut de INGEST_TCG est 'pokemon'.
# Vérifier que les invocations de scheduler/cron n'overrident pas la valeur.
grep -r "INGEST_TCG" .env scripts/

Rollback complet — purger les données One Piece de Postgres + disque ​

À utiliser uniquement si on veut vraiment tout effacer. Les migrations restent (elles sont neutres pour Pokémon).

bash
cd tcg-collector-backend

# 1. Sauvegarde defensive (~30 secondes)
sudo docker compose --env-file .env -f docker/compose.yml exec -T postgres \
  pg_dump -U tcg -d tcg -t cards -t sets -t card_images -t card_embeddings \
  > /tmp/tcg-pre-op-rollback.sql

# 2. Supprimer les lignes OP en DB (FK ON DELETE CASCADE → card_images suit)
sudo docker compose --env-file .env -f docker/compose.yml exec -T postgres \
  psql -U tcg -d tcg <<'SQL'
BEGIN;
DELETE FROM cards WHERE tcg = 'onepiece';
DELETE FROM sets  WHERE tcg = 'onepiece';
COMMIT;
SQL

# 3. Vérifier le compte Pokémon est intact
sudo docker compose --env-file .env -f docker/compose.yml exec -T postgres \
  psql -U tcg -d tcg -c "SELECT tcg, COUNT(*) FROM cards GROUP BY tcg;"

# 4. Purger les images OP du disque (~819 MB libérés)
sudo rm -rf data/images/OP-* data/images/EB-* data/images/PRB-*

Restauration depuis le dump si besoin :

bash
sudo docker compose --env-file .env -f docker/compose.yml exec -T postgres \
  psql -U tcg -d tcg < /tmp/tcg-pre-op-rollback.sql

Rollback du code — revert des PRs ​

Si le code lui-même cause un souci (typo, régression Pokémon non détectée, etc.) :

bash
cd tcg-collector-backend

# Option A — revert "soft" via PR (recommandé en prod)
gh pr create --title "revert: One Piece ingest + scan enrichment" --body "..." \
  --base main --head revert/onepiece
# Puis manuellement : git revert 1497a89 <sha-pr-97> <sha-pr-98>

# Option B — checkout au commit pré-OP, force push (à éviter sauf urgence)
git log --oneline | grep -B1 "feat(ingest): add One Piece"
# Note le SHA du commit AVANT 1497a89, par exemple 0521575
# git reset --hard 0521575     # destructif !

Après revert :

bash
sudo docker compose --env-file .env -f docker/compose.yml build ingest tcg-vision
sudo docker compose --env-file .env -f docker/compose.yml up -d

Tests de non-régression Pokémon ​

À lancer après tout rollback pour vérifier que le path Pokémon reste vert :

bash
# 1. API répond toujours
curl -s -m 5 "http://localhost:8080/cards?tcg=pokemon&limit=1" | python3 -m json.tool | head -10

# 2. Scan-compat répond toujours sur une carte Pokémon
curl -s -m 30 -X POST -F "photo=@<un-jpeg-pokemon>" \
  http://localhost:8000/scan-compat | python3 -m json.tool | head -20
# Attendu : match.name non-null (nom de la carte), cardDetails non-null

# 3. Compte de cartes intact
sudo docker compose --env-file .env -f docker/compose.yml exec -T postgres \
  psql -U tcg -d tcg -c "SELECT COUNT(*) FROM cards WHERE tcg='pokemon';"
# Attendu : 23 159 (ou plus si ingest depuis)

Voir aussi ​

  • Architecture du scan de cartes — vue d'ensemble du pipeline
  • tcg-collector-backend/docs/INGEST.md §One Piece — détails techniques de l'intégration
  • tcg-collector-backend/CHANGELOG.md — entrée ### Added — One Piece TCG end-to-end (#96, #97)