Starseed/CLAUDE.md

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

1. Ne jamais importer d'un module a un autre — passer par Shared/Domain/Contract/ (interfaces) ou domain events.
2. Toujours declare(strict_types=1); en tete de tout fichier PHP.
3. Toujours annoter #[Auditable] les entites metier ; #[AuditIgnore] sur champs sensibles (password, token, secret).
4. Toujours utiliser useApi() pour les appels API cote front — jamais $fetch / ofetch direct.
5. Toujours utiliser les composants Malio* (@malio/layer-ui) pour formulaires/filtres ; MalioDataTable pour listes paginees.
6. Jamais persister l'etat de tableau dans l'URL (filtres, pagination, tri, selection) — state local uniquement.
7. Jamais ajouter un test E2E sauf si un bug critique est passe en prod ; preferer un test Vitest.
8. 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.
9. Jamais commit sans demande explicite de l'utilisateur ; jamais force push sans confirmation.
10. 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.
11. 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.
12. 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.
13. Toujours paginer toute collection exposee par l'API. Aucun retour de collection complete (pas de provider qui retourne un array brut). Standard pose dans config/packages/api_platform.yaml : 10 items par defaut, max 50, le client peut basculer entre 10/25/50 et peut envoyer ?pagination=false pour alimenter un select. Garde-fou : tests/Architecture/CollectionsArePaginatedTest echoue si une GetCollection desactive la pagination sans whitelist. Details et exemples : @.claude/rules/backend.md § Pagination.
14. symfony.lock est versionne (au meme titre que composer.lock) — ne JAMAIS le .gitignore. C'est le registre des recipes Flex appliquees : sans lui, chaque composer require rejoue toutes les recipes et repollue .env, config/bundles.php, docker-compose.yml et recree du scaffolding parasite (src/Entity/, src/Controller/...). Le regenerer si besoin via composer recipes:install --force.

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 provider API Platform qui retourne un array brut sur une GetCollection — court-circuite la pagination Hydra (totalItems / view absents). Utiliser ApiPlatform\Doctrine\Orm\Paginator (ORM) ou un paginator implementant PaginatorInterface (DBAL — cf. DbalPaginator).
• 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).