@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/business-analyse/create-screen/levels/home-screens.md

@@ -0,0 +1,151 @@
+---
+phase: screens
+kind: level
+level: home
+---
+
+# Level — Home pages (SmartAppHome / SmartModuleHome / SmartSectionHome)
+
+Use this level whenever a menu node needs an **explicit landing page** — the
+first thing the user sees when they click an application, a module or a section
+in the navigation. A home page is **not** a free-form analytics dashboard (that
+is `SmartDashboard`); it is a launchpad combining a few KPIs with quickLinks to
+the next level of the hierarchy.
+
+## Where the home screen is written
+
+A home page sits **above** the section level, so it has no section folder of its
+own. Write it in the `screen.md` of the **landing section** of the module/app
+(or a dedicated `*-home` section if the menu has one), and state its scope in
+the heading. The module/app-level `screen.md` stays a one-line rollup pointer.
+
+## When to use
+
+| Type               | Trigger                                                                 |
+|--------------------|-------------------------------------------------------------------------|
+| `SmartAppHome`     | The application has ≥2 modules. One per app. (1 module = skip)           |
+| `SmartModuleHome`  | The module has ≥2 sections. One per such module. (1 section = skip)      |
+| `SmartSectionHome` | The section has ≥3 child resources OR is explicitly a launchpad/overview (`*-home`, `*-overview`). Optional otherwise — a 1-2 resource section can use its `SmartListView` as the entry point. |
+
+The deep audit flags missing home pages: SCR-006 (apps with ≥2 modules but no
+`SmartAppHome`), SCR-007 (modules with ≥2 sections but no `SmartModuleHome`).
+
+## What to produce
+
+Every home screen carries two things:
+
+1. **Widgets** — small KPI / counter / chart cards at the top (same vocabulary
+   as `SmartDashboard`, see `levels/dashboard-screens.md`).
+2. **QuickLinks** — the ordered navigation cards below the widgets, each pointing
+   to a child screen.
+
+The home page is where you wire navigation explicitly — app home → module home →
+section home → list page — mirroring the route hierarchy `scaffold-routes`
+generates.
+
+### `SmartAppHome` — application landing page
+
+```markdown
+### SCR-CRM-HOME-001 — CRM (SmartAppHome)
+- **Entité** : — (chaque widget porte la sienne)
+- **Permission** : `crm.access`
+- **Cas d'usage liés** : UC-CRM-HOME-001
+- **Widgets** :
+  - open-deals — Affaires ouvertes (kpi, Opportunity, count, `status=open`, col 3)
+  - won-amount — Montant signé YTD (kpi, Opportunity, sum, `amount;status=won`, col 3)
+  - active-clients — Clients actifs (counter, Client, count, `status=active`, col 3)
+  - open-claims — Litiges en cours (counter, Claim, count, `status!=closed`, col 3)
+- **QuickLinks** :
+  - Prospects (icon users) → SCR-CRM-PROSPECTS-HOME-001
+  - Clients (icon building) → SCR-CRM-CLIENTS-HOME-001
+  - Facturation (icon file-invoice) → SCR-CRM-BILLING-HOME-001
+```
+
+Notes:
+- No module/section segment in the code — `SmartAppHome` sits above the module
+  level. Write it in the app's landing-section `screen.md`.
+- The screen-level entity is optional; each widget declares its own.
+- QuickLinks typically point to a `SmartModuleHome`. For a single-module app,
+  point directly to the first list page of that module.
+
+### `SmartModuleHome` — module landing page
+
+```markdown
+### SCR-CRM-CLIENTS-HOME-001 — Clients (SmartModuleHome)
+- **Entité** : — (chaque widget porte la sienne)
+- **Permission** : `crm.clients.read`
+- **Cas d'usage liés** : UC-CRM-CLIENTS-HOME-001
+- **Widgets** :
+  - total — Clients (kpi, Client, count, col 3)
+  - new30 — Nouveaux 30j (counter, Client, count, `createdAt>=30d`, col 3)
+  - by-cat — Par catégorie (chart-pie, Client, `category.name`, col 6)
+- **QuickLinks** :
+  - Annuaire clients (icon list) → SCR-CRM-CLIENTS-LIST-001
+  - Segmentation (icon tag) → SCR-CRM-SEGMENTS-LIST-001
+  - Litiges & réclamations (icon alert) → SCR-CRM-CLAIMS-LIST-001
+```
+
+Notes:
+- A module code is present, no section segment. Write it in the module's
+  landing-section `screen.md`.
+- QuickLinks typically point to a `SmartSectionHome` or directly to a
+  `SmartListView`/`SmartDashboard` of a section.
+
+### `SmartSectionHome` — section landing page (optional)
+
+Use only when a section has ≥3 child resources OR is explicitly an
+overview/launchpad. For simpler sections, the `SmartListView` is the section
+landing page (`scaffold-routes` already maps `app.module.section` to the list).
+
+```markdown
+### SCR-HR-EMPLOYEES-HOME-001 — Employés (SmartSectionHome)
+- **Entité** : — (chaque widget porte la sienne)
+- **Permission** : `hr.employees.read`
+- **Cas d'usage liés** : UC-HR-EMPLOYEES-HOME-001
+- **Widgets** :
+  - headcount — Effectif (kpi, Employee, count, col 3)
+  - on-leave — En congé (counter, Employee, count, `status=onLeave`, col 3)
+  - by-dept — Par département (chart-pie, Employee, `department.name`, col 6)
+- **QuickLinks** :
+  - Annuaire (icon users) → SCR-HR-EMPLOYEES-LIST-001
+  - Contrats (icon file-text) → SCR-HR-CONTRACTS-LIST-001
+  - Demandes de congés (icon calendar) → SCR-HR-LEAVE-BOARD-001
+```
+
+## Widget vocabulary
+
+Same shape as `SmartDashboard` widgets — `kpi | counter | chart-line | chart-bar
+| chart-pie | list` (see `levels/dashboard-screens.md`). Home pages typically use
+3-4 KPIs/counters at the top, optionally one chart, and **never more than one
+list widget** (the quickLinks already serve as navigation).
+
+## QuickLinks vocabulary
+
+Each quickLink has a unique key, a button label (user language), an optional
+Lucide `icon`, a navigation target (a screen `code` that exists in the tree),
+and an optional permission gate (the link is hidden if the actor cannot access
+the target). The exact config-as-data shape is in `references/smartcomponents.md`.
+
+## Auto-generation rule
+
+Walking the menu tree top-down, propose home pages eagerly and **before** their
+child screens, so navigation targets stay valid:
+
+1. **Application** with ≥2 modules → a `SmartAppHome` first, then each module.
+2. **Module** with ≥2 sections → a `SmartModuleHome` after the app home, then
+   each section.
+3. **Section** with ≥3 resources (or explicit `*-home`/`*-overview`) → a
+   `SmartSectionHome` before the list/form/kanban screens.
+
+## Common mistakes
+
+- **A module/section segment on `SmartAppHome`**, or a section segment on
+  `SmartModuleHome` → these home types sit above that level.
+- **Forgetting quickLinks** → the page shows KPIs only and the user cannot drill
+  down (audit SCR-006/007 secondary check).
+- **A quickLink target pointing to a missing screen** → fails SCR-008.
+- **Using `SmartDashboard` instead of a home type** for a navigational landing
+  page → no quickLinks grid is rendered. Use `SmartDashboard` only for free-form
+  analytics.
+- **Home pages for a single-module app or single-section module** → unnecessary
+  noise; the list page already serves as the entry point.

