@shanyucoder/flowgrid 0.1.9 → 0.1.11

package/templates/project-skeleton/surfaces/_surface-index.template.md

@@ -0,0 +1,44 @@
+---
+id: SURFACE-TEMPLATE
+surfaceCode: ADM
+title: "Surface channel name"
+status: draft
+contentLocale: vi
+---
+
+# Surface: [Channel name]
+
+> Section titles are **English**. Prose uses `contentLocale` / `docs-hub.locale.yaml`.
+
+## Goals {#goals}
+
+[Value of this channel — one paragraph.]
+
+## Background {#background}
+
+[Who uses this channel and in what context.]
+
+## Scope {#scope}
+
+**In scope:**
+
+- [CMP modules on this surface]
+
+**Out of scope:**
+
+- [Other surface or integration-only scope]
+
+## Modules (CMP)
+
+| CMP | Summary | Primary flow |
+| --- | --- | --- |
+| `CMP-…` | […] | `FLOW-…` (if any) |
+
+## User flows on this surface
+
+- Catalog: [`architecture/03-user-flows/`](/architecture/03-user-flows/)
+- Shared on surface: `common/user-flows/FLOW-*.md` (when ≥2 modules share)
+
+## Features overview
+
+[1–2 paragraphs: how to read the hub — detail per screen in bundles and `ir/generated/spec.md`.]

package/templates/shared/bundle-authoring.md

@@ -8,8 +8,11 @@ Hub: `docs/templates/feature.bundle.yaml` · split: `pnpm spec:split`
 |-----|---------|
 | `page-id` | Screen identity (`cmp-adm-000-01`). Split copies this onto `ir/spec.yaml` as `page-id` (not `id`, so it does not collide with requirement/section ids). Legacy bundles may still use `id`. |
 | `summary` | Phải trình bày dạng bullet. Bắt buộc có các tiêu đề (chuẩn Arc42 business): **mục tiêu nghiệp vụ** (business_goals), **các bên liên quan** (stakeholders), **kịch bản người dùng** (user_journey), **bối cảnh** (description, input liên kết cross-page/module, output) và **cách giải quyết** (tùy chọn). Mục đích để 100% Non-tech Stakeholder hiểu và duyệt. |
-| `successMetrics` | **Tùy chọn** khi có thông tin — bullet (string multiline hoặc list). Chỉ số đo được / qualitative metric cấp **màn/feature**. Product-level → `overview/`. Split → `ir/spec.yaml`; render → section riêng trong `ir/generated/spec.md`. |
-| `nonGoals` | **Tùy chọn** — phạm vi **không làm** trên màn/phase (PRD non-goals). Tránh nhét vào `requirements` prose. |
+| `scopeIn` | **Khuyến nghị** — trong phạm vi màn/phase (PRD). Audit `WARN_NO_SCOPE_IN`. |
+| `nonGoals` | **Khuyến nghị** — ngoài phạm vi màn/phase (PRD). Audit `WARN_NO_NON_GOALS`. |
+| `userFlows` | **Khuyến nghị** — link `FLOW-*` (`03-user-flows` / `common/user-flows`) hoặc journey ngắn. Audit `WARN_NO_USER_FLOWS` khi multi-screen. |
+| `nfr` | **Khuyến nghị** — hiệu năng, bảo mật. Audit `WARN_NO_NFR`. |
+| _(rủi ro)_ | **Không** khai báo trên bundle. SSOT: `architecture/11-risks/risk-register.md` — `/risk-register`. Key `risks:` → audit `WARN_BUNDLE_RISKS_FORBIDDEN`. |
 | `userStories` | **Khối User Stories chuyên sâu cho màn hình:** `primary`, `contextAndHandoff` (+ `screenAccess`), `scenarios` (5 kịch bản chuẩn + **scenario thứ 6 “Affordances UX”** khi màn có delete/filter/breadcrumb/disabled/import — xem `feature.bundle.yaml`), `acceptanceCriteria` (kèm checkbox UX khi áp dụng). **Split:** `pnpm spec:split` copy nguyên khối sang `ir/spec.yaml` (business prose); **không** tự sinh từ `design` — Agent phải cập nhật `userStories` khi bổ sung DSL/`#needs-component`/audit `UX_*`. Render → `## User Stories & Screen Journey` trong Markdown. |
 | `spec` | Design v1 — **`entities`**, **`relationships`**, actors, requirements, `ui.routes`, **`ui.list` / `ui.form` / `ui.detail`**, `acceptance`. **Không** author `spec.api` — API SSOT là `api/<seq>/01-backend-spec.yaml`. |
 | `gen` | **Bắt buộc trước flowgrid gen:** `codegen.profile` (`auth` login/forgot/reset; `change-password`; `public`; `not-found`/`error`; `list`/`create`/`admin-crud`) + entity/module, `tags`, derived `ui.*`. `/grill-dev` ghi. Endpoint `action` ghi trên **01**, không trên bundle. |
