Dette technique et backlog d'amélioration¶
Status: CURRENT / GOVERNANCE
Règle¶
Cette page contient uniquement des dettes encore pertinentes dans la révision courante ou des dettes récemment résolues qu'il est utile de conserver comme preuve.
Une dette exploitable décrit : constat, risque, propriétaire cible, action, interdictions, preuves attendues et critères de sortie.
Priorités :
| Priorité | Signification |
|---|---|
| P0 | viole ou menace une frontière fondamentale / intégrité / reprise |
| P1 | dette importante pour scalabilité, exploitation ou maintenabilité |
| P2 | amélioration utile mais non bloquante |
TD-WP-CORE-001 — Responsabilités métier encore hébergées dans le plugin¶
Statut : OPEN
Priorité : P0
Couche : Plugin WordPress -> Platform
Cible : src/
Constat¶
plugins/ccx-feeds-industrial/ contient encore des zones historiques qui réalisent ou orchestrent des décisions qui doivent fonctionner indépendamment de WordPress : mapping, classification, identity, vertical routing, quality, pipeline et use cases applicatifs.
Des fichiers métier sont encore protégés ou chargés dans un contexte WordPress, notamment dans la chaîne includes/mapping/row-to-item/.
Risque¶
- WordPress reste nécessaire pour exécuter une partie du moteur catalogue ;
- double architecture
src/+ plugin ; - règles marchands dispersées ;
- difficulté à multiplier les workers hors WordPress ;
- dette exponentielle avec le nombre de marchands ;
- risque de recréer une deuxième vérité métier.
Action¶
Migrer responsabilité par responsabilité vers src/ : caractérisation -> contrat -> extraction -> adapter/wrapper mince -> migration consommateurs -> certification -> suppression legacy.
Interdit¶
- nouvelle logique métier dans ces zones historiques ;
- gros déplacement sans caractérisation ;
- déplacement d'une heuristique marchande vers le Domain Core générique ;
- suppression sans preuve des consommateurs.
Critères de sortie¶
- aucune décision catalogue critique n'exige le bootstrap WordPress ;
- wrappers WordPress restants sont minces ;
- frontières protégées par tests d'architecture ;
- certification Platform sans WordPress PASS ;
- documentation plugin marquée adapter/transitional ;
- consommateurs legacy migrés ou explicitement bornés.
TD-WP-RUNTIME-002 — Worker principal encore couplé à WP-CLI¶
Statut : OPEN
Priorité : P1
Couche : Runtime / Adapter
Constat¶
Le playbook CURRENT de synchronisation lance encore wp ccx sync start --feed=<merchant> dans le conteneur worker.
Risque¶
- WordPress reste une dépendance d'exécution pour des traitements qui ne sont pas intrinsèquement CMS ;
- scaling des workers plus coûteux ;
- bootstrap inutile ;
- frontière Runtime/WordPress ambiguë.
Action¶
Introduire progressivement un entrypoint Platform neutre pour les use cases background. Conserver WP-CLI comme adapter opérateur/compatibilité jusqu'à migration des appels.
Critères de sortie¶
- un worker peut synchroniser un marchand sans charger WordPress ;
- mêmes contrats, métriques et semantics de retry ;
- WP-CLI délègue au même use case ou devient optionnel ;
- certification Runtime hors WordPress.
TD-MERCHANT-003 — Modèle d'isolation/fairness à généraliser¶
Statut : OPEN
Priorité : P1
Couche : Runtime / Ingestion
Constat¶
La cible centaines de marchands exige une isolation explicite par marchand, run, batch et job, avec contrôle de concurrence et backpressure.
Le comportement doit être vérifié composant par composant avant de considérer cette capacité comme généralisée.
Risque¶
- un gros marchand monopolise les workers ou la DB ;
- retries globaux ;
- difficulté à reprendre précisément un run ;
- mauvaise visibilité opérationnelle.
Critères de sortie¶
merchant_id, run/batch/job traçables de bout en bout ;- traitements bornés ;
- retry/replay idempotent ;
- concurrence par marchand configurable ;
- backlog et lag observables ;
- panne d'un marchand sans blocage global.
TD-CAPACITY-004 — Capacité VPS non encore certifiée quantitativement¶
Statut : OPEN
Priorité : P1
Couche : Operations / Performance
Constat¶
L'architecture est conçue pour refresh incrémental, workers et projections, mais aucune valeur durable ne doit être affirmée sur le nombre exact d'offres, de marchands ou de refreshs/jour sans benchmark représentatif sur le VPS courant.
Action¶
Construire un capacity benchmark reproductible mesurant : débit ingestion/normalisation/persistence/identity/projection, CPU, RAM, I/O, DB latency, queue lag et projection lag.
Critères de sortie¶
- dataset et scénario versionnés ;
- baseline reproductible ;
- capacité et marge documentées ;
- seuils d'alerte ;
- critères mesurés indiquant quand séparer workers ou DB.
TD-DR-005 — Disaster Recovery à certifier régulièrement¶
Statut : OPEN / CONTINUOUS
Priorité : P1
Couche : Operations
Constat¶
Disposer de commandes de backup/restore est nécessaire mais une capacité de reprise industrielle exige des exercices réellement exécutés et datés.
Critères de sortie récurrents¶
- backup hors VPS ;
- contrôle d'intégrité ;
- restore test réussi ;
- temps de reprise mesuré ;
- projections/rebuilds validés ;
- procédure actualisée après chaque changement significatif.
Cette dette est continue : une ancienne restauration réussie ne certifie pas éternellement la révision courante.
Dette récemment résolue¶
TD-CANONICAL-002 — Rebuild global sur chaque refresh canonical¶
Statut : RESOLVED / REVALIDATE ON CONTRACT CHANGE
Ancienne priorité : P2
Révision de résolution : b3f04684ab2497de618ad72eb0d9cd64fc3ffa3b
La branche a introduit et certifié le refresh canonical scoped/pending sur les chemins Runtime concernés. Les tests de replay couvrent notamment les impacts d'identité ancienne/nouvelle, l'échec de refresh après commit et le retry qui draine les impacts pending sans réappliquer la source.
Le full rebuild doit rester disponible comme voie de recovery et de comparaison canonique.
Cette entrée doit être rouverte si un nouveau chemin de mutation contourne le mécanisme scoped/pending ou si l'équivalence avec le rebuild complet n'est plus protégée.
Familles de dette à surveiller¶
Sources de vérité concurrentes¶
Deux services, tables, plugins ou frontends ne doivent pas prétendre décider du même concept.
Logique métier dans la mauvaise couche¶
Renderer, Runtime, Adapter, SQL ou WordPress ne deviennent pas propriétaires d'une décision parce que l'implémentation y est pratique.
Compatibilité permanente¶
Un shim sans critères de retrait finit par devenir une architecture parallèle.
Full processing inutile¶
Un traitement global sur chaque petit changement peut devenir une dette de scalabilité même s'il est fonctionnellement correct.
Observabilité insuffisante¶
Un traitement qu'on ne peut pas corréler à merchant/run/batch/job devient très coûteux à exploiter à grande échelle.
Format d'une nouvelle entrée¶
ID : TD-XXX
Statut : OPEN / VALIDATING / IN PROGRESS / BLOCKED / RESOLVED
Priorité : P0 / P1 / P2
Composant :
Couche :
Constat observé :
Preuves :
Risque :
Propriétaire TARGET :
Action proposée :
Ce qui est interdit :
Tests / audits :
Critères de sortie :
Rollback / recovery :
Révision vérifiée :
Fermeture¶
Une dette est fermée lorsque le problème n'est plus observable, les frontières sont protégées, les consommateurs ont migré, la documentation CURRENT est corrigée et les tests/runtime requis prouvent le comportement.