@shanyucoder/flowgrid 0.1.5 → 0.1.9

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/ir-spec.yaml

@@ -14,5 +14,5 @@ actors: []
 requirements: []
 acceptance: []
 
-# Filled by spec:split from qa/open/QA-<id>-NNNN.yaml (comma-separated). Omit when none.
+# Filled by spec:split from qa/<SHORT>_NNNN.yaml (comma-separated). Omit when none.
 # "Q&A": QA-role-domain-function-0001, QA-role-domain-function-0002

package/templates/shared/qa-authoring.md

@@ -0,0 +1,78 @@
+# flowgrid-qa-item/v1 — authoring rules (QA inbox)
+
+Hub template: `.flowgrid/templates/qa-item.yaml` (sau `flowgrid init`) · Workflow: `docs/workflows/qa-team.md`
+
+## File naming
+
+| Part | Rule | Example |
+|------|------|---------|
+| **SHORT** | Slug màn/module, ổn định, `A-Z0-9` + `-` | `HOTEL-LIST`, `ADM-AUTH` |
+| **NNNN** | Tăng dần theo SHORT (0001…) | `0001`, `0002` |
+| **Path** | `qa/<SHORT>_<NNNN>.yaml` | `qa/HOTEL-LIST_0001.yaml` |
+| **id** | **Bắt buộc** = basename không `.yaml` | `HOTEL-LIST_0001` |
+
+Legacy id `QA-<page-id>-NNNN` vẫn đọc được — file mới dùng `<SHORT>_NNNN`.
+
+Gợi ý SHORT từ `W-HOTEL-LIST` → `HOTEL-LIST` (bỏ prefix `W-`). Team có thể chọn slug module cố định (vd. `ADM-AUTH` cho nhiều màn auth).
+
+## Top-level fields
+
+| Key | Required | Purpose |
+|-----|----------|---------|
+| `schema` | yes | Luôn `flowgrid-qa-item/v1` |
+| `id` | yes | Khớp tên file |
+| `status` | yes | `open` \| `closed` |
+| `target.path` | yes | Bundle hoặc `01-backend-spec.yaml` (repo-relative) |
+| `target.at` | yes | Pointer field — gắn `#missing_info <id>` / `#tech-debt:<id>` |
+| `updates` | yes | Timeline append-only (≥1 dòng) |
+| `screen` | khuyến nghị | `W-*` hoặc `page-id` — catalog + split |
+| `bundleId` | khi legacy | `page-id` bundle để `Q&A` trên `ir/spec.yaml` |
+| `kind` | khuyến nghị | `customer` \| `choice` \| `tech-debt` \| `integration` \| `coverage` |
+| `skill` | khuyến nghị | Skill mở gap: `spec`, `grill-dev`, `api-spec`, … |
+| `options` | optional | Copy options AskQuestion khi mở (audit) |
+| `tags` | optional | Mirror tag đã gắn trên spec |
+
+## `updates[]` (append-only)
+
+**Không** sửa/xóa dòng cũ. Chỉ **thêm** cuối mảng.
+
+| `kind` | Ai / khi |
+|--------|----------|
+| `question` | Mở QA (Log Tech Debt) — **dòng đầu** |
+| `answer` | `/qa-resolve` — sau khi patch `target.at` |
+| `review` | `/qa-review` — `approved:` hoặc `needs-change:` |
+| `note` | Ghi chú, không đổi spec |
+
+| `at` | Format **bắt buộc** | `20260930 08:00` (YYYYMMDD HH:mm) |
+| `by` | Member / role | `ba-lead`, `middle-dev` |
+| `text` | Nội dung | Block `\|` multiline |
+
+### Vòng đời status
+
+- Mở file: `status: open`, `updates[0].kind: question`
+- `/qa-resolve`: append `answer`, `status: closed`, gỡ tag trên spec
+- `/qa-review` + `needs-change`: append `review`, **`status: open`** lại (cùng file)
+
+## Agent workflow (mở QA)
+
+1. Đọc **whole** `.flowgrid/templates/qa-item.yaml` + file này.
+2. Chọn SHORT (team convention hoặc từ `screen`).
+3. `nextQaId(hub, SHORT)` hoặc glob `qa/<SHORT>_*.yaml` → max NNNN + 1.
+4. Copy template → `qa/<SHORT>_<NNNN>.yaml`; set `id`, `target`, `at` now, `updates[0]`.
+5. Patch spec: `#missing_info <id>` trên field `target.at`.
+6. `flowgrid split` + `flowgrid render`.
+
+## Agent output
+
+- **YAML only** khi tạo/sửa QA file — không markdown giải thích trong repo.
+- Quote string có `:`; multiline dùng `|`.
+
+## Không dùng QA file cho
+
+- ADR → `architecture/09-decisions`
+- Risk dài hạn → `architecture/11-risks`
+- `openQuestions` trên bundle — **cấm**
+
+## Schema
+
+Validate (optional CI): `templates/schemas/qa-item.schema.json` · `flowgrid` test `validateQaItem`.

