@shanyucoder/flowgrid 0.1.5 → 0.1.9

package/templates/shared/bundle-authoring.md

@@ -8,8 +8,10 @@ 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. |
 | `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 — 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`. |
+| `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. |
 | `legacy` | Legacy facts + evidence pointers |
 | `design` | Nested **`sections[]`** (card/container/form + `meaning` + `purpose` + `visual` + `interaction` + `validation` + `messages` + `states` + `bind`/`db`) · **`nav`** (`screenAccess` & `sidebar.hierarchy`) · `zones[]` fallback · `behavior` · **`actions[]`** (onSuccess, onSpecificError, backgroundTrigger) |
@@ -36,6 +38,39 @@ Hub: `docs/templates/feature.bundle.yaml` · split: `pnpm spec:split`
 - Missing hard facts → `#missing_info` on that field. Do not wait for grill to invent inventory.
 - `/grill-bqa`, `/grill-dev`, `/grill-docs` only re-check, fill gaps, or fix conflicts.
 
+## Data model — Phase 0 ERD vs screen detail {#data-model--phase-0-erd-vs-screen-detail}
+
+**Phase 0 (không viết trong `/spec` session đầu nếu chưa có):** `/db-erd` → `<LCA>/common/db-erd.md` (Mermaid ER, ownership). Workflow: [architecture-data.md](../../docs/workflows/architecture-data.md).
+
+**Phase 1 — trên leaf bundle (bắt buộc khi field persisted):**
+
+| Chỗ ghi | Nội dung |
+|---------|----------|
+| `spec.entities[]` | Entity **của màn** (name, mô tả ngắn, link entity ER) — mirror subset ERD, không copy full diagram |
+| `spec.relationships[]` | Quan hệ màn này đọc/ghi (optional) |
+| `design.sections[].items[].db` | `schema` (table hoặc tên khớp ERD), `field` (column), `enumMapping` cho select/chip |
+| `design.sections[].items[].bind` | `field` — tên payload form/API (có thể camelCase khác column DB) |
+| `spec.ui.list.columns[]` | `key` khớp `bind.field` hoặc cột DB; cột chỉ tính toán → `#derived-data`, không `db` |
+| `spec.ui.form` / `detail` fields | Cùng quy tắc `bind` + `db` trên từng control |
+
+**Quy tắc:**
+
+- Có `validation` trên control persisted → **phải** có `db.field` (hoặc QA defer) trừ khi field pure UI (`#derived-data`).
+- `meaning` = nghiệp vụ; `db` = vật lý — không gộp một dòng chung trong `requirements`.
+- Split: `entities` + `db` → **`ir/design.yaml`**; BA MD generated **không** render `db` (dev đọc IR / `01`).
+- Grill-dev: `01.modules[].entities[].fields` phải **khớp** tập `db.field` màn (review tay; `#update:*` khi đổi).
+
+**Không:** dump SQL migration; thay `db-erd.md` bằng `entities: []` rỗng khi form có >3 field persisted.
+
+**Review (multi-table):**
+
+| Artifact | Ai đọc |
+|----------|--------|
+| `design.dataModel` | BA/lead — vai trò từng bảng (`tables[].roleOnScreen`, `summary`) — mẫu [tpl-screen-data-model.md](./tpl-screen-data-model.md) |
+| `ir/generated/data-model.md` | Sau `flowgrid split` — bảng/cột gom theo `schema`; link từ `spec.md` |
+| `api/.../01-backend-spec.yaml` | BE codegen — `modules[].entities[]` + `fields[]` khớp `db` trên design |
+| `flowgrid audit spec` | `confirms[]` `CONFIRM_DB_*` → AskQuestion (extract `db-audit-wizard.md`); không chặn split |
+
 ## spec (design v1) — có
 
 - `actors`, `entities`, `relationships`
@@ -76,8 +111,9 @@ Authoring (`/spec`, grill-*) still **writes** `*.bundle.yaml`, then split.
 | `*.bundle.yaml` | **Ghi** `/spec`, grill-*; **đọc cả file** `/testcase`, `/grill-testcase` | Đầy đủ spec+gen+design+`userStories`; tests hub read-only |
 | `ir/design.yaml` | **Đọc cả file** — grill-*, FE `/prototype`, codegen | Tech sau split; `api` chiếu từ 01. |
 | `ir/spec.yaml` | VitePress + stakeholder | Business page + requirements/acceptance. Không id/tag/bind. `"Q&A"`. Không stub `legacy` rỗng. |