@@ -285,7 +288,7 @@ actions:
     trigger: button_click
     apiRefs: [ feature.create ]
     # tags: ["#reuse-api"]
-    # reuseFrom: surfaces/admin/CMP-01/auth/01/01/01/api/01/01-backend-spec.yaml
+    # reuseFrom: surfaces/admin/CMP-ADM-AUTH-01/01/01/01/api/01/01-backend-spec.yaml
     onSuccess:
       - Navigate to list page
       - Show success toast "Created successfully"

package/templates/shared/default-layout.ejs

@@ -2,9 +2,13 @@
   const pageId = spec['page-id'] || spec.id || '';
   const docStatus = spec.status || 'draft';
   const docOwner = spec.owner || '';
-  const hasMetrics = spec.successMetrics && String(spec.successMetrics).trim();
+  const hasScopeIn = spec.scopeIn && String(spec.scopeIn).trim();
   const hasNonGoals = spec.nonGoals && String(spec.nonGoals).trim();
   const hasStories = !!spec.userStories;
+  const hasNfr = spec.nfr && String(spec.nfr).trim();
+  const hasUserFlows = spec.userFlows && String(spec.userFlows).trim();
+  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 || [];
   const pageActions = spec.actions || spec.design?.actions || [];
   const pageStateMatrix = spec.stateMatrix || spec.design?.stateMatrix;
@@ -21,23 +25,28 @@
   const hasLegacy = spec.legacy && (spec.legacy.behaviors?.length || spec.legacy.fields?.length || spec.legacy.evidence?.length);
   const hasDebt = spec.pendingTechDebt && spec.pendingTechDebt.length;
 
+  const contentLocale = context.docsContentLocale || 'vi';
   const toc = [];
-  toc.push('1. [Tổng quan](#overview)');
-  if (hasMetrics) toc.push('2. [Chỉ số thành công](#success-metrics)');
-  if (hasNonGoals) toc.push('3. [Phạm vi không làm](#non-goals)');
-  if (hasStories) toc.push('4. [User stories và hành trình màn hình](#user-stories--screen-journey)');
-  if (hasState) toc.push('5. [Ma trận trạng thái và phân quyền](#state--permission-matrix)');
-  if (hasListColumns) toc.push('6. [Bảng cột danh sách](#list-columns)');
-  if (hasListExtras) toc.push('6b. [Bộ lọc & phân trang](#list-filters-pagination)');
-  if (hasValidation) toc.push(`${hasListColumns || hasListExtras ? '7' : '6'}. [Từ điển dữ liệu và validation](#data-dictionary--validation)`);
-  if (hasCustomWidget) toc.push(`${hasListColumns ? '8' : '7'}. [Widget tùy biến](#custom-widgets)`);
-  const actionNum = hasListColumns ? (hasCustomWidget ? '9' : '8') : (hasCustomWidget ? '8' : '7');
-  if (hasActions) toc.push(`${actionNum}. [Luồng hành động](#action-flows)`);
-  else if (pageSections.length) toc.push(`${actionNum}. [Bố cục màn hình](#page-composition)`);
-  if (hasReview) toc.push('9. [Ghi chú review](#review-notes)');
-  if (hasLegacy) toc.push('10. [Legacy evidence](#legacy-evidence)');
-  if (hasDebt) toc.push('11. [Tech debt](#pending-tech-debt)');
-  toc.push('- [API SSOT](#api-ssot)');
+  let n = 1;
+  const addToc = (label, anchor) => { toc.push(`${n}. [${label}](#${anchor})`); n += 1; };
+  addToc('Overview', 'overview');
+  if (hasScopeIn) addToc('In scope', 'scope-in');
+  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 (hasNfr) addToc('Non-functional (NFR)', 'nfr');
+  if (hasState) addToc('State & permissions matrix', 'state--permission-matrix');
+  if (hasListColumns) addToc('List columns', 'list-columns');
+  if (hasListExtras) addToc('Filters & pagination', 'list-filters-pagination');
+  if (hasValidation) addToc('Data dictionary & validation', 'data-dictionary--validation');
+  if (hasCustomWidget) addToc('Custom widgets', 'custom-widgets');
+  if (hasActions) addToc('Action flows', 'action-flows');
+  else if (pageSections.length) addToc('Page composition', 'page-composition');
+  if (qaOpen) addToc('Appendix — open questions', 'appendix-open-questions');
+  if (hasReview) addToc('Review notes', 'review-notes');
+  if (hasLegacy) addToc('Legacy evidence', 'legacy-evidence');
+  if (hasDebt) addToc('Tech debt', 'pending-tech-debt');
 
   const route = spec.ui?.routes?.[0];
   const routePath = route?.path || '';
