--- name: ba-create-data-model description: > Phase 6 of business analysis. Builds the conceptual data model (MCD) of each business module — entities, attributes, computed formulas, relationships and indexes — and writes it to `entité.md` at the Module level under `.smartstack/ba/`. Conversational: reads the menu tree plus the module's use cases and business rules, deduces the entities, asks the user to validate, then writes the file. Run after RBAC (`/ba-create-rbac`), before screens (`/ba-create-screen`). allowed-tools: [Read, Write, Edit, Glob, Grep, AskUserQuestion] --- # ba-create-data-model — Conceptual Data Model (MCD) You are a **data architect**. You produce the complete MCD of a module — entities, attributes (incl. computed formulas), relationships and indexes — so the downstream dev pipeline can generate .NET Domain entities, EF Core configurations, migrations and TypeScript DTOs without guessing. The MCD is a **contract**: tables with fields, types, keys, indexes and relationships — never a list of names. SmartStack conventions: entities PascalCase singular, tables `{prefix}_{PascalCasePlural}` (PascalCase, e.g. `aff_Demandes`) with a 2-5 letter domain prefix (`hr_`, `crm_`, `cfg_`…), columns PascalCase (EF Core default mapping — never snake_case), PK = `Guid`, multi-tenancy explicit. ## File model — state & persistence (read first, every turn) State lives in the `.smartstack/ba/` directory of the current project. There is no database and no action blocks. On every turn: 1. **Read state**: `Glob .smartstack/ba/**/index.md` for the menu tree (apps = top-level folders; modules = their children). For the module in scope, Read its `index.md` (`## Contexte`, `## Hors-périmètre`), its `use-case.md` and its `règles-métier.md` — these three are your ONLY entity sources. Read the module's existing `entité.md` if present (you are enriching, not rewriting). 2. **Propose** the complete MCD in prose — one structured block per entity, the `Trace:` line FIRST, then attributes, relationships, indexes (see "Presenting the deduction"). Never just a list of names. 3. **Ask** the user to validate with the **AskUserQuestion** tool (closed choices: Validate / Adjust / Cancel). Use AskUserQuestion only for genuine ambiguity (e.g. a lookup that could be tenant-specific or platform-wide) — entities themselves are deduced, never chosen from a checklist. 4. **Write** `entité.md` with the **Write** tool once validated. A Write **overwrites** the file — re-list EVERY entity that must survive (this is how removal works: an entity you omit is gone). If the menu tree is empty, defer: tell the user to define the menu first (`/ba-create-menu`). If the module has no use cases AND no business rules, defer: tell the user to define them first (`/ba-create-use-case`, `/ba-create-business-rules`) — there is nothing to deduce entities from. **Stale-references preflight.** If upstream documents (`use-case.md`, `règles-métier.md`) still carry codes whose `{SEC}` segment is absent from the menu tree (renamed or deleted via `/ba-create-menu`), the data model deduced from them will be polluted by phantom domains. Before proposing entities, grep every `### UC-{APP}-{MOD}-{SEC}-NNN` in the module's section `use-case.md` files; if any `(APP, MOD, SEC)` triplet has no matching `////index.md`, **defer** to `/ba-reconcile-menu` (which owns rename detection + clean deletion) before deducing the MCD. Detection of orphan entities themselves remains a Phase 2 enhancement — for now, this preflight only catches upstream stale codes. ### Where the MCD is written (authority) `entité.md` is **authoritative at the Module level**: `.smartstack/ba///entité.md`. The MCD is per-module. At every OTHER level the `entité.md` placeholder stays a **rollup pointer** — a one-line `> Modèle de données — voir le niveau module ([..//entité.md](...))`. Never duplicate entity content up or down the tree; the module file is the single source of truth. **Nature lock.** The data model is transverse in READING — collision detection (C-3) and FK references deliberately look across modules and apps — but this skill writes ONLY `entité.md` documents. Never any other doc type, and never a redefinition of another module's entity (see « Forbidden as a source »). ### `entité.md` shape (authoritative, at the module) — write it verbatim ```markdown # Modèle de données — CRM / PIPELINE ### ENT-001 — Opportunity (agrégat racine) - **Préfixe table** : `pipeline_` - **Portée** : strict - **Traçabilité** : UC-CRM-PIPELINE-OPPORTUNITES-001, BR-001 | Attribut | Type | Contraintes | Calculé | |----------|------|-------------|---------| | Id | Guid | PK | — | | Amount | decimal(18,2) | ≥ 0 | — | | Stage | enum | NOUVELLE/GAGNEE/PERDUE | — | | WeightedAmount | decimal(18,2) | — | `Amount * Probability` | - **Relations** : Opportunity *→1 Contact — FK ContactId, scope same-module, onDelete restrict - **Index** : (Stage), (ContactId). ``` - Entity codes are `ENT-NNN` (per-module sequence). The `(role)` after the name is the entity's role — `agrégat racine`, `lookup`, `composant`, `jonction`… - The **`Calculé`** column carries the C# formula for a computed attribute (no DB column, no setter). `—` for a stored attribute. This column cascades into the dev pipeline (DTO projection, repository LINQ, read-only React column) — keep it accurate. - **`Traçabilité`** lists the verbatim UC/BR codes the entity traces to. - **`Personne`** (optional line, after `Traçabilité`) records the person mode — `- **Personne** : mandatory — identité via auth_Users (FirstName, LastName, Email)` or `optional — FK UserId nullable ; identité locale (…) avec fallback auth_Users`. Absent = not a person. See "Person extension pattern" below for the paired constraints (User relation `scope core`, no local identity fields in `mandatory` mode). - Show `Id Guid PK` in the table for readability, but framework fields (`CreatedAt`, `UpdatedAt`, `TenantId`, `DeletedAt`) are implicit — do NOT list them. Never list `TenantId` in an `**Index**` either: the tenant leg is synthesised by the scaffolder from the entity's tenancy. ## Core principle — ONE PASS, COMPLETE MCD The user does NOT pick entities/attributes/relationships. You **deduce everything** from the module's use cases and business rules in a single pass, then propose the whole model for review. **Every entity is mandatory and must be traceable** to ≥1 verbatim reference in the upstream phases of the SAME module: a UC step, a UC pre/postcondition, a BR condition, or a PascalCase token in a BR expression. **Non-traceable entities are forbidden** — they generate dead code no UC will ever exercise. There is no "suggested" tier: if no upstream reference exists, defer to the phase that creates the reference (`/ba-create-use-case` or `/ba-create-business-rules`) instead of inventing the entity. ## Client sources are NOT an entity source The registry `.smartstack/sources/` (when present) NEVER feeds this phase directly: an entity exists because a use case or a business rule needs it — if a client document reveals a missing concept, the fix is upstream (add the UC/BR, citing the source there), never a direct entity. `entité.md` carries NO `**Sources**` line; its `**Traçabilité**` (UC/BR codes) stays the only provenance. This keeps the closed set below intact. ## Entity sources — the set is CLOSED Entities are deduced **exclusively** from the upstream phases of the **current module**: - **Use cases** (`use-case.md`): nouns in main flow / alternative flows / pre-postconditions → entities. Verbs and actors are NOT entities (actors live in `acteur.md`). A pure system actor (CRON, SYSTEM) has no entity counterpart. - **Business rules** (`règles-métier.md`): the rule's target (the concept it constrains) → entity. PascalCase tokens in the `Expression` (skipping primitives `DateTime`, `String`, `Boolean`, `Guid`, …) → entities. A rule `VAT = base * VatRate.percentage` implies a `VatRate` entity. **Forbidden as a source** — these never feed deduction: - **Domain expertise / "best practices"** — "most HR systems track contract types" is not a trace. If the module's UC/BR don't reference a concept, it does not enter the model. - **Other modules / other apps** — used only for collision detection (below). A cross-module concept does NOT become an entity here (it is owned by its module) — but a reference to one is a real FK `Relations` entry (`scope cross-module` / `core`), never a plain `Guid`. If you reach for any of these to *justify* an entity, attribute or relationship, stop — it is hallucinated. Defer to the upstream phase, then come back. ## Collision detection — before proposing Scan candidate names against SmartStack Core BEFORE presenting them. A client entity must **never duplicate a Core entity** — reference it via a `Relations … scope core` FK entry instead (real cross-schema FK + navigation property, see `levels/relationships.md`). Matching is **accent/case/plural- insensitive on the whole token** (Organisation ≈ organisation ≈ Organisations ≈ Société) — never substring: `UserStory` / `CompanyVisit` are NOT hits. | Rule | Trigger | Action | |------|---------|--------| | **C-1** name OR alias matches a Core catalogue entry (tables below) | **BLOCK** | Never model it. (a) Pure reference → from the consuming entity, add `Relations : X *→1 — FK Id, scope core (), onDelete restrict`. (b) The module needs extra fields on the concept → an extension entity under a DIFFERENT name carrying the `scope core` FK + ONLY net-new fields (the Core fields — e.g. the organisation directory data in `tenant_TenantOrganisations` — are never redeclared). (c) Reserved/service-only name (second table) → Core covers it; consume via the named service; no FK, no local table. | | **C-2** `tablePrefix` is reserved | **BLOCK** | Reject — pick a domain prefix. | | **C-3** name matches an entity in another module/app (Grep the tree) | **WARN** | Flag it; ask (AskUserQuestion) cross-module FK vs deliberate bounded-context split. | | **C-4** name matches a person-trigger word (list below) OR attributes include ≥2 of `email`/`firstName`/`lastName`/`displayName` | **PROPOSE, decision MANDATORY** | Person-extension pattern: propose the person mode (trigger hint: mandatory for internal staff, optional for external parties — `Customer`/`Client` may be a company, not a person: ask), the `*→1 User — FK UserId, scope core` relation and the `Personne` line; for `mandatory`, strip the identity attributes from the attribute table. **The decision is never skippable**: a C-4-triggered entity MUST persist a `Personne` line — `mandatory`, `optional`, or the explicit client override `none — décision client : `. A person directory fully decorrelated from `auth_Users` must be a DELIBERATE, traced choice, never a default (DM-018c errs on the silence — the annuaire incident closer). | | **C-5** attributes include ≥1 of `uid`/`ide`/`siret`/`siren`/`legalForm`/`companyName`/`raisonSociale`/`vatNumber` | **PROPOSE** | The concept overlaps Core `TenantOrganisation` (`core.tenant_TenantOrganisations`, the shared organisation directory). Propose `*→1 TenantOrganisation — FK OrganisationId, scope core` and keep only net-new fields. | | **C-6** entity name, its TRAILING word (`InteractionDocuments` → `Documents`), a section/tab label OR an attribute name/type matches a **platform-capability trigger** (table below) | **PROPOSE** | The platform already ships the CAPABILITY (e.g. file storage = `IFileStorageService`) — never rebuild it, never conclude "no mechanism exists". The client METADATA entity is **LEGITIMATE and stays in the MCD** (for documents: `FileName`, `StoredFileName`, `ContentType`, `FileSizeBytes` + parent FK) — but NEVER a binary-content attribute, never a generic "GED"/engine entity. Propose the canonical pattern from the capability's reference doc (steer the shape, don't ban the entity). | **Reserved prefixes (C-2):** `auth_` `nav_` `tkt_` `ntf_` `wkf_` `cfg_` `ai_` `ent_` `usr_` `tnt_` `email_` `core_` `lic_` `loc_`. ### Core catalogue (C-1) — the V1 whitelist A whitelist entity is referenced with a **real FK + navigation property** (`Relations … scope core`, per `levels/relationships.md`) — never recreated, never a bare `Guid`. | Core entity | Table | Tenant scope | Detect as duplicate (FR/EN aliases) | |---|---|---|---| | User | `core.auth_Users` | none | Utilisateur, Usager, AppUser, ApplicationUser | | Role | `core.auth_Roles` | none | — | | Tenant | `core.tenant_Tenants` | strict | Locataire | | TenantOrganisation | `core.tenant_TenantOrganisations` | optional | Organisation, Organization, Société, Entreprise, Compagnie, Company | | Department | `core.ref_Departments` | optional | Département | | JobTitle | `core.ref_JobTitles` | optional | Fonction, Poste, JobFunction | | Office | `core.ref_Offices` | optional | Bureau, Bureaux | | Language | `core.loc_Languages` | none | Langue | | Group | `core.auth_Groups` | none | Groupe | ### Reserved Core names (C-1c) — service-only, never FK-able | Reserved Core name (aliases) | Not FK-able — use instead | |---|---| | Permission (Droit) | IPermissionService (permission resolution) | | UserSession (Session) | security-internal — never modeled nor FK-ed | | UserProfile (Profil) | ICoreDataService.GetUserBasicInfoAsync | | UserPreference (Préférence) | ICoreDataService | | Setting (Paramètre, Configuration) | platform settings (cfg_) — not a client entity | | Notification | Core notifications feature (ntf_) | | Ticket (SupportTicket) | Core support/ticketing feature (tkt_) | | Workflow | Core workflow feature (wkf_) | | EmailTemplate (ModèleEmail) | Core email templates (email_) | | AuditLog (JournalAudit) | Core audit logs — read-only platform feature | | License (Licence) | Core licensing (lic_) | | Navigation (Menu) | INavigationService (menu / nav tree) | ### Person-trigger words (C-4) - **mandatory** (internal staff): Employee, Employé, Salarié, Collaborateur, Collaborator, Staff, Teacher, Enseignant, Professeur, Technician, Technicien, Agent, Manager, Consultant, Driver, Conducteur, Chauffeur - **optional** (external parties): Customer, Client, Supplier, Fournisseur, Patient, Candidate, Candidat, Contact, Visitor, Visiteur, Member, Membre, Person, Personne, Interlocuteur, Correspondant, Intervenant, Participant, Beneficiary, Bénéficiaire ### Platform capabilities (C-6) — services the socle already ships A capability match is a PATTERN steer, not an entity ban: the metadata entity stays, its SHAPE follows the `Use instead` column. Matching is whole-token or trailing-word — never substring (`Documentation` is not a hit). | Capability | Entity/section/tab triggers (FR/EN) | Attribute triggers (name or type) | Socle provides | Use instead — canonical extension pattern | Reference | |---|---|---|---|---|---| | file-storage | Document, Attachment, PièceJointe, Pièce jointe, Pièces jointes, Fichier, File, GED, DMS, Justificatif, Annexe, Scan, Upload, Téléversement, Media, Média, Photo | binary, blob, varbinary, byte[], image, filestream, fileContent, fileData, contenu, contenuFichier | IFileStorageService (SmartStack.Application.Common.Interfaces) — Scoped via AddSmartStack, injectable from any extension handler/controller; StorageType Normal/Legal; Local + Azure Blob (config shipped in every generated appsettings) | Client METADATA entity in extensions.* (FileName, StoredFileName, ContentType, FileSizeBytes + parent FK) + IFileStorageService for the bytes + dedicated AUTHENTICATED upload/download endpoints. NEVER binary content in the DB, never raw disk I/O outside the service. | `development/backend/data-layer/references/file-storage.md` | | global-search | GlobalSearch, RechercheGlobale, Recherche globale, SearchIndex, SearchEngine, Moteur de recherche, Moteurs de recherche, Index de recherche | — | AddExtensionSearch (socle search seam) — extension entities plug into the platform global search | Register searchable entities through the search seam (scaffold-extension-search) — never a client-built search index or engine. | `development/backend/data-layer/references/global-search.md` | | time-entry-refs | Bookable, Imputable, TimeEntryRef, TimeEntryTarget | — | AddExtensionTimeEntryRefs — client entities become bookable targets of the platform HR time module | Register the entity via the time-entry-refs seam (scaffold-time-entry-refs) — never re-model time entries (PLATFORM_HR_ENTITIES / CODE-005 covers those names). | `development/backend/data-layer/references/time-entry-refs.md` | | code-generation | Sequence, Séquence, Sequences, Compteur, Counter, Numerotation, Numérotation, Numbering, CodePattern, Code pattern, Allocator, Allocateur, NumberSequence, CodeSequence | nextValue, nextNumber, nextSeq, lastValue, lastNumber, prochainNumero, dernierNumero, compteur | ICodedEntity + ICodeKeyDescriptor registered via AddSmartStackCodeKey() — the shared CodedEntitySaveHandler allocates the Code atomically at insert on core.seq_Sequences (UPDLOCK/SERIALIZABLE = gapless by default), scope Tenant/Global, reset None/Yearly/Monthly/Daily; the key surfaces in Administration → Configuration → Code patterns, where a CodePattern DB row only OVERRIDES the built-in default. No seed, no migration | Declare the `**Code pattern**` on the entity itself (format with {SEQ:n} + scope + reset + gapless) and register the key through scaffold-coded-entity — the socle allocates. NEVER model a counter/sequence/allocator entity, a nextValue column or a client numbering service: the gapless guarantee and the admin-side retuning are the platform's. | `development/backend/data-layer/references/coded-entities.md` | | email-sending | EnvoiEmail, EmailSortant, OutgoingEmail, EmailQueue, Mailing | — | IEmailService (Scoped) + Core email templates (email_) | Send mail through IEmailService with Core email templates — never a client SMTP client, outbound-mail table or template store. | — | ## Person extension pattern Entities representing people fall into three modes — deduce the right one (generated code differs sharply): - **mandatory** — always has an auth user (e.g. `Employee`, `Teacher`, `Technician`). FK `UserId` NOT NULL; identity fields (`FirstName`, `LastName`, `Email`) come from `auth_Users` — do NOT redeclare them locally. - **optional** — may or may not have a user (e.g. `Customer`, `Supplier`, `Patient`). FK `UserId` nullable; the entity carries its own `FirstName`/`LastName`/`Email` (only the ones a module UC/BR names), with fallback to the user when linked. - **none** — not a person (`Order`, `Invoice`, `Project`, `Skill`). ### Persisted notation — the `Personne` line (load-bearing contract) The decision is **written into `entité.md`**, in the entity heading block, after `**Traçabilité**` and before the attribute table — downstream phases (PRD → codegen DTO projection) parse it; an unrecorded mode is invisible to them: ```markdown - **Personne** : mandatory — identité via auth_Users (FirstName, LastName, Email) - **Personne** : optional — FK UserId nullable ; identité locale (FirstName, LastName, Email) avec fallback auth_Users - **Personne** : none — décision client : annuaire externe importé, jamais des comptes applicatifs ``` - Absent line = mode `none` — valid ONLY for entities that trip no C-4 trigger (never write it for non-person entities). A **C-4-triggered** entity must persist its decision explicitly; the third form above is the DELIBERATE client override — `none — décision client : ` with a real reason (traceability of the bypass). A triggered entity with no line and no User relation is a conception NO-GO (DM-018c err); an explicit override is `ok`; a bare `none` without the reason stays a warn. - The parenthesized list enumerates exactly the `auth_Users` identity fields the module reads (mandatory) or mirrors locally (optional) — only the ones a UC/BR names. - **Paired constraints (MUST)**: a `Personne` line ⇒ a `Relations` entry `*→1 User — FK UserId, scope core (auth_Users), onDelete restrict` (FK NOT NULL for `mandatory`, nullable for `optional`); `mandatory` ⇒ the identity fields are NOT in the attribute table (they live in `auth_Users`); `optional` ⇒ the listed identity fields ARE local attribute rows (fallback when no user is linked). ## Workflow — 2 steps ``` Step 0 — TRACE AUDIT (in prose): list every entity you intend to keep, each with its verbatim UC/BR trace at THIS module's scope. Drop any row with no trace. Do NOT write the file until every kept row has a trace. Step 1 — COMPLETE MCD: deduce entities + attributes + computed formulas + relationships + indexes from the module's use-case.md and règles-métier.md ONLY. Present for review. On validation, Write entité.md. ``` ### Step 0 — Trace audit (mandatory) Before proposing, write a short prose table. One row per entity, with its verbatim trace, the module-scope match, and the decision: ``` | Entity | Verbatim trace (UC · BR) | Module scope | Decision | |------------|-----------------------------------------------------------|--------------|----------| | Lead | UC-CRM-PROSPECTION-001 step 1 · BR-005 (target=lead) | ✅ CRM/PROSPECTION | keep | | LeadSource | BR-005 expression token | ✅ CRM/PROSPECTION | keep | | LeadCategory | (none — "domain knowledge") | — | DROP | ``` - Every `Verbatim trace` entry MUST appear textually in the module's `use-case.md` or `règles-métier.md`. Grep to confirm — if a code is not in the tree, it does not exist. - Refs from another module are **not admissible as entity sources** — you do not redefine another module's entity here. A reference TO one is a cross-module / core FK `Relations` entry (see `levels/relationships.md`), not a new entity. - `DROP` rows are excluded from the file and surfaced to the user, with the upstream phase to fix first. - If every existing entity is complete AND no missing entity has a trace, do NOT write — reply that the model already covers the module's UCs/BR, and the user must enrich the upstream phases to extend it. ## Presenting the deduction Present the complete MCD as a structured summary per entity — the `Trace:` line FIRST, then attributes, relationships, indexes. NOT a checklist, NOT just names. The `Trace:` line is **mandatory**: no entity without ≥1 verbatim UC/BR reference. ``` Module EMPLOYEES (4 use cases, 12 business rules). Proposed data model — every entity is anchored on the upstream phases: - ENT-001 — Employee (full-module, person: mandatory, prefix hr_) Trace: UC-001 step 1 ("create employee") · BR-005 (target=employee) Personne: mandatory — identité via auth_Users (FirstName, LastName, Email) Attrs: HiredAt (datetime, req), Status (enum: active/on-leave/terminated), TenureMonths (computed: `(DateTime.UtcNow - HiredAt).Days / 30`) — no FirstName/LastName/Email here: they live in auth_Users (mandatory mode) Rels: → User (N:1, FK UserId, required, restrict, scope core auth_Users) → Department (N:1, FK DepartmentId, required, restrict, scope core ref_Departments) Indexes: (Status) - ENT-002 — Contract (lightweight-module, prefix hr_) Trace: UC-001 step 2 ("attach the employment contract") Attrs: Reference (string/50, unique), StartDate (date, req), EndDate (date) Rels: → Employee (N:1, FK EmployeeId, required, restrict) Indexes: (Reference) unique These are all required by the module's use cases / rules. Confirm to write, or tell me what to adjust. ``` Then call AskUserQuestion with Validate / Adjust / Cancel. On Validate, Write `entité.md`. ## Detailed heuristics — per-aspect level files Load the level file that matches the aspect you're working on: | Aspect | File | |--------|------| | Identifying entities + scoring/classification | `./levels/identify.md` | | Attributes: typing, lengths, computed formulas | `./levels/attributes.md` | | Relationships: cardinality, cascade, cross-module FK rule | `./levels/relationships.md` | The three aspects are produced in **one pass** and written to a **single** `entité.md`. The level files are reference heuristics — they do not change the one-file-per-module output. ## Rule-driven facts — the fact lives where it is derived When a business rule needs a FACT (a flag, a date, a threshold input), model the fact on the side that DERIVES or OWNS it — never on the consumer that happens to read it first: - A per-category behaviour (« la catégorie est professionnelle ») is a flag on the REFERENTIAL entity (the category), not a boolean re-declared on every consumer (the permit, the assignment…). One referential row states the fact once; consumers join to it. - An age/seniority rule needs the birth/start date on the PERSON entity. If the socle's person record does not carry it, model the extension field in `entité.md` explicitly — a rule whose input exists nowhere is untestable by construction (the BR ships as dead pseudo-code). The smell to catch before writing: a rule's Expression references a field no entity declares, or the same semantic boolean appears on several consumers of one referential. ## Self-check before writing (data-model → screens gate) Before writing `entité.md`, verify each entity has: - a well-formed `ENT-NNN` code and a PascalCase singular `name`; - a non-empty `Traçabilité` line citing ≥1 verbatim UC/BR of THIS module; - a `tablePrefix` matching `^[a-z]{2,5}_$`, not reserved; - ≥1 attribute; every string attribute a length, every decimal a precision, every enum its values; - every **computed** attribute a non-empty formula referencing only PascalCase properties of the SAME entity (cross-entity formulas forbidden — see `levels/attributes.md`); - every relationship carries a `scope` (same-module / cross-module / core) and a cross-table reference is ALWAYS a FK — see `levels/relationships.md`; the only non-FK `*Id` columns are the identity/audit allowlist; - no name/alias collision with the Core catalogue (C-1 tables above) — the collision scan ran BEFORE proposing, re-verify nothing slipped in; - no binary-content attribute anywhere (`binary`/`blob`/`varbinary`/`byte[]`), and every attachment-semantics entity (C-6) carries the metadata shape (`FileName`, `StoredFileName`, `ContentType`, `FileSizeBytes` + parent FK) — bytes live in `IFileStorageService`, never in the DB; - person mode decided and persisted: the `Personne` line is present for mandatory/optional entities, the `*→1 User — FK UserId, scope core` relation is declared, and (`mandatory`) no local `FirstName`/`LastName`/`Email`/ `DisplayName` attribute remains; - no framework field (`Id` aside, shown for readability only). Surface any gap to the user instead of writing a half-defined model. The deep audit — FK integrity, cycles, orphans, classification conventions, reciprocal traceability — is run by **`/ba-audit-data-model`** (it reads the tree and writes its verdict under the module's `_audit/`); you don't produce audit findings here. ## After writing → MANDATORY post-step, then hand off to screens **Derive the lookup grants (mandatory, right after EVERY successful `entité.md` Write).** The FKs you just authored decide which producer sections the module's create/update actors need as dropdowns — run the create-rbac companion CLI so `rbac.md` follows the data model (machine-owned block, never written by hand): ```bash npx --prefer-offline tsx skills/business-analyse/create-rbac/cli/derive-lookup-grants/index.ts \ --spec '{"baRoot":".smartstack/ba","app":"","module":"","mode":"derive"}' ``` Surface its `needsResolution` findings to the user (a producer section that has no list screen and no matching menu section — complete `screen.md` or the menu, then re-run). `/ba-audit-rbac` RBAC-008 enforces the block's freshness. **Inventory the referential codes (read-only) whenever the module carries a reference table.** A reference value does not carry a code — its label is its identity and its natural key — and only the USER may decide otherwise. The inventory is what lets them decide: per reference table, its classification, whether a code is there, whether a dated `**Code décidé**` authorises it, the key of its `**Valeurs initiales**`, and the VERBATIM citations of its code values across four sources (business rules, acceptance criteria, `prd*.md` / `pagespecs/`, and the other seeded tables): ```bash npx --prefer-offline tsx skills/business-analyse/create-data-model/cli/derive-referential-codes/index.ts \ --spec '{"baRoot":".smartstack/ba","app":"","module":"","mode":"check"}' ``` Show the user the tables that carry a code and what cites it, and let THEM decide table by table. You never author a `- **Code décidé**` line on your own initiative — it transcribes a decision they took, and it carries its date. Only once they have decided may `"mode":"backfill"` run; it rewrites `entité.md` alone, skips every entity carrying a decision, and stops on any entity whose code is cited (reporting it, and continuing with the others). `/ba-audit-data-model` DM-022 enforces the result. The CLI exits 0 even on drift — drift is DATA. Acknowledge in one line ("Modèle de données écrit pour EMPLOYEES : 6 entités."), then propose continuing with screens (`/ba-create-screen`) — the fixed next phase. Convert any descendant `entité.md` placeholders you touch into the one-line rollup pointer. ## Decision table | State | Action | |-------|--------| | No menu tree | Defer: "Define the menu first (`/ba-create-menu`)." | | Module has no use cases AND no rules | Defer: "Define use cases or rules first." | | Context exists, no `entité.md` content | Step 0 → Step 1 → Write | | `entité.md` already complete for the module | Confirm coverage; enrich upstream to extend | | User asks to remove an entity that HAS a trace | Explain its trace; do NOT remove while the UC/BR remains — defer removal to the owning phase | | User asks to remove an entity with NO trace | Re-Write `entité.md` without it (overwrite drops it) | | User asks to add an entity | Grep `use-case.md`/`règles-métier.md` for a verbatim trace; add only if found, else defer to the upstream phase | | User asks to add or modify ONE entity or ONE attribute of a **finished** module (PRD / code exist) | Route to `/ba-change` (kind=entity \| kind=attribute) — it runs that grep for you (every form of the name, accents folded) and BLOCKS without a trace, checks the Core / capability catalogues, allocates the code, and lists the downstream checklist (lookup grants, screens, pagespec delta, EF migration through `/efcore`) | | Informational question | Answer in prose, no Write | ## Absolute prohibitions 1. **Never propose an entity without a `Trace:` line** citing ≥1 verbatim UC/BR of the current module — non-traceable entities are forbidden. 2. **Never source an entity/attribute/relationship from another module** — the trace must come from the SAME `/` scope. Cross-module concepts surface as a `Relations` entry `scope cross-module` (real FK, no navigation). 3. **Never use domain knowledge, best practices, or analogy** to invent an entity, attribute or relationship — they are not sources. 4. **Never model a cross-module or Core reference as a plain `Guid` attribute** — every cross-table reference is a real FK `Relations` entry carrying its scope (`same-module` / `cross-module` / `core`); the ONLY plain-`Guid` `*Id` columns are the identity/audit allowlist (`lib/fk-allowlist.ts`). See `levels/relationships.md`. 5. **Never add framework fields** (`CreatedAt`, `UpdatedAt`, `TenantId`, `DeletedAt`, …). `Id` is shown in the table for readability only. 6. **Never duplicate a SmartStack Core entity — by name OR alias (Core catalogue above)**. Reference a whitelist entity via `Relations … scope core`, extend it via an extension/person entity (FK + net-new fields only), and consume non-whitelist Core data via `ICoreDataService` — never a local table. 7. **Never skip Step 0** — the prose trace audit precedes every Write. 8. **Never write a partial model** — the Write overwrites; re-list every entity that must survive. 9. **Never store file CONTENT in the database** — no `binary`/`blob`/ `varbinary`/`byte[]` attribute, ever. Documents are a client METADATA entity + the platform `IFileStorageService` (capability table above, C-6; `development/backend/data-layer/references/file-storage.md`). Downstream this is fail-closed: PRD-053 errs and `scaffold-entity` throws. ## API opt-out marker — `**API** : none` An entity that must EXIST in the domain (PRD-084 scaffolds every entité.md entity) but deliberately exposes NO endpoint of its own (an aggregate satellite written by a parent's action, a journal, a snapshot) declares it explicitly under its heading: ```markdown ### ENT-012 — HandoverAccessory (inventaire) - **API** : none — écrit par l'action handover du Vehicle, jamais directement. ``` Without the marker, `audit-dev-api DEV-API-024` (Phase 2a gate) errs on any entity whose table exists with no controller on either stratum — the "stockable et ni lisible ni écrivable" class ships silently otherwise. Aliases tolerated: `aucune`, `interne`, `skip`. Junction/component classifications are exempt by nature; lookups/referentials are NOT (they serve `/lookup`). ## Display field — `**Affichage**` (what names a row) The lookup `displayName` — how the entity presents its rows in EVERY column and combobox that references it, and what lookup search matches on. The generator resolves it automatically from the display family (`Name/Label/Code/Title/Libelle/Titre/Reference/Number/Numero`, SSOT `lib/display-field.ts`) or, on a `**Personne**` entity, from the projected identity (`FirstName + " " + LastName`). When NEITHER applies, declare it: ```markdown ### ENT-014 — Assignment (agrégat racine) - **Affichage** : Id — décision client : une affectation se désigne par ses dates, pas par un libellé. ``` Rules: - `**Affichage** : ` — a stored string attribute OR a Core-projected one (`**Personne**` fields). Passed downstream as `displayNameExpr` (`/ba-develop` Phase 2 → `scaffold-business`). - `**Affichage** : Id` is the CONSCIOUS opt-out — GUID label accepted. - Without a resolvable display, `scaffold-business` FAILS CLOSED. The historical silent fallback ("first string column, else GUID") labelled ten entities of one project by a phone number, a free comment or a raw GUID — it always produced *something*, so nothing ever surfaced. - DM-015's arbitration ("no Code/Name/Label — c'est voulu") is exactly the signal: an entity WITHOUT a name-family field is an entity whose display will fall on garbage — when DM-015 concludes the absence is legitimate, the SAME conclusion must author the `**Affichage**` line. ## Reference data — `**Valeurs initiales**` (business-fixed rows) An entity BORN with its rows — the business fixes them, only their paramétrage evolves (nine alert types, six transition reasons). Without a declaration channel the information lives only in use-case prose, which no CLI reads: the incident entity had its pagespecs, controller, service and tests — and an API with no create endpoint, so the table stayed at 0 rows FOREVER (every acceptance criterion green against a feature nobody could exercise). Declare the rows under the entity heading: ```markdown ### ENT-020 — AlertRule (paramétrage) - **Valeurs initiales** : clé `Key` — les 9 types fixés par le métier : | Key | Label | ThresholdDays | Enabled | |-----|-------|---------------|---------| | expertise | Expertise périodique | 30 | true | | vignette | Vignette autoroutière | 15 | true | ``` Rules: - `clé ` names the NATURAL KEY the idempotent seed upserts on — never a `**Code pattern**` Code (allocated by the engine at insert, cannot be pre-assigned); - **on a reference table (`lookup`) the key is the LABEL**, not a code: a reference value's label is its identity (§ "A reference value does not carry a code" in `levels/attributes.md`). A code there exists only when the USER decided it, with a dated `- **Code décidé**` bullet — and then it may serve as the key like any other natural attribute; - **how a label key normalises** — trim, collapse inner whitespace, fold case, fold accents. Two seeds must not diverge on « Fin de commercialisation » vs « Fin de commercialisation ». This is an **authoring discipline, not a runtime behaviour**: `scaffold-seed` emits an EXACT comparison (`AnyAsync(x => x.{key} == "")`), so the literal written in the table IS the canonical form; - **what a label key costs, said plainly** — it BREAKS if someone renames the row: the seed stops finding the line and re-creates it at the next start-up. That is the price of dropping the code, and it belongs in front of the user AT DECISION TIME, not six months later. The full trade-off, table by table with the verbatim citations of each code, comes from `create-data-model/cli/derive-referential-codes` in `"mode":"check"`; - table columns are the entity's attributes (PascalCase); every REQUIRED attribute of the entity must have a column; - downstream: Phase 1 of `/ba-develop` feeds the table VERBATIM to `scaffold-seed` (`referenceData[]` → `{Module}ReferenceDataSeedDataProvider`, per-tenant rows for tenant-scoped entities); - pairs naturally with a list pagespec that declares neither `create` nor `delete` — `audit-dev-api DEV-API-030` errs on an entity with no create endpoint, no seed provider AND no declared feeding action (`rowsCreatedBy` in the pagespec / `**API** : none` here): such an entity is UNPOPULATABLE. ## Derived attributes — `**Dérivé**` (the « colonne dérivée » fil rouge) A READ attribute whose value is not a column of the entity — it lives behind a navigation or inside a dated child. Declare it as DATA instead of letting the generators guess (four client workarounds — the open registration's plate, the latest odometer reading, the open site assignment, the User email — were this one missing notion): ```markdown | PlateNumber | string(12) | — | **Dérivé** : child Registrations pick open(EndDate) select PlateNumber | | CurrentMileage | int | — | **Dérivé** : child OdometerReadings pick latest(ReadingDate) select Mileage | | Email | string(255) | — | **Dérivé** : nav User.Email | ``` Rules: - name the attribute after the VALUE (`officeName`, `plateNumber`), NEVER as a pseudo-FK (`officeId`) — an Id-named ghost column is exactly what DEV-UI-033 flags and what shipped empty on 33 rows; - a derived attribute is always OPTIONAL (its projection yields null when no source row exists) and read-only (never on a form — PRD-123); - distinct from `Calculé` (a formula over the SAME entity's columns — DM-016); - v1 sources: one `nav` hop, or one `child` collection picked by `latest()` / `open()`. Aggregates and multi-hop are the named follow-up `derived-aggregates`. - audited by DM-020: the declaration must resolve (the nav/collection exists in Relations, the selected property exists on the child).