@fui-org/fui-cli 1.3.2 → 2.1.0

package/skills/fui-skill/references/fullstack-workflow.md

@@ -1,80 +1,56 @@
 # Full-Stack Module Workflow
 
-> File này sở hữu: **quy trình 6 bước tạo một module fullstack, UI-first (phân tích → dựng UI data cứng → chốt contract → SP → wiring API → kiểm chứng tĩnh)**, và **quy trình Design Review Gate** (SKILL.md §3 chỉ giữ *luật* "phải qua gate", các bước nằm ở đây). Quy ước tAPI xem [tapi-reference.md](tapi-reference.md); thiết kế nhiều module xem [system-design.md](system-design.md).
+> Owns: **the 6-step UI-first fullstack module workflow (analyze → UI with hard-coded data → lock contract → SP → API wiring → static verification)** and **the Design Review Gate procedure** (SKILL.md §3 holds only the rule "must pass the gate"; the steps live here). tAPI conventions: [tapi-reference.md](tapi-reference.md); multi-module design: [system-design.md](system-design.md).
 
-Quy trình 6 bước để thiết kế một FUI module hoàn chỉnh: có cả UI (FUI) lẫn backend API (tAPI).
-
-**Nguyên tắc UI-first:** dựng UI bằng dữ liệu cứng trước, xác nhận hình ảnh đúng bằng `module_simulate({ renderUI: true })`, RỒI mới chốt contract API và viết SP. Tách pha "làm UI" khỏi pha "nối API" giảm hẳn lỗi so với viết cả hai cùng lúc — sửa cấu trúc data khi còn là literal trong `data[]` rẻ hơn nhiều so với sửa sau khi đã có `IN`/`OUT`/`watch` phụ thuộc vào nó. Không có bước nào trong quy trình này gọi API/SP thật để "test" — kiểm chứng luôn là đọc + suy luận + mock (xem [verification.md](verification.md)).
-
-Đọc [tapi-reference.md](tapi-reference.md) trước khi bắt đầu bước 3.
+**UI-first:** build UI (FUI) with hard-coded data, confirm visuals with `fui module simulate --render`, THEN lock the API (tAPI) contract and write SPs. Fixing data shape while it is a literal in `data[]` is far cheaper than after `IN`/`OUT`/`watch` depend on it. No step calls a real API/SP to "test" — verification = read + reason + mock ([verification.md](verification.md)). Read [tapi-reference.md](tapi-reference.md) before step 3.
 
 ---
 
-## Bước 1 — Phân tích yêu cầu
+## Step 1 — Analyze requirements
 
-Trước khi viết bất kỳ dòng code nào, xác định rõ:
+**1.1 Business need:** list / search / filter? add / edit / delete? report / statistics? workflow (approve, reject, status)?
 
-**1.1 Nghiệp vụ cần làm gì?**
-- Danh sách / tìm kiếm / lọc dữ liệu?
-- Thêm / sửa / xoá bản ghi?
-- Báo cáo / thống kê?
-- Workflow (duyệt, từ chối, trạng thái)?
+**1.2 Data (initial estimate — locked in step 3):** main entity and linked entities; which fields are displayed, which are input.
 
-**1.2 Dữ liệu liên quan (ước lượng ban đầu — sẽ chốt lại chính xác ở bước 3):**
-- Entity chính là gì? Các entity liên kết?
-- Trường nào hiển thị, trường nào nhập liệu?
+**1.3 Permissions and auth:**
 
-**1.3 Quyền và xác thực:**
-- Module có cần login không? (nếu không → dùng `AUTH_` trong SP)
-- Có phân quyền theo `sys_SystemRight` không? → xử lý trong thân SP
+- Login required? (no → use `AUTH_` in the SP)
+- Rights by `sys_SystemRight`? → handle in the SP body
 
-**Output bước 1:** Danh sách tính năng + tên các entity chính (chưa cần chốt kiểu dữ liệu/tên cột).
+**Output:** feature list + main entity names (types/column names not yet locked).
 
 ---
 
-## Bước 1b — Design Review Gate (bắt buộc, trước khi viết dòng code đầu tiên)
+## Step 1b — Design Review Gate (mandatory, before the first line of code)
 
-SKILL.md §3 quy định **luật**: mọi hệ thống/trang/chức năng mới đều phải qua gate này. Đây là
-**quy trình** của nó. Áp dụng cho cả module fullstack lẫn module chỉ có UI.
+SKILL.md §3 = the **rule** (every new system/page/function passes); this = the **procedure**, for fullstack and UI-only modules.
 