@@ -45,13 +54,13 @@
 %>
 # <%= spec.title || spec.id %>
 
-## Mục lục (Contents)
+## Table of contents
 
 <%= toc.join('\n') %>
 
 ---
 
-## Tổng quan {#overview}
+## Overview {#overview}
 
 | | |
 | --- | --- |
@@ -75,36 +84,29 @@
 %>
 <%= screenLine %>
 
-- **QA inbox:** [Danh sách câu hỏi treo](../../qa/index.md) (cùng function leaf)
+- **QA inbox:** [Open questions](../../qa/index.md) (same function leaf)
 - **Generated (VitePress):** [spec](./spec.md) · [data-model](./data-model.md) · [api](./api.md) _(khi có `01`)_
 
 <% if (spec.summary) { %>
 <%= spec.summary %>
 <% } %>
 
-<% if (hasMetrics) { %>
-## Chỉ số thành công {#success-metrics}
+<% if (hasScopeIn) { %>
+## In scope {#scope-in}
 
-<%= spec.successMetrics %>
+<%= spec.scopeIn %>
 
 <% } %>
 
 <% if (hasNonGoals) { %>
-## Phạm vi không làm {#non-goals}
+## Out of scope {#scope-out}
 
 <%= spec.nonGoals %>
 
 <% } %>
 
-## API SSOT {#api-ssot}
-
-Hợp đồng backend: `api/<seq>/01-backend-spec.yaml` trong cùng function leaf (không gộp vào bundle). Sau split: `ir/design.yaml` chiếu endpoint; OpenAPI/mock theo stack.
-
-- **Data model (review, multi-table):** [data-model.md](./data-model.md) — bảng/cột; SSOT codegen = `01` + `ir/design.yaml` `db`.
-- **API (đọc trên site):** [api.md](./api.md) — tóm tắt endpoint từ `01-backend-spec.yaml` (khi có file).
-
 <% if (spec.userStories) { %>
-## User Stories & Screen Journey {#user-stories--screen-journey}
+## User stories & requirements {#user-stories--screen-journey}
 
 <% if (typeof spec.userStories === 'string') { %>
 <%= spec.userStories %>
@@ -112,29 +114,29 @@ Hợp đồng backend: `api/<seq>/01-backend-spec.yaml` trong cùng function lea
 <% spec.userStories.forEach(story => { %>
 ### <%= story.title || story.name || 'User Story' %>
 <% if (story.asA || story.role) { %>
-> **Là một** <%= story.asA || story.role %>,  
-> **Tôi muốn** <%= story.iWant || story.action %>,  
-> **Để** <%= story.soThat || story.benefit %>.
+> **As a** <%= story.asA || story.role %>,  
+> **I want** <%= story.iWant || story.action %>,  
+> **so that** <%= story.soThat || story.benefit %>.
 <% } else if (story.story) { %>
 > <%= story.story %>
 <% } %>
 
 <% if (story.preConditions && story.preConditions.length) { %>
-**Điều kiện tiên quyết (Pre-conditions):**
+**Pre-conditions:**
 <% (Array.isArray(story.preConditions) ? story.preConditions : [story.preConditions]).forEach(p => { %>
 - <%= p %>
 <% }); %>
 <% } %>
 
 <% if (story.scenarios && story.scenarios.length) { %>
-**Kịch bản chi tiết trên màn hình (Scenarios):**
+**Scenarios:**
 <% story.scenarios.forEach(sc => { %>
 - **<%= sc.name || sc.title %>:** <%= sc.description || sc.steps || sc %>
 <% }); %>
 <% } %>
 
 <% if (story.acceptanceCriteria && story.acceptanceCriteria.length) { %>
-**Tiêu chí nghiệm thu (Acceptance Criteria):**
+**Acceptance criteria:**
 <% (Array.isArray(story.acceptanceCriteria) ? story.acceptanceCriteria : [story.acceptanceCriteria]).forEach(ac => { %>
 - [ ] <%= ac %>
 <% }); %>
@@ -143,34 +145,34 @@ Hợp đồng backend: `api/<seq>/01-backend-spec.yaml` trong cùng function lea
 <% }); %>
 <% } else if (typeof spec.userStories === 'object') { %>
 <% if (spec.userStories.primary) { %>
-### User Story Chính
-> **Là một** <%= spec.userStories.primary.asA || spec.userStories.primary.role %>,  
-> **Tôi muốn** <%= spec.userStories.primary.iWant || spec.userStories.primary.action %>,  
-> **Để** <%= spec.userStories.primary.soThat || spec.userStories.primary.benefit %>.
+### Primary user story
+> **As a** <%= spec.userStories.primary.asA || spec.userStories.primary.role %>,  
+> **I want** <%= spec.userStories.primary.iWant || spec.userStories.primary.action %>,  
+> **so that** <%= spec.userStories.primary.soThat || spec.userStories.primary.benefit %>.
 <% } %>
 
 <% if (spec.userStories.contextAndHandoff) { %>
-### Cách thức Truy cập & Chuyển giao Màn hình (Screen Access & Handoff)
+### Screen access & handoff
 <% if (spec.userStories.contextAndHandoff.screenAccess) { %>
 <% const sa = spec.userStories.contextAndHandoff.screenAccess; %>
-- **Loại truy cập (Access Type):** `<%= sa.accessType || 'N/A' %>`
+- **Access type:** `<%= sa.accessType || 'N/A' %>`
 <% if (sa.accessType === 'directRoute' && sa.directRoute) { %>
-  - **Đường dẫn URL (Path Router):** `<%= sa.directRoute.routePath || '' %>` <%= sa.directRoute.isPublic ? '(Công khai / Public)' : '(Cần đăng nhập / Authenticated)' %>
+  - **Path:** `<%= sa.directRoute.routePath || '' %>` <%= sa.directRoute.isPublic ? '(public)' : '(authenticated)' %>
 <% } else if (sa.accessType === 'sidebarMenu' && sa.sidebarMenu) { %>
-  - **Menu Sidebar:** <%= sa.sidebarMenu.menuHierarchy ? sa.sidebarMenu.menuHierarchy.join(' > ') : '' %> > **<%= sa.sidebarMenu.menuLabel || '' %>**
+  - **Sidebar menu:** <%= sa.sidebarMenu.menuHierarchy ? sa.sidebarMenu.menuHierarchy.join(' > ') : '' %> > **<%= sa.sidebarMenu.menuLabel || '' %>**
 <% } else if (sa.accessType === 'contextualAction' && sa.contextualAction) { %>
-  - **Kích hoạt từ (Triggered By):** <%= sa.contextualAction.triggerControl || '' %> từ màn hình `<%= sa.contextualAction.sourceScreen || '' %>` (Loại: `<%= sa.contextualAction.navigationType || 'pageRedirect' %>`)
+  - **Triggered by:** <%= sa.contextualAction.triggerControl || '' %> on screen `<%= sa.contextualAction.sourceScreen || '' %>` (navigation: `<%= sa.contextualAction.navigationType || 'pageRedirect' %>`)
 <% } %>
 <% } %>
-- **Màn hình nguồn (Source Screen):** `<%= spec.userStories.contextAndHandoff.sourceScreen || 'Direct' %>`
+- **Source screen:** `<%= spec.userStories.contextAndHandoff.sourceScreen || 'Direct' %>`
 <% if (spec.userStories.contextAndHandoff.inputsReceived && spec.userStories.contextAndHandoff.inputsReceived.length) { %>
-- **Dữ liệu tiếp nhận (Inputs):** <%= Array.isArray(spec.userStories.contextAndHandoff.inputsReceived) ? spec.userStories.contextAndHandoff.inputsReceived.join(' · ') : spec.userStories.contextAndHandoff.inputsReceived %>
+- **Inputs received:** <%= Array.isArray(spec.userStories.contextAndHandoff.inputsReceived) ? spec.userStories.contextAndHandoff.inputsReceived.join(' · ') : spec.userStories.contextAndHandoff.inputsReceived %>
 <% } %>
-- **Điều hướng tiếp theo (Next Screen):** `<%= spec.userStories.contextAndHandoff.nextScreenOnSuccess || 'None' %>`
+- **Next screen on success:** `<%= spec.userStories.contextAndHandoff.nextScreenOnSuccess || 'None' %>`
 <% } %>
 
 <% if (spec.userStories.scenarios && spec.userStories.scenarios.length) { %>
-### Kịch bản Chi tiết trên Màn hình (Scenarios)
+### Scenarios
 <% spec.userStories.scenarios.forEach(sc => { %>
 #### <%= sc.name || sc.title %>
 <% if (sc.steps && sc.steps.length) { %>
@@ -184,7 +186,7 @@ Hợp đồng backend: `api/<seq>/01-backend-spec.yaml` trong cùng function lea
 <% } %>
 
 <% if (spec.userStories.acceptanceCriteria && spec.userStories.acceptanceCriteria.length) { %>
-### Tiêu chí Nghiệm thu (Acceptance Criteria)
+### Acceptance criteria
 <% spec.userStories.acceptanceCriteria.forEach(ac => { %>
 - [ ] <%= ac %>
 <% }); %>
@@ -193,6 +195,37 @@ Hợp đồng backend: `api/<seq>/01-backend-spec.yaml` trong cùng function lea
 <% } %>
 <% } %>
 
+## Data & integrations / API {#data-integrations}
+
+Backend contract: `api/<seq>/01-backend-spec.yaml` on the same function leaf (not merged into bundle).
+
+- **Data model (read):** [data-model.md](./data-model.md)
+- **API (read):** [api.md](./api.md) — summary from `01-backend-spec.yaml` when present
+- **Codegen SSOT:** `ir/design.yaml` + `01` + bundle `db` fields
+
+<% if (hasEntities) { %>
+### Entities on this screen (summary)
+
+```yaml
+<%= context.stringify(spec.entities).trim() %>
+```
+
+<% } %>
+
+<% if (hasUserFlows) { %>
+## User flows {#user-flows}
+
+<%= spec.userFlows %>
+
+<% } %>
+
+<% if (hasNfr) { %>
+## Non-functional (NFR) {#nfr}
+
+<%= spec.nfr %>
+
+<% } %>
+
 <%
   const page = {
     nav: spec.nav || spec.design?.nav,
@@ -204,21 +237,25 @@ Hợp đồng backend: `api/<seq>/01-backend-spec.yaml` trong cùng function lea
 %>
 
 <% if (pageStateMatrix) { %>
-## Ma Trận Trạng Thái Giao Diện & Phân Quyền (State & Permission Matrix) {#state--permission-matrix}
+## State & permissions matrix {#state--permission-matrix}
 
 <%- context.renderStateMatrixTable(pageStateMatrix) %>
 
 <% } %>
 
+<% if (hasListColumns || hasListExtras || hasValidation || hasCustomWidget || hasActions || pageSections.length) { %>
+> **Note (business reviewers):** Sections below are technical screen detail (dev/QA). Skip when reviewing scope and user stories only.
+
+<% } %>
 <% 
   const listColumnsMd = context.renderListColumnsTable && context.renderListColumnsTable(listUi);
   if (listColumnsMd) {
 %>
-## Bảng cột danh sách (List columns) {#list-columns}
+## List columns {#list-columns}
 
 <%- listColumnsMd %>
 
-<p><strong>DB chi tiết / multi-table:</strong> <a href="./data-model.md">data-model.md</a> · SSOT ghi: <code>*.bundle.yaml</code> + <code>ir/design.yaml</code>.</p>
+<p><strong>Multi-table DB detail:</strong> <a href="./data-model.md">data-model.md</a> · SSOT: <code>*.bundle.yaml</code> + <code>ir/design.yaml</code>.</p>
 
 <% } %>
 
@@ -227,16 +264,16 @@ Hợp đồng backend: `api/<seq>/01-backend-spec.yaml` trong cùng function lea
   const paginationMd = context.renderListPaginationBlock && context.renderListPaginationBlock(listUi);
   if (filtersMd || paginationMd) {
 %>
-## Bộ lọc & phân trang (List filters & pagination) {#list-filters-pagination}
+## List filters & pagination {#list-filters-pagination}
 
 <% if (filtersMd) { %>
-### Bộ lọc
+### Filters
 
 <%- filtersMd %>
 
 <% } %>
 <% if (paginationMd) { %>
-### Phân trang
+### Pagination
 
 <%- paginationMd %>
 
@@ -248,7 +285,7 @@ Hợp đồng backend: `api/<seq>/01-backend-spec.yaml` trong cùng function lea
   const validationTableMd = context.renderValidationDictionaryTable(pageSections);
   if (validationTableMd) {
 %>
-## Danh Mục Trường Nhập Liệu & Quy Tắc Kiểm Tra Hợp Lệ (Data Dictionary & Validation) {#data-dictionary--validation}
+## Data dictionary & validation {#data-dictionary--validation}
 
 <%- validationTableMd %>
 
@@ -268,19 +305,28 @@ Hợp đồng backend: `api/<seq>/01-backend-spec.yaml` trong cùng function lea
   const actionFlowsMd = context.renderActionFlowsDetailed(pageActions);
   if (actionFlowsMd) {
 %>
-## Đặc Tả Quy Trình Hành Động (Action Flows) {#action-flows}
+## Action flows {#action-flows}
 
 <%- actionFlowsMd %>
 
 <% } else { %>
-## Bố cục màn hình {#page-composition}
+## Page composition {#page-composition}
 
 <%- context.renderPageComposition(page, { businessOnly: true }) %>
 <% } %>
 
+<% if (qaOpen) { %>
+## Appendix — open questions {#appendix-open-questions}
+
+Câu hỏi treo (SSOT): [qa/index.md](../../qa/index.md)
+
+**ID trên leaf:** `<%= spec['Q&A'] %>`
+
+<% } %>
+
 <% 
   const skipKeys = new Set([
-    'id', 'page-id', 'title', 'summary', 'successMetrics', 'nonGoals', 'userStories', 'acceptance', 'ui', 'design', 'legacy', 'review', 'template',
+    'id', 'page-id', 'title', 'summary', 'successMetrics', 'scopeIn', 'nonGoals', 'userFlows', 'nfr', 'userStories', 'acceptance', 'ui', 'design', 'legacy', 'review', 'template', 'entities', 'relationships',
     'nav', 'sections', 'zones', 'behavior', 'actions', 'stateMatrix', 'grillStatus', 'specOrigin',
     'status', 'owner', 'schema', 'qa', 'Q&A', 'pendingTechDebt', 'i18n', 'gen', '_meta'
   ]);

package/templates/shared/feature.bundle.yaml

@@ -6,7 +6,7 @@ title: Feature title
 status: draft
 owner: portal-team
 
-# 1. BẢN TÓM TẮT TỔNG QUAN (ARC42 BUSINESS SUMMARY)
+# 1. TỔNG QUAN NGHIỆP VỤ (PRD — mặt đọc BA)
 summary: |
   - mục tiêu nghiệp vụ (business_goals): [Nêu rõ vấn đề đang giải quyết và giá trị kinh tế/nghiệp vụ mang lại. Viết sâu sắc để Stakeholder hiểu rõ vì sao phải làm.]
   - các bên liên quan (stakeholders): [Ai dùng, ai hưởng lợi, ai quản lý?]
@@ -17,13 +17,22 @@ summary: |
     - output: [Kết quả đầu ra]
   - cách giải quyết (solution): [Tuỳ chọn. Ghi kỹ thuật phức tạp nếu có.]
 
-successMetrics: |
-  - [Chỉ số đo được khi màn/feature đạt mục tiêu — VD: thời gian hoàn tất thao tác, tỷ lệ lỗi validation]
-  - [Bỏ bullet nếu chưa có số — ghi qualitative metric]
+scopeIn: |
+  - [Trong phạm vi màn/phase này — bullet rõ việc màn làm]
+  - [VD: xem danh sách, lọc, mở chi tiết từ dòng bảng]
 
 nonGoals: |
-  - [Phạm vi KHÔNG làm trên màn/phase này — tránh scope creep]
-  - [VD: không xử lý export Excel tại màn list — defer QA/debt]
+  - [Ngoài phạm vi — tránh scope creep]
+  - [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]
+
+nfr: |
+  - **Hiệu năng:** [VD: danh sách < 2s với 10k bản ghi — phân trang server]
+  - **Bảo mật:** [VD: RBAC theo role; audit log thao tác nhạy cảm]
+
+# Rủi ro: KHÔNG khai báo trên bundle — chỉ architecture/11-risks/risk-register.md
 
 userStories:
   primary:

package/templates/shared/ir/generated/spec.md

@@ -1,22 +1,22 @@
 
 # Feature title
 
-## Mục lục (Contents)
-
-1. [Tổng quan](#overview)
-2. [Chỉ số thành công](#success-metrics)
-3. [Phạm vi không làm](#non-goals)
-4. [User stories và hành trình màn hình](#user-stories--screen-journey)
-5. [Ma trận trạng thái và phân quyền](#state--permission-matrix)
-6. [Bảng cột danh sách](#list-columns)
-7. [Từ điển dữ liệu và validation](#data-dictionary--validation)
-8. [Widget tùy biến](#custom-widgets)
-9. [Luồng hành động](#action-flows)
+## Table of contents
+
+1. [Overview](#overview)
+2. [Success metrics](#success-metrics)
+3. [Out of scope](#non-goals)
+4. [User stories & requirements](#user-stories--screen-journey)
+5. [State & permissions matrix](#state--permission-matrix)
+6. [List columns](#list-columns)
+7. [Data dictionary & validation](#data-dictionary--validation)
+8. [Custom widgets](#custom-widgets)
+9. [Action flows](#action-flows)
 - [API SSOT](#api-ssot)
 
 ---
 
-## Tổng quan {#overview}
+## Overview {#overview}
 
 | | |
 | --- | --- |
@@ -44,7 +44,7 @@
 
 
 
-## Chỉ số thành công {#success-metrics}
+## Success metrics {#success-metrics}
 
 - [Chỉ số đo được khi màn/feature đạt mục tiêu — VD: thời gian hoàn tất thao tác, tỷ lệ lỗi validation]
 - [Bỏ bullet nếu chưa có số — ghi qualitative metric]
@@ -53,7 +53,7 @@
 
 
 
-## Phạm vi không làm {#non-goals}
+## Out of scope {#scope-out}
 
 - [Phạm vi KHÔNG làm trên màn/phase này — tránh scope creep]
 - [VD: không xử lý export Excel tại màn list — defer QA/debt]
@@ -68,14 +68,14 @@ Hợp đồng backend: `api/<seq>/01-backend-spec.yaml` trong cùng function lea
 - **Data model (review, multi-table):** [data-model.md](./data-model.md) — bảng/cột tách khỏi spec BA; SSOT codegen = `01` + `ir/design.yaml` `db`.
 
 
-## User Stories & Screen Journey {#user-stories--screen-journey}
+## User stories & requirements {#user-stories--screen-journey}
 
 
 
-### User Story Chính
-> **Là một** [Persona / Role - vd: Nhân viên Vận hành / Khách hàng / Quản trị viên],  
-> **Tôi muốn** [Hành động chính trên màn hình: xem danh sách, lọc, tạo mới, cập nhật, phê duyệt...],  
-> **Để** [Mục đích kinh doanh và giá trị thực tế đạt được].
+### Primary user story
+> **As a** [persona / role],  
+> **I want** [primary action on this screen],  
+> **so that** [business outcome].
 
 
 
@@ -192,7 +192,7 @@ Hợp đồng backend: `api/<seq>/01-backend-spec.yaml` trong cùng function lea
 
 
 
-## Ma Trận Trạng Thái Giao Diện & Phân Quyền (State & Permission Matrix) {#state--permission-matrix}
+## State & permissions matrix {#state--permission-matrix}
 
 | Trạng Thái Bản Ghi (Record Status) | Trạng Thái Trường Form (Fields State) | Nút Hành Động Khả Dụng (Visible Buttons) | Ghi Chú Phân Quyền RBAC (Role Overrides) |
 | --- | --- | --- | --- |
@@ -204,7 +204,7 @@ Hợp đồng backend: `api/<seq>/01-backend-spec.yaml` trong cùng function lea
 
 
 
-## Bảng cột danh sách (List columns) {#list-columns}
+## List columns {#list-columns}
 
 | Nhãn cột | Key | Ý nghĩa nghiệp vụ | Mục đích UI | Widget / render | Sort | DB (schema.field) |
 | --- | --- | --- | --- | --- | --- | --- |
@@ -215,7 +215,7 @@ Hợp đồng backend: `api/<seq>/01-backend-spec.yaml` trong cùng function lea
 
 
 
-## Danh Mục Trường Nhập Liệu & Quy Tắc Kiểm Tra Hợp Lệ (Data Dictionary & Validation) {#data-dictionary--validation}
+## Data dictionary & validation {#data-dictionary--validation}
 
 | Tên Trường (Label) | Mã Kỹ Thuật (Key) | Kiểu (Type) | Bắt Buộc? | Ràng Buộc & Quy Tắc Hợp Lệ (Rules) | Thông Báo Lỗi Inline (Messages) |
 | --- | --- | --- | --- | --- | --- |
@@ -229,7 +229,7 @@ Hợp đồng backend: `api/<seq>/01-backend-spec.yaml` trong cùng function lea
 
 <div id="custom-widgets"></div>
 
-## Đặc Tả Khối Giao Diện Tùy Biến (Custom UI Blocks)
+## Custom widgets {#custom-widgets}
 
 ### Khối Tùy Biến (`custom`)
 - **Mục đích thao tác:** Theo dõi tiến độ xử lý và xem chi tiết phản hồi từng bước duyệt
@@ -238,7 +238,7 @@ Hợp đồng backend: `api/<seq>/01-backend-spec.yaml` trong cùng function lea
 
 
 
-## Đặc Tả Quy Trình Hành Động (Action Flows) {#action-flows}
+## Action flows {#action-flows}
 
 ### Lưu & Xác Nhận
 - **Mục đích thao tác:** Thẩm định toàn bộ form và gửi dữ liệu lên máy chủ

package/templates/shared/tpl-api-contract.md

@@ -6,7 +6,7 @@
 
 ---
 
-## Đọc trước khi viết (global)
+## Read before writing (global)
 
 | Ai | Đọc gì trên VitePress / docs hub | Khi nào mở YAML `01` |
 |----|-----------------------------------|----------------------|
@@ -19,7 +19,7 @@ Sau `flowgrid split` + `flowgrid render`: sidebar leaf **Spec · W-*** · **Data
 
 ---
 
-## Bộ trio trên function leaf
+## Function leaf trio
 
 ```text
 surfaces/<surface>/CMP-*/<NN…>/<slug>/
@@ -42,7 +42,7 @@ surfaces/<surface>/CMP-*/<NN…>/<slug>/
 
 ---
 
-## Cấu trúc `01` (tóm tắt field)
+## `01` structure (field summary)
 
 Mẫu đầy đủ: [`backend-api.yaml`](./backend-api.yaml) (sau `flowgrid init` → `.flowgrid/templates/backend-api.yaml`).
 
@@ -108,7 +108,7 @@ Skill: `/openapi` · Redoc/Swagger UI: `openapi_build_ui` (tùy hub).
 
 ---
 
-## YAML an toàn
+## Safe YAML
 
 - Chuỗi có `:` → bọc `"..."`.
 - Chạy `flowgrid api:check` trước handoff.
@@ -116,7 +116,7 @@ Skill: `/openapi` · Redoc/Swagger UI: `openapi_build_ui` (tùy hub).
 
 ---
 
-## Liên kết bundle FE
+## FE bundle link
 
 Trên bundle chỉ khai báo **hành vi UI** và `apiRefs`; chi tiết endpoint nằm trên `01`:
 

package/templates/tests-skeleton/cases/README.md

@@ -2,7 +2,7 @@
 
 Đặt `TC-*.yaml` mirror path function trên docs-hub (bỏ prefix `surfaces/`).
 
-Ví dụ docs: `surfaces/admin/CMP-ADM-002/02/01/login/` → `cases/admin/CMP-ADM-002/02/01/login/TC-*.yaml`
+Ví dụ docs: `surfaces/admin/CMP-ADM-ORD-01/02/01/login/` → `cases/admin/CMP-ADM-ORD-01/02/01/login/TC-*.yaml`
 
 - SSOT ghi: `TC-*.yaml` (`schemaVersion: 2`) — copy mẫu từ `../_templates/TC.example.yaml` (init từ harness).
 - SSOT đọc QA/Dev: `pnpm cases:render` → `TC-*.md` cùng thư mục — **không sửa tay** MD.