Le développement — du PRD au code, par scaffoldersDevelopment — from PRD to code, through scaffolders

Dans un projet SmartStack, le code appartient aux scaffolders : backend et frontend sont générés par des CLIs déterministes à partir des documents BA (marqueur @generated-by dans chaque fichier). On ne modifie pas le code généré à la main — on corrige le document BA ou le pagespec, puis on régénère. Pour un vrai cas sur-mesure, le fichier est marqué // @customised : les régénérations le laissent alors intact. In a SmartStack project, the scaffolders own the code: backend and frontend are generated by deterministic CLIs from the BA documents (an @generated-by marker in every file). You do not hand-edit generated code — you fix the BA document or the pagespec, then regenerate. For a genuinely bespoke case, the file is marked // @customised: regenerations then leave it untouched.

Ces scaffolders sont normalement pilotés par /ba-develop — cette page décrit ce qu'ils produisent, pour comprendre ce qui est généré et par quoi. These scaffolders are normally driven by /ba-develop — this page describes what they produce, so you understand what is generated and by what.

Les couches backendThe backend layers

CoucheLayer Scaffolder ProduitProduces
Amorce CoreCore seed scaffold-core-seed Navigation, applications, modules, sections, rôles et permissions de l'app (seed)App navigation, applications, modules, sections, roles and permissions (seed)
DonnéesData scaffold-entity (+ variantes coded-entity, data-scope, search…) Entités, configurations EF, index, FK réelles, portées ligne à ligne, recherche globaleEntities, EF configurations, indexes, real FKs, row-level scopes, global search
MétierBusiness scaffold-business Services, validation FluentValidation, règles métier implémentéesServices, FluentValidation, implemented business rules
API scaffold-controller Contrôleurs REST avec RBAC ([RequirePermission]), actions custom alignées sur les pagespecsREST controllers with RBAC ([RequirePermission]), custom actions aligned with the pagespecs
Jeux de donnéesSeed data scaffold-seed Données de démo/référence par fonctionnalitéDemo/reference data per feature Deux paliers : referenceData[] (Valeurs initiales, tous environnements) et testData[] (jeu de test métier jeu-de-test.md, gardé par SmartStack:EnableDevSeeding — dev/test/qual, jamais prod).Two tiers: referenceData[] (initial values, every environment) and testData[] (the business test dataset jeu-de-test.md, guarded by SmartStack:EnableDevSeeding — dev/test/qual, never prod).

Les couches frontendThe frontend layers

CoucheLayer Scaffolder ProduitProduces
ThèmeTheme scaffold-theme Tokens CSS + design system (couleurs, tables, dataviz)CSS tokens + design system (colors, tables, dataviz)
PrimitivesPrimitives scaffold-ui-primitives DataTable, EntityLookup, DateInput, TabStrip, SectionCard… — les briques que toutes les pages utilisentDataTable, EntityLookup, DateInput, TabStrip, SectionCard… — the bricks every page uses
PagesPages scaffold-component Listes (recherche/tri/pagination CÔTÉ SERVEUR), fiches, formulaires (sections, lifecycle), dashboards, kanbanLists (SERVER-side search/sort/pagination), detail views, forms (sections, lifecycle), dashboards, kanban
RoutesRoutes scaffold-routes Routage dynamique piloté par le menu en base (/api/navigation/menu)Dynamic routing driven by the DB menu (/api/navigation/menu)
Client APIAPI client scaffold-api-client Services TypeScript + hooks React Query, types = DTOsTypeScript services + React Query hooks, types = DTOs
i18ni18n (intégré aux scaffolders)(built into the scaffolders) Bundles fr/en/it/de complets, clés jamais brutes à l'écranComplete fr/en/it/de bundles, never raw keys on screen

Les packs d'audit par coucheThe per-layer audit packs

Neuf packs de règles vérifient le code généré, chacun appelable indépendamment (et exécutés automatiquement par les gates de /ba-develop). Leur rôle fonctionnel : Nine rule packs verify the generated code, each callable independently (and run automatically by /ba-develop's gates). Their functional role:

Audit Vérifie que…Checks that…
audit-dev-domain …les entités du domaine respectent les conventions…domain entities follow the conventions
audit-dev-data …la couche données (EF, index, FK) est saine…the data layer (EF, indexes, FKs) is sound
audit-dev-core …le seed nav/rôles/permissions est complet et cohérent…the nav/roles/permissions seed is complete and coherent
audit-dev-api …chaque règle métier est appliquée, chaque action a son endpoint, les permissions déclarées sont seedées, rien ne rend 500/405…every business rule is enforced, every action has its endpoint, declared permissions are seeded, nothing returns 500/405
audit-dev-frontend …les pages respectent le thème, l'i18n est complète, les listes restent lisibles (≤ 7 colonnes), les FK n'affichent jamais un GUID…pages respect the theme, i18n is complete, lists stay readable (≤ 7 columns), FKs never show a GUID
audit-dev-wire …services, repositories et DI sont câblés à travers les strates…services, repositories and DI are wired across strata
audit-dev-tests …chaque critère d'acceptation BA a son test (gate bloquant)…every BA acceptance criterion has its test (blocking gate)
audit-dev-pwa …le mode hors ligne est correctement câblé (voir PWA)…offline mode is wired correctly (see PWA)
audit-dev-customised …les pages @customised n'ont pas dérivé du contrat…@customised pages have not drifted from the contract

Vérifier que ça marche vraimentVerifying it really works

  • /validate-feature — validation de bout en bout d'une fonctionnalité scaffoldée : compile + tests + smoke API.end-to-end validation of a scaffolded feature: compile + tests + API smoke.
  • smoke-test — le gate d'exécution final : démarre backend + frontend et vérifie 4 axes (sondes HTTP sur toutes les routes, navigateur Chromium headless, cohérence du menu, contrat des actions custom).the final runtime gate: boots backend + frontend and checks 4 axes (HTTP probes on every route, headless Chromium, menu consistency, custom-action contract).
  • Skills debug — triage (audit-bug), diagnostic contradictoire (discuss-bug), correction (fix-bug).debug skills — triage (audit-bug), adversarial diagnosis (discuss-bug), fix (fix-bug).

Dans quel cas ?Which situation, which command?

Je suis dans ce cas…I am in this situation… …alors je fais…then I do
Un champ manque sur un formulaire généréA field is missing on a generated form corriger entité.md / le pagespec, puis régénérer (jamais éditer le TSX à la main)fix entité.md / the pagespec, then regenerate (never hand-edit the TSX)
Je dois écrire une page vraiment sur-mesureI need a truly bespoke page marquer le fichier // @customised — il survit aux régénérations, audit-dev-customised surveille sa dérivemark the file // @customised — it survives regenerations, audit-dev-customised watches its drift
Un endpoint rend 500 alors que tout compileAn endpoint returns 500 though everything compiles audit-dev-api (DI manquante, permission non seedée…)audit-dev-api (missing DI, unseeded permission…)
Une page affiche des clés i18n brutesA page shows raw i18n keys audit-dev-frontend
La fonctionnalité est finie, je veux une preuveThe feature is done, I want proof /validate-feature puis smoke-test/validate-feature then smoke-test