package/templates/skills/business-analyse/create-screen/levels/kanban-screens.md

@@ -0,0 +1,86 @@
+---
+phase: screens
+kind: level
+level: kanban
+---
+
+# Level — Kanban screens (SmartKanban)
+
+Use this level when an entity has a **workflow lifecycle** — a status enum with
+at least 3 distinct states the user transitions between (draft → submitted →
+approved → done, etc.).
+
+## When to use
+
+Trigger words: "kanban", "board", "workflow", "pipeline", "swimlane",
+"approval flow", "tableau", "flux", "approbation".
+
+**Mandatory** when (post-check rule 10):
+- An entity has a `status` enum attribute with **≥3 options**.
+- The entity does NOT belong to a portal / read-only module.
+- No SmartKanban exists yet for this entity.
+
+In that case, propose a `*-board` section in the menu (or reuse an existing one)
+and create a SmartKanban screen.
+
+## What to produce
+
+```markdown
+### SCR-HR-LEAVE-BOARD-001 — Tableau des demandes de congé (SmartKanban)
+- **Entité** : LeaveRequest (ENT-008)
+- **Permission** : `hr.leave.read`
+- **Cas d'usage liés** : UC-HR-LEAVE-BOARD-001, UC-HR-LEAVE-BOARD-002
+- **Champ statut** : status
+- **Colonnes** : draft (Brouillon, gray), submitted (Soumis, blue), approved (Approuvé, green), rejected (Refusé, red)
+- **Carte** : titre = code, sous-titre = employeeName, champs = startDate, endDate, days
+- **Navigation** : clic carte → SCR-HR-LEAVE-DETAIL-001
+```
+
+The exact kanban config-as-data shape is in `references/smartcomponents.md`.
+
+## Column color guidance
+
+| Status semantic         | Color    |
+|-------------------------|----------|
+| draft / pending         | `gray`   |
+| submitted / in progress | `blue`   |
+| approved / completed    | `green`  |
+| rejected / cancelled    | `red`    |
+| under review / on hold  | `orange` |
+
+The generator maps these to design tokens. Stick to the table — invented colors
+are ignored.
+
+## Card content rules
+
+- The title field is mandatory — pick the natural identifier (`code`, `title`).
+- The subtitle is optional — pick the most-cited related entity name
+  (`employeeName`, `customerName`, `assigneeName`).
+- 2 to 4 card fields below the title — keep them short. Dates, numbers and short
+  status fields work best.
+
+## Drag-and-drop semantics
+
+The generated `KanbanBoard.tsx` moves a card between columns and calls a
+status-update API on drop. When the workflow has guards ("only the approver can
+move submitted → approved"), document those as **business rules** of category
+`workflow` (`/ba-create-business-rules`) — the runtime evaluates them and
+disables the drop accordingly.
+
+## Pairing with other screens
+
+A kanban almost always coexists with:
+- A `SmartListView` in the same `*-list` section (for power users who prefer the
+  table layout).
+- A `SmartForm` in a `*-detail` section (clicking a card opens the form) — name
+  that form as the card click target.
+
+## Common mistakes
+
+- **Fewer than 2 columns** → invalid board.
+- **A status field that does not match an entity attribute** → fails post-check
+  rule 7.
+- **More than 4 card fields** → overflows the card visually.
+- **Used for a portal module** → portals are read-only; the kanban is wasted.
+- **Missing for a workflow entity** → fails post-check rule 10 (a highly visible
+  warning).

package/templates/skills/business-analyse/create-screen/levels/list-screens.md

@@ -0,0 +1,134 @@
+---
+phase: screens
+kind: level
+level: list
+---
+
+# Level — List view (SmartListView)
+
+Use this level when the user wants to **see / browse / search** a collection of
+entities. Mental model: a single page with a filters bar at the top, a table (or
+card grid) below, and row-level / collection-level action buttons. Filters and
+table are **always one screen** — never split.
+
+## When to use
+
+Trigger words: "list", "grid", "browse", "show all", "view all", "table",
+"liste", "voir", "afficher".
+
+Mandatory when:
+- The section code ends in `-list`, `-grid`, `-browse`, `-search` (or is `list`).
+- The bound use cases (the section's `use-case.md`) include verbs like "view",
+  "browse", "find", "filter", "search", "review".
+
+## What to produce
+
+Produce **exactly one** `SmartListView` per list section. It carries:
+
+- **Filtres** — the filter bar above the table (0+ fields; a list with only a
+  global search input is fine).
+- **Colonnes** — the table columns (4 to 7).
+- **Actions** — collection-level (top toolbar) and row-level buttons, each gated
+  by a permission code from the module's `rbac.md`.
+- **Navigation** — the row click target: the matching `SmartForm` detail screen
+  `code`, so the generator wires row-click navigation.
+
+This one-page model mirrors the React page `scaffold-component` generates
+(`<FiltersBar>` + `<DataTable>` in a single `ListPage.tsx`).
+
+`screen.md` entry:
+
+```markdown
+### SCR-HR-EMPLOYEES-LIST-001 — Liste des employés (SmartListView)
+- **Entité** : Employee (ENT-003)
+- **Permission** : `hr.employees.read`
+- **Cas d'usage liés** : UC-HR-EMPLOYEES-LIST-001, UC-HR-EMPLOYEES-LIST-002
+- **Colonnes** : code (text), fullName (text, tri), department.name (lookup → Department), status (badge: active/inactive/onLeave), hireDate (date)
+- **Filtres** : fullName (text/recherche), status (select), department (lookup → Department), hireDate (date-range) — orientation horizontale
+- **Actions** : create (header, `hr.employees.create`), export (header, `hr.employees.export`), edit (row, `hr.employees.update`), delete (row, `hr.employees.delete`, scope « own »)
+- **Navigation** : clic ligne → SCR-HR-EMPLOYEES-DETAIL-001
+```
+
+The richer per-field config-as-data shape (filter `type`, column `type`,
+`options`, `entity` on lookups) is documented in `references/smartcomponents.md`.
+
+## Choosing filters
+
+Match what the user filters by **most often**. Pick 3 to 6 fields:
+
+1. **Always** a global text search (the primary display attribute — `fullName`,
+   `name`, `code`).
+2. **Always** the workflow status filter if the entity has a status enum.
+3. The most-cited foreign key (department, category, customer).
+4. The primary date as a date-range (`createdAt`, `hireDate`, `dueDate`).
+5. 1-2 more filters the use cases reference explicitly.
+
+Orientation is `horizontal` by default; use `vertical` only for portals or
+screens with ≥6 filters where a left sidebar makes sense.
+
+## Choosing columns
+
+Pick 4 to 7 columns:
+
+1. **Always** the entity's natural key (`code`, or `id` if no code).
+2. **Always** the primary display attribute (`name`, `fullName`, `title`).
+3. A `status` badge if the entity has a status enum.
+4. The most-cited foreign key.
+5. The primary date.
+6. 1-2 more attributes the use cases reference.
+
+Avoid: long text fields (use `textarea` in the form), heavy computed fields,
+more than 7 columns (stops fitting on a normal screen).
+
+## Choosing actions
+
+Map permissions to top-level (collection) and row-level actions:
+
+| Action key | Where | Permission needed      |
+|------------|-------|------------------------|
+| `create`   | top   | `*.create`             |
+| `export`   | top   | `*.export`             |
+| `edit`     | row   | `*.update`             |
+| `delete`   | row   | `*.delete`             |
+| `approve`  | row   | `*.approve` (workflow) |
+| `view`     | row   | `*.read` (default)     |
+
+Always include row-level `edit` when a matching detail `SmartForm` exists, and
+name that form as the row click target so navigation is wired.
+
+### Custom (non-CRUD) actions — `sync`, `archive`, `approve`, `analyzeImpact`, …
+
+Anything beyond the standard CRUD verbs above is a **custom action** and MUST be
+declared under a separate `- **Actions personnalisées** :` bullet using the
+structured format defined in `SKILL.md` (`## Custom actions — format structuré`).
+Free-text mentions are silently dropped by `ba-create-prd`.
+
+Two flavours :
+
+- `kind: api` — emits a backend endpoint + service method + React Query hook +
+  button. Use for `sync`, `archive`, `approve`, `mapToPce`, `analyzeImpact`, …
+- `kind: navigate` — emits ONLY a button that calls `navigate(targetRoute)`.
+  Use for row-level open / detail clicks that lead to another screen and
+  **must not produce an axios call** (this is the fix for the legacy pattern
+  `POST /{id}/open → 405`).
+
+Append the sub-bullet to the list screen exactly as shown in the SKILL example.
+The audit (`/ba-audit-screens` SCR-011/012/013) verifies the metadata is
+complete and the endpoints/targets are unique and resolvable.
+
+## When to use SmartCard instead
+
+If the section is a customer-facing portal or the entity is best shown as tiles
+(gallery, mobile-first), use `SmartCard` instead. Cards embed a search input in
+their toolbar rather than a full filter bar — see `references/smartcomponents.md`
+for the SmartCard shape.
+
+## Common mistakes
+
+- **Two screens (one filter + one table) for the same section** → deprecated.
+  One section = one `SmartListView`.
+- **Forgetting `entity` on lookup columns** → fails post-check rule 5.
+- **No row click target** → the generated page is not navigable (audit SCR-008
+  also fires if the named target is broken).
+- **Computed fields in the form's create mode** → fails the type-mapping rule.
+- **More than 7 columns** → trim to the most important ones.

package/templates/skills/business-analyse/create-screen/references/post-check.md

@@ -0,0 +1,101 @@
+---
+phase: screens
+kind: reference
+---
+
+# Post-check — Self-check before writing `screen.md`
+
+Run this checklist mentally on every screen before you Write the section's
+`screen.md`. Catching an issue here keeps the spec consistent with the data
+model, RBAC and use cases the screens depend on. The deep audit
+(`/ba-audit-screens`, rules SCR-001..010) re-checks all of this against the tree
+and writes a verdict — but a clean self-check avoids a rework round-trip.
+
+## Blocking checks (fix before writing)
+
+1. **Unique code**: every screen has a unique `code` of the form
+   `SCR-{APP}-…-NNN` within the section's `screen.md`.
+2. **Menu reference**: the application / module / section the screen belongs to
+   exists as a folder in the `.smartstack/ba/` tree (the folder path is the code
+   chain). A home page's scope matches its type:
+   - `SmartAppHome` is app-scoped (no module/section segment in the code).
+   - `SmartModuleHome` is module-scoped (no section segment).
+3. **Entity reference**: `SmartListView`, `SmartForm`, `SmartKanban`,
+   `SmartCard` name a non-empty entity, and that `ENT-…` code is found by Grep
+   in the module's `entité.md`. `SmartDashboard` and the home types may omit the
+   screen-level entity but each widget MUST name its own.
+4. **Config shape**: the per-screen bullets match the type (see
+   `references/smartcomponents.md`):
+   - `SmartListView`     → ≥1 column, optional filters.
+   - `SmartForm`         → fields OR tabs non-empty; related tabs only in
+                           `edit`/`detail`.
+   - `SmartDashboard`    → ≥1 widget.
+   - `SmartKanban`       → a status field + ≥2 columns + a title field.
+   - `SmartCard`         → a title field.
+   - `SmartAppHome`      → ≥1 widget + ≥1 quickLink; app-scoped.
+   - `SmartModuleHome`   → ≥1 widget + ≥1 quickLink; module-scoped.
+   - `SmartSectionHome`  → ≥1 widget + ≥1 quickLink.
+5. **Lookup integrity**: every column or field of type `lookup` names a
+   non-empty entity that exists in the data model.
+6. **Badge/enum integrity**: every `badge` column and every `enum` form field
+   names a non-empty `options` set.
+7. **Column attributes exist**: every `SmartListView` column references an
+   actual attribute of the screen's entity. For nested paths like
+   `department.name`, the head segment (`department`) must be an attribute.
+8. **Form attributes exist**: every `SmartForm` field references an actual
+   attribute of the screen's entity.
+9. **Filter validity**: every list filter of type `lookup` names an entity, and
+   every filter references a valid entity attribute.
+10. **Action permission references**: every action permission referenced exists
+    in the module's `rbac.md` (Grep it).
+11. **Navigation targets exist**: every row-click / card-click / quickLink /
+    related-tab target references a screen `code` that exists in the tree (this
+    `screen.md` or an already-written sibling). Broken targets fail SCR-008.
+12. **Related-tab consistency**: every related tab has (a) a related entity that
+    exists in the data model, (b) a relationship FK on that entity pointing back
+    to the parent, (c) a navigation target that is a `SmartListView` for that
+    related entity.
+13. **Home-page scope**: a `SmartAppHome` code carries no module/section
+    segment; a `SmartModuleHome` code carries no section segment.
+
+## Non-blocking warnings (surface to the user)
+
+- **Missing use cases**: a screen with no linked use case is suspicious — at
+  least one use case should justify any UI surface. Warn but proceed.
+- **Computed not readonly**: a SmartForm field whose entity attribute is
+  computed must be `readonly` in edit/detail. Fix it.
+- **Workflow without kanban**: an entity with a `status` enum ≥3 options and no
+  SmartKanban — the board is highly recommended. Warn.
+- **Missing related tabs**: a `SmartForm` in `edit`/`detail` whose entity has
+  ≥1 incoming 1:N FK but no related tab is suspicious (the fiche client —
+  Client → Factures, Contacts, Litiges — is the canonical example). Warn (SCR-009).
+- **Missing app/module home**: an app with ≥2 modules but no `SmartAppHome`, or
+  a module with ≥2 sections but no `SmartModuleHome`. Warn (SCR-006/007).
+
+## Self-test sequence
+
+Before writing, walk through these questions:
+
+1. Did I read the menu tree (`Glob .smartstack/ba/**/index.md`)? Does every
+   screen sit under a folder that exists? Did I keep home-page scope correct?
+2. Did I read the module's `entité.md`? Does every named entity exist (Grep
+   `ENT-…`)? Do all column/field names match attributes on those entities? Do
+   the related-tab entity + FK map to real entities and FKs?
+3. Did I read the module's `rbac.md`? Do the screen and action permissions
+   appear there?
+4. Did I read the section's `use-case.md`? Are my linked use cases real `UC-…`
+   codes from it?
+5. For every application with ≥2 modules, did I propose a `SmartAppHome`?
+6. For every module with ≥2 sections, did I propose a `SmartModuleHome`?
+7. For every section with ≥3 resources or `*-home`/`*-overview` naming, did I
+   consider a `SmartSectionHome`?
+8. For every `SmartForm` in `edit`/`detail` whose entity has incoming 1:N FKs,
+   did I propose related tabs?
+9. For every entity with a `status` enum ≥3 options, do I have a SmartKanban?
+10. Did I respect the type-mapping table for every column and field?
+11. Did I keep computed attributes `readonly` in edit forms and absent in create
+    forms?
+12. Did every navigation target reference an existing screen `code`?
+
+If any answer is "no" or "unsure", refine before writing — or surface the gap to
+the user via AskUserQuestion.