--- name: ba-audit-data-model description: > Audits the conceptual data model (MCD) of a `.smartstack/ba/` module — attributes, FK integrity, cycles, naming, orphans, traceability, indexes, implicit FKs, unreferenced lookups, classification conventions, code-pattern numbering, Core-entity duplication, platform-capability steering, no file content in the MCD, derived declarations, and code-like classification — near-miss Code-pattern declarations + unclassified synonym attributes (Référence/Numéro/Matricule…) — plus, moved LEFT of the readiness GO: index integrity (every **Index** column exists, never TenantId in a unique — the scaffolder's own error, six phases earlier), complete attribute types (string maxLength, decimal precision/scale, enum values), no framework field listed, tenancy declared (**Portée** → tenantMode), and the model retaining what the BA no longer uses — dead columns (attribute grain) and leftover state values (value grain), and the business TEST DATASET `jeu-de-test.md` — present where the module carries business entities, coherent with the MCD, the rules, the actors and the cited modules' datasets, never on a reference table, every Flow status represented (DM-001..032). Reads the module's `entité.md` + `use-case.md` + `règles-métier.md` (+ `jeu-de-test.md`), writes a verdict to `/_audit/entité.md`. Run after `/ba-create-data-model` or as part of pre-dev readiness. allowed-tools: [Read, Write, Glob, Grep, Bash] # Bash: the audit-ba engine (deterministic mechanical rules) --- # ba-audit-data-model — Data Model (MCD) audit You audit the conceptual data model of a `.smartstack/ba/` module against the rules below and write a verdict file. The rules are unchanged from the SmartStack convention; only the I/O is file-based. ## Deterministic engine — how this audit runs The MECHANICAL rules of this dimension are evaluated by the shared `audit-ba` CLI (see `/ba-audit-run`) — **never by reading the corpus yourself, never by spawning per-module subagents** (the 394M-token incident shape). Your only job here is the judgment residue. 1. **Run the engine, scoped to this dimension**: ```bash npx --prefer-offline tsx skills/business-analyse/audit-run/cli/audit-ba/index.ts \ --spec '{"baRoot":".smartstack/ba","scope":{"app":"","module":""},"dimensions":["data-model"]}' ``` 2. **Exit 3 = parsing suspect -> STOP.** A control counter disagrees with the parser (`report.parseControl.perDoc`): fix the doc's form or report the parser bug, then re-run. Never « complete by hand » — no green verdict may be born from a silent parser. 3. **No judgment rules in this dimension** — a single engine run suffices; the verdict is final. 4. **Chat summary** (3-6 lines, business terms): the PARSE TOTALS (say the counts — that is how a « 0 erreur » stays verifiable), err/warn counts, remaining judgments, and the fix skill each finding names. The CLI writes the verdict to `.smartstack/ba///_audit/entité.md` (existing format — anchor, `Verdict :` header, emoji sections; `0 err` = pass for the downstream gate). The rule texts below remain the AUTHORITATIVE spec — the CLI registry is drift-tested against them. ## Scope - **Module scope** (default): the MCD is authoritative at the Module level, so a data-model audit always targets one module. Apply DM-001..023, DM-026, DM-027 to every entity declared in that module's `entité.md`. The verdict file lives at the audited module's `_audit/entité.md`. - If asked to audit an application, run the module-scoped audit once per module under it (one verdict file each); don't merge them into a single report. ## Rules ### DM-001 — At least 1 entity exists per module - **Severity**: err (if 0), ok (if >= 1) - **ok**: the module declares ≥ 1 entity (state the count). - **err**: the module has 0 entities — it cannot expose any data. - Fix: `/ba-create-data-model`. ### DM-002 — All entities have at least 1 attribute - **Severity**: err (if entities without attributes), ok (if all have) - **err**: list the entities whose attribute table is empty. - Fix: `/ba-create-data-model`. ### DM-003 — Attribute types are complete (string maxLength, decimal precision/scale, enum values) - **Severity**: err (if any incomplete type), ok (if all complete) - The whole contract of `create-data-model/levels/attributes.md` § Quality checks — « every string has a length, every decimal precision/scale, every enum non-empty values ». This rule used to implement the string third only. - Check, for each STORED attribute (a `Calculé` member has NO column — `scaffold-entity` drops `formula` fields — and is exempt; it used to err here for nothing): - `string` → a maxLength > 0, in the type (`string(150)`) or the constraints (`maxLength 150`). Without it the column is `nvarchar(max)`. - `decimal` → `decimal(p, s)`. Without it no `.HasPrecision` is emitted and SQL Server falls back to `decimal(18,2)`: a declared `decimal(5,4)` (a rate) silently loses two decimals — the generator's own comment names the loss. - `enum` → at least one VALUE in Contraintes (`A/B/C`), constraint facets (`requis`, `unique`, `readonly`…) not counting as values. - **err**: list the offending `entity.attr : ` items. - Fix: `/ba-create-data-model`. ### DM-004 — Relationship targets exist in the data model - **Severity**: err (if broken FKs), ok (if all valid) - Check: each relationship's target entity code must match an existing entity code in the MCD. - **err**: list the broken references. - Fix: `/ba-create-data-model`. ### DM-005 — No circular relationship chains - **Severity**: warn (if cycles found), ok (if none) - Check: follow the relationship graph A→B→C→…→A. Self-references are OK (skip them). - **warn**: list the entities in each cycle. - Fix: `/ba-create-data-model`. ### DM-006 — Entity names follow PascalCase convention - **Severity**: warn (if violations), ok (if all comply) - Pattern: `/^[A-Z][A-Za-z0-9]*$/` (starts with uppercase, no underscores/hyphens). - **warn**: list the non-conforming entity names. - Fix: `/ba-create-data-model`. ### DM-007 — Attribute names follow camelCase convention - **Severity**: warn (if violations), ok (if all comply) - Pattern: `/^[a-z][A-Za-z0-9]*$/` (starts with lowercase). - **warn**: list the non-conforming attributes. - Fix: `/ba-create-data-model`. ### DM-008 — All entities have a valid table prefix - **Severity**: warn (if missing or invalid), ok (if all valid) - Pattern: `/^[a-z]{2,5}_$/` (2-5 lowercase letters + underscore). - **warn**: list the entities with a missing or invalid prefix. - Fix: `/ba-create-data-model`. ### DM-009 — No unjustified isolated entities (no relationships at all) - **Severity**: warn (if unjustified orphans found), ok (if none) - Check: entity has no outgoing AND no incoming relationships AND classification is neither `lookup` NOR `technical` AND its `entité.md` heading block carries no `Isolation: by-design — ` line with a non-empty reason. - Rationale: most isolated entities are modeling mistakes, but two cases are legitimately standalone and exempt: - classification `lookup` (admin reference table, referenced by `code`/FK) and `technical` (outbox / integration journal / audit log — isolated by nature; NEVER a code allocator, see DM-017 check 5); - any entity carrying an `Isolation: by-design — ` line (reason non-empty) — the override is then captured AND justified in the model, instead of being waved away in chat at audit time. - An entity that is isolated, is neither `lookup`/`technical`, and has the marker but with an EMPTY reason → still **warn** (justify it or link it). - **warn**: list the isolated entity names (note whether the marker is missing or empty). - Fix: `/ba-create-data-model` — link it, reclassify it `technical`, or add an `Isolation: by-design — ` line. ### DM-010 — Every entity referenced by a business rule exists in the MCD - **Severity**: warn (if unknown entities referenced), ok (if all valid) - Symmetric inverse of the legacy BR-005: at audit-rules time the data model is still BLOCKED, so the check has been pulled here where the entity catalogue is authoritative. Direction now: rule → entity ref → MCD lookup. - Check: for each business rule expression, extract PascalCase tokens (skip primitives `DateTime`, `DateOnly`, `TimeOnly`, `String`, `Boolean`). Each remaining token must match an entity code or name in the current MCD. - Skip when no business rules exist in scope (rules phase still EMPTY). - **warn**: list the rule expressions that reference unknown entities. - Fix: `/ba-create-data-model` (or fix the rule via `/ba-create-business-rules`). ### DM-011 — Every entity must be referenced by ≥1 use case, business rule, or resource - **Severity**: warn (if untraced entities found), ok (if all entities traceable) - Reciprocal direction of DM-010: prevents hallucinated entities (entities proposed by `/ba-create-data-model` from "domain knowledge" or web search, with no anchor in the upstream phases). Anti-hallucination guard. - Check: for each entity `e` in the current MCD, scan upstream phases for ≥1 verbatim reference. Tokens to match : `[e.name, e.code]` (NOT `e.tablePrefix` — collisions). Junctions inherit traceability from their relationships: if `e` has relationships whose target entity codes are themselves traced, `e` is traced by inheritance. - Sources to scan, in order : - use case main flow + alternative flow steps + exception flow steps + preconditions + postconditions (PascalCase token match, case-insensitive) - business rule expression (PascalCase tokens, skip primitives — same skip-list as DM-010) - business rule resource code (string equality with `e.code` OR `e.name`) - Resource codes from the menu tree (esp. `SmartListView`) - Dual parsing of the entity **Traçabilité** line : - If it carries structured references (`{ references: [...] }`) — use the array directly. - If it is prose — extract via regex `/(UC|BR|RES)-[A-Z0-9_-]+/g`. - Skip when the module has no use cases, no rules and no resources (upstream phases empty — nothing to match against, default `ok`). - **ok**: state the count of traced entities. - **warn**: list the untraced entity names. - Fix: `/ba-create-data-model`. - **solution** (mandatory on warn): "For each listed entity, either add a verbatim reference in its **Traçabilité** line (e.g. `deduced from UC-XYZ step 3` or structured `{references: ['UC-XYZ', 'BR-NNN']}`), or remove the entity if it has no business justification in the upstream phases." ### DM-012 — A SANCTIONED reference code carries its unique index - **Severity**: warn (if a lookup whose code DM-022 sanctions has no unique index on it), ok (if all lookups conform, no lookups in scope, or DM-022 already errs on them) - A reference table is pointed at by a **Guid FK**, never by its `code` — so this rule is not about referential integrity, it is about the code the USER decided to keep. Where such a code exists, its uniqueness must be enforced at the DB level (a column-level UNIQUE MAY suffice, but composite tenant-scoped uniqueness needs an explicit index entry), otherwise the seed can produce duplicates. - Check: for each entity with classification `lookup` AND an attribute whose name is "code" (case-insensitive): - The entity's index list MUST contain at least one entry whose fields begin with `"code"` AND that is `unique`. - The check accepts `{fields:["code"], unique:true}`, and a composite whose FIRST field is `code`. **Never list `TenantId` in an index**: the tenant discriminator is synthesised from the entity's tenancy — the scaffolder prefixes every declared unique with it, so a declared `(TenantId, Code)` used to emit `new { e.TenantId, e.TenantId, e.Code }` (CS0833, an uncompilable Configuration). DM-023 errs on that shape. - Skip when the entity has no attribute named "code" (a reference table keyed by its label — the default state of the doctrine). - **Skip when DM-022 errs on the entity** — a code with no `**Code décidé**` line, or an allocated one. Proposing `(code) unique` there would recommend HARDENING the very column being removed: two contradictory remedies on one line. Both rules read the same verdict (`lib/ba-referential-codes` `classifyReferentialCode`), so they cannot diverge. - **warn**: list the lookup entities missing the unique index. - Fix: `/ba-create-data-model`. - **solution** (mandatory on warn): "Add `{fields:[\"code\"], unique:true}` to the index list of each listed lookup entity — never `TenantId`, the scaffolder adds the tenant leg itself." ### DM-013 — Every `*Id:guid` attribute is a declared FK relationship (or an allowlisted identity/audit column) - **Severity**: err (if any implicit FK detected), ok (if all FK attributes are relationships) - A cross-table reference is ALWAYS a foreign key — non-negotiable, whatever module the target lives in. This rule rejects the "implicit FK" anti-pattern: an attribute that LOOKS like a foreign key (`*Id:guid`) but is NOT a declared relationship, so EF Core generation would leave it a bare `Guid` with no constraint. (Replaces the old WARN that let a mere description "document" the reference away — documentation is not a constraint.) - Check: for each entity, for each attribute where dataType is `guid` AND name ends with `"Id"` AND name is not `"id"`: - PASS if the entity's relationships contain a relationship whose foreign-key name (case-insensitive) matches the PascalCase form of the attribute name (e.g., `clientId` → `ClientId`), OR whose name matches the attribute name without the trailing `Id` (e.g., `clientId` ↔ `client`). The relationship's `scope` (`same-module` / `cross-module` / `core`) records HOW the FK is realized — but a relationship is REQUIRED regardless of scope. - PASS if the attribute is an identity/audit allowlist column (intentionally NOT a FK — `lib/fk-allowlist.ts`): `CreatedByUserId`, `UpdatedByUserId`, `ModifiedByUserId`, `DeletedByUserId`, `ChangedByUserId`, `ApprovedByUserId`, `AssignedToUserId`, `UserId`. **`TenantId` is NOT allowlisted** — but it is realized as a FK automatically from the entity's tenant mode, so it PASSES too. - Otherwise **err** — flag the `entity.attr` pair (a cross-table reference with no FK relationship). - Skip when the attribute is the implicit primary key (name is `"id"`). - **err**: list the offending `entity.attr` pairs. - Fix: `/ba-create-data-model`. - **solution** (mandatory on err): "For each listed `entity.attr`, add a `Relations` entry whose foreign-key name matches the attribute, with the right cardinality, cascade and `scope` (`same-module` / `cross-module` / `core` — for `core` name the physical table, e.g. `tenant_Tenants`). A documented description is NOT enough: every cross-table reference needs a real FK. Only the identity/audit allowlist may remain a plain `Guid`." ### DM-014 — Lookup entities are referenced by ≥1 other entity - **Severity**: warn (if unreferenced lookup found), ok (if all lookups referenced) - Reciprocal of DM-009 specifically for lookups. A lookup that no other entity references — neither via a relationship nor via an `*Id:guid` attribute — is dead code: no UC will ever read or write it. Distinct from DM-009 (which fires on isolated NON-lookup entities) and DM-011 (which flags hallucinated entities lacking an upstream UC/BR/RES anchor). - Check: for each entity `L` with classification `lookup`: - Count incoming declared relationships : every entity `e` in the MCD such that one of `e`'s relationships targets `L.code` or `L.name`. - Count plain-guid FK attributes that look like FK to `L` : every entity `e` with an attribute `a` where `a` is `guid` AND its name is `${camelCase(L.name)}Id` (e.g., `BudgetType` → `budgetTypeId`). - If BOTH counts are 0 → WARN. List `L.name` (and `L.code`). - Skip when the module has no lookup entities. - **warn**: list the unreferenced lookup names. - Fix: `/ba-create-data-model`. - **solution** (mandatory on warn): "For each listed lookup, either declare a relationship from the entity that needs it (parent → lookup, N:1, cascade `restrict`), add a `${camelCase(name)}Id:guid` attribute on that entity, or remove the lookup via `/ba-create-data-model` if no entity needs it." ### DM-015 — Classification-based attribute conventions - **Severity**: warn (if conventions violated), ok (if all entities conform) - Each classification has a conventional minimum attribute set that downstream generation (Domain entity, EF Core mapping, seed data, list/form UI) expects. Missing fields don't block development but produce thin scaffolds that won't render correctly in the generated app. - Check by classification: - **lookup** : SHOULD declare `label:string` (OR `name:string`), `isActive:bool`. `sortOrder:int` is recommended (controls display order). **No `code`** — a reference value's label IS its identity and its natural key. Whether such a table carries a code at all is a USER decision, judged by **DM-022**, never prescribed here: this rule states a MISSING field, it never judges a presence. (Until 2026-09 this convention REQUIRED a unique `code` attribute and the mandatory `solution` below re-asked for it — three lines of skill that produced 11 `Code` columns on a single module. Do not restore it.) - **technical** : infrastructure — outbox, integration journal, audit-only log. **EXEMPT** from the lookup `label/isActive/sortOrder` set; SHOULD carry the `Isolation: by-design — ` line (DM-009 exemption). A code **allocator is never one of these**: a counter/sequence entity (`nextValue`, `lastValue`, a `{tenantId, year}` key) duplicates the socle's engine — DM-017 check 5 errors on it. - **component** : SHOULD have ≥1 FK linking it to a parent entity — either a relationship (any cardinality) OR a `*Id:guid` attribute pairable with DM-013. A component with neither is a misclassified lightweight-module candidate. - **lightweight-module** / **full-module** : SHOULD have a business identifier — a `name:string` / `label:string` attribute (the DEFAULT), OR a `code:string` attribute ONLY when the entity passes the code-worthiness decision test (`create-data-model` levels/attributes.md § "When an entity deserves a code" — referenced outside the UI), with a declared `codePattern` only for system-ALLOCATED codes. The list UI uses this as the row title. Never prescribe a `code` merely because a convention lists it — a superfluous allocated code is what DM-017 check 1 flags. - Skip entities already flagged by DM-002 (no attributes at all — fix that first, the convention check is meaningless on empty entities). - For each violation, list `entity.code:missing-fields` (e.g., `BudgetType:label,isActive`). - **warn**: list the entities with their missing convention fields. - **Display corollary (the §26 predictor)** — when the arbitration concludes the absence of `code`/`name`/`label` is LEGITIMATE ("c'est voulu — identité projetée / désignée par ses dates"), the SAME conclusion must be persisted: the entity either carries a `**Personne**` line (projected identity resolves the display automatically) or an explicit `**Affichage** : ` line (`: Id` = conscious GUID opt-out). An entity without a name-family field AND without either line is a **warn**: its `displayName` has nothing sanctioned to fall on, and `scaffold-business` now fails closed on it (no more silent first-string/GUID fallback — the phone-number-as-label incident). - Fix: `/ba-create-data-model`. - **solution** (mandatory on warn): "Add the missing convention fields per classification. Lookups : `label:string(150)`, `isActive:bool` (default true), `sortOrder:int` — NEVER a `code`: the label names the row, and a code on a reference table is a dated user decision (DM-022). Components : declare the FK to the parent (preferred) or convert to lightweight-module. Modules : add a `name` attribute as the business identifier ; a `code` ONLY when the entity passes the code-worthiness test (referenced outside the UI — phone/email, outbound document, legal numbering, long-lived case), with `codePattern` only when system-allocated. Entities legitimately without a name-family field : author `**Affichage** : ` (or `: Id`) so the display decision is data, not luck." ### DM-016 — Computed attributes (`formula`) reference only same-entity properties - **Severity**: err (if any formula references a foreign attribute), ok (if all conform or no formulas in scope) - Computed attributes are translated downstream into a LINQ projection (`scaffold-repository`) running inside a single SQL query. Cross-entity formulas would require a JOIN that EF Core can't infer from the MCD alone and produce broken SQL at runtime — the `dev` cascade can't recover. - Check: for each attribute `a` with a non-empty **Calculé** formula: - Tokenize the formula and extract every PascalCase identifier (regex `/\b[A-Z][A-Za-z0-9]*\b/g`), skipping C# primitives (`Math`, `Convert`, `String`, `DateTime`, `DateOnly`, `TimeOnly`, `Boolean`, `Int32`, `Decimal`, `Guid`). - Each remaining token MUST match (case-insensitive) the PascalCase form of one of the SAME entity's attributes capitalised — `currentBalance` → `CurrentBalance`. - Otherwise ERR — list `entity.attr→missing-token`. - Also flag formulas exceeding 1000 characters (defensive: matches the DB column constraint). - Skip attributes without a formula. - **ok**: state the number of formulas verified. - **err**: list each `entity.attr→token` whose formula crosses entities. - Fix: `/ba-create-data-model`. - **solution** (mandatory on err): "Cross-entity formulas are not supported. Either rewrite the formula using only attributes of the SAME entity (denormalize the foreign value into a local attribute updated by a business rule), or move the computation to the backend service layer (out of the MCD) and remove the formula from the attribute." ### DM-017 — Code patterns are engine-compatible, ruled, and never re-implemented - **Severity**: err (unknown token / missing `{SEQ}` / re-modelled allocator), warn (incomplete or unmatched spec), ok (if all coherent or none) - A `codePattern` is the data-model side of a `numbering` business rule. Without a matching rule the generated numbering has no spec (format / scope / reset / gapless) to follow; an inconsistent scope silently collides across tenants. And the format is not free text: the socle's code engine parses it with a CLOSED grammar and throws on every insert if a token is unknown. - **Check**, for each entity carrying a `codePattern` (checks 1-4), then module-wide (checks 5-6): 1. A `numbering` business rule for this entity exists — Grep the module's `règles-métier.md` for a `Type: numbering` rule naming the entity, OR a `BR-…` ref in the entity's **Traçabilité**. Missing → warn. The remedy is BIDIRECTIONAL: EITHER the entity passes the code-worthiness decision test (`create-data-model` levels/attributes.md § "When an entity deserves a code") → author the `numbering` rule; OR it does not → REMOVE the `**Code pattern**` line (and the `code` attribute unless a user-typed code is wanted) — a superfluous allocated code is a modelling error, not a missing rule. 2. The pattern's **scope** is `tenant` or `global` (the whole `CodeScopeKind` enum — `parent:` does not exist) and is consistent with `tenantMode`: a `tenant`-scoped pattern requires `tenantMode` ≠ `none`; a `global` pattern on `strict` tenant data must be explicitly intended. Unsupported scope → err; mismatch → warn. 3. Every `{…}` group of the **format** is a known token — `{YYYY}` `{YY}` `{MM}` `{DD}` `{TENANT}` `{SEQ:n}` or a derived `{FIELD|UPPER|LOWER|SLUG|INITIALS:Champ}` / `{ABBR:Champ:n}` — and `{SEQ}`/`{SEQ:n}` is present unless ≥1 derived token is. An invented token (`{NNNN}`, `{YEAR}`, `{SEQUENCE}`) or a sequence-less, field-less format → **err**: the engine raises `InvalidCodePatternException` at the first create, so the feature ships broken. 4. The **reset** period aligns with a date token in the format (yearly ⇒ `{YY}` / `{YYYY}`, monthly ⇒ + `{MM}`, daily ⇒ + `{DD}`). Misaligned → warn (the engine rejects it at runtime too). 5. **No allocator is re-modelled — MODULE-WIDE, whether or not any `codePattern` is declared.** Scan EVERY entity of the module (not just the coded ones — a counter entity modelled WITHOUT any declared pattern is the pure hand-rolled-generator shape, and used to pass this rule via the skip): an entity whose name ends in `Sequence` / `Séquence` / `Compteur` / `Counter` / `Numerotation`, or carrying a `nextValue`-like attribute. The socle allocates gaplessly at insert on `core.seq_Sequences` and surfaces the key in Administration → Configuration → Code patterns. Present → **err** (this is the duplication DM-019 / C-6 name the `code-generation` capability for). 6. **Every `numbering` rule lands on a coded entity — MODULE-WIDE.** For each `Type: numbering` rule of the module's `règles-métier.md`, resolve the entity it targets (whole-token match of the Condition / title / Portée against the module's entities). Resolved entity WITHOUT a `**Code pattern**` line → **err** `rule:no-code-pattern`: the rule is INVISIBLE to the entire downstream chain (`ruleExemption` marks it `type-numbering` presuming the codePattern channel exists, DEV-API-022 never arms, no scaffold spec is emitted — the dev agent improvises an allocator). Unresolvable rule → warn `rule:unmappable`. 7. **Supplied + `{SEQ}` = the deferred-collision corridor — warn.** A pattern declaring `surchargeable à la création` on a SEQUENTIAL format: the engine's sequential allocator never consults the uniqueness probe before allocating, so a manually supplied code inside the sequence's FUTURE corridor only fails LATER, as a unique-index violation, when the sequence reaches it. The import/reprise case is legitimate (the index stays the last-resort net, as at the socle) — the remedy is SHAPE separation, never a ban: keep supplied codes out of the mask's shape (different prefix), reserve them to imports/reprises, or use a derived (no-`{SEQ}`) format. - Skip checks 1-4 when the module has no entity with a code pattern; checks 5 and 6 ALWAYS run (their signal is precisely the module where nothing declares one). - **err**: list `entity:unknown-token:{TOKEN}` / `entity:no-seq-token` / `entity:unsupported-scope` / `allocator:remodelled` / `rule:no-code-pattern`. - **warn**: list `entity:missing-numbering-rule` / `entity:scope-mismatch` / `entity:reset-misaligned` / `rule:unmappable` / `entity:supplied-sequential-corridor`. - Fix: `/ba-create-data-model` (or add the rule via `/ba-create-business-rules`). - **solution** (mandatory on err/warn): "Rewrite the format with the socle tokens only (`{SEQ:n}` required, plus `{YY}`/`{YYYY}`/`{MM}`/`{DD}`/`{TENANT}` and the `{ABBR:Champ:n}` family) — never invent one; use scope `tenant` or `global` only; DELETE any counter/sequence entity modelled for this pattern (the socle allocates — declaring the `**Code pattern**` is the whole job). A `numbering` rule without its `**Code pattern**` line: EITHER the entity passes the code-worthiness test → declare the `**Code pattern**` on the entity (the ONLY channel the dev chain reads — never implement the rule in code); OR it does not → delete the rule. A `**Code pattern**` without its rule: author the `numbering` rule (format + scope + reset + gapless) in `règles-métier.md` and reference it in the entity **Traçabilité** — or remove the unjustified pattern." - Scope note: this rule only audits `**Code pattern**` lines that PARSE. A Code pattern MENTIONED in an unparsable shape (table cell, wrong casing) is **DM-021**'s near-miss check — a different axis (is every code-like signal classified?), not a 7th check here. ### DM-018 — No entity duplicates a SmartStack Core entity (catalogue collision + person/company linkage) - **Severity**: err (duplication / redeclaration / unlinked person cluster on a triggered entity), warn (untraced `none` override, unlinked company cluster), ok - Core ships inside the SmartStack NuGet (schema `core`) — it is invisible to any code scan, so this rule checks the MCD against the static Core catalogue below (drift-tested against `lib/core-catalog.ts`). Match = whole-token, accent/case/plural-insensitive comparison of the entity name against each catalogue name + alias (never substring — `UserStory` is not a hit). | 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 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) | - Check (a) — **whitelist collision**: an entity whose name/alias matches a Core catalogue entry → **err**. The Core table pre-exists and may be pre-populated (`core.tenant_TenantOrganisations` is the shared organisation directory) — recreating it forks the data with no way to reconcile. e.g. "Organisation" / "Société" duplicates Core **TenantOrganisation**. - Check (b) — **reserved collision**: name/alias matches the reserved (service-only) table → **err**: the concept is a Core platform feature; it is not FK-able and must not be a client table. - Check (c) — **unlinked person cluster (fail-closed)**: the entity is person-triggered — its name matches a `PERSON_TRIGGERS` word (lib/core-catalog.ts, mirrored in create-data-model's person-triggers:v1 block) OR its attribute table contains ≥2 of `email`, `firstName`, `lastName`, `displayName` (case-insensitive) — AND it has NO `- **Personne**` line AND no Relations entry `*→1 User — FK UserId, scope core` → **err** (a person directory fully decorrelated from `auth_Users` must be a DELIBERATE choice, never a silence — the annuaire incident). Gradations: an explicit `- **Personne** : none — décision client : ` line = **ok** (the sanctioned override, traced); a bare `none` WITHOUT the client reason = **warn** (decision recorded but not traced). NOTE: DM-013 allowlists a bare `userId` attribute, so this case passes DM-013 silently — DM-018 catches it regardless. - Check (d) — **mandatory person redeclares identity**: the `Personne` line says `mandatory` but the attribute table still declares `firstName`/`lastName`/ `email`/`displayName` → **err** (identity comes from `auth_Users`; local copies drift and violate the zero-duplication contract). - Check (e) — **company-identity cluster**: an entity not flagged by (a) whose attributes include ≥1 of `uid`, `ide`, `siret`, `siren`, `legalForm`, `companyName`, `raisonSociale`, `vatNumber` AND no Relations entry `*→1 TenantOrganisation — scope core` → **warn**: the concept overlaps Core **TenantOrganisation** (`core.tenant_TenantOrganisations`, the shared org directory) — reference it and keep only net-new fields. - **err**/**warn**: list each `entity → core-entity (qualified table)` / `entity:cluster` pair. - Fix: `/ba-create-data-model`. - **solution** (mandatory on err/warn): "(a)/(b) remove the entity; reference the Core entity via a `Relations … scope core` FK (whitelist) or the named service (reserved), or rename + reduce it to an extension entity carrying the FK + net-new fields only. (c) decide the person mode: add the `- **Personne** : mandatory|optional — identité via auth_Users (…)` line + the `*→1 User — FK UserId, scope core` relation (mandatory ⇒ delete the local identity attributes) — or, when the client DELIBERATELY wants the directory decorrelated from the accounts, the explicit override `- **Personne** : none — décision client : `. (d) delete the redeclared identity attributes — the `Personne` field list already names them. (e) add `*→1 TenantOrganisation — FK OrganisationId, scope core (tenant_TenantOrganisations)` and remove any attribute that mirrors the registry data." ### DM-019 — No file content in the MCD; attachment entities follow the metadata pattern - **Severity**: err (binary-content attribute), warn (attachment entity without the metadata shape), ok - The platform ships transverse CAPABILITIES as services inside the NuGet — invisible to any code scan and carrying no entity name DM-018 could match. This rule checks the MCD against the static capability catalogue below (drift-tested against `lib/capability-catalog.ts`). Trigger match = whole-token OR trailing-word of a compound name (`InteractionDocuments` → `Documents` = hit; `Documentation` = single word, never 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. | — | - **Which rule arms each row** (the table is shared; checking is not): the file-storage row → checks (a)/(b) below; the **code-generation row → DM-017 checks 5+6** (re-modelled allocator err, numbering rule without its `**Code pattern**` err); global-search / time-entry-refs / email-sending → CODE-006 (`/ba-audit-cross-ref-code`, always-on catalogue match). No row is decorative — a trigger hit lands in exactly one rule's verdict. - Check (a) — **binary content**: ANY entity (attachment-flavored or not) whose attribute table declares a type or name in the file-storage ATTRIBUTE triggers (`binary`, `blob`, `varbinary`, `byte[]`, `image` as a TYPE, `filestream`, `fileContent`, …) → **err**. File content is never a column — the bytes belong to `IFileStorageService` (downstream: PRD-053 errs, `scaffold-entity` throws on these types). - Check (b) — **attachment entity without the metadata shape**: an entity whose name (whole-token or trailing-word) matches a file-storage ENTITY trigger but lacks the metadata trio (`StoredFileName`-like opaque key, `ContentType`, a size attribute) or a parent FK → **warn**: it is an attachment entity in name only; align it with the canonical shape (`FileName` string/256, `StoredFileName` string/500 unique, `ContentType` string/100, `FileSizeBytes` long + parent FK relation). - The METADATA entity itself is **LEGITIMATE** — this rule steers its shape, it never asks to remove it (contrast DM-018, where a Core duplicate is deleted). - **err**/**warn**: list each `entity.attribute → trigger` / `entity → missing shape element` pair. - Fix: `/ba-create-data-model`. - **solution** (mandatory on err/warn): "(a) replace the binary attribute with the metadata trio; the bytes go through `IFileStorageService` (pattern: `development/backend/data-layer/references/file-storage.md`). (b) complete the metadata shape + parent FK." ## Output Write `_audit/entité.md` per the doc-templates skeleton: - Header `# Audit entité — / ` + `_ · Verdict : N warn · M err · K ok_`. - `## ✅ Conforme`, `## ⚠️ Avertissements`, `## ❌ Bloquants` sections; one bullet per finding. For `warn`/`err`: what's wrong (offending codes / `entity.attr` **bold**), why it matters, and a `→` fix naming `/ba-create-data-model`. When a rule defines a **solution**, fold it into the fix bullet. - The rule codes (`DM-001`, …) stay **bold** so they remain greppable, but they are explained in business terms (no i18n label codes). - Re-Write the whole file each run (overwrite — it's a fresh verdict). Then a 3–6 line chat summary in the user's language — business terms, not rule codes. If any `err`, state clearly that the data model must be fixed before moving on. ## Used by the readiness orchestrator `/ba-audit-pre-dev` runs every dimension and aggregates the verdicts. When invoked by it, still write `_audit/entité.md` as usual — the orchestrator reads these files. ### DM-020 — A `**Dérivé**` declaration resolves - **Severity**: err, ok otherwise. - Check, for every attribute carrying the `**Dérivé**` marker: - `nav