feat(db) : documenter toutes les colonnes BDD via COMMENT ON COLUMN + garde-fou (ERP-67)

- Migration retrofit Version20260528120000 : pose COMMENT ON TABLE/COLUMN sur les 11 tables metier existantes (53 colonnes) via le catalogue partage ColumnCommentsCatalog (Shared/Infrastructure/Database). - Commande app:apply-column-comments : rejoue le catalogue apres doctrine:schema:update --force (sinon l'ORM drop les commentaires absents du mapping PHP). Branchee dans makefile test-db-setup et workflow CI Gitea. - Test architecture tests/Architecture/ColumnsHaveSqlCommentTest : echoue si une colonne public n'a pas de col_description (hors doctrine_migration_versions et fake_site_aware_entity). Whitelist metier vide. - Convention documentee dans CLAUDE.md (regle ABSOLUE n°12) et .claude/rules/backend.md (section Migrations Doctrine) avec exemples et helper standardise pour les colonnes Timestampable/Blamable.
2026-05-28 16:44:18 +02:00
parent 9613857650
commit 2ecfe226af
8 changed files with 469 additions and 0 deletions
@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DoctrineMigrations;
+
+use App\Shared\Infrastructure\Database\ColumnCommentsCatalog;
+use Doctrine\DBAL\Schema\Schema;
+use Doctrine\Migrations\AbstractMigration;
+
+/**
+ * ERP-67 — Retrofit `COMMENT ON COLUMN` / `COMMENT ON TABLE` sur toutes les
+ * tables metier existantes.
+ *
+ * Postgres stocke la description dans `pg_description`. Les outils d'admin
+ * (DBeaver, DataGrip, pgAdmin) l'affichent automatiquement, ce qui evite de
+ * remonter au code Doctrine pour comprendre la semantique d'une colonne.
+ *
+ * Source unique : `ColumnCommentsCatalog::comments()`. Le meme catalogue est
+ * rejoue par `app:apply-column-comments` apres `doctrine:schema:update --force`
+ * en environnement de test (Doctrine ORM ne conservant pas les commentaires
+ * absents du mapping PHP).
+ *
+ * Convention :
+ * - Description en francais, ≤ 200 caracteres.
+ * - Semantique du champ + contraintes / lien RG si pertinent.
+ *
+ * Migration placee au namespace racine `DoctrineMigrations` (regle ABSOLUE
+ * Starseed n°11) car elle touche plusieurs modules. Les futures migrations
+ * applicatives devront poser leur propre `COMMENT ON COLUMN` au moment de
+ * creer leurs colonnes (cf. regle ABSOLUE n°12 + .claude/rules/backend.md).
+ */
+final class Version20260528120000 extends AbstractMigration
+{
+    public function getDescription(): string
+    {
+        return 'ERP-67 : retrofit COMMENT ON COLUMN/TABLE sur toutes les tables metier existantes.';
+    }
+
+    public function up(Schema $schema): void
+    {
+        foreach (ColumnCommentsCatalog::toSqlStatements() as $sql) {
+            $this->addSql($sql);
+        }
+    }
+
+    public function down(Schema $schema): void
+    {
+        foreach (ColumnCommentsCatalog::comments() as $table => $entries) {
+            $quotedTable = '"'.str_replace('"', '""', $table).'"';
+            foreach ($entries as $column => $_) {
+                if ('_table' === $column) {
+                    $this->addSql(sprintf('COMMENT ON TABLE %s IS NULL', $quotedTable));
+
+                    continue;
+                }
+
+                $this->addSql(sprintf(
+                    'COMMENT ON COLUMN %s.%s IS NULL',
+                    $quotedTable,
+                    '"'.str_replace('"', '""', $column).'"',
+                ));
+            }
+        }
+    }
+}