-1. **Phân tích hiệu quả nghiệp vụ** — bao nhiêu bước để user hoàn thành tác vụ, dữ liệu nào thực sự
-   cần hiển thị/nhập, có bước nào thừa không.
-2. **Tham khảo pattern đã có trong project** — `module_list` + `module_get` xem module tương tự
-   (layout, cách đặt tên control, vị trí action, cách trình bày filter/table/dialog). Thiết kế mới
-   phải đồng bộ với trang hiện có, **không tự sáng tạo kiểu khác nếu project đã có convention**.
-3. **Phác thảo UI trước** bằng lời hoặc khung layout sơ bộ — control nào, ở đâu, luồng dialog/form
-   ra sao.
-4. **Tự đánh giá lại phác thảo** — thân thiện không? số bước hợp lý không? vị trí nút Thêm/Sửa/Xóa,
-   filter, phân trang có đúng chỗ user mong đợi không? nhất quán với trang khác không? Phát hiện bất
-   hợp lý → **sửa phác thảo trước**, không mang bất hợp lý vào code.
-5. Chỉ khi phác thảo đã hợp lý mới viết code thật (bước 2 trở đi).
+1. **Business efficiency** — steps to finish the task, data truly needed, redundant steps.
+2. **Project patterns** — `fui module list` + `fui module get` on similar modules (layout, control naming, action placement, filter/table/dialog). Match existing pages; **never invent a new style when a convention exists**.
+3. **Sketch the UI** in words/rough layout — controls, placement, dialog/form flow.
+4. **Self-review** — friendly? step count? Add/Edit/Delete, filters, pagination where expected? consistent? Issues → **fix the sketch first**, never in code.
+5. Only then write code (step 2+).
 
-**Chọn phương án dựng UI:**
+**Choose the build approach:**
 
-| Phương án | Khi nào dùng |
-|---|---|
-| **A — module.json thuần** | Trang đơn giản: hiển thị dữ liệu, CRUD một bảng, form nhập liệu cơ bản. Ít file, dễ maintain. |
-| **B — Vue component (`uc-*.vue`)** | Giao diện phức tạp: dashboard nhiều vùng, layout tùy chỉnh, logic UI lặp lại nhiều nơi, hoặc `controls` vượt ~200 dòng ([component-design.md](component-design.md)). |
+| Approach                           | When                                                                                                                                                         |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **A — plain module.json**          | Simple page: data display, single-table CRUD, basic form. Fewer files, easy to maintain.                                                                     |
+| **B — Vue component (`uc-*.vue`)** | Complex UI: multi-area dashboard, custom layout, UI logic reused in many places, or `controls` over ~200 lines ([component-design.md](component-design.md)). |
 
-> User không chỉ định → **tự đề xuất** dựa trên mô tả, giải thích ngắn lý do và **chờ xác nhận** —
-> đừng tự chọn im lặng.
+> Unspecified → **propose** one with a short reason and **wait for confirmation**; never choose silently.
 
-**Ưu tiên component**: dùng `f-*` trước (`f-button` thay `v-btn`, `f-table` thay `v-data-table` cho
-MỌI bảng, `f-echart` cho mọi biểu đồ), chỉ dùng `v-*` khi không có FUI equivalent.
-→ [component-quickref.md](component-quickref.md)
+**Component priority**: `f-*` first (`f-button` over `v-btn`, `f-table` over `v-data-table` for EVERY table, `f-echart` for every chart); `v-*` only when no FUI equivalent exists. → [component-quickref.md](component-quickref.md)
 
-**Cổng Design System** chạy song song ở đây: xác định App-mode hay Web-mode và kiểm tra
-`{projectId}/DESIGN.md` **trước khi** phác thảo — hai chế độ có bộ quy tắc thẩm mỹ riêng, không vay
-mượn qua lại. → [design-modes.md](design-modes.md)
+**Design System gate** (parallel): decide App-mode vs Web-mode and check `{projectId}/DESIGN.md` **before** sketching — separate aesthetic rules; never mix. → [design-modes.md](design-modes.md)
 
-**Output bước 1b:** phác thảo UI đã tự review, phương án A/B đã chốt (có xác nhận của user nếu do ta
-đề xuất), chế độ thẩm mỹ đã xác định.
+**Output:** self-reviewed sketch, approach A/B locked (user-confirmed if we proposed it), aesthetic mode decided.
 
 ---
 
-## Bước 2 — Dựng UI với dữ liệu cứng
+## Step 2 — Build UI with hard-coded data
 
