@shanyucoder/flowgrid 0.1.5 → 0.1.8

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

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

@@ -0,0 +1,281 @@
+
+# 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)
+- [API SSOT](#api-ssot)
+
+---
+
+## Tổng quan {#overview}
+
+| | |
+| --- | --- |
+| **Page ID** | `role-domain-function` |
+| **Status** | draft |
+| **Owner** | portal-team |
+
+
+- **Testcase plans:** [base_test](https://github.com/raintr91/base_test) (`pnpm cases:render` on tests hub) — see docs-hub TESTS-HUB
+
+
+
+- **Screen:** None
+
+
+- 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ý?]
+- kịch bản người dùng (user_journey): [Kể câu chuyện người dùng trải qua các bước trên màn hình bằng ngôn ngữ đời thường.]
+- bối cảnh (context):
+  - description: [Phân tích sâu luồng nghiệp vụ chi tiết]
+  - input: [Dữ liệu đầu vào. CHÚ Ý liên kết cross-page / cross-module nếu có]
+  - 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ó.]
+
+
+
+
+## Chỉ số thành công {#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]
+
+
+
+
+
+## Phạm vi không làm {#non-goals}
+
+- [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]
+
+
+
+
+## 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 tách khỏi spec BA; SSOT codegen = `01` + `ir/design.yaml` `db`.
+
+
+## User Stories & Screen Journey {#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].
+
+
+
+### Cách thức Truy cập & Chuyển giao Màn hình (Screen Access & Handoff)
+
+
+- **Loại truy cập (Access Type):** `sidebarMenu`
+
+  - **Menu Sidebar:** Quản trị hệ thống &gt; Quản lý Người dùng > **Danh sách tài khoản**
+
+
+- **Màn hình nguồn (Source Screen):** `W-ADM-LIST-01`
+
+- **Dữ liệu tiếp nhận (Inputs):** customer_id · booking_id
+
+- **Điều hướng tiếp theo (Next Screen):** `W-ADM-DETAIL-01`
+
+
+
+### Kịch bản Chi tiết trên Màn hình (Scenarios)
+
+#### Khởi tạo &amp; Tải dữ liệu ban đầu (Initial Load)
+
+
+- Kiểm tra quyền hạn người dùng (Role / Permissions) đối với màn hình.
+
+- Tải danh sách dữ liệu theo bộ lọc mặc định hoặc bind thông tin bản ghi theo ID nhận được.
+
+- Hiển thị trạng thái tải (Skeleton / Spinner), nếu không có dữ liệu hiển thị Empty State.
+
+
+
+#### Tương tác Nhập liệu &amp; Thẩm định Dữ liệu (Input &amp; Validation)
+
+
+- Người dùng nhập liệu các trường bắt buộc và tùy chọn trên form.
+
+- Hệ thống validate trực tiếp trên giao diện (Inline error) khi nhập sai định dạng hoặc bỏ trống.
+
+- Các trường có logic phụ thuộc tự động cập nhật hoặc mở thêm vùng nhập (Dynamic visibility / calculation).
+
+
+
+#### Nộp dữ liệu &amp; Hoàn tất Thành công (Happy Path Submit)
+
+
+- Người dùng nhấn nút thực thi chính (Primary Action Button).
+
+- 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.
+
+
+
+#### Affordances UX chuẩn portal (UX — khi áp dụng)
+
+
+- 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õ).
+
+- Danh sách: Tìm kiếm/lọc (nếu có) và phân trang; empty state khác &#39;không có kết quả filter&#39;.
+
+- Cột trạng thái: Hiển thị chip/badge có chữ, không chỉ màu.
+
+- Hành động trên dòng bị khóa: Có lý do hiển thị (tooltip/badge/chip), không chỉ nút disabled im lặng.
+
+- Xóa / xóa hàng loạt: Hộp thoại xác nhận chặn → gọi API → hộp thoại kết quả (thành công/lỗi) bắt người dùng xác nhận — không chỉ toast.
+
+- Import CSV (nếu có): Chọn file → kiểm tra → xác nhận → báo kết quả; lỗi theo dòng có thể tải log.
+
+
+
+#### Xử lý Ngoại lệ &amp; Lỗi Giao diện (Exceptions &amp; Edge Cases)
+
+
+- Xung đột dữ liệu / Đã bị sửa đổi bởi người khác (409 Conflict): Cảnh báo và tải lại.
+
+- Lỗi kết nối / Máy chủ (Network / 5xx error): Giữ nguyên dữ liệu đã nhập trên form, không bắt nhập lại.
+
+- Hết hạn phiên làm việc (Session timeout): Yêu cầu xác thực lại và bảo lưu tạm bản nháp.
+
+
+
+#### Tác vụ Ngầm Kích hoạt từ Màn hình (Background / Async Logic - Tùy chọn)
+
+
+- Nếu thao tác kích hoạt xử lý ngầm (gửi tin nhắn, tạo job đồng bộ): Hệ thống đẩy sự kiện vào hàng đợi.
+
+- Cập nhật trạng thái hiển thị trên màn hình thành &#39;Đang xử lý ngầm&#39; (Processing) để người dùng theo dõi.
+
+
+
+
+
+
+### Tiêu chí Nghiệm thu (Acceptance Criteria)
+
+- [ ] [ ] Người dùng có quyền truy cập xem được toàn bộ thông tin hợp lệ.
+
+- [ ] [ ] Form chặn nộp khi thiếu các trường bắt buộc và thông báo lỗi rõ ràng.
+
+- [ ] [ ] Khi nộp thành công (không phải delete), dữ liệu được lưu đúng và chuyển trang mượt mà.
+
+- [ ] [ ] (Khi có delete) Confirm trước xóa và result dialog sau API — không toast-only.
+
+- [ ] [ ] (Khi có action disabled theo rule) Người dùng hiểu lý do bị khóa (copy/badge/tooltip).
+
+- [ ] [ ] (Khi list/detail drill-down) Breadcrumb hoặc ngữ cảnh điều hướng đủ cho deep link.
+
+
+
+
+
+
+
+
+
+## Ma Trận Trạng Thái Giao Diện & Phân Quyền (State & Permission 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) |
+| --- | --- | --- | --- |
+| `DRAFT` | ✏️ Cho phép sửa (Editable) | `btn_save_draft`, `btn_submit_record`, `btn_cancel` | Áp dụng cho mọi vai trò |
+| `PENDING_APPROVAL` | 🔒 Chỉ đọc (Readonly) | `btn_cancel_request` | **manager**: Nút khả dụng [`btn_approve`, `btn_reject`] |
+| `APPROVED` | 🔒 Chỉ đọc (Readonly) | `btn_print`, `btn_export` | Áp dụng cho mọi vai trò |
+| `REJECTED` | ✏️ Cho phép sửa (Editable) | `btn_resubmit`, `btn_delete` | Áp dụng cho mọi vai trò |
+
+
+
+
+## Bảng cột danh sách (List columns) {#list-columns}
+
+| Nhãn cột | Key | Ý nghĩa nghiệp vụ | Mục đích UI | Widget / render | Sort | DB (schema.field) |
+| --- | --- | --- | --- | --- | --- | --- |
+| Trạng thái | `status` | Tình trạng hoạt động của tài khoản trong hệ thống để quản lý quyền đăng nhập và giao dịch | Cho user thấy tài khoản còn hoạt động hay đã bị tạm khóa | chip / custom | Không | — |
+
+<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>
+
+
+
+
+## Danh Mục Trường Nhập Liệu & Quy Tắc Kiểm Tra Hợp Lệ (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) |
+| --- | --- | --- | --- | --- | --- |
+| Mã hồ sơ | `N/A` | input | Bắt buộc | Kiểu: `slug_uppercase`<br>Regex: `^[A-Z0-9_-]{5,20}$`<br>Độ dài [5, 20]<br>Unique DB: `/api/v1/records/check-duplicate-code` | Required: "Vui lòng nhập mã hồ sơ."<br>"Mã hồ sơ chỉ được gồm chữ in hoa, chữ số và ký tự gạch (- _)"<br>"Độ dài mã hồ sơ bắt buộc từ 5 đến 20 ký tự"<br>DB: "Mã hồ sơ này đã tồn tại trên hệ thống. Vui lòng chọn mã khác." |
+| Tên hồ sơ | `N/A` | input | Bắt buộc | Kiểu: `text_clean`<br>Độ dài [3, 100] | Required: "Vui lòng nhập tên hồ sơ."<br>"Tên hồ sơ bắt buộc từ 3 đến 100 ký tự" |
+| Cấp độ dịch vụ | `N/A` | select | Bắt buộc | Kiểu: `enum` | Required: "Vui lòng chọn cấp độ dịch vụ." |
+| Yêu cầu đặc biệt cho gói VIP | `N/A` | textarea | Tùy chọn | Độ dài [0, 500]<br>Phụ thuộc: `service_level == 'PREMIUM'` | Required: "Vui lòng nhập yêu cầu đặc biệt khi đăng ký gói VIP."<br>"Yêu cầu đặc biệt không được vượt quá 500 ký tự." |
+
+
+
+
+<div id="custom-widgets"></div>
+
+## Đặc Tả Khối Giao Diện Tùy Biến (Custom UI Blocks)
+
+### 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
+
+
+
+
+
+## Đặc Tả Quy Trình Hành Động (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ủ
+- **Vị trí hiển thị:** `form_footer` | **Trigger:** `click` | **Variant:** `primary`
+
+### Hủy Bỏ
+- **Mục đích thao tác:** Hủy thao tác tạo mới và quay lại trang trước
+- **Vị trí hiển thị:** `form_footer` | **Trigger:** `click` | **Variant:** `outline`
+
+
+
+
+
+## actors
+
+
+```yaml
+[]
+```
+
+
+
+## requirements
+
+
+```yaml
+- &#34;[Ghi chú: Bắt buộc định nghĩa State Machine, và UI Permissions vào thuộc tính
+  states của từng item trong design.sections. KHÔNG liệt kê chung chung ở đây]&#34;
+- &#34;Edge Cases: [Bắt buộc định nghĩa ngoại lệ như lỗi luồng, data hỏng,
+  concurrency]&#34;
+```
+
+
+
+
+
+
+
+
+

package/templates/shared/qa-item.yaml

@@ -1,7 +1,7 @@
 # Copy to qa/open/QA-<bundle.id>-NNNN.yaml — do not leave this file in qa/open/.
 id: QA-cmp-adm-002-02-01-02-0001
 kind: customer # customer | choice | tech-debt
-skill: spec # spec | grill-bqa | grill-dev | grill-docs | api-spec | api-update | api-integration
+skill: spec # spec | grill-bqa | grill-dev | grill-docs | api-spec | api-update
 target:
   path: surfaces/<surface>/CMP-*/<NN…>/<slug>.bundle.yaml
   at: design.zones.main.items.title.purpose