MALIO-DEV/Starseed
3
0
Fork 0
Code Issues Pull Requests 5 Actions Packages Projects Releases Wiki Activity

[ERP-67] Documenter toutes les colonnes BDD via COMMENT ON COLUMN + garde-fou #24

Merged
malio merged 3 commits from feature/ERP-67-sql-column-comments into develop 2026-05-29 09:41:30 +00:00
Conversation 0 Commits 3 Files Changed 8
+469
matthieu commented 2026-05-28 14:46:36 +00:00
Owner
Copy Link
Copy Source

Ticket Lesstime : ERP-67 — [Convention SQL / Backend / L]

Objectif

Documenter toutes les colonnes BDD via COMMENT ON COLUMN (visible dans DBeaver / DataGrip / pgAdmin sans lire le code Doctrine) et verrouiller la convention par un garde-fou de test architecture.

Changements

Convention (CLAUDE.md + rules)

  • CLAUDE.md regle ABSOLUE n°12 : toute migration creant ou modifiant une colonne doit poser un COMMENT ON COLUMN (FR, ≤ 200 caracteres).
  • .claude/rules/backend.md § Migrations Doctrine : exemples + helper standardise pour les 4 colonnes du TimestampableBlamableTrait.

Garde-fou architecture

  • tests/Architecture/ColumnsHaveSqlCommentTest : echoue si une colonne public n'a pas de col_description (hors doctrine_migration_versions et fake_site_aware_entity fixture de test).
  • Whitelist metier EXCLUDED_TABLES volontairement vide.

Retrofit des tables existantes

  • Migration Version20260528120000 : 64 COMMENT ON TABLE/COLUMN sur les 11 tables metier (audit_log, category, category_type, permission, role, role_permission, site, user, user_permission, user_role, user_site).
  • Source unique de verite : src/Shared/Infrastructure/Database/ColumnCommentsCatalog.php.
  • Commande app:apply-column-comments (Module/Core/Infrastructure/Console) : 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 .gitea/workflows/pull-request.yml.

Validation

  • make db-reset puis make test : 312 tests verts, 0 regression.
  • make php-cs-fixer-allow-risky : 0 fix.
  • Couverture : 53/53 colonnes documentees sur starseed et starseed_test.

Test plan

  • make db-reset passe sans erreur.
  • make test passe ; ColumnsHaveSqlCommentTest vert sur DB de test.
  • Verifier dans DBeaver / pgAdmin que les commentaires apparaissent sur les colonnes de category, user, audit_log.
  • Verifier que le workflow CI Gitea (pull-request.yml) passe.

A noter pour la suite

La convention options: ['comment' => '...'] sur chaque #[ORM\Column] reste recommandee pour les nouvelles entites — Doctrine genere alors automatiquement le COMMENT ON COLUMN dans la migration et schema:update le preserve sans avoir a rejouer le catalogue. A discuter si on veut en faire une regle forte.

