@atlashub/smartstack-cli 3.4.1 → 3.6.0

package/templates/skills/business-analyse/steps/step-03b-ui.md

@@ -0,0 +1,414 @@
+---
+name: step-03b-ui
+description: Per-module specification - state machines, wireframes, layouts, dashboards (UI & visualization phase)
+model: opus
+next_step: steps/step-03c-compile.md
+---
+
+> **Context files:** `_shared.md` | `_module-loop.md`
+
+# Step 3b: Specification - UI & Visualization
+
+## MANDATORY EXECUTION RULES
+
+- ALWAYS use ULTRATHINK mode
+- This step is EXECUTED ONCE PER MODULE, after step-03a-data.md
+- **WIREFRAME RULE:** Every section MUST have a wireframe in `specification.uiWireframes[]`. No section without a validated mockup.
+- **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
+
+Define the UI layer for the current module: state machines for entities with status fields, wireframes for every section, component mapping, structural layouts, and dashboards.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 3a-state. Define Entity State Machine (Full Depth)
+
+> **For full depth modules with entities that have a status/enum field, define the complete state machine.**
+> **This drives conditional actions, badges, and transition effects throughout the UI.**
+
+For each entity with a status-like attribute:
+
+1. **Identify states** from the enum values or business rules:
+```
+Ask client: "Quels sont les états possibles pour {Entity}.{statusField} ?"
+```
+
+2. **Define transitions** - for each state, ask:
+```
+Ask client: "Depuis l'état {state}, quelles transitions sont possibles ?"
+```
+
+3. **For each transition**, capture:
+   - `action`: verb label (submit, approve, reject, cancel, archive)
+   - `permission`: which permission is required
+   - `guards`: which BR must pass (reference existing BR-XXX from analysis)
+   - `effects`: what happens after (notification, email, field update)
+   - `confirm`: does the user need to confirm?
+
+4. **Assign colors** to states for badge rendering:
+   - Draft/New → gray
+   - In Progress/Submitted → blue
+   - Approved/Active → green
+   - Warning/Pending → yellow
+   - Error/Rejected → red
+   - Archived/Cancelled → purple
+
+5. **Store** in `specification.lifeCycles[]`:
+```json
+{
+  "entity": "{Entity}",
+  "field": "status",
+  "initialState": "{firstState}",
+  "states": [
+    { "id": "draft", "displayName": "Brouillon", "color": "gray", "allowedTransitions": ["submitted"], "isTerminal": false }
+  ],
+  "transitions": [
+    {
+      "from": "draft", "to": "submitted", "action": "submit",
+      "permission": "business.{app}.{module}.submit",
+      "guards": ["BR-VAL-{PREFIX}-001"],
+      "effects": [{ "type": "notification", "target": "role:manager", "template": "{module}-submitted" }],
+      "confirm": true
+    }
+  ]
+}
+```
+
+6. **Cross-validate:** Every `allowedTransitions` entry must have a matching `transitions[]` entry.
+
+### 3a-bis. Structure Sections with Resources (Levels 4 & 5)
+
+> **DEPTH GATE:** Execute this section for **full** depth, or for individual sections flagged for customization in **override** depth. For **convention** depth, sections are auto-generated by 3a-infer — skip to 3b.
+
+For EACH section confirmed in 3a, build the `specification.sections[]` structure:
+
+1. For each resource in the section, determine:
+   - The SmartStack component type (SmartTable, SmartForm, DetailCard, KpiPanel, Chart, Map, Timeline, etc.)
+   - The entity it operates on
+   - Columns/fields based on entity attributes
+   - Permission (inherit from section or more specific)
+   - Available actions
+
+2. Link use cases to sections:
+   - Each UC MUST belong to exactly ONE section
+   - Map UC to section based on the primary action (list → UC-XX-001, create → UC-XX-003, etc.)
+
+3. Link business rules to sections:
+   - Each BR can belong to one or more sections
+   - Map BR based on where it's enforced (validation BR → create/edit section, calc BR → detail section)
+
+4. Build the section object:
+
+> **STRUCTURE CARD: specification.sections[]** — Resources MUST include full depth definitions.
+> ```json
+> {
+>   "code": "list",
+>   "labels": { "fr": "Liste", "en": "List", "it": "Elenco", "de": "Liste" },
+>   "route": "/business/{app}/{module}/list",
+>   "icon": "list",
+>   "permission": "business.{app}.{module}.read",
+>   "wireframe": "{module}-list",
+>   "useCases": ["UC-{PREFIX}-001", "UC-{PREFIX}-002"],
+>   "businessRules": ["BR-VAL-{PREFIX}-001"],
+>   "resources": [
+>     {
+>       "code": "{module}-grid",
+>       "type": "SmartTable",
+>       "entity": "{MainEntity}",
+>       "permission": "business.{app}.{module}.read",
+>       "columns": ["name", "status", "createdAt"],
+>       "columnDefs": [
+>         { "field": "code", "label": {"fr": "Code", "en": "Code"}, "format": "text", "sortable": true, "filterable": true, "clickAction": "navigate:detail" },
+>         { "field": "name", "label": {"fr": "Nom", "en": "Name"}, "format": "text", "sortable": true, "filterable": true },
+>         { "field": "status", "label": {"fr": "Statut", "en": "Status"}, "format": "badge", "sortable": true, "filterable": true, "colorMap": "stateMachine:{Entity}" },
+>         { "field": "createdAt", "label": {"fr": "Créé le", "en": "Created"}, "format": "date-relative", "sortable": true }
+>       ],
+>       "actions": ["view", "edit", "delete"],
+>       "rowActions": [
+>         { "action": "view", "icon": "eye", "permission": "business.{app}.{module}.read" },
+>         { "action": "edit", "icon": "edit", "permission": "business.{app}.{module}.update", "showWhen": {"status": ["draft"]} },
+>         { "action": "delete", "icon": "trash", "permission": "business.{app}.{module}.delete", "confirm": true }
+>       ],
+>       "filters": ["status", "dateRange"],
+>       "defaultSort": { "field": "createdAt", "direction": "desc" },
+>       "defaultPageSize": 20,
+>       "emptyState": { "icon": "inbox", "message": {"fr": "Aucun enregistrement", "en": "No records"}, "createAction": true }
+>     }
+>   ]
+> }
+> ```
+>
+> **SmartForm resource example (for create/edit sections):**
+> ```json
+> {
+>   "code": "{module}-form",
+>   "type": "SmartForm",
+>   "entity": "{MainEntity}",
+>   "permission": "business.{app}.{module}.create",
+>   "fields": [
+>     { "name": "code", "component": "Input", "required": true, "validation": "Unique, auto-generated" },
+>     { "name": "name", "component": "Input", "required": true },
+>     { "name": "type", "component": "Select", "required": true, "source": "EntityTypeEnum" },
+>     { "name": "description", "component": "TextArea", "required": false },
+>     { "name": "parentId", "component": "EntitySelect", "source": "ParentEntity", "required": true },
+>     { "name": "startDate", "component": "DatePicker", "required": true },
+>     { "name": "isActive", "component": "Toggle", "default": true }
+>   ],
+>   "formLayout": {
+>     "type": "tabs",
+>     "tabs": [
+>       { "code": "general", "label": {"fr": "Général", "en": "General"}, "fields": ["code", "name", "type", "description"] },
+>       { "code": "details", "label": {"fr": "Détails", "en": "Details"}, "fields": ["parentId", "startDate", "isActive"] }
+>     ]
+>   }
+> }
+> ```
+> **MANDATORY for SmartTable:** `columnDefs`, `rowActions`, `defaultSort`, `emptyState`
+> **MANDATORY for SmartForm:** `fields` with `component` type, `formLayout`
+
+5. Write `specification.sections[]` via ba-writer.enrichSection()
+
+**VALIDATION:** Every UC must appear in exactly one section.useCases[]. No orphan UCs.
+
+### 3b. For Each Section: Generate MANDATORY ASCII Mockup
+
+> **BLOCKING RULE:** Every section MUST have a wireframe. No section proceeds to entity definition (step 6) without a validated mockup stored in `specification.uiWireframes[]`.
+> **HTML INTEGRATION:** These wireframes are also rendered in the interactive HTML document (`ba-interactive.html`) deployed at handoff. The client can review and annotate mockups directly in their browser.
+
+For each confirmed section, generate an ASCII mockup and validate with client:
+
+Example for a list section:
+
+```
+╔═══════════════════════════════════════════════════════════╗
+║  {Module} > Liste                                 [+ Nouveau] ║
+╠═══════════════════════════════════════════════════════════╣
+║  🔍 Rechercher...  │ Statut: [Tous ▾]  │ Date: [Ce mois ▾] ║
+╠═══════════════════════════════════════════════════════════╣
+║  # │ {Field1}  │ {Field2}    │ {Field3} │ Statut  │ ···  ║
+║  1 │ VAL-001   │ Exemple 1   │ 12'500.- │ ● Brouillon │ ⋮ ║
+║  2 │ VAL-002   │ Exemple 2   │  8'300.- │ ● Envoyé    │ ⋮ ║
+╠═══════════════════════════════════════════════════════════╣
+║  1-25 de 142  │  ◀  1  2  3  ···  6  ▶                   ║
+╚═══════════════════════════════════════════════════════════╝
+```
+
+Store in specification.uiWireframes[] (**MANDATORY** for every section):
+
+> **STRUCTURE CARD: specification.uiWireframes[]** — ALL fields below are MANDATORY.
+> ```json
+> {
+>   "screen": "{module}-{section}",
+>   "section": "{section}",
+>   "description": "Description of the screen",
+>   "mockupFormat": "ascii",
+>   "mockup": "╔═══...",
+>   "elements": ["DataGrid", "FilterBar", "Pagination", "CreateButton"],
+>   "actions": ["filter", "sort", "create", "view-detail"],
+>   "permissionsRequired": ["business.{app}.{module}.read"],
+>   "componentMapping": [
+>     { "wireframeElement": "DataGrid", "reactComponent": "SmartTable" },
+>     { "wireframeElement": "FilterBar", "reactComponent": "SmartFilter" },
+>     { "wireframeElement": "CreateButton", "reactComponent": "Button" }
+>   ],
+>   "layout": {
+>     "type": "page",
+>     "regions": [
+>       { "id": "toolbar", "position": "top", "components": [
+>         { "type": "FilterBar", "resourceRef": "{module}-filters" },
+>         { "type": "ActionMenu", "resourceRef": "{module}-actions", "permission": "business.{app}.{module}.create" }
+>       ]},
+>       { "id": "content", "position": "main", "span": 12, "components": [
+>         { "type": "SmartTable", "resourceRef": "{module}-grid" }
+>       ]}
+>     ]
+>   }
+> }
+> ```
+> **REQUIRED fields:** `screen`, `mockup`, `elements`, `section`, `componentMapping`, `layout` are ALL mandatory.
+> A wireframe without `componentMapping` or `layout` will FAIL validation in step 9.
+> **layout.regions[].components[].resourceRef** MUST match a `sections[].resources[].code`.
+
+Ask client to validate each mockup via AskUserQuestion (batch 2-3 mockups at once if possible).
+
+> **IF client rejects a mockup:** Revise and re-propose until validated. Do NOT proceed without client approval on the layout.
+
+### 3b-bis. Wireframe-to-Component Mapping
+
+After client validates the mockup, map each wireframe element to a SmartStack React component:
+
+| Wireframe Element | SmartStack Component | Notes |
+|-------------------|---------------------|-------|
+| DataGrid | `SmartTable` or `EntityCard` grid | Use EntityCard for card layouts |
+| FilterBar | `SmartFilter` | Integrated with SmartTable |
+| SearchInput | `SearchInput` | Debounced search |
+| Pagination | Built into `SmartTable` | Server-side pagination |
+| ActionButton | `Button` + `RequirePermission` | Always wrapped in permission check |
+| StatusBadge | `StatusBadge` | Uses entity lifecycle states |
+| DetailCard | `EntityDetailCard` | Standard detail layout |
+| Form | `SmartForm` | FluentValidation-backed |
+| KpiCard | `StatCard` (Recharts) | Dashboard KPI display |
+| Chart:bar/line/pie | Recharts `BarChart`/`LineChart`/`PieChart` | CSS variables for colors |
+
+Store the component mapping alongside the wireframe to ensure downstream skills use the correct components.
+
+### 3b-ter. Generate Structural Layout
+
+For EACH wireframe generated in 3b, generate a `layout` object alongside the ASCII mockup:
+
+1. From the ASCII mockup, extract the visual regions (header, toolbar, main content, sidebar, etc.)
+2. For each region, map the visual elements to SmartStack component types
+3. Build the layout structure:
+```json
+{
+  "type": "page",
+  "regions": [
+    { "id": "toolbar", "position": "top", "components": [
+      { "type": "FilterBar", "resourceRef": "{module}-filters" },
+      { "type": "ActionMenu", "resourceRef": "{module}-actions", "permission": "business.{app}.{module}.create" }
+    ]},
+    { "id": "content", "position": "main", "span": 12, "components": [
+      { "type": "SmartTable", "resourceRef": "{module}-grid" }
+    ]}
+  ]
+}
+```
+4. Cross-validate: each component in layout.regions[].components[] MUST have a corresponding resource in sections[].resources[]
+5. Write layout alongside mockup in uiWireframes[]
+
+**RULE:** The layout is the source of truth for ralph-loop. The mockup is for human validation only.
+
+### 3c. Identify Resources per Section
+
+For each section, identify what resources/components are needed:
+
+- List section → DataGrid, FilterBar, SearchInput, ExportButton
+- Detail section → DetailCard, StatusBadge, ActionButtons, Timeline
+- Create section → Form, ValidationMessages, SubmitButton
+- Approve section → StatusTransitionPanel, CommentBox, ApproveRejectButtons
+- Dashboard section → StatCard, RechartsChart (Bar/Line/Pie/Area), DashboardGrid, FilterBar
+
+### 3d. Dashboard Specification (if section = dashboard)
+
+When a "dashboard" section is selected, capture structured KPI and chart data **in addition** to the standard ASCII mockup.
+
+1. **Ask client for KPIs** via AskUserQuestion (batch):
+   - KPI name and metric description
+   - Visualization type: `kpi-card`, `bar`, `line`, `pie`, `area`, `donut`, `stacked-bar`
+   - Data source entity
+   - Format: `number`, `currency`, `percent`, `duration`
+   - Thresholds (warning/critical) if applicable
+
+2. **Ask client for filters:**
+   - Date range filter? Default period? (day/week/month/quarter/year)
+   - Entity-based filters? (status, category, etc.)
+
+3. **Ask client for refresh mode:**
+   - Static (load on page open)
+   - Polling (periodic refresh)
+   - SignalR (real-time push)
+
+4. **Store in specification.dashboards[]:**
+
+```json
+{
+  "code": "{module}-dashboard",
+  "title": "{Module} Dashboard",
+  "description": "Vue d'ensemble des métriques {module}",
+  "linkedUCs": ["UC-XXX"],
+  "refreshMode": "static",
+  "defaultPeriod": "month",
+  "kpis": [
+    {
+      "code": "total-items",
+      "label": "Total Items",
+      "metric": "COUNT(entity)",
+      "format": "number",
+      "visualization": "kpi-card",
+      "dataSource": "Entity",
+      "thresholds": { "warning": 100, "critical": 50 }
+    },
+    {
+      "code": "items-by-status",
+      "label": "Items by Status",
+      "metric": "COUNT(entity) GROUP BY status",
+      "format": "number",
+      "visualization": "pie",
+      "dataSource": "Entity",
+      "dimensions": ["status"]
+    }
+  ],
+  "filters": [
+    { "field": "dateRange", "type": "dateRange", "label": "Période" },
+    { "field": "status", "type": "multiselect", "label": "Statut" }
+  ],
+  "permissionsRequired": ["business.{app}.{module}.read"]
+}
+```
+
+5. **ALSO generate the standard ASCII mockup** for the dashboard with KPI cards + chart placeholders:
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  {Module} > Dashboard              Période: [Ce mois ▾]     ║
+╠═══════════════════════════════════════════════════════════════╣
+║  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    ║
+║  │ KPI #1   │  │ KPI #2   │  │ KPI #3   │  │ KPI #4   │    ║
+║  │  1,234   │  │  567     │  │  89.2%   │  │  12,400  │    ║
+║  │  ↑ +12%  │  │  ↓ -3%  │  │  → 0%   │  │  ↑ +5%   │    ║
+║  └──────────┘  └──────────┘  └──────────┘  └──────────┘    ║
+╠═══════════════════════════════════════════════════════════════╣
+║  ┌─────────────────────────┐  ┌─────────────────────────┐    ║
+║  │  [Bar Chart]            │  │  [Pie Chart]            │    ║
+║  │  Items by Month         │  │  Items by Status        │    ║
+║  │  ████                   │  │      ████████           │    ║
+║  │  ████ ████              │  │   ███      ███          │    ║
+║  │  ████ ████ ████         │  │  ██   42%    ██         │    ║
+║  └─────────────────────────┘  └─────────────────────────┘    ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+Store the mockup in specification.wireframes[] AS WELL (for visual reference).
+
+---
+
+## SELF-VERIFICATION (MANDATORY before loading step-03c-compile)
+
+Before proceeding to step-03c-compile.md, VERIFY:
+
+1. **Wireframes exist for all sections** in `specification.uiWireframes[]`
+2. **All wireframes have componentMapping** with smarter mapping rules
+3. **All wireframes have layout** with regions and resourceRef references
+4. **All resource references** in layout.regions[].components[].resourceRef exist in sections[].resources[]
+5. **State machines defined** (if module has status fields) in `specification.lifeCycles[]`
+
+**IF any check fails → FIX before proceeding.** Do NOT load step-03c-compile with incomplete data.
+
+---
+
+## NEXT STEP
+
+Load: `steps/step-03c-compile.md`