package/templates/shared/qa-item.yaml

@@ -1,15 +1,36 @@
-# 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
+# flowgrid-qa-item/v1 — Authoring: qa-authoring.md · Hub: docs/workflows/qa-team.md
+# Copy to qa/<SHORT>_NNNN.yaml (id = basename without .yaml). Append-only updates[].
+
+schema: flowgrid-qa-item/v1
+id: HOTEL-LIST_0001
+screen: W-HOTEL-LIST
+bundleId: cmp-adm-000-01-01
+status: open
+kind: tech-debt
+skill: spec
+tags:
+  - "#missing_info HOTEL-LIST_0001"
 target:
-  path: surfaces/<surface>/CMP-*/<NN…>/<slug>.bundle.yaml
-  at: design.zones.main.items.title.purpose
-question: |
-  What is still unknown?
-options: []
-# - id: a
-#   text: Option A
-#   recommended: true
-# - id: other
-#   text: Member supplies copy
+  path: surfaces/<surface>/CMP-*/<slug>.bundle.yaml
+  at: design.sections.main.items.filter_timezone.purpose
+options:
+  - label: "(Recommended) Theo timezone property"
+    recommended: true
+  - label: Theo locale user
+updates:
+  - at: "20260930 08:00"
+    by: <member-id>
+    kind: question
+    text: |
+      Filter timezone lấy theo property hay user locale?
+# Append only — never delete or rewrite prior lines:
+#  - at: "20260930 10:00"
+#    by: ba-lead
+#    kind: answer
+#    text: |
+#      Theo property TZ; label UTC+7 trên UI.
+#  - at: "20261001 08:00"
+#    by: senior
+#    kind: review
+#    text: |
+#      needs-change: thêm AC khi property chưa set TZ.

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

