Files

T

Auto Tag Develop / tag (push) Successful in 7s

Details

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

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.

---------

Co-authored-by: admin malio <malio@yuno.malio.fr>
Co-authored-by: Matthieu <contact@malio.fr>
Co-authored-by: Matthieu <mtholot19@gmail.com>
Reviewed-on: #24
Co-authored-by: THOLOT DECHENE Matthieu <matthieu@yuno.malio.fr>
Co-committed-by: THOLOT DECHENE Matthieu <matthieu@yuno.malio.fr>

2026-05-29 09:41:29 +00:00

4.5 KiB

Raw Blame History

Starseed

Contexte

CRM/ERP en architecture modular monolith DDD. Le backend est la source de verite unique (modules actifs, sidebar). Le frontend scanne frontend/modules/*/ comme layers Nuxt et consomme l'API pour la navigation. Multi-tenant : chaque module est activable/desactivable.

Doc humaine : @README.md — Spec audit : @doc/audit-log.md

Stack

Backend : PHP 8.4, Symfony 8, API Platform 4, Doctrine ORM, PostgreSQL 16 (port 5437)
Frontend : Nuxt 4 (SPA), Vue 3, Pinia, Tailwind, @malio/layer-ui, @nuxtjs/i18n
Auth : JWT HTTP-only cookie (Lexik), login a /login_check
Containers : php-starseed-fpm, nginx-starseed (port 8083), dev Nuxt port 3004

Regles ABSOLUES

Ne jamais importer d'un module a un autre — passer par Shared/Domain/Contract/ (interfaces) ou domain events.
Toujours declare(strict_types=1); en tete de tout fichier PHP.
Toujours annoter #[Auditable] les entites metier ; #[AuditIgnore] sur champs sensibles (password, token, secret).
Toujours utiliser useApi() pour les appels API cote front — jamais $fetch / ofetch direct.
Toujours utiliser les composants Malio* (@malio/layer-ui) pour formulaires/filtres ; MalioDataTable pour listes paginees.
Jamais persister l'etat de tableau dans l'URL (filtres, pagination, tri, selection) — state local uniquement.
Jamais ajouter un test E2E sauf si un bug critique est passe en prod ; preferer un test Vitest.
Toujours mettre a jour les 3 sources RBAC ensemble : config/sidebar.php, frontend/tests/e2e/_fixtures/personas.ts, src/Module/Core/Infrastructure/Console/SeedE2ECommand.php.
Jamais commit sans demande explicite de l'utilisateur ; jamais force push sans confirmation.
Jamais mentionner Claude, Anthropic ou une IA dans un commit (message, titre, body, footer, trailer) ou une PR (titre, description). Pas de Co-Authored-By: Claude, pas de Generated with Claude Code, pas de 🤖, pas d'emoji robot, rien. Les commits sont signes par l'utilisateur uniquement.
Migrations d'initialisation au namespace racine DoctrineMigrations dans migrations/ (setup user, RBAC, seed de base). Les migrations modulaires (src/Module/*/Infrastructure/Doctrine/Migrations/) sont reservees aux evolutions post-schema (ajout de colonnes, index) — cf. @.claude/rules/architecture.md pour la raison.
Toujours documenter chaque colonne BDD via COMMENT ON COLUMN dans la migration qui la cree ou la modifie. Description en francais, courte (≤ 200 caracteres), explique la semantique metier + contraintes implicites (unicite partielle, FK importante, lien RG). Garde-fou : tests/Architecture/ColumnsHaveSqlCommentTest echoue si une colonne public n'a pas de description (col_description IS NULL). Details et exemples : @.claude/rules/backend.md § Migrations Doctrine.

Conventions

@.claude/rules/architecture.md @.claude/rules/backend.md @.claude/rules/frontend.md @.claude/rules/testing.md @.claude/rules/naming.md @.claude/rules/git.md @.claude/rules/workflow.md

Commandes (liste complete dans @README.md)

Demarrer : make start
Dev front (hot reload) : make dev-nuxt (port 3004)
Shell PHP : make shell
Tests back : make test
Tests front unitaires : make nuxt-test
Tests E2E : make test-e2e (prerequis : make seed-e2e && make dev-nuxt)
Reset BDD : make db-reset
Lint PHP : make php-cs-fixer-allow-risky

Activer / desactiver un module

Editer uniquement config/modules.php (commenter la ligne). Cascade automatique via /api/modules, /api/sidebar, middleware front modules.global.ts. Details : @.claude/rules/architecture.md

A NE PAS faire

Pas de controller Symfony custom sous /api/ sans priority: 1 sur #[Route] (conflit API Platform {id}).
Pas de getClientMimeType() pour valider un upload — utiliser $file->getMimeType() (serveur).
Pas de hardcode de la sidebar cote front, pas de modules-loader.ts ni .module.ts.
Pas d'edition manuelle de extends dans frontend/nuxt.config.ts — les layers sont scannes automatiquement.
Pas de commentaires en anglais dans le code — commentaires en francais, code (noms) en anglais.
Pas d'<input> / <select> / <table> bruts quand un composant @malio/layer-ui existe (exceptions documentees dans @.claude/rules/frontend.md).
Pas de modification de la config git.

Skills projet

create-module — scaffolder un nouveau module back+front et wirer la sidebar.

Credentials (dev)

admin / admin (ROLE_ADMIN) ; alice / alice, bob / bob (ROLE_USER).

4.5 KiB Raw Blame History