-Thiết kế toàn bộ UI của module bằng dữ liệu **literal** khai báo thẳng trong `data[]` — chưa có API nào cả. Xem [module-json-anatomy.md](module-json-anatomy.md) và [controls-patterns.md](controls-patterns.md) để biết cấu trúc control/grid.
+Whole UI on **literal** data in `data[]`, no API yet. Structure: [module-json-anatomy.md](module-json-anatomy.md), [controls-patterns.md](controls-patterns.md).
 
 ```json
 "data": [
@@ -89,34 +65,28 @@ Thiết kế toàn bộ UI của module bằng dữ liệu **literal** khai báo
 ]
 ```
 
-Dựng `f-table`/`v-dialog`/form theo dữ liệu cứng này — component-table/dialog patterns xem [component-table.md](component-table.md), [ui-templates.md](ui-templates.md).
+`f-table`/`v-dialog`/form patterns: [component-table.md](component-table.md), [ui-templates.md](ui-templates.md).
 
-**QA hình ảnh ngay ở bước này:** `module_simulate({ renderUI: true, vueData: {...dữ liệu cứng nếu muốn override} })`, đọc screenshot + DOM audit, tự sửa lỗi hiển thị (tràn ngang, dialog vỡ, thiếu label...) trước khi đi tiếp — không mang lỗi UI sang các bước sau.
+**Visual QA now:** `fui module simulate --render` (vueData override: `fui module simulate --help`). Read screenshot + DOM audit; fix display bugs (horizontal overflow, broken dialog, missing labels...) before moving on.
 
-**Output bước 2:** `module.json` có layout hoàn chỉnh, chạy được với data cứng, đã qua `renderUI` QA sạch.
+**Output:** `module.json` with complete layout, running on hard-coded data, clean `--render` QA.
 
 ---
 
-## Bước 3 — Chốt cấu trúc data + thiết kế API endpoints
-
-Từ chính các field đã dùng ở data cứng bước 2 (đây là lý do bước 2 đi trước — cấu trúc field đã được xác nhận đúng bằng mắt trước khi biến thành contract SP), chốt:
-- Tên field chính xác, kiểu dữ liệu (dùng để suy ra kiểu cột SQL)
-- Entity/table nào sinh ra field nào
+## Step 3 — Lock data shape + design API endpoints
 
-Rồi map sang các SP tAPI cần tạo. Quy ước đặt tên đầy đủ (`spAPI_*` / `spAPI_AUTH_*` / `spAPIFILE_*`, params `@url1_`, response contract) là của [tapi-reference.md](tapi-reference.md) — ở đây chỉ áp dụng vào việc map tính năng sang SP theo pattern `spAPI_{Entity}{Action}`.
+From the step-2 fields (visually confirmed before becoming an SP contract), lock exact field names + types (→ SQL column types) and the source entity/table of each. Map features to SPs as `spAPI_{Entity}{Action}`; full naming (`spAPI_*` / `spAPI_AUTH_*` / `spAPIFILE_*`, `@url1_`, response contract) is in [tapi-reference.md](tapi-reference.md).
 
-**Bảng mapping thường gặp:**
+| Feature           | SP name                      | Main params            |
+| ----------------- | ---------------------------- | ---------------------- |
+| List              | `spAPI_{Entity}List`         | Filter params (custom) |
+| Detail            | `spAPI_{Entity}Get`          | `@url1_{EntityID}`     |
+| Insert            | `spAPI_{Entity}Insert`       | Entity fields          |
+| Update            | `spAPI_{Entity}Update`       | ID + fields to update  |
+| Delete            | `spAPI_{Entity}Delete`       | `@url1_{EntityID}`     |
+| Lookup / dropdown | `spAPI_AUTH_{Entity}Options` | No auth, returns list  |
 
-| Tính năng | SP name | Params chính |
-|---|---|---|
-| Lấy danh sách | `spAPI_{Entity}List` | Filter params (custom) |
-| Lấy chi tiết | `spAPI_{Entity}Get` | `@url1_{EntityID}` |
-| Thêm mới | `spAPI_{Entity}Insert` | Các field của entity |
-| Cập nhật | `spAPI_{Entity}Update` | ID + các field cần cập nhật |
-| Xoá | `spAPI_{Entity}Delete` | `@url1_{EntityID}` |
-| Lookup / dropdown | `spAPI_AUTH_{Entity}Options` | Không cần auth, trả danh sách |
-
-**Ví dụ cho module "Quản lý Sinh viên"** (khớp field đã dùng ở data cứng bước 2: `StudentID`, `FullName`, `ClassID`, `ClassName`, `GPA`):
+**Example — "Student management"** (matches step-2 fields `StudentID`, `FullName`, `ClassID`, `ClassName`, `GPA`):
 
 ```
 spAPI_StudentList       -- danh sách, lọc theo ClassID + Keyword — trả đúng các cột đã hiển thị ở bước 2
@@ -127,15 +97,15 @@ spAPI_StudentDelete     -- xoá theo url1=StudentID
 spAPI_AUTH_ClassOptions -- dropdown danh sách lớp (không cần auth)
 ```
 