@@ -0,0 +1,133 @@
+# Template — Hợp đồng API (review & authoring)
+
+**Mục đích:** Cùng một ngôn ngữ cho BA / Dev BE / Dev FE / QA — **đọc trên site**, **ghi trên YAML**. SSOT codegen BE là `api/<seq>/01-backend-spec.yaml`; OpenAPI và Markdown là **bản render**, không sửa tay làm nguồn.
+
+**Workflow:** [docs/workflows/backend.md](../../docs/workflows/backend.md) · Skills: `/api-spec`, `/grill-api-spec`, `/openapi`, `/api-update`.
+
+---
+
+## Đọc trước khi viết (global)
+
+| Ai | Đọc gì trên VitePress / docs hub | Khi nào mở YAML `01` |
+|----|-----------------------------------|----------------------|
+| BA / PO | `ir/generated/spec.md` (hành vi màn) + `ir/generated/api.md` (bảng endpoint tóm tắt) | Không — delta nghiệp vụ qua `/update-spec` + Dev |
+| QA | `spec.md` + `api.md` (phạm vi API khớp scenario) | Chỉ khi trace lỗi `#err:*` / status code |
+| Dev FE | `ir/design.yaml` (`apiRefs`, `#reuse-api`) | Không — contract BE không phải input layout |
+| Dev BE | `api.md` → `01` → (preview) `02` sau `openapi_gen` | Author `/api-spec`, grill, codegen |
+
+Sau `flowgrid split` + `flowgrid render`: sidebar leaf **Spec · W-*** · **Data model** · **API summary** (`api.md`).
+
+---
+
+## Bộ trio trên function leaf
+
+```text
+surfaces/<surface>/CMP-*/<NN…>/<slug>/
+  <slug>.bundle.yaml          # FE/business — KHÔNG author spec.api
+  ir/design.yaml              # apiRefs, actions — FE + audit fe-be
+  ir/generated/api.md         # render từ 01 (đọc team)
+  api/<seq>/
+    01-backend-spec.yaml      # SSOT BE — mẫu: backend-api.yaml
+    02-openapi.yaml           # CHỈ gen từ 01 (flowgrid openapi_gen)
+    03-mock.yaml              # optional — copy from api-03-mock.stub.yaml
+```
+
+**Common API** (auth, dropdown dùng chung): `…/common/yaml/<slug>/` — cùng bộ file, một primary entity.
+
+**Quy tắc:**
+
+- Một file `01` = một **module** + một **primary entity** — không gộp cả CMP.
+- Action đã có API: `#reuse-api` + `reuseFrom` trên `ir/design.yaml` — **không** tạo `api/<seq>/` mới.
+- URI có **hậu tố hành động** (`/create`, `/{id}/update`, `/list`, `/{id}/detail`) — không REST mơ hồ `PUT /users/{id}`.
+
+---
+
+## Cấu trúc `01` (tóm tắt field)
+
+Mẫu đầy đủ: [`backend-api.yaml`](./backend-api.yaml) (sau `flowgrid init` → `.flowgrid/templates/backend-api.yaml`).
+
+| Khối | Vai trò |
+|------|---------|
+| `feature` | id, title, version, `source` (portal vs `base: none`) |
+| `approval` | `draft` → `approved` trước `api-gen` (policy team) |
+| `modules[].entities[]` | Bảng, field, quan hệ — khớp `design.sections[].db` / ERD |
+| `api.endpoints[]` | method, path, `purpose`, `errorStorming`, `#err:*` |
+| `requests` / `responses` | DTO — `meaning`/`purpose` khi có validation nghiệp vụ |
+| `codegen` | `profile`, `module`, `entity` — grill-api-spec bổ sung `#gen:*` |
+| `externalCalls` / `services` | Chỉ khi có `#call-external` / `#cross-entity-service` |
+
+**Không** dùng [`backend-api.bundle.yaml`](./backend-api.bundle.yaml) để sinh `01` mới — file legacy (bundle lồng `spec.api`); chỉ tham chiếu lịch sử.
+
+---
+
+## OpenAPI (01 → 02 → hub)
+
+Chuỗi **bắt buộc** sau mỗi lần sửa `01`:
+
+```text
+flowgrid api:check --spec …/01-backend-spec.yaml
+flowgrid openapi_gen --spec …/01-backend-spec.yaml    # ghi sibling 02-openapi.yaml
+flowgrid openapi_render                               # gộp → docs/openapi/api.yaml (hub)
+flowgrid render                                       # cập nhật ir/generated/api.md
+```
+
+| File | SSOT? | Ai sửa |
+|------|-------|--------|
+| `01-backend-spec.yaml` | **Có** | `/api-spec`, `/api-update`, `/grill-api-spec` |
+| `02-openapi.yaml` | Không — output gen | Vá thiếu bằng cách sửa `01`, gen lại |
+| `docs/openapi/api.yaml` | Không — merge hub | `openapi_render` |
+| `ir/generated/api.md` | Không — đọc | `flowgrid render` |
+
+**Cấm:** sửa `02` tay; dùng `nestjs --openapi` (hoặc stack tương đương) ghi đè docs hub; `flowgrid check` trên `01` (`check` chỉ cho `*.bundle.yaml`).
+
+Skill: `/openapi` · Redoc/Swagger UI: `openapi_build_ui` (tùy hub).
+
+---
+
+## Portal-backed vs BE-only
+
+| | Portal (`source.base` ≠ `none`) | BE-only (`base: none`) |
+|--|--------------------------------|-------------------------|
+| Input `/api-spec` | `ir/design.yaml` + actions | Requirement / partner doc — **không** `ir/design` làm contract |
+| Grill | `audit fe-be` + `audit api` | `audit api` only |
+| `feature.source` | `portalSpec`, `portalRefs` | `integrationRefs`, auth API key/HMAC |
+
+---
+
+## Error storming (review nhanh)
+
+| Tình huống endpoint | Tag / status gợi ý |
+|---------------------|-------------------|
+| Có `{id}` trong path | `#err:not-found` (404), `#err:idor-violation` (403) |
+| POST/PUT form body | `#err:validation` (422) + field rules |
+| Có permission | `#err:permission-denied` (403) |
+| Create/duplicate | `#err:conflict` (409) |
+| Partner/webhook | `#err:signature-invalid`, `#err:rate-limit`, `#err:unauthorized` |
+
+401/503/500 toàn cục: thường `$ref` OpenAPI components — không lặp từng endpoint.
+
+---
+
+## YAML an toàn
+
+- Chuỗi có `:` → bọc `"..."`.
+- Chạy `flowgrid api:check` trước handoff.
+- Thiếu fact → AskQuestion hoặc `qa/` — **không** `openQuestions` trong YAML.
+
+---
+
+## Liên kết bundle FE
+
+Trên bundle chỉ khai báo **hành vi UI** và `apiRefs`; chi tiết endpoint nằm trên `01`:
+
+```yaml
+design:
+  actions:
+    - id: submit_form
+      apiRefs: [ feature.create ]
+      onSpecificError:
+        - condition: "422 Validation"
+          notes: "Inline errors"
+```
+
+Xem [bundle-authoring.md § design.actions](./bundle-authoring.md#designactions-api-calls--ui-error-handling).

package/templates/shared/tpl-screen-data-model.md

@@ -0,0 +1,76 @@
+# Template — Mô tả bảng trên màn (review, multi-table)
+
+**Mục đích:** Member/BA review **vai trò từng bảng** trước khi đọc cột chi tiết. SSOT kỹ thuật vẫn là `design.sections[].db` + `01-backend-spec.yaml`.
+
+**Sau `flowgrid split`:** engine sinh `ir/generated/data-model.md` (tự động). Block YAML dưới đây **bổ sung** overview — author trên bundle `design.dataModel`.
+
+---
+
+## Author trên bundle (`design.dataModel`)
+
+```yaml
+design:
+  dataModel:
+    erdRef: "<LCA>/common/db-erd.md"
+    notes: |
+      Màn này ghi bảng chính `records` và đọc `record_attachments` cho sidebar.
+      Không tạo dòng mới trên bảng phụ.
+    tables:
+      - schema: records
+        erdEntity: Record
+        roleOnScreen: read-write   # read | write | read-write | join | aggregate
+        summary: "Hồ sơ chính — form create/update"
+      - schema: record_attachments
+        erdEntity: RecordAttachment
+        roleOnScreen: read
+        summary: "File đính kèm — chỉ list & download"
+```
+
+| `roleOnScreen` | Ý nghĩa review |
+|----------------|----------------|
+| `read-write` | Form/list ghi + đọc cột persisted |
+| `read` | Chỉ hiển thị / lookup |
+| `write` | Chỉ insert/update (ít gặp tách read) |
+| `join` | FK lookup từ bảng khác (select options) |
+| `aggregate` | KPI/count — thường `#derived-data`, không map `db` |
+
+---
+
+## Cột chi tiết (per table)
+
+Ghi trên từng control / list column trong bundle:
+
+```yaml
+bind:
+  field: record_code          # payload API / form state
+db:
+  schema: records             # khớp ERD + 01 entities[].table
+  field: code                 # khớp 01 entities[].fields[].name
+  enumMapping:                # optional
+    ACTIVE: "Đang hoạt động"
+```
+
+List nhiều bảng — **mỗi cột** khai `db` nếu sort/filter/search DB:
+
+```yaml
+spec:
+  ui:
+    list:
+      columns:
+        - key: attachment_name
+          title: "Tệp"
+          db:
+            schema: record_attachments
+            field: file_name
+```
+
+---
+
+## Checklist review (không chặn split)
+
+1. `flowgrid audit spec <bundle>` — `confirms[]` `CONFIRM_DB_*` → AskQuestion (`db-audit-wizard.md`).
+2. Mở `ir/generated/data-model.md` — một section `## Bảng \`...\`` per table.
+3. `01-backend-spec.yaml` — mỗi `db.schema` có entity; mỗi `db.field` có `fields[]`.
+4. ERD Phase 0 — entity mới đã có trên `db-erd.md`.
+
+Workflow: [bundle-authoring.md](./bundle-authoring.md#data-model--phase-0-erd-vs-screen-detail) · [architecture-data.md](../../docs/workflows/architecture-data.md).

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

@@ -3,3 +3,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`
+
+- 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.
+- Hướng dẫn: `../tpl-testcase-plan.md` · workflow `docs/workflows/test.md` (toolkit repo).

package/templates/tests-skeleton/catalog/locale.yaml

@@ -5,3 +5,12 @@ headings:
     cases: Testcase
     scenarios: Scenario
     plans: Kế hoạch kiểm thử
+    preconditions: Điều kiện tiên quyết
+    steps: Các bước thực hiện
+    expected: Kết quả mong đợi
+    traceability: Liên kết docs (traceability)
+    testMatrix: Ma trận kiểm thử
+    crossRefDocs: Đối chiếu docs hub
+    technical: Chi tiết kỹ thuật
+    testData: Dữ liệu kiểm thử
+    coverage: Phạm vi coverage

package/templates/tests-skeleton/tpl-testcase-plan.md

@@ -0,0 +1,9 @@
+# Testcase plan — hướng dẫn hub
+
+Bản đầy đủ (toolkit): sau `flowgrid init` copy từ package `harness/tests/templates/tpl-testcase-plan.md` hoặc xem repo FlowGrid `templates/tests-skeleton/tpl-testcase-plan.md` (sync với harness).
+
+- SSOT ghi: `cases/**/TC-*.yaml`
+- SSOT đọc team: `cases:render` → `TC-*.md` trên VitePress (`flowgrid dev` port 5174)
+- Đối chiếu nghiệp vụ: docs hub `FLOWGRID_DOCS_ROOT` — bundle + `ir/generated/spec.md`
+
+Mẫu vàng: `TC.example.yaml` (init / harness templates).