Ticket Lesstime : ERP-67 — `[Convention SQL / Backend / L]` ## Objectif Documenter toutes les colonnes BDD via `COMMENT ON COLUMN` (visible dans DBeaver / DataGrip / pgAdmin sans lire le code Doctrine) et verrouiller la convention par un garde-fou de test architecture. ## Changements ### Convention (CLAUDE.md + rules) - `CLAUDE.md` regle ABSOLUE n°12 : toute migration creant ou modifiant une colonne doit poser un `COMMENT ON COLUMN` (FR, ≤ 200 caracteres). - `.claude/rules/backend.md` § Migrations Doctrine : exemples + helper standardise pour les 4 colonnes du `TimestampableBlamableTrait`. ### Garde-fou architecture - `tests/Architecture/ColumnsHaveSqlCommentTest` : echoue si une colonne `public` n'a pas de `col_description` (hors `doctrine_migration_versions` et `fake_site_aware_entity` fixture de test). - Whitelist metier `EXCLUDED_TABLES` volontairement vide. ### Retrofit des tables existantes - Migration `Version20260528120000` : 64 `COMMENT ON TABLE/COLUMN` sur les 11 tables metier (audit_log, category, category_type, permission, role, role_permission, site, user, user_permission, user_role, user_site). - Source unique de verite : `src/Shared/Infrastructure/Database/ColumnCommentsCatalog.php`. - Commande `app:apply-column-comments` (Module/Core/Infrastructure/Console) : 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 `.gitea/workflows/pull-request.yml`. ## Validation - `make db-reset` puis `make test` : 312 tests verts, 0 regression. - `make php-cs-fixer-allow-risky` : 0 fix. - Couverture : 53/53 colonnes documentees sur `starseed` et `starseed_test`. ## Test plan - [ ] `make db-reset` passe sans erreur. - [ ] `make test` passe ; `ColumnsHaveSqlCommentTest` vert sur DB de test. - [ ] Verifier dans DBeaver / pgAdmin que les commentaires apparaissent sur les colonnes de `category`, `user`, `audit_log`. - [ ] Verifier que le workflow CI Gitea (`pull-request.yml`) passe. ## A noter pour la suite La convention `options: ['comment' => '...']` sur chaque `#[ORM\Column]` reste recommandee pour les nouvelles entites — Doctrine genere alors automatiquement le `COMMENT ON COLUMN` dans la migration et `schema:update` le preserve sans avoir a rejouer le catalogue. A discuter si on veut en faire une regle forte.
matthieu added 1 commit 2026-05-28 14:46:37 +00:00
feat(db) : documenter toutes les colonnes BDD via COMMENT ON COLUMN + garde-fou (ERP-67)
Pull Request — Quality gate / Frontend (lint + Vitest + build) (pull_request) Successful in 1m13s
Details
Pull Request — Quality gate / Backend (PHP CS + PHPUnit) (pull_request) Failing after 1m35s
Details
2ecfe226af 
- 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.
matthieu added 1 commit 2026-05-28 15:20:55 +00:00
fix(ci) : recree l'index partiel uq_category_name_type_active apres schema:update (ERP-67)
Pull Request — Quality gate / Backend (PHP CS + PHPUnit) (pull_request) Successful in 1m28s
Details
Pull Request — Quality gate / Frontend (lint + Vitest + build) (pull_request) Successful in 1m5s
Details
a62380e2d2 
Le workflow CI lancait `doctrine:schema:update --force` (ajoute par ERP-67
pour aligner sur le mapping ORM avant `app:apply-column-comments`) sans
recreer ensuite l'index partiel `uq_category_name_type_active`. Doctrine
ORM 3 ne sait pas exprimer un index fonctionnel + partiel (LOWER(name)
WHERE deleted_at IS NULL), le considere donc comme orphelin et le DROP
silencieusement. Resultat en CI : les tests RG-1.07 (CategoryUniqueTest)
attendent 409 sur un doublon (name, type) mais recoivent 201 car la
contrainte SQL n'existe plus.

La cible `make test-db-setup` (ligne 222 du makefile) recreait deja l'index
via `dbal:run-sql` ; on aligne le workflow CI sur le meme pas, et on ajoute
un commentaire pointant vers la cause-racine pour eviter le drift au
prochain refactor du workflow.
malio added 1 commit 2026-05-29 09:41:25 +00:00
Merge branch 'develop' into feature/ERP-67-sql-column-comments
Pull Request — Quality gate / Backend (PHP CS + PHPUnit) (pull_request) Successful in 2m3s
Details
Pull Request — Quality gate / Frontend (lint + Vitest + build) (pull_request) Successful in 1m0s
Details
feb21e7fab
malio merged commit a948eed9b6 into develop 2026-05-29 09:41:30 +00:00
malio deleted branch feature/ERP-67-sql-column-comments 2026-05-29 09:41:30 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
back
Backend PHP / Symfony / API Platform
 blocked
Bloqué par une dépendance externe
 breaking
Breaking change — impact API / contrat
 db
Migrations Doctrine / schéma BDD
 front
Frontend Nuxt / Vue / @malio/layer-ui
 infra
Docker / nginx / config infra
 type/chore
Tâche de maintenance (bump, conf, etc.)
 type/ci
CI / pipeline / workflows
 type/docs
Documentation
 type/feat
Nouvelle fonctionnalité
 type/fix
Correction de bug
 type/perf
Amélioration de performance
 type/refactor
Refacto sans changement fonctionnel
 type/test
Ajout ou modification de tests
 wip
Work in progress — ne pas merger
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
malio (admin malio) matthieu (THOLOT DECHENE Matthieu) tristan (Autin )
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: MALIO-DEV/Starseed#24
Delete Branch "feature/ERP-67-sql-column-comments"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?