lifetrack/CONVENTIONS.md

LifeTrack — CONVENTIONS

Extrait de docs/design/architecture.md §10 — règles obligatoires pour tout développeur (humain ou agent).

C1. Langues

• Code (identifiants, fichiers, tables, colonnes, routes API, commentaires, messages de commit) : anglais.
• UI et messages d'erreur destinés à l'utilisateur (AppError(message=...), labels, strings.ts, docs utilisateur) : français, ponctuation française correcte, pas d'anglicismes gratuits. Formats d'affichage fr-FR (virgule décimale, espace insécable des milliers, € après le montant).

C2. Créer un module backend

1. Créer apps/api/app/modules/<name>/ avec __init__.py (vide) et obligatoirement router.py exposant router = APIRouter(prefix="/<name>", tags=["<name>"]). Fichiers standard : models.py, schemas.py, service.py ; optionnels : importers.py, ingest.py, calculations.py.
2. Ne jamais modifier main.py, module_loader.py, ni le module d'un autre chantier. L'enregistrement est automatique (pkgutil) : routers montés sous /api, models.py/ importers.py/ingest.py importés au démarrage pour create_all et les registres.
3. models.py : style SQLAlchemy 2.0 typé (Mapped/mapped_column), héritage class X(TimestampMixin, Base) ; noms de tables snake_case pluriel ; toute table métier porte user_id = mapped_column(ForeignKey("users.id"), index=True) ; datetimes en DateTime(timezone=True) et valeurs UTC ; colonnes « jour local » en Date ; poids kg, longueurs cm ou m (distances), volumes ml, énergie kcal, durées secondes, argent en centimes (int) ou Numeric pour les prix unitaires.
4. Table alimentée par import/ingestion → ajouter SourceMixin et les deux contraintes uniques : (user_id, source, external_id) et (user_id, content_hash) (noms uq_<table>_external, uq_<table>_hash). Agrégats journaliers → clé (user_id, day, source) + upsert ON CONFLICT DO UPDATE.
5. schemas.py : Pydantic v2 ; suffixes XxxCreate, XxxUpdate (champs optionnels), XxxRead (avec model_config = ConfigDict(from_attributes=True)) ; jamais de modèle ORM retourné sans schéma Read.
6. service.py : logique métier ; signature def fn(db: Session, user_id: int, ...). Les routeurs restent minces (dépendances + appel service + schéma de réponse). Le service lève les sous-classes d'AppError (NotFoundError, ConflictError, DomainValidationError…) avec message français ; interdit de lever HTTPException dans un module.
7. Sécurité : tout endpoint (hors auth public et healthz) dépend de get_current_user et filtre systématiquement par user.id. Endpoints d'ingestion : dépendance get_ingest_identity("ingest:<domain>").
8. Pagination : toute liste utilise PageParams/Page[T]/paginate de core.pagination — pas de pagination maison. Tri via ?sort= (préfixe - = desc), champs autorisés explicites.
9. Requêtes : select() SQLAlchemy 2.0 uniquement (pas de session.query). Le routeur/service ne fait pas de commit partiel par ligne ; un commit par opération logique (le get_db fournit la session, le service commit).

C3. Ajouter un importeur de fichier