-**Output bước 3:** Danh sách đầy đủ SP, tên + params + response shape khớp field đã dùng trong UI.
+**Output:** full SP list; names + params + response shape match the fields used in the UI.
 
 ---
 
-## Bước 4 — Viết SQL Stored Procedures
+## Step 4 — Write SQL stored procedures
 
-Viết SP theo đúng quy tắc tAPI và đúng contract đã chốt ở bước 3. Xem chi tiết tại [tapi-reference.md](tapi-reference.md).
+Per tAPI rules ([tapi-reference.md](tapi-reference.md)) and the step-3 contract.
 
-**Template SP SELECT (danh sách):**
+**SELECT (list):**
 
 ```sql
 CREATE PROCEDURE spAPI_StudentList
@@ -152,7 +122,7 @@ AS BEGIN
 END
 ```
 
-**Template SP INSERT:**
+**INSERT:**
 
 ```sql
 CREATE PROCEDURE spAPI_StudentInsert
@@ -172,7 +142,7 @@ AS BEGIN
 END
 ```
 
-**Template SP DELETE:**
+**DELETE:**
 
 ```sql
 CREATE PROCEDURE spAPI_StudentDelete
@@ -184,7 +154,7 @@ AS BEGIN
 END
 ```
 
-**Template SP GET (chi tiết, dùng convert_to_object):**
+**GET (detail, convert_to_object):**
 
 ```sql
 CREATE PROCEDURE spAPI_StudentGet
@@ -199,38 +169,30 @@ AS BEGIN
 END
 ```
 
-> Dùng `convert_to_object = ''` khi SP trả về đúng một record → response dạng object thay vì `data[0][0]`.
+> `convert_to_object = ''` when the SP returns exactly one record → response is an object instead of `data[0][0]`.
 
-Deploy bằng `db_sp_save` + `db_sp_deploy` (không tự gọi endpoint để "chạy thử" — xem bước 6).
+Deploy with `fui sp save` + `fui sp deploy` (never call the endpoint to "try it" — see step 6).
 
-**KHÔNG viết `GRANT EXECUTE` vào file .sql.** Thân `CREATE PROCEDURE` kéo dài **tới hết batch**, mà
-`_sql_execute_NonQuery` gửi đúng một batch và **không hỗ trợ `GO`** (`GO` là chỉ thị của client, không
-phải lệnh T-SQL). Nên câu `GRANT` đặt sau `END` bị **nuốt vào trong thân SP** — nó thành một lệnh chạy
-mỗi lần gọi SP, chứ không cấp quyền lúc deploy. Không lỗi nào nổi lên; chỉ là endpoint tAPI trả lỗi
-quyền trong khi SP nhìn vào thì hoàn toàn đúng.
+**NEVER put `GRANT EXECUTE` in the .sql file.** A `CREATE PROCEDURE` body runs **to end of batch**; `_sql_execute_NonQuery` sends one batch and **does not support `GO`** (client directive, not T-SQL). A `GRANT` after `END` is **swallowed into the SP body** — runs on every call, never grants at deploy. No error; the endpoint just returns a permission error while the SP looks right.
 
-`db_sp_deploy` **tự cấp quyền** cho procedure mới (không áp dụng cho FUNCTION — function không cần
-EXECUTE cho `[public]`), rồi **hỏi lại `sys.database_permissions` xem quyền có thật hay không** và báo
-trong kết quả:
+`fui sp deploy` **auto-grants** new procedures (not FUNCTIONs — functions need no EXECUTE for `[public]`), then **re-checks `sys.database_permissions`** and reports:
 
-- `✓ [public] đã có quyền EXECUTE trên "..."` — xong.
-- `❗ [public] CHƯA có quyền EXECUTE ...` — kết quả in sẵn câu chạy được, copy nguyên văn:
-  `db_sql_execute_nonquery({ sqlcmd: "GRANT EXECUTE ON [dbo].[spAPI_StudentList] TO [public] AS [dbo]", db: "..." })`
-- Bước cấp quyền hỏng nhưng deploy thành công thì **SP vẫn đã lên server** — chạy câu GRANT ở trên,
-  **đừng deploy lại**.
+- `✓ [public] đã có quyền EXECUTE trên "..."` — done.
+- `❗ [public] CHƯA có quyền EXECUTE ...` — the output prints a runnable command; copy verbatim:
+  `fui exec "GRANT EXECUTE ON [dbo].[spAPI_StudentList] TO [public] AS [dbo]" --db ...`
+- Grant failed but deploy succeeded → **the SP is already on the server**; run the GRANT above, **do not redeploy**.
 
