SPB Git

Repository Public

SCHEMA_AND_MIGRATIONS.md 6.4 KB

# Schéma et migrations — data/metre.db

SQLite (better-sqlite3, WAL, foreign_keys = ON, busy_timeout 5 s). Schéma défini dans src/lib/metre/db.ts, version courante 2 (metre_meta.schema_version). Les tables de cost.db, vraiprix.db et immoka.db ne sont pas modifiées.

# 1. Tables (modèle canonique adapté)

Modèle canonique demandé Table(s) Notes
users, roles metre_users, metre_access_codes, metre_sessions codes hachés, sessions hachées, rôle par utilisateur
projects, buildings, floors, spaces metre_projects (+ metre_project_members) bâtiment/étages décrits sur le projet (building_kind, stories) ; les espaces sont des objets room sur les pages
plan_files, plan_versions, plan_objects metre_plan_files (sha256, chemin), metre_plan_pages, metre_calibrations (révisions), metre_plan_objects (points JSON, props JSON, suppression logique) une nouvelle version de plan = nouveau fichier ; l'original est conservé
measurements metre_measurements (formule, entrées JSON, valeur, unité, révision de calibration, stale, confiance, vérificateur, lignage, version des formules)
resources, resource_categories, units cost.db : cost_items, labour_rates, cost_locations (lecture) ; unités = src/lib/metre/units.ts pas de duplication
assemblies, assembly_versions, assembly_components metre_assemblies (composants JSON), metre_assembly_versions (instantané immuable par version) + cost_assemblies du catalogue
cost_sources, source_documents, raw_observations, normalized_price_observations metre_sources, metre_source_documents (brut conservé sur disque + hash), metre_price_observations le brut n'est pas dupliqué en base (fichier + hash)
regions, price_indices cost_locations, construction_cost_indices (cost.db)
estimates, estimate_versions, estimate_lines, quantity_links, scenarios, pricing_snapshots metre_estimates (état de travail : params_json, lines_json — chaque ligne porte measurementId = lien de quantité et adjustmentFactor), metre_estimate_versions (immuables : lignes, paramètres, résultat, instantané de prix, versions catalogue/formules, content_hash, scenario) les scénarios non figés sont calculés à la volée (/analyze)
valuation_cases, depreciation_inputs metre_valuation_cases (input_json, result_json, lien à une révision)
report_jobs metre_report_jobs
assignments, submissions metre_assignments (answer_key_json réservé au personnel), metre_submissions
audit_events, quality_flags metre_audit_events, metre_quality_flags, metre_ingest_runs
suggestions d'IA (v2) metre_ai_suggestions (kind, cible, modèle, version de prompt, empreinte d'entrée, sortie JSON, preuves, statut pending/accepted/rejected, réviseur, jetons, coût) jamais appliquée automatiquement

Index : propriétaires de projets, pages par fichier, objets par page, mesures par projet/objet, estimations par projet, révisions (estimate_id, number) uniques, observations par (source, classe) et par code de classification, audit par (projet, date).

# 2. Invariants garantis par le code

  • metre_estimate_versions n'est jamais mis à jour ni supprimé par l'application (seule la suppression en cascade d'un projet effacé les retire ; la suppression de projet est logique, deleted_at).
  • Une ligne liée à une mesure relit toujours la valeur du registre au calcul (sanitizeLines, computeEstimateRow).
  • Une révision ne peut pas être figée si une mesure liée est stale.
  • Une ouverture ne se déduit que d'un seul mur (deductFrom) et seulement si sa mesure est vérifiée.
  • Le corrigé d'un devoir n'est jamais sélectionné pour un rôle student.

# 3. Procédure de migration

  1. Sauvegarde avant toute mise à jour : sqlite3 data/metre.db ".backup data/metre-backup-$(date +%F).db" + copie de data/metre-files/.
  2. Déploiement du code ; au premier getMetreDb(), migrate() exécute CREATE TABLE IF NOT EXISTS … puis les blocs if (cur < n) (ALTER TABLE additifs, tolérants).
  3. schema_version mis à jour ; seedSources() idempotent (ON CONFLICT DO UPDATE).
  4. Retour arrière : restaurer la sauvegarde (le schéma n'est jamais rétréci ; un code plus ancien ignore simplement les colonnes ajoutées).

Règles pour les migrations futures : jamais de DROP/RENAME ; nouvelles colonnes NULL ou avec défaut ; nouvelles tables avec IF NOT EXISTS ; incrémenter METRE_DB_SCHEMA_VERSION ; documenter ici.

Historique : v1 (2026-10-28) création ; v2 (2026-10-28) metre_ai_suggestions (additif).

# 3 bis. Sauvegarde et restauration

scripts/metre-backup.sh [destination] : copie cohérente de metre.db (sqlite3 .backup, compatible WAL en marche), rsync de data/metre-files/, sommes SHA-256, journal backup.log, rotation 30 jours (défaut ~/backups/uqo-eval-metre/<horodatage>/). Planifié par PM2 (uqo-eval-metre-backup, cron_restart quotidien 04:10, autorestart: false). Restauration : pm2 stop uqo-eval && scripts/metre-backup.sh --restore <horodatage> && pm2 start uqo-eval (la base courante est copiée en metre.db.before-restore-*).

# 4. Fichiers

text
data/metre.db                               base du module (WAL : -shm, -wal)
data/metre-files/<projectId>/<fileId>/original.<pdf|png|jpg>, page-<n>.png
data/metre-files/_sources/<sourceKey>/<sha256>.<json|csv>
public/metre/pdf.worker.min.mjs             worker pdfjs (copie de node_modules/pdfjs-dist/build)

data/ est ignoré par git (déjà le cas) ; les fichiers doivent être inclus dans les sauvegardes du nœud avec les autres bases.

# 5. Variables d'environnement

Variable Rôle Valeur en production
METRE_ENABLED feature flag serveur (0/false = pages et API en 404) 1
NEXT_PUBLIC_METRE_ENABLED entrée « Métré » dans la navigation 1
METRE_ADMIN_CODE, METRE_INSTRUCTOR_CODE codes d'amorçage (jamais stockés en clair en base ; comparaison à temps constant) définis dans .env.local du nœud (2026-10-28)
METRE_DB, METRE_FILES_DIR chemins (tests : répertoires temporaires) défauts
METRE_AI_MODEL, METRE_AI_DAILY_BUDGET_USD, METRE_AI_PRICE_IN/OUT assistance IA (modèle, budget quotidien, tarif de suivi) ; clé = ANTHROPIC_API_KEY existante défauts (claude-haiku-5-5, 5 $)
Files main
Menu

Theme