-| `…/api/<seq>/01-backend-spec.yaml` | BE `/api`, `openapi:gen`, **author API** | Tech BE — SSOT duy nhất cho endpoint |
-| `<slug>.md` | Người (BA/QA) | Render từ **`ir/spec.yaml`** (chưa split thì không có trang) |
+| `…/api/<seq>/01-backend-spec.yaml` | BE `/api`, `openapi_gen`, **author API** | Tech BE — SSOT duy nhất cho endpoint |
+| `ir/generated/data-model.md` | BA/lead/BE review | Bảng/cột theo `schema` (multi-table); sinh từ `ir/design.yaml` |
+| `ir/generated/spec.md` · `ir/generated/api.md` | BA/QA/Dev review (VitePress) | Render từ `ir/spec.yaml` + `01`; hướng dẫn API: [tpl-api-contract.md](./tpl-api-contract.md) |
 
 Không còn `ir/legacy.yaml`. `legacy:` trên `ir/spec.yaml` chỉ khi có evidence thật.
 
@@ -267,13 +303,14 @@ actions:
 
 YAML only per schema. No explanation. No markdown.
 
-## Questions: AskQuestion wizard or hub `qa/open/`
+## Questions: AskQuestion wizard or hub `qa/`
 
 Do **not** write `openQuestions` anywhere. Schema/render không còn field này.
 
 - Member trả lời **ngay:** AskQuestion (options + Recommended + **Other**) → **STOP** → ghi field thật.
-- Member chọn **Other** mà **chưa quyết:** `.cursor/extracts/qa-inbox.md` → `qa/open/QA-<bundle.id>-NNNN.yaml`. Đóng sau bằng **`/qa-resolve <id>` + giải pháp**.
-- `grillStatus` có thể `done` khi vẫn còn file QA.
+- Member chọn **Log as Tech Debt:** copy `.flowgrid/templates/qa-item.yaml` — quy tắc field/timeline: **`qa-authoring.md`** · extract `qa-inbox.md`.
+- Đóng sau bằng **`/qa-resolve <id>` + giải pháp** (append `kind: answer`, `status: closed`).
+- `grillStatus` có thể `done` khi vẫn còn file QA `status: open`.
 
 ## YAML Syntax & Escaping Rules
 
@@ -282,7 +319,7 @@ Do **not** write `openQuestions` anywhere. Schema/render không còn field này.
 
 ## ir/spec.yaml vs ir/design.yaml
 
-`pnpm spec:split` ghi hai file. FlowGrid bộ docs grill **không** đọc `ir/*` khi author — chỉ bundle. Split ghi `"Q&A":` trên **`ir/spec.yaml`** (id `QA-<bundle.id>-NNNN` cách nhau bởi `, `) từ `qa/open/` — không nhét list vào bundle.
+`pnpm spec:split` ghi hai file. FlowGrid bộ docs grill **không** đọc `ir/*` khi author — chỉ bundle. Split ghi `"Q&A":` trên **`ir/spec.yaml`** (id `QA-<bundle.id>-NNNN` cách nhau bởi `, `) từ `qa/` — không nhét list vào bundle.
 
 Downstream (UI gen, API gen, testcase) đọc **chỉ `ir/design.yaml`**. Thiếu file = split/spec chưa xong. Story/copy chưa đủ thì **bổ sung design** (bundle.gen + split), không đọc `ir/spec.yaml`. `ir/spec.yaml` chỉ văn mô tả + `legacy` + `qa` (id treo).
 

package/templates/shared/default-layout.ejs