-Deploy SP bằng đường khác (`db_sql_execute_nonquery` với `CREATE PROCEDURE`) thì **không có auto-grant
-và không xoá cache tham số tAPI** — tool sẽ cảnh báo và nêu đúng hai lệnh cần chạy tiếp.
+Deploying via `fui exec` with `CREATE PROCEDURE` → **no auto-grant, no tAPI param-cache clear**; fui warns and names the two commands to run next.
 
-**Output bước 4:** Toàn bộ SQL script đã deploy cho các SP thiết kế ở bước 3.
+**Output:** all step-3 SPs deployed.
 
 ---
 
-## Bước 5 — Thay dữ liệu cứng bằng binding API
+## Step 5 — Replace hard-coded data with API bindings
 
-Sửa lại `module.json` đã dựng ở bước 2: giữ nguyên layout, thay giá trị literal trong `data[]` bằng named action `IN`/`OUT`/`CALLBACK` trỏ vào các SP vừa deploy.
+Keep the step-2 layout; replace `data[]` literals with named `IN`/`OUT`/`CALLBACK` actions on the deployed SPs.
 
-**5.1 Khai báo action thay cho data cứng**
+**5.1 Actions replacing hard-coded data**
 
 ```json
 "data": [
@@ -270,7 +232,7 @@ Sửa lại `module.json` đã dựng ở bước 2: giữ nguyên layout, thay
 ]
 ```
 
-**5.2 Khai báo watch để tự load khi filter thay đổi**
+**5.2 `watch` to reload when filters change**
 
 ```json
 "watch": {
@@ -279,42 +241,42 @@ Sửa lại `module.json` đã dựng ở bước 2: giữ nguyên layout, thay
 }
 ```
 
-**5.3 Thêm `{ "CALL": "vueData.fetchStudents" }` cuối `data[]`** để auto-load khi module mở.
+**5.3** Append `{ "CALL": "vueData.fetchStudents" }` at the end of `data[]` to auto-load on open.
 
-**Output bước 5:** `module.json` đã wiring API đầy đủ, layout không đổi so với bước 2.
+**Output:** `module.json` fully wired, layout unchanged from step 2.
 
 ---
 
-## Bước 6 — Kiểm chứng tĩnh và hoàn thiện
+## Step 6 — Static verification and finish
+
+Pre-publish checklist — **no step calls a real API/SP/DML**:
+
+**API/SP** — full checklist (naming, params, security, `GRANT EXECUTE`, deploy workflow): [verification.md](verification.md). Here:
 
-Checklist trước khi publish — **không bước nào gọi API/SP/DML thật**:
+- [ ] `AUTH_` on endpoints that need no login
+- [ ] `fui sp verify` per new SP — reads the real body, infers response shape/error contract, checks params, emits a `--mocks` snippet (no endpoint call)
+- [ ] **Write** APIs: read the body and reason (WHERE, transaction, RAISERROR) — no trial run
 
