SPB Git

Repository Public

SCHEMA_AND_MIGRATIONS.md 6.4 KB 69 lines markdown

1# Schéma et migrations — `data/metre.db`23> 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.45## 1. Tables (modèle canonique adapté)67| Modèle canonique demandé | Table(s) | Notes |8|---|---|---|9| users, roles | `metre_users`, `metre_access_codes`, `metre_sessions` | codes hachés, sessions hachées, rôle par utilisateur |10| 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 |11| 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é |12| measurements | `metre_measurements` (formule, entrées JSON, valeur, unité, révision de calibration, `stale`, confiance, vérificateur, lignage, version des formules) | |13| resources, resource_categories, units | **`cost.db`** : `cost_items`, `labour_rates`, `cost_locations` (lecture) ; unités = `src/lib/metre/units.ts` | pas de duplication |14| assemblies, assembly_versions, assembly_components | `metre_assemblies` (composants JSON), `metre_assembly_versions` (instantané immuable par version) + `cost_assemblies` du catalogue | |15| 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) |16| regions, price_indices | `cost_locations`, `construction_cost_indices` (cost.db) | |17| 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`) |18| valuation_cases, depreciation_inputs | `metre_valuation_cases` (`input_json`, `result_json`, lien à une révision) | |19| report_jobs | `metre_report_jobs` | |20| assignments, submissions | `metre_assignments` (`answer_key_json` réservé au personnel), `metre_submissions` | |21| audit_events, quality_flags | `metre_audit_events`, `metre_quality_flags`, `metre_ingest_runs` | |22| 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 |2324Index : 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).2526## 2. Invariants garantis par le code2728- `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`).29- Une ligne liée à une mesure relit **toujours** la valeur du registre au calcul (`sanitizeLines`, `computeEstimateRow`).30- Une révision ne peut pas être figée si une mesure liée est `stale`.31- Une ouverture ne se déduit que d'un seul mur (`deductFrom`) et seulement si sa mesure est vérifiée.32- Le corrigé d'un devoir n'est jamais sélectionné pour un rôle `student`.3334## 3. Procédure de migration35361. **Sauvegarde** avant toute mise à jour : `sqlite3 data/metre.db ".backup data/metre-backup-$(date +%F).db"` + copie de `data/metre-files/`.372. 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).383. `schema_version` mis à jour ; `seedSources()` idempotent (ON CONFLICT DO UPDATE).394. **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).4041Rè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.4243Historique : **v1** (2026-10-28) création ; **v2** (2026-10-28) `metre_ai_suggestions` (additif).4445## 3 bis. Sauvegarde et restauration4647`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-*`).4849## 4. Fichiers5051```52data/metre.db                               base du module (WAL : -shm, -wal)53data/metre-files/<projectId>/<fileId>/original.<pdf|png|jpg>, page-<n>.png54data/metre-files/_sources/<sourceKey>/<sha256>.<json|csv>55public/metre/pdf.worker.min.mjs             worker pdfjs (copie de node_modules/pdfjs-dist/build)56```5758`data/` est ignoré par git (déjà le cas) ; les fichiers doivent être inclus dans les sauvegardes du nœud avec les autres bases.5960## 5. Variables d'environnement6162| Variable | Rôle | Valeur en production |63|---|---|---|64| `METRE_ENABLED` | feature flag serveur (`0`/`false` = pages et API en 404) | `1` |65| `NEXT_PUBLIC_METRE_ENABLED` | entrée « Métré » dans la navigation | `1` |66| `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) |67| `METRE_DB`, `METRE_FILES_DIR` | chemins (tests : répertoires temporaires) | défauts |68| `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 $) |69
Files main
Menu

Theme