@@ -1,5 +1,64 @@
+<%
+  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 hasNonGoals = spec.nonGoals && String(spec.nonGoals).trim();
+  const hasStories = !!spec.userStories;
+  const pageSections = spec.sections || spec.design?.sections || [];
+  const pageActions = spec.actions || spec.design?.actions || [];
+  const pageStateMatrix = spec.stateMatrix || spec.design?.stateMatrix;
+  const hasState = !!pageStateMatrix;
+  const listUi = spec.ui?.list || {};
+  const hasListColumns = !!(context.renderListColumnsTable && context.renderListColumnsTable(listUi));
+  const hasListFilters = !!(context.renderListFiltersTable && context.renderListFiltersTable(listUi));
+  const hasListPagination = !!(listUi.pagination && typeof listUi.pagination === 'object');
+  const hasListExtras = hasListFilters || hasListPagination;
+  const hasValidation = !!(context.renderValidationDictionaryTable && context.renderValidationDictionaryTable(pageSections));
+  const hasCustomWidget = !!(context.renderCustomWidgetSpecs && context.renderCustomWidgetSpecs(pageSections));
+  const hasActions = pageActions && pageActions.length;
+  const hasReview = spec.review && (spec.review.layoutNotes || spec.review.summary);
+  const hasLegacy = spec.legacy && (spec.legacy.behaviors?.length || spec.legacy.fields?.length || spec.legacy.evidence?.length);
+  const hasDebt = spec.pendingTechDebt && spec.pendingTechDebt.length;
+
+  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)');
+
+  const route = spec.ui?.routes?.[0];
+  const routePath = route?.path || '';
+  const testId = route?.pageTestId || '';
+%>
 # <%= spec.title || spec.id %>
 