1. Dans importers.py du module métier concerné, sous-classer BaseImporter (app.core.importing.base) et décorer avec @register_importer.
2. Renseigner id (snake_case unique, suffixe format : _csv, _ofx), label (français, affiché dans l'UI), domain, accepted_extensions.
3. sniff() ne lève jamais et reste bon marché (extension + en-têtes dans les 4096 premiers octets). parse() gère les encodages utf-8-sig puis cp1252 et les CSV ; à décimale virgule ; il produit des NormalizedRecord en unités canoniques avec external_id si la source en fournit un, sinon dedupe_fields pertinents (ex : ("posted_at", "amount_cents", "label_raw")).
4. upsert() retourne INSERTED / UPDATED / DUPLICATE — la détection de doublon se fait par lookup sur les contraintes du C2.4 (pas par try/except d'IntegrityError en boucle).
5. Ne pas créer d'endpoint d'upload : POST /api/imports du module imports sert toutes les sources.

C4. Ajouter un handler d'ingestion JSON

Dans ingest.py du module : sous-classer BaseIngestHandler, décorer @register_ingest_handler, déclarer domain et record_types, implémenter apply() (mêmes règles de dédup que C3.4). Le endpoint POST /api/ingest/{domain} existe déjà ; il exige le scope ingest:<domain> (ou ingest:*) pour les clés d'appareil.

C5. Créer un module frontend

1. Créer apps/web/src/modules/<name>/ avec index.ts dont l'export default est un ModuleManifest (src/types/module.ts) : id = nom du dossier (anglais), title français, order réservé (home 0, health 10, vape 20, finance 30, imports 80, settings 90 ; nouveaux modules : dizaine libre), routes (chemins absolus, slugs français : /sante/..., /vape/..., /finances/...), nav (labels français + icône lucide-react).
2. Ne jamais modifier router.tsx, modules.ts, Sidebar.tsx : la découverte import.meta.glob est automatique. Ajouter une entrée de nav = ajouter un élément au tableau nav du manifeste de son module.
3. Fichiers standard du module : api.ts (hooks React Query + types TS des schémas API), strings.ts (chaînes françaises du module, export d'un objet constant — pas de français en dur éparpillé dans le JSX pour les libellés réutilisés), pages/, components/.
4. Données : toujours via les hooks React Query de api.ts du module, qui appellent le wrapper api() de src/lib/api.ts (jamais fetch direct). Clés de requête [moduleId, resource, params] ; toute mutation invalide [moduleId, resource].
5. Graphiques : exclusivement via <EChart option={...}/> (src/components/charts/EChart.tsx) et le thème lifetrack-dark ; pas d'accès direct à echarts.init dans les pages ; formats d'axes/tooltips via src/lib/format.ts.
6. UI : composants partagés de src/components/ui/ d'abord ; classes Tailwind (palette sombre du §7.5) ; pas de CSS externe, pas de CDN, pas de nouvelle dépendance sans l'ajouter à package.json du repo.
7. Pages : nom XxxPage.tsx, chargées via React.lazy dans le manifeste ; états vide/chargement/erreur systématiques (EmptyState, Spinner, message d'ApiError.message).

C6. API — rappels contractuels

• Préfixe /api/<module> ; ressources au pluriel anglais ; GET liste paginée (Page[T]), POST création (201), PATCH partiel, PUT singleton, DELETE → 204.
• Forme d'erreur unique {"error": {"code", "message", "details"}} — code snake_case stable, message en français.
• Datetimes : UTC ISO 8601 (Z) ; jours locaux : YYYY-MM-DD ; agrégations journalières : paramètre ?tz= (défaut Europe/Paris).
• Filtres temporels : ?from=/?to= inclusifs.

C7. Qualité

• Python : ruff (lint + format), type hints partout, pas d'import inutilisé ; tests pytest dans apps/api/app/tests/ (au minimum : contrat du routeur du module + dédup des importeurs).
• TypeScript : strict: true, pas de any non justifié ; build npm run build sans erreur.
• Aucune dépendance réseau à l'exécution côté web (fonts/icônes/librairies embarquées).
• Secrets uniquement via variables d'environnement ; rien de sensible commité (.env est git-ignoré, .env.example documente).

C8. Portabilité des types (tests SQLite)

La suite pytest s'exécute sur SQLite en mémoire (PostgreSQL en production) : tous les modèles doivent donc utiliser des types de colonnes portables.

1. Énumérations : sa.Enum(..., native_enum=False) — jamais d'ENUM natif PostgreSQL.
2. UUID : sa.Uuid (type générique SQLAlchemy), pas postgresql.UUID.
3. JSON : sa.JSON().with_variant(postgresql.JSONB, "postgresql") — utiliser l'alias prêt à l'emploi JSONB_V exporté par app/core/mixins.py (JSON simple sous SQLite, JSONB sous PostgreSQL).
4. Index uniques partiels : déclarer les deux clauses sqlite_where et postgresql_where (mêmes expressions) ; jamais postgresql_nulls_not_distinct.
5. Rollback centralisé des imports : toute table portant une colonne référençant import_runs.id doit déclarer la clé étrangère avec ondelete="CASCADE" (ForeignKey("import_runs.id", ondelete="CASCADE")) — c'est ce qui permet à DELETE /api/imports/{id} de supprimer les lignes importées d'un lot. (Sous SQLite, le moteur active PRAGMA foreign_keys=ON automatiquement — voir app/core/database.py.)