@shanyucoder/flowgrid 0.1.11 → 0.1.12

package/templates/shared/default-layout.ejs

@@ -7,6 +7,13 @@
   const hasStories = !!spec.userStories;
   const hasNfr = spec.nfr && String(spec.nfr).trim();
   const hasUserFlows = spec.userFlows && String(spec.userFlows).trim();
+  const icBlock = spec.interactionCases;
+  const icItems = icBlock && Array.isArray(icBlock.items) ? icBlock.items : [];
+  const hasInteractionCases =
+    icBlock &&
+    (icBlock.policy === 'skip' ||
+      icItems.length > 0 ||
+      (icBlock.policy === 'required' && icItems.length === 0));
   const qaOpen = spec['Q&A'] && String(spec['Q&A']).trim();
   const hasEntities = spec.entities && (Array.isArray(spec.entities) ? spec.entities.length : true);
   const pageSections = spec.sections || spec.design?.sections || [];
@@ -34,8 +41,9 @@
   if (hasNonGoals) addToc('Out of scope', 'scope-out');
   if (hasStories) addToc('User stories & requirements', 'user-stories--screen-journey');
   addToc('Data & integrations / API', 'data-integrations');
-  if (hasUserFlows) addToc('User flows', 'user-flows');
+  if (hasUserFlows) addToc('Linked user flows (FLOW)', 'user-flows');
   if (hasNfr) addToc('Non-functional (NFR)', 'nfr');
+  if (hasInteractionCases) addToc('Interaction cases', 'interaction-cases');
   if (hasState) addToc('State & permissions matrix', 'state--permission-matrix');
   if (hasListColumns) addToc('List columns', 'list-columns');
   if (hasListExtras) addToc('Filters & pagination', 'list-filters-pagination');
@@ -213,7 +221,11 @@ Backend contract: `api/<seq>/01-backend-spec.yaml` on the same function leaf (no
 <% } %>
 
 <% if (hasUserFlows) { %>
-## User flows {#user-flows}
+## Linked user flows (FLOW) {#user-flows}
+
+Use product journey docs (`FLOW-*.md`) — include §6 sequence. Convention per line:
+
+`FLOW-<id> — role: entry|step-N-*|exit — screens: W-* … (this leaf)`
 
 <%= spec.userFlows %>
 
@@ -226,6 +238,39 @@ Backend contract: `api/<seq>/01-backend-spec.yaml` on the same function leaf (no
 
 <% } %>
 
+<% if (hasInteractionCases) { %>
+## Interaction cases {#interaction-cases}
+
+<% if (icBlock.policy === 'skip') { %>
+_Screen interaction sequences skipped:_ <%= icBlock.skipReason || '(no reason given)' %>
+
+<% } else { %>
+> Sequence diagrams: [design.md](./design.md) (generated). Authoring: `interactionCases` on `*.bundle.yaml`.
+
+<% for (const item of icItems) { %>
+### <%= item.id || 'IC-?' %> {#<%= String(item.id || 'ic').toLowerCase() %>}
+
+<% if (item.title) { %>**<%= item.title %>**
+
+<% } %>
+<% if (item.description) { %>
+<%= item.description %>
+
+<% } %>
+<% if (item.links && typeof item.links === 'object') { %>
+| Link | Value |
+| --- | --- |
+<% for (const [k, v] of Object.entries(item.links)) { %>
+| `<%= k %>` | <%= v %> |
+<% } %>
+
+<% } %>
+[View sequence diagram](./design.md#<%= String(item.id || 'ic').toLowerCase() %>)
+
+<% } %>
+<% } %>
+<% } %>
+
 <%
   const page = {
     nav: spec.nav || spec.design?.nav,

package/templates/shared/feature.bundle.yaml

@@ -26,7 +26,35 @@ nonGoals: |
   - [VD: không export Excel tại màn list — defer QA/debt]
 
 userFlows: |
-  - [Luồng người dùng — link FLOW-* trong architecture/03-user-flows hoặc common/user-flows]
+  - FLOW-checkout — role: step-3-ops — screens: W-ADM-ORD-01 (this leaf)
+  # Journey SSOT: FLOW-*.md (§6 sequenceDiagram) — read via userFlows before codegen
+
+# Optional — màn nhiều state / case trên một W-* (L2). Không thay FLOW-*.md.
+# interactionCases:
+#   policy: required
+#   items:
+#     - id: IC-SUBMIT-HAPPY
+#       title: "Lưu từ DRAFT"
+#       description: |
+#         User bấm Lưu; form hợp lệ; chuyển trạng thái.
+#       links:
+#         actionId: btn_save_record
+#         recordStatus: DRAFT
+#       sequenceDiagram: |
+#         sequenceDiagram
+#           actor U as User
+#           participant W as [W-ADM-ORD-01]
+#           U->>W: Submit
+#     - id: IC-SUBMIT-409
+#       title: "Conflict"
+#       description: |
+#         Optimistic lock conflict — giữ form, reload.
+#       links:
+#         actionId: btn_save_record
+#       sequenceDiagram: |
+#         sequenceDiagram
+#           U->>W: Submit
+#           W-->>U: 409 message
 
 nfr: |
   - **Hiệu năng:** [VD: danh sách < 2s với 10k bản ghi — phân trang server]

package/templates/shared/tpl-runtime-sequence.md

@@ -0,0 +1,56 @@
+---
+page-id: W-XXX-DOMAIN-01
+title: "Runtime sequence — <feature title>"
+status: draft
+---
+
+# Runtime sequence — `<page-id>`
+
+> SSOT for **tech review** (BE/FE). Journey context: link `FLOW-*` from bundle `userFlows`.  
+> Authoring: `ir/runtime-sequence.md` or `api/<seq>/02-runtime-sequence.md` — not this generated copy.
+
+## Scope
+
+- **In this diagram:** …
+- **Out of scope:** …
+
+## Preconditions & state
+
+| State / gate | Rule |
+| --- | --- |
+| e.g. `DRAFT` | User may edit until submit |
+
+## Sequence
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor U as User
+    participant W as [W-XXX-DOMAIN-01]
+    participant API as [API-XXX-DOMAIN-01]
+    participant Svc as DomainService
+    participant DB as Database
+
+    U->>W: Open screen
+    W->>API: Load (GET …)
+    API->>Svc: fetch
+    Svc->>DB: query
+    DB-->>Svc: rows
+    Svc-->>API: DTO
+    API-->>W: 200 + body
+    W-->>U: Render
+
+    alt Validation error
+        API-->>W: 422 field errors
+        W-->>U: Inline messages
+    else Conflict
+        API-->>W: 409
+        W-->>U: Toast + stay
+    end
+```
+
+## Traceability
+
+| Step | Endpoint / action | Tables / events |
+| --- | --- | --- |
+| 1 | `endpoints[].id` … | … |