-**API/SP** — checklist đầy đủ (naming, params, security, `GRANT EXECUTE`, deploy workflow) ở
-[verification.md](verification.md#deploy-workflow). Ở bước này:
-- [ ] SP có `AUTH_` cho các endpoint không cần login
-- [ ] `db_sp_verify` cho từng SP mới deploy — đọc thân SP thật, suy luận response shape/contract lỗi, đối chiếu params, sinh sẵn snippet `apiMocks` (không gọi endpoint thật)
-- [ ] API **ghi**: đọc thân SP suy luận (WHERE, transaction, RAISERROR) — không có "chạy thử" nào khác ngoài đọc + suy luận
+**module.json:**
 
-**FUI module.json:**
-- [ ] `API` path trong mỗi action khớp đúng `/{apiName}/{FunctionName}`
-- [ ] `IN` params khớp đúng tên param trong SP (phân biệt hoa thường)
-- [ ] Route params (url1, url2) được truyền qua URL, không phải qua `IN`
-- [ ] `OUT` nhận đúng kiểu dữ liệu (array hay object tuỳ SP) — đối chiếu với response shape suy luận từ `db_sp_verify`
-- [ ] `watch` đã khai báo cho các filter tự động reload
-- [ ] `data[]` khai báo named action fetch ban đầu, kết thúc bằng `{ "CALL": ... }` auto-startup
+- [ ] Each action's `API` path matches `/{apiName}/{FunctionName}`
+- [ ] `IN` params match SP param names exactly (case-sensitive)
+- [ ] Route params (url1, url2) go via the URL, not `IN`
+- [ ] `OUT` receives the right type (array vs object per SP) — check against the shape inferred by `fui sp verify`
+- [ ] `watch` declared for auto-reload filters
+- [ ] `data[]` declares the initial fetch action and ends with a startup `{ "CALL": ... }`
 
-**Kiểm chứng cuối cùng theo thứ tự:** `module_validate` (lỗi cú pháp/quy tắc) → `module_outline` (review cấu trúc UI dạng text) → `module_simulate` với `apiMocks` lấy từ snippet của `db_sp_verify` (verify luồng action/watch/dialog) → nếu còn nghi ngờ hiển thị, `module_simulate({ renderUI: true })` lần cuối với cùng `apiMocks`.
+**Final verification, in order:** `fui module validate` (syntax/rule errors) → `fui module outline` (text review of UI structure) → `fui module simulate --mocks '{...}'` using the `fui sp verify` snippet (action/watch/dialog flow) → if display is still in doubt, a last `fui module simulate --render` with the same `--mocks`. (`fui module check` runs validate + outline + simulate in one step.)
 
-**Output bước 6:** Module hoạt động end-to-end, UI ↔ API thông suốt, chưa từng có lời gọi thật nào trong suốt quá trình kiểm chứng.
+**Output:** module works end-to-end, UI ↔ API connected, zero real calls during verification.
 
 ---
 
-## Ví dụ đầu ra hoàn chỉnh
+## Complete output example
 
-### SP cần tạo (bước 4 output)
+### SPs (step 4)
 
-Mỗi SP là **một file riêng** qua `db_sp_save` → `db_sp_deploy`. Không GRANT trong file, không `GO`
-(xem bước 4); tham số tAPI **không được có default value** — `db_sp_deploy` chặn cứng.
+Each SP is **its own file** via `fui sp save` → `fui sp deploy`. No GRANT in the file, no `GO` (step 4); tAPI params **must not have default values** — `fui sp deploy` hard-blocks them.
 
 ```sql
 -- 1. Danh sách  (file spAPI_StudentList.sql)
@@ -334,7 +296,7 @@ AS BEGIN
 END
 ```
 
-### module.json actions (bước 5 output)
+### module.json actions (step 5)
 
 ```json
 "fetchStudents": { "API": "/me/StudentList", "IN": { "Keyword": "vueData.keyword" }, "OUT": "studentList" },
@@ -343,9 +305,9 @@ END
 
 ---
 
-## Lưu ý quan trọng
+## Key notes
 
-- **`{apiName}`** trong API path là tên apiName của app trong tAPI (ví dụ `me`, `lms`, `hr`). Hỏi người dùng nếu chưa biết. **Một project có thể dùng nhiều apiName** (mỗi cái một database) — mỗi alias cần một lần `db_connect` riêng, và alias trong path chính là tham số `db` của các DB tool ([db-workflow.md](db-workflow.md) §4).
-- **Route params** (`@url1_`) truyền qua URL, không qua `IN`: dùng backtick prefix trong API path: `"API": "/me/StudentDelete/\`{{vueData.selectedID}}"`
-- **Response từ SP có nhiều SELECT** → `data[0]`, `data[1]`... — khai báo rõ trong `OUT` hoặc dùng `EXE` để tách.
-- **`convert_to_object = ''`** → response là object phẳng, đọc trực tiếp `vueData.studentDetail.FullName` thay vì `vueData.studentDetail[0].FullName`.
+- **`{apiName}`** in the API path is the app's tAPI apiName (e.g. `me`, `lms`, `hr`). Ask the user if unknown. **A project may use several apiNames** (one database each) — each alias needs its own `fui db add`, and the alias in the path is the `--db` argument of DB commands ([db-workflow.md](db-workflow.md) §4).
+- **Route params** (`@url1_`) go via the URL, not `IN`, using the backtick prefix: `"API": "/me/StudentDelete/\`{{vueData.selectedID}}"`
+- **SP with multiple SELECTs** → `data[0]`, `data[1]`... — declare explicitly in `OUT` or split with `EXE`.
+- **`convert_to_object = ''`** → flat object response: read `vueData.studentDetail.FullName`, not `vueData.studentDetail[0].FullName`.

package/skills/fui-skill/references/module-data-patterns.md

@@ -1,14 +1,14 @@
-# module.json `data[]` — Khai báo state & value resolution (chuyên sâu)
+# module.json `data[]` — State declaration & value resolution
 
-> File này sở hữu: **pattern khai báo `data[]`: ba loại phần tử, thứ tự state → named action → auto-startup**. Value resolution xem [controls-patterns.md](controls-patterns.md) §0; cú pháp key lồng nhau (dot/bracket/`#PARENT`) xem [controls-patterns.md](controls-patterns.md) §1; trao đổi cross-window xem [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md).
+> Owns: **`data[]` declaration patterns: three element kinds, order state → named action → auto-startup**. Value resolution: [controls-patterns.md](controls-patterns.md) §0; nested key syntax (dot/bracket/`#PARENT`): [controls-patterns.md](controls-patterns.md) §1; cross-window: [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md).
 
-Cách FUI đọc `data[]`: xử lý **tuần tự từ trên xuống**, mỗi object gán/chạy dựa trên cách viết value. Ví dụ trong file này rút từ `ex/ex-v3-1SetData` + `ex-v3-2CauTruc` (module demo chính thức của FUI).
+FUI processes `data[]` **sequentially top to bottom**; each object assigns/runs based on how its value is written. Examples come from `ex/ex-v3-1SetData` + `ex-v3-2CauTruc` (official FUI demo modules).
 
-> Quy tắc value resolution hình thức: [controls-patterns.md](controls-patterns.md) §0. Tổng quan 4 thành phần: [module-json-anatomy.md](module-json-anatomy.md). Engine nền tảng: [platform-architecture.md](platform-architecture.md) §5.
+> Overview of the 4 blocks: [module-json-anatomy.md](module-json-anatomy.md). Engine: [platform-architecture.md](platform-architecture.md) §5.
 
 ---
 
-## 1. Ba loại phần tử trong `data[]`
+## 1. Three element kinds in `data[]`
 
 ```json
 "data": [
@@ -19,53 +19,44 @@ Cách FUI đọc `data[]`: xử lý **tuần tự từ trên xuống**, mỗi ob
 ]
 ```
 
-- (a) không có key action → tạo biến reactive trong `vueData`.
-- (b) key là **tên hàm** → định nghĩa action tái sử dụng (gọi bằng `CALL`).
-- (c) object là chính một action (`API`/`CALL`/`FUN`…) → **chạy ngay khi trang load**, theo thứ tự.
+- (a) no action key → creates reactive var in `vueData`.
+- (b) key is a **function name** → reusable action (invoke via `CALL`).
+- (c) object is itself an action (`API`/`CALL`/`FUN`…) → **runs on page load**, in order.
 
 ---
 
-## 2. Value resolution — CÁCH VIẾT quyết định GIÁ TRỊ (điểm hay sai)
+## 2. Value resolution — HOW you write it decides the VALUE (common mistake)
 
-Bảng quy tắc đầy đủ (`getVueData`: backtick / `{{ }}` / chuỗi có dấu cách / chuỗi không dấu cách →
-JS eval) nằm ở [controls-patterns.md §0](controls-patterns.md#0-value-resolution-rules-fundamental)
-— file Tier A luôn được nạp sẵn, không chép lại ở đây.
+Full rules (`getVueData`: backtick / `{{ }}` / string with spaces / string without spaces → JS eval) live in [controls-patterns.md §0](controls-patterns.md#0-value-resolution-rules-fundamental) — Tier A, always loaded; not repeated here.
 
-> **Hệ quả cho AI khi viết `data[]`:** muốn gán **chuỗi cố định không dấu cách** (id, url, mã) →
-> **bọc backtick** (`` "`winUser" ``) hoặc single-quote (`"'winUser'"`), nếu không FUI sẽ hiểu là
-> biến. Đây là lỗi phổ biến nhất khi viết `data`/`IN`.
+> **Consequence for `data[]`:** to assign a **fixed string without spaces** (id, url, code) → **wrap in backticks** (``"`winUser"``) or single quotes (`"'winUser'"`), otherwise FUI treats it as a variable. This is the most common `data`/`IN` bug.
 
 ---
 
-## 3. Key là đường dẫn lồng nhau (deep set)
+## 3. Keys as nested paths (deep set)
 
-Key bên trái cũng được phân giải (dot / bracket / index động / `#PARENT`) — bảng cú pháp đầy đủ nằm ở
-[controls-patterns.md §1](controls-patterns.md#1-khai-báo-và-gán-dữ-liệu-trong-data) *(Tier A, đã nạp sẵn)*,
-không chép lại ở đây.
+The left-hand key is also resolved (dot / bracket / dynamic index / `#PARENT`) — full syntax in [controls-patterns.md §1](controls-patterns.md#1-data-keys-and-assignment) _(Tier A, already loaded)_.
 
 ---
 
-## 4. Action tự chạy: inline `IN`/`OUT`/`API` khi load
+## 4. Auto-run action: inline `IN`/`OUT`/`API` on load
 
-Object là action đứng riêng trong `data[]` → chạy khi load. Không cần đặt tên:
+A standalone action object in `data[]` runs on load; no name needed:
 
 ```json
 { "API": "https://tapi.example.vn/me/auth/ApplicationList", "OUT": "Mang" },
 { "IN": { "ABC": "`gdsgdsg", "DEF": "val5", "CBV": 1233 }, "OUT": "DoiTuong" }
 ```
 
-→ dùng để nạp dữ liệu ban đầu của trang (danh mục, dropdown, dữ liệu bảng).
+→ loads the page's initial data (catalogs, dropdowns, table data).
 
 ---
 
-## 5. Named action + CALLBACK (tái sử dụng)
+## 5. Named action + CALLBACK (reusable)
 
 ```json
 {
-  "cmdSETData": [
-    { "MESS": "Thông báo" },
-    { "#Win1.GiaTriSetTuCHA": "Giá trị set từ CHA" }
-  ],
+  "cmdSETData": [{ "MESS": "Thông báo" }, { "#Win1.GiaTriSetTuCHA": "Giá trị set từ CHA" }],
   "apiChart": {
     "API": "/ts/TS_Report_ForChart/{{ab}}",
     "IN": { "sachID": "apiLoadFBUser", "modeY": 12345 },
@@ -75,13 +66,13 @@ Object là action đứng riêng trong `data[]` → chạy khi load. Không cầ
 }
 ```
 
-Gọi bằng `{ "CALL": "cmdSETData" }` từ `controls`, `watch`, hay action khác. `CALLBACK` chạy sau khi API xong (xem [ui-patterns.md](ui-patterns.md) §7).
+Invoke with `{ "CALL": "cmdSETData" }` from `controls`, `watch` or another action. `CALLBACK` runs after the API completes (see [ui-patterns.md](ui-patterns.md) §7).
 
 ---
 
-## 6. `watch` với `v_old` — giá trị cũ
+## 6. `watch` with `v_old` — previous value
 
-Trong `watch`, `v_old.<field>` cho giá trị **trước khi đổi**:
+In `watch`, `v_old.<field>` gives the value **before the change**:
 
 ```json
 "watch": {
@@ -95,13 +86,13 @@ Trong `watch`, `v_old.<field>` cho giá trị **trước khi đổi**:
 }
 ```
 
-Chi tiết `v_old`, `deep-watch`: [watcher-patterns.md](watcher-patterns.md).
+`v_old`, `deep-watch` details: [watcher-patterns.md](watcher-patterns.md).
 
 ---
 
-## 7. Trao đổi cross-window ngay trong `data[]`
+## 7. Cross-window exchange inside `data[]`
 
-`data[]` có thể đọc/ghi cửa sổ khác bằng key/value `#PARENT.*` / `#WinID.*` — đặt **trước** các CALL fetch:
+`data[]` can read/write other windows via `#PARENT.*` / `#WinID.*` keys/values — place **before** fetch CALLs:
 
 ```json
 "data": [
@@ -113,14 +104,14 @@ Chi tiết `v_old`, `deep-watch`: [watcher-patterns.md](watcher-patterns.md).
 ]
 ```
 
-Đầy đủ: [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md).
+Full: [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md).
 
 ---
 
-## 8. Checklist viết `data[]`
+## 8. `data[]` checklist
 
-1. Khởi tạo **mọi** biến state ở object đầu (kể cả `[]`, `false`, `null`) — để reactive hoạt động.
-2. Named action nhóm giữa; auto-startup (`CALL`/`API`) đặt **cuối**.
-3. Gán chuỗi cố định không dấu cách → **backtick**; đừng để FUI hiểu nhầm là biến.
-4. `#PARENT.*` / biến từ URL đặt trước các CALL fetch.
-5. Không nhồi logic phức tạp vào `data` — tách sang `script.js` (hàm) hoặc `EXE` dè xẻn.
+1. Initialize **every** state var in the first object (including `[]`, `false`, `null`) so reactivity works.
+2. Named actions in the middle; auto-startup (`CALL`/`API`) **last**.
+3. Fixed space-free strings → **backticks**; never let FUI read them as variables.
+4. `#PARENT.*` / URL vars before fetch CALLs.
+5. No complex logic in `data` — move to `script.js` (functions) or sparing `EXE`.