@fui-org/fui-cli 1.3.2 → 2.1.0

package/skills/fui-skill/references/verification.md

@@ -1,246 +1,236 @@
-# FUI Definition-of-Done Checklists
-
-> File này sở hữu: **checklist definition-of-done trước khi publish (module.json, `.vue`, SP, deploy workflow)** và **ma trận chọn tầng kiểm chứng theo triệu chứng**.
-
-Use these checklists before publishing any artifact. Each item is a gate — a module/SP/component is not ready if any required item is unchecked.
-
----
-
-## Chọn tầng kiểm chứng theo TRIỆU CHỨNG (đọc trước khi render)
-
-Năm tầng, chênh nhau khoảng **hai bậc** về chi phí mỗi lượt:
-
-| Tầng | Lệnh | Chi phí | Thấy được gì |
-|---|---|---|---|
-| 1 | `module_validate` | tức thì, chỉ đọc file | lỗi quy tắc/tham chiếu tĩnh |
-| 2 | `module_outline` | tức thì | cấu trúc layout, action mồ côi, dialog không ai mở |
-| 3 | `module_simulate` | ~1 s | luồng chạy: action chain, watch, OUT gán gì |
-| 4 | `component_preview` | browser, 1 component | lỗi của riêng một `uc-*.vue` |
-| 5 | `module_simulate({renderUI:true})` | browser, ~10–30 s | **hình ảnh thật**: layout, chiều cao, style, responsive |
-
-**Quy tắc:** đi từ tầng rẻ nhất **bắt được triệu chứng đó**, không mặc định leo thẳng lên tầng 5. Tầng 5 là tầng duy nhất thấy được hình ảnh, nhưng cũng là tầng duy nhất **không nói được vì sao** — nó chỉ chụp lại hậu quả.
-
-| Triệu chứng | Tầng rẻ nhất bắt được | Vì sao |
-|---|---|---|
-| Trang trắng / app rỗng, **không** JS error, **không** `[Vue warn]` | **1** `module_validate` | dấu hiệu kinh điển của statement trong một `:attr` — Vue nuốt lỗi compile template, browser không có gì để báo |
-| `[Vue warn] Property or method "x" is not defined` | **1** | biến dùng trong template chưa khai trong `data[]` |
-| Nút bấm không làm gì | **1** (CALL target) → **3** (luồng thật) | |
-| `Unknown custom element: <f-…>` / component trống | **1** | sai tên component, hoặc thiếu import bắt buộc |
-| Chart không vẽ ra gì | **1** (thiếu `echarts.min.js`/`fechart.js`) → **5** (canvas 0-size) | thiếu import chiếm phần lớn số ca |
-| Cột lệch, một hàng quá chật | **2** `module_outline` (Σw > 12) | |
-| Dialog không mở được | **2** (`⚠ không thấy lệnh mở`) → **3** | |
-| Action chạy sai thứ tự · watch lặp vô hạn · CONFIRM/MESS không đúng nhánh | **3** `module_simulate` | |
-| Số liệu sai · `undefined`/`NaN` hiện trên trang | **3** | gần như luôn là `OUT`/mapData trỏ sai khoá, không phải lỗi hiển thị |
-| API trả không đúng shape mong đợi | `db_sp_verify` (suy luận tĩnh, **không gọi endpoint nào**) | suy luận từ thân SP thật + sinh sẵn `apiMocks` cho tầng 3. Không phải "zero HTTP" nguyên văn: khi chưa có `.sql` local nó lấy `OBJECT_DEFINITION`, và `checkGrant: true` hỏi `sys.database_permissions` — cả hai là **đọc metadata**, không chạy SP |
-| Một `uc-*.vue` hiển thị sai | **4** `component_preview` | chứng minh component đúng trước ⇒ mọi lỗi còn lại là lỗi lắp ráp |
-| Bảng tràn ngang · chiều cao sai · style rò rỉ · khoảng cách xấu · vỡ ở mobile | **5** `renderUI` | không tầng nào khác thấy được hình học |
-| Import/asset không nạp được | **5**, đọc section `⛔ MÔI TRƯỜNG THIẾU FILE` | lỗi của môi trường, **không** sửa module theo nó |
-| Nghi "thư viện platform có bug" | **5**, kiểm section `⛔ ASSET CŨ` TRƯỚC khi kết luận | asset stale ⇒ đang chạy bản trên đĩa, mọi kết luận về CDN đều vô giá trị |
-| Nút/menu **có gác quyền** không hiện với user thật (nhưng hiện trong preview) | **1** `module_validate` sau khi chạy `right_function_list` | mã quyền chưa được định nghĩa ⇒ `rightTest()` luôn false, không lỗi JS. Tầng 3/5 **cấp sẵn** đúng mã quét được nên chúng luôn hiện — xem [permission-system.md](permission-system.md) |
-
-**Không kết luận về platform từ một lượt render có asset stale.** renderUI revalidate mọi asset mỗi lượt (conditional GET), nên bình thường bạn đang xem đúng bản CDN hiện tại — dòng trace ghi `N revalidate 304`. Nhưng nếu report có khối `⛔ ASSET CŨ, KHÔNG XÁC MINH ĐƯỢC` thì mạng hỏng và trang đang chạy bằng bản trên đĩa: câu "thư viện X có bug" rút ra từ lượt đó **không dùng được**. Nối mạng render lại, hoặc `refreshAssets: true` để ép tải mới. Dòng `ℹ️ ASSET PLATFORM ĐÃ ĐỔI` nghĩa là file nền tảng vừa đổi giữa hai lượt — hành vi đổi mà `module.json` không đụng tới thì tìm nguyên nhân ở đó trước.
-
-**Đọc report renderUI đúng thứ tự:** khối `═══ CHẨN ĐOÁN ═══` ở đầu đã xếp mọi thứ hỏng vào ba nhóm theo **nơi phải sửa** — `[MÔI TRƯỜNG]` (sửa môi trường trước, lỗi hai nhóm dưới có thể chỉ là hệ quả) · `[MODULE]` (module.json/script.js/component) · `[HIỂN THỊ]` (DOM audit + ảnh). Dòng `↪` gợi ý tầng rẻ hơn lẽ ra bắt được triệu chứng đó.
-
-**Dấu hiệu phải DỪNG render lại:** dòng `Δ so với lượt trước` báo *không chỉ số nào đổi*. Nghĩa là thay đổi vừa rồi không chạm tới lỗi đang có — render lại lần nữa với cùng hướng sửa chỉ tốn thêm một lượt. Quay xuống tầng 1–3 để biết **vì sao**, rồi mới lên lại tầng 5.
-
----
-
-## Module Checklist
-
-### Structure
-
-- [ ] `_moduleInfo.json` exists with `ModuleID`, `ModuleName`, `Framework`, `mTitle`, `HTMLOnly`
-- [ ] `module.json` exists and is valid JSON (no trailing commas, no comments) — **validate trước khi ghi**: sau mỗi lần edit JSON dài, mentally check hoặc re-read để đảm bảo không có trailing comma sau element cuối cùng trong mảng/object
-- [ ] If custom components are used: `components/_components.json` exists and lists all `uc-*.vue` files
-- [ ] `imports/_imports.json` exists if module imports external JS/CSS
-
-### module.json — Data
-
-- [ ] All reactive state variables declared in `data[]` before being referenced in actions
-- [ ] All named actions are reachable (at least one `CALL` or `watch` or button click references each)
-- [ ] No hardcoded IDs — inputs reference `vueData.someVar` not literal numbers
-- [ ] `OUT` keys match declared state variable names exactly (case-sensitive)
-
-### module.json — Actions
-
-- [ ] Every `API` action has both `IN` and `OUT` (or `CALLBACK`) defined
-- [ ] Every delete action has `CONFIRM` before `API`
-- [ ] Every mutating action has a `CALLBACK` that either reloads data or shows `MESS`
-- [ ] Literal string values in `IN` use backtick prefix or single-quote wrap: `` "`winId" `` or `"'text'"`
-- [ ] `IF/THEN/ELSE` branches all have matching action structures
-- [ ] No raw `EXE` blocks that duplicate logic already expressible in actions
-
-### module.json — Controls
-
-- [ ] `controls` array starts with `{ "prop": "fluid grid-list-md", "rows": [...] }`
-- [ ] Every item in `cols` has a `w` property
-- [ ] Events use `v-on:click` not `@click`
-- [ ] No `children` key — nesting uses `innerHTML` array
-- [ ] Permission gates use `col: { "v-if": "vueData.user.SystemRight>=N" }` (not on `attr`)
-- [ ] **Mọi mã `FunctionRight`/`SystemRight` đem gác đã TỒN TẠI thật** — đã chạy `right_function_list`/`right_system_list` (cũng là thứ tạo cache cho `module_validate` đối chiếu), mã chưa có thì `right_function_new`/`right_system_new` TRƯỚC. Mã bịa ra làm control biến mất im lặng và **preview vẫn hiện đúng** nên ảnh render không phát hiện được — xem [permission-system.md](permission-system.md)
-- [ ] All `v-if` expressions include `vueData.` prefix where referencing state
-- [ ] Dialog containers use `el: "hidden-container"` — one per dialog
-
-### module.json — Watch
-
-- [ ] Watch keys reference declared state variables
-- [ ] `deep-watch` used for nested object/array observation
-- [ ] No watch entry calls an action that also triggers the same watch (infinite loop risk)
-
-### UI Quality
-
-- [ ] Vuetify classes/props used before inline `style` (đúng version của project: FUI V2 = Vuetify 1.5, FUI V3 = Vuetify 3)
-- [ ] `f-*` components chosen over raw `v-*` when FUI equivalent exists
-- [ ] Tables use `f-table` (not `v-data-table`) — cả CRUD lẫn read-only (read-only = không khai `:update-api`)
-- [ ] Tổng cột dùng `sum-format` (object → hàng tổng trong bảng; string → dòng text dưới bảng) — không tự dựng hàng tổng thủ công
-- [ ] Charts dùng **`f-echart`** — không dùng `v-chart`, `<canvas>`, hay lib khác
-- [ ] Chart tuân thủ **Quy ước hiển thị mặc định** trong components-echart.md
-- [ ] Date/time fields use `f-date`/`f-time` (not `v-text-field` + manual parsing)
-
-### Import JS/CSS
-
-- [ ] Với mỗi component có import (xem bảng trong `component-quickref.md`): đã gọi `file_import_list` để kiểm tra — import đang có hay chưa
-- [ ] Nếu thêm component cần import và chưa có → `file_import_new` cho từng file thiếu
-- [ ] Nếu bỏ component có import → kiểm tra import đó còn dùng ở component/module khác không; nếu không còn → `file_import_delete`
-- [ ] **Nếu có `f-echart`**: cả hai import phải có và đúng thứ tự — `echarts.min.js` trước, `fechart.js` sau:
-  - `/include/chart/echarts.min.js`
-  - `/include/chart/fechart.js`
-
-### Validate trước khi publish
-
-- [ ] Module mới có cả UI lẫn API: đã dựng UI bằng dữ liệu cứng trong `data[]` + `module_simulate({ renderUI: true })` QA hình ảnh TRƯỚC khi chốt contract API và viết SP — xem quy trình đầy đủ ở [fullstack-workflow.md](fullstack-workflow.md)
-- [ ] Chạy `module_validate` sau khi sửa `module.json` — sửa hết **error** (CALL target không tồn tại, `@`/`#` shorthand, `children`, grid structure sai...)
-- [ ] Warning được review từng cái — có thể là chủ ý (component chưa có trong list, param optional...), nhưng không được bỏ qua mà không đọc
-- [ ] Warning nhóm **`[design]`** (toolbar dialog có màu, nút xóa màu đỏ, width dialog lạ, form không floating label, delete thiếu CONFIRM, nút Đóng thừa, tự dựng v-snackbar/v-alert thay vì MESS/MESSBOX, f-table/f-sheet bảng chính thiếu `":height": -16` nên cả trang cuộn thay vì cuộn trong bảng...) = vi phạm chuẩn thẩm mỹ mặc định — **phải sửa**, trừ khi chính user đã yêu cầu rõ kiểu khác trong phiên này
-- [ ] Strict mode (`FUI_MCP_STRICT=1`): error sẽ CHẶN publish — không thể bỏ qua
-- [ ] Chạy `module_outline` và ĐỌC cây layout để tự review cấu trúc UI: mỗi row có Σw hợp lý (≤12)? dialog nào có `⚠ không thấy lệnh mở`? action nào có `⚠ không thấy nơi gọi`? state nào `⚠ không thấy dùng`?
-- [ ] Với module có logic runtime phức tạp (action chain, watch cascade, dialog flow): chạy `module_simulate` với kịch bản luồng chính + `apiMocks` (shape lấy từ snippet do `db_sp_verify` sinh sẵn) + assert điều kiện then chốt — sửa mọi `⚠` và assert ✘ trong trace trước khi publish. **Lưu ý**: `apiMocks` bạn truyền luôn thắng, nhưng một API tĩnh KHÔNG có mock mà SP đích đã xác nhận chỉ đọc (`db_sp_verify`/đã có `.sql` local) sẽ tự động được gọi thật (giới hạn 8 lượt/lần, có cache `_testdata/`) thay vì rơi thẳng `{data:[]}` — đọc dòng "Live/Cache data" trong report để biết SP nào lấy từ đâu; SP có lệnh ghi thì không bao giờ bị gọi thật
-- [ ] **`apiMocks` của SP đã tồn tại phải đến từ `db_sp_verify`, không tự đoán** — thấy `module_simulate` trả cảnh báo `🚨 CẤU TRÚC MOCK CHƯA ĐƯỢC KIỂM CHỨNG` thì dừng, chạy `db_sp_verify` rồi copy nguyên văn snippet nó sinh ra, không tự sửa tay rồi bỏ qua. Bịa cấu trúc chỉ hợp lệ cho SP thật sự chưa tồn tại (chưa deploy)
-- [ ] **QA hiển thị cuối cùng (khi có Playwright)**: chạy `module_simulate({ renderUI: true, vueData: {..demo data..}, apiMocks: {...} })` — render browser thật, ĐỌC screenshot trả về (luôn có ảnh inline — PNG quá lớn tự nén JPEG) + DOM audit (app rỗng? tràn ngang? text "undefined"/"NaN"? ảnh vỡ? canvas chart 0-size?) + JS error/`[Vue warn]` + state cuối vueData — tự fix lỗi hiển thị rồi render lại cho tới khi sạch. **Có section `⛔ MÔI TRƯỜNG THIẾU FILE` thì đọc nó TRƯỚC**: import/asset chưa nạp được là lỗi môi trường (chạy lệnh nó gợi ý — `project_sync`/`module_get`), các lỗi JS/hiển thị bên dưới có thể chỉ là hệ quả — đừng sửa module.json theo chúng — cách ĐỌC ảnh có hệ thống: xem `ui-screenshot-review.md`. Chart/animation render thiếu trong ảnh → tăng `settleMs` (vd 1500). Dialog đang mở được chụp riêng `render-dialog.jpg`. Module có dùng trên mobile → render thêm lượt `device: "mobile"`. Không có Playwright → bỏ qua bước này (tool sẽ trả hướng dẫn cài)
-- [ ] **Vừa sửa cả cấp project lẫn cấp module** (component project, import project, `project.json`/menu): publish phần **cấp project** TRƯỚC rồi mới render — renderUI lấy `$projectData` + component project + CSS project từ server (`_aset`), nên bản project chưa publish sẽ không xuất hiện trong ảnh; ngược lại phần cấp module dựng cục bộ, cứ sửa-render-sửa thoải mái rồi publish sau. Riêng **component cấp project** thì không còn là lời nhắc: renderUI đối chiếu từng `uc-*.vue` local với bundle server và **chặn cứng** (không có cờ bỏ qua) nếu lệch — kiểm chứng bản local bằng `component_preview`, rồi `component_new`/`component_update`, rồi mới render. Bị chặn vì bản server mới hơn (ai đó sửa trên web IDE) → `project_sync`, đừng push đè
-
-### Publish Workflow — Smart (sửa cái nào, up cái đó)
-
-Không phải lúc nào cũng dùng `module_publish_html`. Chọn tool theo phần đã thay đổi:
-
-- [ ] Chỉ sửa `module.json` → dùng `module_publish_json` (không cần preview/approval)
-- [ ] Sửa `header.html` / `body.html` / title → `module_preview` → user approve → `module_publish_html` (đã kèm module.json, không cần gọi thêm `module_publish_json`)
-- [ ] Sửa `script.js` (kể cả làm rỗng) → `module_publish_script` — **⚠️ `module_publish_html` không clear script rỗng trên server**
-- [ ] Sửa `uc-*.vue` → `component_new` (lần đẩy đầu tiên) hoặc `component_update` (các lần sau), per file — `component_update` lỗi cứng nếu component chưa có trên server, không âm thầm tạo
-- [ ] Nhiều phần → gọi tool tương ứng cho từng phần, lần lượt
-
-Khi dùng `module_publish_html`:
-- [ ] `module_preview` đã chạy và diff đã được review
-- [ ] User đã xác nhận rõ ràng
-- [ ] Có approval token từ `module_preview`
-
----
-
-## Stored Procedure Checklist
-
-### Naming
-
-- [ ] Prefix is `spAPI_` (e.g., `spAPI_ContractList`, `spAPI_ContractInsert`)
-- [ ] Name follows pattern: `spAPI_{Entity}{Action}` where Action is `List`/`Select`/`Insert`/`Update`/`Delete`/`Save`
-- [ ] No spaces, no lowercase prefix (`sp_`, `SP_`, etc.)
-
-### Parameters
-
-- [ ] `@sys_UserID int` present in all write operations (INSERT/UPDATE/DELETE)
-- [ ] `@sys_SystemRight int` present when permission check is needed
-- [ ] Input parameters declared before system parameters
-- [ ] No unused parameters
-
-### Security
-
-- [ ] Permission check at top: `IF @sys_SystemRight < N BEGIN RAISERROR(N'[Unauthorized]Bạn không có quyền...', 16, 1) RETURN END` — severity luôn là `16`, prefix `[Unauthorized]` bắt buộc trên lỗi thiếu quyền để tAPI trả HTTP 401 (xem [tapi-reference.md](tapi-reference.md) §5)
-- [ ] No direct string concatenation for SQL (use parameterized queries)
-- [ ] File `.sql` **KHÔNG chứa `GRANT EXECUTE`** — thân `CREATE PROCEDURE` kéo dài tới hết batch, mà tAPI gửi một batch và không hỗ trợ `GO`, nên câu GRANT viết sau `END` bị **nuốt vào thân SP**: nó chạy mỗi lần gọi SP chứ không cấp quyền lúc deploy, và không có lỗi nào nổi lên. `db_sp_deploy` tự cấp quyền cho procedure mới rồi **hỏi lại `sys.database_permissions` để xác nhận**
-- [ ] Kết quả `db_sp_deploy` báo `✓ [public] đã có quyền EXECUTE` — nếu thấy `❗` thì chạy đúng câu GRANT nó in ra (**đừng deploy lại**, SP đã lên server rồi). Deploy SP qua `db_sql_execute_nonquery` thì không có auto-grant; tool cảnh báo và nêu lệnh cần chạy. Nghi ngờ về sau: `db_sp_verify({ name, checkGrant: true })`
-
-### Logic
-
-- [ ] SP returns exactly what FUI `OUT` expects (column names match exactly)
-- [ ] Error conditions use `RAISERROR(N'...', 16, 1)` followed by `RETURN` (not silent failures)
-- [ ] Transactions used for multi-step writes
-- [ ] SP logic reviewed statically (read the body, reason about branches/edge cases) before deploy — never smoke-tested against the live endpoint
-
-### Deploy Workflow
-
-- [ ] `db_sp_save` called first (save to local, no DB change)
-- [ ] Full SP body reviewed in local file before deploy
-- [ ] Summary presented to user: SP name, operation type (CREATE/ALTER), affected tables
-- [ ] User has explicitly confirmed before `db_sp_deploy`
-- [ ] Sau deploy bất kỳ API nào (đọc hay ghi) sắp wire vào module.json → `db_sp_verify` một lần: suy luận tĩnh response shape/contract lỗi từ thân SP thật, đối chiếu params — **không gọi endpoint nào**. (Không phải "zero HTTP" nguyên văn: chưa có `.sql` local thì nó lấy `OBJECT_DEFINITION`, `checkGrant: true` thì hỏi `sys.database_permissions` — cả hai là *đọc metadata*, không chạy SP)
-- [ ] API **ghi** (Insert/Update/Delete) → kiểm tra tính đúng bằng cách đọc thân SP (`db_sp_get`/`db_sp_verify`) và suy luận logic tĩnh (WHERE, transaction, RAISERROR); test luồng UI gọi API ghi bằng `module_simulate({ apiMocks: {...} })` với dữ liệu giả (snippet có sẵn từ `db_sp_verify`), không gọi API thật
-
----
-
-## Vue Component Checklist (`uc-*.vue`)
-
-### File
-
-- [ ] Filename starts with `uc-` prefix
-- [ ] Registered in `_components.json`
-- [ ] `<style scoped>` block (nếu có): mọi selector đã tự tiền tố bằng class định danh của component — `scoped` KHÔNG scope thật (server chỉ nối text `ComCSS`), selector trần sẽ leak sang component khác. Xem [component-design.md](component-design.md)
-- [ ] No backtick template strings inside `<template>`
-
-### API Design
-
-- [ ] All inputs declared as `props` with types
-- [ ] Component emits events upward (`input`, `change`, `select`, `action`) rather than mutating parent state
-- [ ] Props use neutral names (`items`, `value`, `label`) not screen-specific names
-- [ ] Loading, empty, and error states handled (prop or slot)
-
-### Behavior
-
-- [ ] Component does not fetch data directly unless it is explicitly a data-owning component
-- [ ] No hardcoded route/module paths inside the component
-- [ ] No permission logic inside component — permission gating stays in `module.json`
-
-### Kiểm chứng trong không gian riêng (trước khi ráp vào module / trước khi push)
-
-- [ ] Đã chạy `component_preview` với **ít nhất 2 case**: một case dữ liệu bình thường và một case biên (danh sách rỗng / chuỗi rất dài / thiếu trường) — component sai ở case biên là lỗi hay gặp nhất
-- [ ] Đã ĐỌC ảnh chụp của **cả desktop lẫn mobile** (mặc định tool render cả hai): không tràn ngang, không vỡ layout ở 390px, không text "undefined"/"NaN"
-- [ ] Không còn JS error / `[Vue warn]` trong report
-- [ ] Component có tương tác → `scenario` với `click`/`set` + `assert` đã chạy đúng (dùng `nth`, không `item`/`index`)
-- [ ] Component tự đo chiều cao (chart, table) → thử thêm `viewport` chiều cao thấp
-- [ ] **Component cấp project**: đã push (`component_new` lần đầu / `component_update` các lần sau) NGAY SAU khi preview sạch — renderUI của module sẽ chặn cứng nếu bản local còn lệch bản server
-
----
-
-## Import File Checklist
-
-- [ ] File type matches declared `ContentType` (`.js` → `application/javascript`, `.css` → `text/css`)
-- [ ] `sort` >= 40 khi thêm import mới — giá trị 1–39 dành cho hệ thống, không dùng
-- [ ] Content tested locally before `file_import_upload_content`
-- [ ] No sensitive data (tokens, passwords) in JS/CSS import files
-- [ ] If updating an existing file: `file_import_get` called first to review current content
-
----
-
-## Debug Workflow — Sau khi publish có lỗi
-
-Khi server báo lỗi hoặc trang hiển thị sai sau khi publish:
-
-1. **Review file vừa sửa trước tiên** — đọc lại toàn bộ file đã chỉnh sửa trong lần publish đó, không nhảy sang nguyên nhân khác
-2. Nếu file trông đúng: chạy `module_preview` để xem diff — kiểm tra server đang lưu gì so với local
-3. Nếu preview báo `Controls: 0` / `Data keys: 0`: đó là server đang giữ bản cũ bị lỗi, không phải local — push lại để ghi đè
-4. Chỉ khi local file đã xác nhận đúng mà lỗi vẫn còn: mới kiểm tra các file khác (header.html, script.js, imports)
-
----
-
-## Quick Risk Gate
-
-Before any mutating tool call, answer:
-
-| Question | If NO → |
-|---|---|
-| Is this a ReadOnly tool? | Confirm intent with user |
-| Have I shown the user a summary? | Show summary first, then wait |
-| Is this a 🔴 Destructive tool? | Require explicit user confirmation |
-| For `module_publish_html`: do I have an approval token? | Run `module_preview` first |
-| For `db_sp_deploy`: has user seen the SP body? | Show SP body, wait for OK |
-
-See [tools-registry.md](tools-registry.md) for the full per-tool classification.
+# FUI Definition-of-Done Checklists
+
+> Owns: **definition-of-done checklists before publish (module.json, `.vue`, SP, deploy)** and **symptom → verification tier matrix**. Flags: `fui <command> --help`.
+
+Each item is a gate: not ready while any required item is unchecked.
+
+---
+
+## Pick the tier by SYMPTOM (read before rendering)
+
+Tiers differ ~100× in cost per run:
+
+| Tier | Command                        | Cost                 | Sees                                                |
+| ---- | ------------------------------ | -------------------- | --------------------------------------------------- |
+| 1    | `fui module validate`          | instant, file-only   | static rule/reference errors                        |
+| 2    | `fui module outline`           | instant              | layout, orphan actions, dialogs nobody opens        |
+| 3    | `fui module simulate`          | ~1 s                 | flow: action chain, watch, what OUT assigns         |
+| 4    | `fui component preview`        | browser, 1 component | bugs in one `uc-*.vue`                              |
+| 5    | `fui module simulate --render` | browser, ~10–30 s    | **real visuals**: layout, height, style, responsive |
+
+`fui module check` = tiers 1–3 in one step.
+
+**Start at the cheapest tier that catches the symptom**, never tier 5 by default. Tier 5 alone sees visuals but can't say **why**.
+
+| Symptom                                                                             | Cheapest tier                                                                     | Why                                                                                                                                                                                              |
+| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Blank page, **no** JS error, **no** `[Vue warn]`                                    | **1**                                                                             | statement inside a `:attr` — Vue swallows template compile errors                                                                                                                                |
+| `[Vue warn] Property or method "x" is not defined`                                  | **1**                                                                             | variable not in `data[]`                                                                                                                                                                         |
+| Button does nothing                                                                 | **1** (CALL target) → **3**                                                       |                                                                                                                                                                                                  |
+| `Unknown custom element: <f-…>` / empty component                                   | **1**                                                                             | wrong name or missing required import                                                                                                                                                            |
+| Chart draws nothing                                                                 | **1** (missing `echarts.min.js`/`fechart.js`, most cases) → **5** (0-size canvas) |                                                                                                                                                                                                  |
+| Misaligned columns, cramped row                                                     | **2** (Σw > 12)                                                                   |                                                                                                                                                                                                  |
+| Dialog won't open                                                                   | **2** (`⚠ không thấy lệnh mở`) → **3**                                            |                                                                                                                                                                                                  |
+| Wrong action order · infinite watch loop · CONFIRM/MESS wrong branch                | **3**                                                                             |                                                                                                                                                                                                  |
+| Wrong numbers · `undefined`/`NaN` on page                                           | **3**                                                                             | almost always `OUT`/mapData on the wrong key, not display                                                                                                                                        |
+| API returns unexpected shape                                                        | `fui sp verify` (static, **calls no endpoint**)                                   | infers from the real SP body + generates `--mocks` for tier 3. Only metadata reads: `OBJECT_DEFINITION` when no local `.sql`, `sys.database_permissions` with `--check-grant`; never runs the SP |
+| One `uc-*.vue` wrong                                                                | **4**                                                                             | once proven, remaining bugs are assembly                                                                                                                                                         |
+| Horizontal overflow · wrong height · leaking style · bad spacing · broken on mobile | **5**                                                                             | only tier seeing geometry                                                                                                                                                                        |
+| Import/asset not loaded                                                             | **5**, section `⛔ MÔI TRƯỜNG THIẾU FILE`                                         | environment error — **don't** edit the module for it                                                                                                                                             |
+| Suspected "platform library bug"                                                    | **5**, check `⛔ ASSET CŨ` FIRST                                                  | stale asset ⇒ on-disk copy ran; CDN conclusions worthless                                                                                                                                        |
+| **Permission-gated** button/menu hidden for real users but shown in preview         | **1** after `fui right function list`                                             | undefined code ⇒ `rightTest()` always false, no JS error. Tiers 3/5 **pre-grant** scanned codes so they always show — [permission-system.md](permission-system.md)                               |
+
+**Stale assets:** `--render` revalidates every asset per run (conditional GET; trace shows `N revalidate 304`). `⛔ ASSET CŨ, KHÔNG XÁC MINH ĐƯỢC` = network failed, on-disk copy ran ⇒ "library X has a bug" from that run is **unusable**; reconnect and re-render, or `--refresh-assets`. `ℹ️ ASSET PLATFORM ĐÃ ĐỔI` = platform file changed between runs — behavior changed without a `module.json` edit ⇒ look there first.
+
+**Read the `--render` report top-down:** `═══ CHẨN ĐOÁN ═══` groups failures by **where to fix** — `[MÔI TRƯỜNG]` (fix first; the others may be consequences) · `[MODULE]` (module.json/script.js/component) · `[HIỂN THỊ]` (DOM audit + image). `↪` = cheaper tier that should have caught it.
+
+**STOP re-rendering** when `Δ so với lượt trước` shows _no metric changed_: the fix missed the bug. Drop to tiers 1–3 to learn why, then return.
+
+---
+
+## Module Checklist
+
+### Structure
+
+- [ ] `_moduleInfo.json` has `ModuleID`, `ModuleName`, `Framework`, `mTitle`, `HTMLOnly`
+- [ ] `module.json` is valid JSON (no trailing commas, no comments) — re-read after every long edit to catch a comma after the last array/object element
+- [ ] Custom components ⇒ `components/_components.json` lists all `uc-*.vue`
+- [ ] External JS/CSS ⇒ `imports/_imports.json` exists
+
+### module.json — Data
+
+- [ ] All state declared in `data[]` before use in actions
+- [ ] Every named action reachable (`CALL`, `watch` or button click)
+- [ ] No hardcoded IDs — use `vueData.someVar`, not literal numbers
+- [ ] `OUT` keys match state names exactly (case-sensitive)
+
+### module.json — Actions
+
+- [ ] Every `API` has `IN` and `OUT` (or `CALLBACK`)
+- [ ] Every delete has `CONFIRM` before `API`
+- [ ] Every mutation has a `CALLBACK` that reloads data or shows `MESS`
+- [ ] Literal strings in `IN`: backtick prefix or single quotes — ``"`winId"`` or `"'text'"`
+- [ ] `IF/THEN/ELSE` branches have matching action structures
+- [ ] No raw `EXE` duplicating logic expressible as actions
+
+### module.json — Controls
+
+- [ ] `controls` starts with `{ "prop": "fluid grid-list-md", "rows": [...] }`
+- [ ] Every `cols` item has `w`
+- [ ] `v-on:click`, not `@click`
+- [ ] No `children` — nest with `innerHTML` array
+- [ ] Permission gates on `col: { "v-if": "vueData.user.SystemRight>=N" }` (not `attr`)
+- [ ] **Every gated `FunctionRight`/`SystemRight` code EXISTS** — ran `fui right function list`/`fui right system list` (also builds the cache `fui module validate` checks); missing ⇒ `fui right function new`/`fui right system new` FIRST. Invented codes hide controls silently while **preview still shows them** — [permission-system.md](permission-system.md)
+- [ ] `v-if` uses `vueData.` prefix for state
+- [ ] Dialogs use `el: "hidden-container"`, one per dialog
+
+### module.json — Watch
+
+- [ ] Keys reference declared state
+- [ ] `deep-watch` for nested object/array
+- [ ] No watch calls an action that re-triggers itself (infinite loop)
+
+### UI Quality
+
+- [ ] Vuetify classes/props before inline `style` (FUI V2 = Vuetify 1.5, FUI V3 = Vuetify 3)
+- [ ] `f-*` over raw `v-*` when an equivalent exists
+- [ ] Tables: `f-table`, not `v-data-table` — CRUD and read-only (read-only = no `:update-api`)
+- [ ] Totals via `sum-format` (object → total row; string → text line below) — never hand-built
+- [ ] Charts: **`f-echart`** only — not `v-chart`, `<canvas>`, other libs; follow **default display conventions** in components-echart.md
+- [ ] Date/time: `f-date`/`f-time`, not `v-text-field` + manual parsing
+
+### Import JS/CSS
+
+- [ ] Each component needing imports (table in `component-quickref.md`): checked with `fui import list`
+- [ ] Missing ⇒ `fui import new` per file
+- [ ] Component removed ⇒ if its import is unused elsewhere, `fui import delete`
+- [ ] **`f-echart`**: both imports, in order:
+  - `/include/chart/echarts.min.js`
+  - `/include/chart/fechart.js`
+
+### Validate before publish
+
+- [ ] New module with UI + API: UI built with hardcoded `data[]` + visual QA (`fui module simulate --render`) BEFORE the API contract and SPs — [fullstack-workflow.md](fullstack-workflow.md)
+- [ ] `fui module validate` after editing `module.json` — fix every **error** (missing CALL target, `@`/`#` shorthand, `children`, bad grid...)
+- [ ] Read each warning — may be intentional (unlisted component, optional param...), never skip unread
+- [ ] **`[design]`** warnings (colored dialog toolbar, red delete button, odd dialog width, no floating label, delete without CONFIRM, redundant Close button, hand-built v-snackbar/v-alert instead of MESS/MESSBOX, main f-table/f-sheet without `":height": -16` so the page scrolls instead of the table...) — **must fix** unless the user explicitly asked otherwise this session
+- [ ] Strict mode (`FUI_STRICT=1`): errors BLOCK publish
+- [ ] `fui module outline`, READ the tree: row Σw ≤12? `⚠ không thấy lệnh mở`? `⚠ không thấy nơi gọi`? `⚠ không thấy dùng`?
+- [ ] Complex runtime logic (action chain, watch cascade, dialog flow): `fui module simulate` with main-flow `--scenario` + `--mocks` (shape from `fui sp verify` snippet) + asserts — fix every `⚠` and ✘ first. Your `--mocks` always win; a static API with NO mock whose SP is confirmed read-only (`fui sp verify`/local `.sql`) is called for real (max 8 calls/run, cached in `_testdata/`) instead of `{data:[]}` — see the "Live/Cache data" line. SPs with writes are never called
+- [ ] **`--mocks` for existing SPs come from `fui sp verify`, never guessed** — on `🚨 CẤU TRÚC MOCK CHƯA ĐƯỢC KIỂM CHỨNG`, stop, run `fui sp verify`, copy the snippet verbatim (no hand edits). Invented shapes only for SPs not yet deployed
+- [ ] **Final visual QA (Playwright available)**: `fui module simulate --render --vue-data '{..demo data..}' --mocks '{...}'`. READ the screenshot (always inline; big PNG → JPEG) + DOM audit (empty app, overflow, "undefined"/"NaN", broken image, 0-size chart canvas) + JS errors/`[Vue warn]` + final vueData; fix and re-render until clean. **`⛔ MÔI TRƯỜNG THIẾU FILE` first**: environment error — run its suggested command (`fui project sync`/`fui module get`); errors below may be consequences, don't edit module.json for them. How to read screenshots: `ui-screenshot-review.md`. Chart/animation missing → raise `--settle-ms` (e.g. 1500). Open dialog captured as `render-dialog.jpg`. Mobile use → extra run `--device mobile`. No Playwright → skip (command returns install steps)
+- [ ] **Changed project level + module level** (project component/import, `project.json`/menu): publish **project level FIRST**, then render — `--render` loads `$projectData`, project components and project CSS from the server (`_aset`); module-level parts render locally (iterate freely, publish later). **Project components are hard-blocked** (no bypass flag) if a local `uc-*.vue` differs from the server bundle: `fui component preview` → `fui component new`/`update` → render. Blocked because server is newer (web IDE edit) → `fui project sync`, never push over
+
+### Publish — only what changed
+
+- [ ] Only `module.json` → `fui module publish json` (no preview/approval)
+- [ ] `header.html` / `body.html` / title → `fui module preview` → user approves → `fui module publish html --approval <token>` (includes module.json)
+- [ ] `script.js` (even emptied) → `fui module publish script` — **⚠️ `publish html` does not clear an empty script on the server**
+- [ ] `uc-*.vue` → `fui component new` (first) / `fui component update` (later), per file — `update` hard-errors if absent on server, never creates
+- [ ] Several parts → one command each, in turn
+
+For `fui module publish html`: preview ran and diff reviewed · user explicitly confirmed · approval token in hand.
+
+---
+
+## Stored Procedure Checklist
+
+### Naming
+
+- [ ] `spAPI_{Entity}{Action}`, Action = `List`/`Select`/`Insert`/`Update`/`Delete`/`Save` (e.g. `spAPI_ContractList`, `spAPI_ContractInsert`)
+- [ ] No spaces, no `sp_`/`SP_` prefix
+
+### Parameters
+
+- [ ] `@sys_UserID int` in all writes (INSERT/UPDATE/DELETE)
+- [ ] `@sys_SystemRight int` when checking permission
+- [ ] Input params before system params; no unused params
+
+### Security
+
+- [ ] Permission check at top: `IF @sys_SystemRight < N BEGIN RAISERROR(N'[Unauthorized]Bạn không có quyền...', 16, 1) RETURN END` — severity always `16`; `[Unauthorized]` prefix required so tAPI returns HTTP 401 ([tapi-reference.md](tapi-reference.md) §5)
+- [ ] No SQL string concatenation (parameterize)
+- [ ] `.sql` has **NO `GRANT EXECUTE`** — tAPI sends one batch, no `GO`, so a GRANT after `END` is **swallowed into the SP body** and runs on every call, silently. `fui sp deploy` grants new procedures and **re-queries `sys.database_permissions` to confirm**
+- [ ] `fui sp deploy` shows `✓ [public] đã có quyền EXECUTE`; on `❗` run exactly the printed GRANT (**don't redeploy**). `fui exec` deploys have no auto-grant (fui warns with the command). Later doubts: `fui sp verify <name> --check-grant`
+
+### Logic
+
+- [ ] Returns exactly the columns `OUT` expects
+- [ ] Errors: `RAISERROR(N'...', 16, 1)` then `RETURN`, never silent
+- [ ] Transactions for multi-step writes
+- [ ] Reviewed statically (read body, reason about branches/edge cases) — never smoke-tested against the live endpoint
+
+### Deploy
+
+- [ ] `fui sp save` first (local only)
+- [ ] Full body reviewed in the local file
+- [ ] Summary to user: SP name, CREATE/ALTER, affected tables
+- [ ] User explicitly confirmed before `fui sp deploy`
+- [ ] Any API (read or write) about to be wired into module.json → `fui sp verify` once: static shape/error contract + param check, **no endpoint call** (metadata reads only, as above)
+- [ ] **Write** APIs: verify by reading the body (`fui sp get`/`fui sp verify`) — WHERE, transaction, RAISERROR; test the UI flow with `fui module simulate --mocks '{...}'` (snippet from `fui sp verify`), never the real API
+
+---
+
+## Vue Component Checklist (`uc-*.vue`)
+
+### File
+
+- [ ] Name starts with `uc-`; registered in `_components.json`
+- [ ] `<style scoped>`: every selector prefixed with the component's own class — `scoped` does NOT scope (server concatenates `ComCSS`), bare selectors leak. [component-design.md](component-design.md)
+- [ ] No backtick template strings in `<template>`
+
+### API Design
+
+- [ ] Inputs are typed `props`; neutral names (`items`, `value`, `label`)
+- [ ] Emits events (`input`, `change`, `select`, `action`), never mutates parent state
+- [ ] Loading, empty, error states handled (prop or slot)
+
+### Behavior
+
+- [ ] No data fetching unless explicitly data-owning
+- [ ] No hardcoded route/module paths
+- [ ] No permission logic — gating stays in `module.json`
+
+### Verify in isolation (before assembling / pushing)
+
+- [ ] `fui component preview` with **≥2 cases**: normal + edge (empty list / very long string / missing field) — edge cases fail most
+- [ ] READ **desktop and mobile** screenshots (default): no overflow, no break at 390px, no "undefined"/"NaN"
+- [ ] No JS error / `[Vue warn]`
+- [ ] Interactive ⇒ `scenario` with `click`/`set` + `assert` passes (use `nth`, not `item`/`index`)
+- [ ] Self-sizing (chart, table) ⇒ also a low-height `viewport`
+- [ ] **Project-level component**: push (`fui component new`/`update`) RIGHT AFTER a clean preview — module `--render` hard-blocks on mismatch
+
+---
+
+## Import File Checklist
+
+- [ ] File type matches `ContentType` (`.js` → `application/javascript`, `.css` → `text/css`)
+- [ ] `sort` >= 40 for new imports (1–39 reserved)
+- [ ] Content tested locally before `fui import upload`
+- [ ] No tokens/passwords in JS/CSS
+- [ ] Updating ⇒ `fui import get` first
+
+---
+
+## Debug — errors after publish
+
+1. **Re-read every file changed in that publish first**; don't jump elsewhere
+2. Looks right ⇒ `fui module preview` for server vs local diff
+3. Preview shows `Controls: 0` / `Data keys: 0` ⇒ server holds a broken old version — push again
+4. Only when local is confirmed correct: check other files (header.html, script.js, imports)
+
+---
+
+## Quick Risk Gate
+
+Before any mutating command:
+
+| Question                                   | If NO →                        |
+| ------------------------------------------ | ------------------------------ |
+| Read-only command?                         | Confirm intent with user       |
+| Summary shown to user?                     | Show it, then wait             |
+| 🔴 Destructive?                            | Require explicit confirmation  |
+| `fui module publish html`: approval token? | Run `fui module preview` first |
+| `fui sp deploy`: user saw the SP body?     | Show it, wait for OK           |
+
+Per-command classification: [tools-registry.md](tools-registry.md).