+## Mục lục (Contents)
+
+<%= toc.join('\n') %>
+
+---
+
+## Tổng quan {#overview}
+
+| | |
+| --- | --- |
+| **Page ID** | `<%= pageId || '—' %>` |
+| **Status** | <%= docStatus %> |
+| **Owner** | <%= docOwner || '—' %> |
+
 <% if (context.testcases && context.testcases.length) { %>
 - **Testcase plans:** <%= context.testcases.map(tc => '`' + (tc.data.title || tc.data.id || tc.file) + '`').join(' · ') %> (hub: [base_test](https://github.com/raintr91/base_test))
 <% } else { %>
@@ -7,24 +66,45 @@
 <% } %>
 
 <% 
-  const route = spec.ui?.routes?.[0];
-  const path = route?.path || '';
-  const testId = route?.pageTestId || '';
   let screenLine = '- **Screen:** None';
-  if (path) {
-    const screen = context.renderScreenLink ? context.renderScreenLink(path) : '`' + path + '`';
+  if (routePath) {
+    const screen = context.renderScreenLink ? context.renderScreenLink(routePath) : '`' + routePath + '`';
     const suffix = testId ? ` · \`${testId}\`` : '';
     screenLine = `- **Screen:** ${screen}${suffix}`;
   }
 %>
 <%= screenLine %>
 
+- **QA inbox:** [Danh sách câu hỏi treo](../../qa/index.md) (cùng 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}
+
+<%= spec.successMetrics %>
+
+<% } %>
+
+<% if (hasNonGoals) { %>
+## Phạm vi không làm {#non-goals}
+
+<%= 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--screen-journey}
 
 <% if (typeof spec.userStories === 'string') { %>
 <%= spec.userStories %>
@@ -114,11 +194,6 @@
 <% } %>
 
 <%
-  // 1. Executive Summary & Screen Journey
-  const pageSections = spec.sections || spec.design?.sections || [];
-  const pageActions = spec.actions || spec.design?.actions || [];
-  const pageStateMatrix = spec.stateMatrix || spec.design?.stateMatrix;
-
   const page = {
     nav: spec.nav || spec.design?.nav,
     sections: pageSections,
@@ -129,17 +204,51 @@
 %>
 
 <% if (pageStateMatrix) { %>
-## Ma Trận Trạng Thái Giao Diện & Phân Quyền (State & Permission Matrix)
+## Ma Trận Trạng Thái Giao Diện & Phân Quyền (State & Permission Matrix) {#state--permission-matrix}
 
 <%- context.renderStateMatrixTable(pageStateMatrix) %>
 
 <% } %>
 
+<% 
+  const listColumnsMd = context.renderListColumnsTable && context.renderListColumnsTable(listUi);
+  if (listColumnsMd) {
+%>
+## Bảng cột danh sách (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>
+
+<% } %>
+
+<% 
+  const filtersMd = context.renderListFiltersTable && context.renderListFiltersTable(listUi);
+  const paginationMd = context.renderListPaginationBlock && context.renderListPaginationBlock(listUi);
+  if (filtersMd || paginationMd) {
+%>
+## Bộ lọc & phân trang (List filters & pagination) {#list-filters-pagination}
+
+<% if (filtersMd) { %>
+### Bộ lọc
+
+<%- filtersMd %>
+
+<% } %>
+<% if (paginationMd) { %>
+### Phân trang
+
+<%- paginationMd %>
+
+<% } %>
+
+<% } %>
+
 <% 
   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)
+## Danh Mục Trường Nhập Liệu & Quy Tắc Kiểm Tra Hợp Lệ (Data Dictionary & Validation) {#data-dictionary--validation}
 
 <%- validationTableMd %>
 
@@ -149,6 +258,8 @@
   const customWidgetMd = context.renderCustomWidgetSpecs(pageSections);
   if (customWidgetMd) {
 %>
+<div id="custom-widgets"></div>
+
 <%- customWidgetMd %>
 
 <% } %>
@@ -157,17 +268,19 @@
   const actionFlowsMd = context.renderActionFlowsDetailed(pageActions);
   if (actionFlowsMd) {
 %>
-## Đặc Tả Quy Trình Hành Động (Action Flows)
+## Đặc Tả Quy Trình Hành Động (Action Flows) {#action-flows}
 
 <%- actionFlowsMd %>
 
 <% } else { %>
+## Bố cục màn hình {#page-composition}
+
 <%- context.renderPageComposition(page, { businessOnly: true }) %>
 <% } %>
 
 <% 
   const skipKeys = new Set([
-    'id', 'page-id', 'title', 'summary', 'userStories', 'acceptance', 'ui', 'design', 'legacy', 'review', 'template',
+    'id', 'page-id', 'title', 'summary', 'successMetrics', 'nonGoals', 'userStories', 'acceptance', 'ui', 'design', 'legacy', 'review', 'template',
     'nav', 'sections', 'zones', 'behavior', 'actions', 'stateMatrix', 'grillStatus', 'specOrigin',
     'status', 'owner', 'schema', 'qa', 'Q&A', 'pendingTechDebt', 'i18n', 'gen', '_meta'
   ]);
@@ -187,7 +300,7 @@
 <% }); %>
 
 <% if (spec.pendingTechDebt && spec.pendingTechDebt.length) { %>
-## Pending tech debt
+## Pending tech debt {#pending-tech-debt}
 
 | ID | Status | Summary |
 | --- | --- | --- |
@@ -198,7 +311,7 @@
 <% } %>
 
 <% if (spec.review && (spec.review.layoutNotes || spec.review.summary)) { %>
-## Review — layout notes
+## Review — layout notes {#review-notes}
 
 <% if (spec.review.layoutNotes) { %>
 <% if (Array.isArray(spec.review.layoutNotes)) { %>
@@ -210,7 +323,7 @@
 <% } %>
 
 <% if (spec.legacy && (spec.legacy.behaviors?.length || spec.legacy.fields?.length || spec.legacy.evidence?.length)) { %>
-## Legacy evidence
+## Legacy evidence {#legacy-evidence}
 
 <% if (spec.legacy.behaviors && spec.legacy.behaviors.length) { %>
 ### Behaviors

package/templates/shared/design-spec.yaml

@@ -1,6 +1,5 @@
-# Design spec v1 — /spec (round 1)
-# Do NOT add codegen, ui.filters, ui.columns, or portal-gen tags here.
-# After /grill-docs → see docs/templates/spec.yaml (portal-gen-ready).
+# DEPRECATED — không author leaf mới. SSOT: feature.bundle.yaml + bundle-authoring.md
+# File giữ cho repo cũ / tham chiếu shape spec (design v1). /spec skill → chỉ bundle.
 
 id: role-page-function
 title: Feature title

package/templates/shared/design.registry.base.json

@@ -0,0 +1,38 @@
+{
+  "version": 1,
+  "canonicalSystem": "flowgrid-fe",
+  "description": "Design DSL registry (UI shells, #ui, Mo*). Refresh with flowgrid registry:sync after base changes.",
+  "defaults": {
+    "shellByProfile": {
+      "list": "DataListPage",
+      "create": "DataFormPage",
+      "detail": "DataDetailPage",
+      "admin-crud": "DataListPage",
+      "auth": "AuthShell"
+    }
+  },
+  "shells": {
+    "DataListPage": {
+      "tag": "#shell: DataListPage",
+      "portal": { "status": "planned", "path": "components/organisms/DataListPage.vue" },
+      "portalGen": {
+        "templateStandard": "list/page-standard",
+        "templateCustom": "list/page-custom"
+      }
+    },
+    "DataFormPage": {
+      "tag": "#shell: DataFormPage",
+      "portal": { "status": "planned", "path": "components/organisms/DataFormPage.vue" }
+    },
+    "DataDetailPage": {
+      "tag": "#shell: DataDetailPage",
+      "portal": { "status": "planned", "path": "components/organisms/DataDetailPage.vue" }
+    }
+  },
+  "fieldWidgets": {},
+  "componentAliases": {},
+  "aliasIndex": {},
+  "components": {},
+  "composables": {},
+  "helpers": {}
+}

package/templates/shared/feature.bundle.yaml

@@ -1,6 +1,4 @@
-# SSOT — portal-feature-bundle/v1. Split: pnpm spec:split -- <path>
-# Authoring: docs/templates/bundle-authoring.md
-# /spec MUST fill inventory when information exists. grill-* only re-checks gaps/conflicts.
+# portal-feature-bundle/v1 — Authoring: bundle-authoring.md · Split: flowgrid split <path>
 
 schema: portal-feature-bundle/v1
 page-id: role-domain-function
@@ -19,7 +17,14 @@ 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ó.]
 
-# 2. KHỐI USER STORIES CHI TIẾT CHO MÀN HÌNH (SCREEN USER STORIES & SCENARIOS)
+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]
+
+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]
+
 userStories:
   primary:
     asA: "[Persona / Role - vd: Nhân viên Vận hành / Khách hàng / Quản trị viên]"
@@ -27,10 +32,7 @@ userStories:
     soThat: "[Mục đích kinh doanh và giá trị thực tế đạt được]"
 
   contextAndHandoff:
-    # 3 LOẠI CÁCH THỨC VÀO MÀN HÌNH (SCREEN ACCESS ENTRY MODE):
-    # - directRoute: Dành cho Login, Register, Public/Guest Page (mô tả path router)
-    # - sidebarMenu: Dành cho Dashboard, CRUD List, Admin Pages (mô tả menu đa cấp dropdown + label text)
-    # - contextualAction: Dành cho Detail, Edit Modal, Settings (mô tả nút bấm xxx từ màn hình A)
+    # screenAccess: directRoute | sidebarMenu | contextualAction — xem bundle-authoring.md
     screenAccess:
       accessType: sidebarMenu # directRoute | sidebarMenu | contextualAction
       directRoute:
@@ -74,7 +76,6 @@ userStories:
         - "Hệ thống khóa nút và hiển thị loading để chống bấm đúp (double submit prevention)."
         - "Lưu dữ liệu thành công (không phải xóa): Toast hoặc inline alert; điều hướng theo Handoff. Thao tác xóa — xem scenario UX affordances bên dưới."
 
-    # Thêm scenario này khi màn có delete/breadcrumb/filter/disabled reason / import CSV (sau audit UX_* hoặc DSL gap).
     - name: "Affordances UX chuẩn portal (UX — khi áp dụng)"
       steps:
         - "Breadcrumb / ngữ cảnh: Người dùng luôn biết đang ở module và bản ghi nào (trail hoặc back + title rõ)."
@@ -194,6 +195,12 @@ gen:
     testIds: null
 
 design:
+  # dataModel:  # optional — multi-table review; xem tpl-screen-data-model.md
+  #   erdRef: "<LCA>/common/db-erd.md"
+  #   tables:
+  #     - schema: records
+  #       roleOnScreen: read-write
+  #       summary: "Hồ sơ chính trên form"
   inherits: null
   shell:
     tag: "#shell: DataListPage" # AuthPage | AppShell