@atlashub/smartstack-cli 3.4.1 → 3.6.0

package/templates/skills/business-analyse/steps/step-03c-compile.md

@@ -0,0 +1,343 @@
+---
+name: step-03c-compile
+description: Module specification compilation - actors, use cases, FRs, permissions, navigation, seed data, Gherkin, i18n
+model: opus
+next_step: steps/step-03d-validate.md
+---
+
+> **Context files:** `_shared.md` | `_module-loop.md`
+
+# Step 3c: Specification Compilation
+
+## MANDATORY EXECUTION RULES
+
+- ALWAYS use ULTRATHINK mode
+- This step COMPILES the specification from the interactive phase (step-03a) into feature.json
+- ALWAYS validate specification completeness before writing
+- ALL communication in `{language}`
+- NEVER skip per-module validation
+- **ID NAMING RULE (MANDATORY, NO EXCEPTION):**
+  All IDs MUST include a module prefix to guarantee application-wide uniqueness.
+  The prefix is derived from the module code initials (2-4 chars):
+    UserManagement → UM | VehicleManagement → VM | PartsInventory → PI
+    RepairManagement → RM | MaintenanceSchedule → MS | DataSync → DS
+    Notifications → NT | Dashboard → DB | Orders → OR | Customers → CU
+
+  Patterns:
+    UC-{PREFIX}-{NNN}        → UC-RM-001, UC-PI-003
+    BR-{CAT}-{PREFIX}-{NNN}  → BR-VAL-RM-001, BR-CALC-PI-002
+    FR-{PREFIX}-{NNN}        → FR-RM-001
+    OBJ-{PREFIX}-{NNN}       → OBJ-RM-001
+    AC-{PREFIX}-{NNN}        → AC-RM-001
+    RISK-{PREFIX}-{NNN}      → RISK-RM-001
+
+  NEVER use bare IDs (UC-001, BR-VAL-001) in multi-module mode.
+- **SCHEMA CONFORMITY RULE:**
+  ALL data MUST fit within the defined feature-schema.json structure.
+  NEVER create custom top-level fields (KPIDefinitions, ChartConfigurations, etc.)
+  Dashboard modules MUST use specification.dashboards[] (it exists in the schema).
+  If truly needed, use specification.extensions: {} (additionalProperties: true).
+
+## YOUR TASK
+
+Compile all data collected in step-03a (data) and step-03b (UI) into the module specification: generate actors, use cases, functional requirements, permission matrix, navigation, seed data, Gherkin scenarios, validations, messages, lifecycle, API endpoints, and i18n keys.
+
+---
+
+### 8. Full Specification
+
+Generate the complete specification for this module. **Each subsection below includes a STRUCTURE CARD showing the EXACT JSON format. Follow them precisely.**
+
+#### 8a. Actors
+
+Inherited from application roles → mapped to module permissions.
+
+> **STRUCTURE CARD: specification.actors[]**
+> ```json
+> {
+>   "role": "Sales Manager",
+>   "description": "Creates and approves orders",
+>   "permissions": [
+>     "business.{app}.{module}.read",
+>     "business.{app}.{module}.create",
+>     "business.{app}.{module}.update"
+>   ]
+> }
+> ```
+> **MANDATORY fields:** `role`, `permissions` (array of permission paths)
+> **FORBIDDEN fields:** Do NOT use `systemRole`. Use `permissions` array.
+
+#### 8b. Use Cases (UC-{PREFIX}-NNN)
+
+Per section: list, create, read, update, delete, approve, etc.
+
+> **STRUCTURE CARD: specification.useCases[]**
+> ```json
+> {
+>   "id": "UC-{PREFIX}-001",
+>   "name": "Create Order",
+>   "primaryActor": "Sales Representative",
+>   "permission": "business.{app}.{module}.create",
+>   "preconditions": ["Customer exists", "Products in stock"],
+>   "postconditions": ["Order created with Draft status"],
+>   "mainScenario": [
+>     "1. User navigates to creation form",
+>     "2. User fills in required fields",
+>     "3. System validates data (BR-VAL-{PREFIX}-001)",
+>     "4. System creates the record",
+>     "5. System displays confirmation"
+>   ],
+>   "alternativeScenarios": [
+>     { "name": "Validation failure", "steps": ["1. System detects invalid data", "2. System highlights errors"] }
+>   ],
+>   "errorScenarios": [
+>     { "name": "Server error", "steps": ["1. System shows error message", "2. Data preserved for retry"] }
+>   ],
+>   "linkedRules": ["BR-VAL-{PREFIX}-001", "BR-WF-{PREFIX}-002"]
+> }
+> ```
+> **MANDATORY fields:** `id`, `name`, `primaryActor`, `permission`, `mainScenario`, `linkedRules`
+> **FORBIDDEN fields:** Do NOT use `actor` (use `primaryActor`), `linkedBRs` (use `linkedRules`), `linkedFRs` (not in UC, FRs link to UCs instead)
+
+#### 8c. Functional Requirements (FR-{PREFIX}-NNN)
+
+Linked to BRs and UCs.
+
+> **STRUCTURE CARD: specification.functionalRequirements[]**
+> ```json
+> {
+>   "id": "FR-{PREFIX}-001",
+>   "statement": "System MUST validate customer budget before order creation",
+>   "priority": "must|should|could",
+>   "linkedRules": ["BR-VAL-{PREFIX}-001"],
+>   "linkedUseCases": ["UC-{PREFIX}-001"],
+>   "acceptanceCriteria": [
+>     "Order rejected if total > budget",
+>     "Error message displayed with remaining budget"
+>   ]
+> }
+> ```
+> **MANDATORY fields:** `id`, `statement`, `priority`, `linkedUseCases`
+> **FORBIDDEN fields:** Do NOT use `name`/`description` (use `statement` with System MUST/SHOULD/COULD format), `linkedUCs` (use `linkedUseCases`), `linkedBRs` (use `linkedRules`)
+
+#### 8d. Permission Matrix
+
+Roles × resources × operations with full paths.
+
+> **STRUCTURE CARD: specification.permissionMatrix**
+> ```json
+> {
+>   "permissions": [
+>     { "path": "business.{app}.{module}.read", "action": "read", "description": "View records" },
+>     { "path": "business.{app}.{module}.create", "action": "create", "description": "Create new records" },
+>     { "path": "business.{app}.{module}.update", "action": "update", "description": "Update existing records" },
+>     { "path": "business.{app}.{module}.delete", "action": "delete", "description": "Delete records" },
+>     { "path": "business.{app}.{module}.export", "action": "export", "description": "Export data" }
+>   ],
+>   "roleAssignments": [
+>     { "role": "{App} Admin", "permissions": ["business.{app}.{module}.read", "business.{app}.{module}.create", "business.{app}.{module}.update", "business.{app}.{module}.delete", "business.{app}.{module}.export"] },
+>     { "role": "{App} Manager", "permissions": ["business.{app}.{module}.read", "business.{app}.{module}.create", "business.{app}.{module}.update"] },
+>     { "role": "{App} Viewer", "permissions": ["business.{app}.{module}.read"] }
+>   ]
+> }
+> ```
+> **STRUCTURE:** Object with 2 arrays: `permissions[]` and `roleAssignments[]`
+> **FORBIDDEN:** Do NOT use a flat array with `resource`/`roles` fields. Always use the nested structure above.
+
+#### 8e. Navigation
+
+Module → Sections → Resources (levels 3-4-5 of the hierarchy).
+
+> **STRUCTURE CARD: specification.navigation**
+> ```json
+> {
+>   "entries": [
+>     { "level": "module", "code": "{module}", "labels": {"fr": "...", "en": "..."}, "route": "/business/{app}/{module}", "icon": "list" },
+>     { "level": "section", "code": "list", "labels": {"fr": "Liste", "en": "List", "it": "Elenco", "de": "Liste"}, "route": "/business/{app}/{module}/list", "icon": "list" },
+>     { "level": "section", "code": "dashboard", "labels": {"fr": "Dashboard", "en": "Dashboard"}, "route": "/business/{app}/{module}/dashboard", "icon": "chart-bar", "isNew": true }
+>   ]
+> }
+> ```
+
+#### 8f. SeedData Core
+
+5 MANDATORY typed arrays — each with structured objects, NOT flat strings or objects.
+
+> **STRUCTURE CARD: specification.seedDataCore**
+> ```json
+> {
+>   "navigationModules": [
+>     { "code": "{module}", "label": "{Module Name}", "icon": "list", "route": "/business/{app}/{module}", "parentCode": "{app}", "sort": 1 }
+>   ],
+>   "navigationTranslations": [
+>     { "moduleCode": "{module}", "language": "fr", "label": "..." },
+>     { "moduleCode": "{module}", "language": "en", "label": "..." },
+>     { "moduleCode": "{module}", "language": "it", "label": "..." },
+>     { "moduleCode": "{module}", "language": "de", "label": "..." }
+>   ],
+>   "permissions": [
+>     { "path": "business.{app}.{module}.read", "action": "read", "description": "View {module}" },
+>     { "path": "business.{app}.{module}.create", "action": "create", "description": "Create {module}" }
+>   ],
+>   "rolePermissions": [
+>     { "role": "{App} Admin", "permissionPath": "business.{app}.{module}.*" },
+>     { "role": "{App} Manager", "permissionPath": "business.{app}.{module}.read" }
+>   ],
+>   "permissionConstants": [
+>     { "constantName": "{Module}Read", "path": "business.{app}.{module}.read" },
+>     { "constantName": "{Module}Create", "path": "business.{app}.{module}.create" }
+>   ]
+> }
+> ```
+> **MANDATORY:** All 5 arrays must be present. Each element must be an object, NOT a string.
+> **FORBIDDEN:** Do NOT use `navigationModule` (singular string), `permissions` as flat string array, `rolePermissions` as flat object, `permissionsConstants` as comma-separated string.
+
+#### 8g. Gherkin Scenarios
+
+BDD acceptance tests per UC.
+
+> **STRUCTURE CARD: specification.gherkinScenarios[]**
+> ```json
+> {
+>   "feature": "{Module} Management",
+>   "scenarios": [
+>     {
+>       "name": "Create a new record with valid data",
+>       "tags": ["@{module}", "@create", "@smoke"],
+>       "given": ["An authenticated user with role Manager", "No existing record with code 'TEST-001'"],
+>       "when": ["The user fills the creation form", "The user submits the form"],
+>       "then": ["The record is created with Draft status", "A success message is displayed"]
+>     }
+>   ]
+> }
+> ```
+> **STRUCTURE:** Object with `feature` string + `scenarios[]` array. Each scenario has `given`, `when`, `then` as ARRAYS of strings.
+> **FORBIDDEN:** Do NOT use flat arrays of `{uc, scenario, given, when, then}` where given/when/then are single strings.
+
+#### 8h. Validations
+
+Field validation rules per entity.
+
+> **STRUCTURE CARD: specification.validations[]**
+> ```json
+> {
+>   "entity": "Order",
+>   "field": "amount",
+>   "rules": ["required", "decimal", "min:0.01", "max:999999.99"],
+>   "errorMessageKey": "validation.{module}.amount.invalid"
+> }
+> ```
+> **MANDATORY fields:** `entity`, `field`, `rules` (array), `errorMessageKey`
+> **FORBIDDEN fields:** Do NOT use `rule` (singular string) or `message` (use `errorMessageKey`).
+
+#### 8i. Business Messages
+
+Minimum 4: success, error CRUD, error validation, error permission.
+
+> **STRUCTURE CARD: specification.messages[]**
+> ```json
+> {
+>   "code": "{MODULE}-SUCCESS-CREATE",
+>   "type": "success|error|warning|info",
+>   "title": "Record Created",
+>   "message": "The record {code} has been created successfully.",
+>   "i18nKey": "message.{module}.created"
+> }
+> ```
+> **MANDATORY fields:** `code`, `type`, `message`, `i18nKey`
+> **FORBIDDEN:** Do NOT omit `title` or `i18nKey`. Every message MUST have an i18n key.
+
+#### 8j. Entity Lifecycle
+
+State machines for entities with status/state.
+**Note:** If depth = full and 3a-state was executed, lifeCycles are already defined. Verify completeness and add any missing states/transitions.
+
+> **STRUCTURE CARD: specification.lifeCycles[]**
+> ```json
+> {
+>   "entity": "Order",
+>   "field": "status",
+>   "initialState": "draft",
+>   "states": [
+>     { "id": "draft", "displayName": "Brouillon", "color": "gray", "allowedTransitions": ["submitted"], "isTerminal": false },
+>     { "id": "submitted", "displayName": "Soumis", "color": "blue", "allowedTransitions": ["approved", "rejected"], "isTerminal": false },
+>     { "id": "approved", "displayName": "Approuvé", "color": "green", "allowedTransitions": ["archived"], "isTerminal": false },
+>     { "id": "rejected", "displayName": "Rejeté", "color": "red", "allowedTransitions": [], "isTerminal": true },
+>     { "id": "archived", "displayName": "Archivé", "color": "purple", "allowedTransitions": [], "isTerminal": true }
+>   ],
+>   "transitions": [
+>     {
+>       "from": "draft", "to": "submitted", "action": "submit",
+>       "label": { "fr": "Soumettre", "en": "Submit" },
+>       "permission": "business.{app}.{module}.update",
+>       "guards": ["BR-VAL-{PREFIX}-001"],
+>       "effects": [{ "type": "notification", "target": "role:manager", "template": "{module}-submitted" }],
+>       "confirm": true
+>     }
+>   ]
+> }
+> ```
+> **MANDATORY:** `states` MUST be an array of OBJECTS with `id`, `displayName`, `color`, `allowedTransitions`, `isTerminal`. NEVER use flat string arrays.
+> **Colors:** gray (draft/new), blue (in-progress), green (active/approved), yellow (warning/pending), orange (review), red (error/rejected), purple (archived/terminal)
+> **FORBIDDEN:** Do NOT use `states: ["Active", "Inactive"]` (flat strings), `terminalStates` (use `isTerminal: true` on each state).
+
+#### 8k. API Endpoints
+
+RESTful routes following SmartStack patterns.
+
+> **STRUCTURE CARD: specification.apiEndpoints[]**
+> ```json
+> {
+>   "method": "GET|POST|PUT|PATCH|DELETE",
+>   "path": "/api/business/{app}/{module}",
+>   "permission": "business.{app}.{module}.read",
+>   "requestDto": "Get{Module}Query",
+>   "responseDto": "{Module}Dto[]",
+>   "description": "List all records with pagination and filters"
+> }
+> ```
+> **MANDATORY fields:** `method`, `path`, `permission`, `description`
+> **Recommended:** Include `requestDto` and `responseDto` for implementation clarity.
+
+#### 8l. i18n Keys
+
+Translation keys for all UI text (4 languages: fr, en, it, de).
+
+> **STRUCTURE CARD: specification.i18nKeys**
+> ```json
+> {
+>   "title": { "fr": "{Module}", "en": "{Module}", "it": "{Module}", "de": "{Module}" },
+>   "list": { "title": { "fr": "Liste", "en": "List" }, "empty": { "fr": "Aucun enregistrement", "en": "No records" } },
+>   "create": { "title": { "fr": "Nouveau", "en": "New" } },
+>   "detail": { "title": { "fr": "Détail", "en": "Detail" } },
+>   "buttons": { "create": { "fr": "Créer", "en": "Create" }, "edit": { "fr": "Modifier", "en": "Edit" }, "delete": { "fr": "Supprimer", "en": "Delete" } },
+>   "validation": { "required": { "fr": "Ce champ est requis", "en": "This field is required" } }
+> }
+> ```
+
+---
+
+## SELF-VERIFICATION (MANDATORY before loading next step)
+
+Before loading step-03d-validate, verify all 12 subsections (8a-8l) are populated:
+
+1. **8a. Actors** - At least 2 roles with permissions
+2. **8b. Use Cases** - At least 2 UCs with complete structure
+3. **8c. Functional Requirements** - At least 4 FRs with linked UCs and BRs
+4. **8d. Permission Matrix** - Resources and role assignments defined
+5. **8e. Navigation** - Module, sections, and resource routes specified
+6. **8f. SeedData Core** - All 5 arrays populated with structured objects
+7. **8g. Gherkin Scenarios** - BDD scenarios for each major UC
+8. **8h. Validations** - Field rules with error message keys
+9. **8i. Business Messages** - Minimum 4 messages (success, error CRUD, validation, permission)
+10. **8j. Entity Lifecycle** - State machines with transitions if entity has status
+11. **8k. API Endpoints** - RESTful routes with permissions
+12. **8l. i18n Keys** - Translation keys in 4 languages (fr, en, it, de)
+
+**IF any subsection is missing → STOP and request the missing data before proceeding.**
+
+---
+
+## NEXT STEP
+
+Load: `steps/step-03d-validate.md`