@fui-org/fui-cli 0.2.0 → 0.3.0

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

@@ -0,0 +1,218 @@
+# f-sheet — Bảng tính nhập liệu (dựa trên AG Grid)
+
+> File này sở hữu: **`f-sheet` (AG Grid): import, props, cấu hình cột, cell renderer dựng sẵn, chọn vùng/fill/clipboard, wiring API**.
+
+`f-sheet` là **data grid nhập liệu kiểu Excel**, xây dựng **hoàn toàn trên AG Grid Community**. Mọi cấu hình cột/lưới đều là cấu hình AG Grid — **khi cần tuỳ biến, dựa vào kiến thức AG Grid** (https://www.ag-grid.com/, phiên bản Community). FUI chỉ bọc thêm: toolbar (thêm/xoá/lưu/xuất Excel), theo dõi dòng thay đổi, chọn vùng nhiều ô kiểu Excel + fill handle + copy/paste TSV, và wiring API.
+
+> **Phân biệt với `f-table`**: `f-table` hiển thị dữ liệu dạng datatable, sửa dòng qua dialog form riêng. `f-sheet` sửa **ngay trên ô của bảng** (không qua dialog), phù hợp nhập liệu hàng loạt kiểu Excel (dán nhiều dòng, sửa nhanh nhiều ô). Cùng là component có sẵn — không tự viết bảng nhập liệu bằng `uc-*.vue`.
+
+> Nền tảng (nguồn sự thật): `scripts/fsheet.js` — **một file DUY NHẤT dùng chung cho cả V2 và V3** (không còn khái niệm 2 bản phải giữ đồng bộ). Component khai cả `beforeDestroy` (Vue 2) lẫn `beforeUnmount` (Vue 3) để hoạt động đúng trên cả hai runtime. Template dùng thuần class/prop **Vuetify 3** (`variant="text"`, `density="comfortable"`, `text-primary`, `text-subtitle-1`, `text-caption`) — trên module V2 (Vuetify 2) toolbar vẫn bấm được nhưng có thể không lên đúng màu/kiểu vì Vuetify 2 bỏ qua các prop/class lạ này. Dùng `ajaxCALL`/`confirm`/`jsonToExcel` bên trong — khớp [component-design.md](component-design.md) §12.
+
+---
+
+## Import BẮT BUỘC (thiếu → không dùng được f-sheet)
+
+Thêm đúng 2 file, **đúng thứ tự**, qua `file_import_new`:
+
+```
+/include/ag-grid/ag-grid-community.min.js
+/include/ag-grid/fsheet.js
+```
+
+Quy trình khi thêm/bỏ f-sheet: `file_import_list` (projectId + moduleId) → chưa có thì `file_import_new` từng file → bỏ f-sheet mà không module/component khác dùng thì `file_import_delete`. Xem [component-quickref.md](component-quickref.md).
+
+---
+
+## Props
+
+| Prop (kebab-case trong `attr`) | Kiểu | Ý nghĩa |
+|---|---|---|
+| `label` | string | Tiêu đề + hiện trên thanh công cụ |
+| `:columns` | array | **colDefs của AG Grid** (xem mục Cột). Bỏ trống → tự suy cột từ `items[0]` (mỗi field → `{ field, headerName: field }`) |
+| `:items` | array | Dữ liệu dòng (rowData) |
+| `row-key` | string | Tên field khóa chính (mặc định `id`) — dùng để nhận diện dòng đổi/mới/xoá |
+| `:height` | number | Bỏ trống = tự giãn theo số dòng; `<=0` = fill tới đáy màn hình chừa `abs(height)` px; `>0` = px cố định (xem mục Chiều cao) |
+| `:allow-add` | bool | Hiện nút Thêm dòng |
+| `:allow-delete` | bool | Hiện cột checkbox chọn + nút Xoá |
+| `readonly` | bool | Khoá toàn bộ chỉnh sửa (đồng thời tắt luôn fill handle) |
+| `update-api` | string | Endpoint tAPI **lưu từng dòng đã đổi** (gọi qua `ajaxCALL`, tự prepend `apiDomain`). Không khai thì nút Lưu bị `disabled` |
+| `delete-api` | string | Endpoint tAPI xoá một dòng |
+| `:save-extra` | object | Tham số phụ **trộn vào payload** mỗi lần lưu/xoá (vd `{ LopID: vueData.lopID }`) — đi qua `mapData`, hỗ trợ tham chiếu động `vueData.x` |
+| `:default-item` | object | Mẫu giá trị cho dòng mới khi bấm Thêm — cũng đi qua `mapData`, hỗ trợ tham chiếu động `vueData.x`, không chỉ literal tĩnh |
+
+---
+
+## Cột (`columns`) = colDef của AG Grid
+
+Mỗi phần tử `columns` là một **AG Grid colDef** — dùng trực tiếp kiến thức AG Grid:
+
+| Key colDef hay dùng | Ý nghĩa |
+|---|---|
+| `field` | Tên field trong dòng dữ liệu |
+| `headerName` | Nhãn cột |
+| `editable` | Cho sửa ô — **mặc định bật** (f-sheet đặt `editable: !readonly` trong `defaultColDef`); cột chỉ đọc khai `"editable": false` |
+| `width` / `minWidth` / `flex` | Bề rộng cột (mặc định `flex:1`, `minWidth:80`) |
+| `pinned` | `'left'`/`'right'` cố định cột |
+| `sortable` / `filter` / `resizable` | Mặc định đều bật |
+| `valueFormatter` / `valueGetter` | Định dạng/hiển thị (hàm AG Grid) |
+| `cellEditor` | Editor tuỳ chỉnh — tên có sẵn của AG Grid (vd `agDateStringCellEditor`) hoặc tên hàm global tự viết |
+| `cellRenderer` | Renderer tuỳ chỉnh — 4 renderer dựng sẵn của f-sheet (xem bên dưới) hoặc tên hàm global tự viết |
+| `type` | **Tên columnType đã đăng ký** — chỉ có `"number"` và `"date"`. **KHÔNG phải** chỗ khai kiểu dữ liệu tự do (xem mục columnType ngay dưới) |
+
+> Các tính năng cột nâng cao khác (cellClassRules, aggregation...) tra tài liệu AG Grid Community — f-sheet truyền colDef thẳng vào grid. Riêng cột `type:"number"`/`type:"date"` được f-sheet **tự gắn** `cellStyle`/`valueFormatter`/`valueParser`/`filter` (xem bên dưới) — chỉ khai tay khi cần logic khác mặc định.
+
+### columnType — f-sheet đăng ký ĐÚNG 2 tên: `number` và `date`
+
+`type` **không phải** key gốc của AG Grid dùng để khai kiểu dữ liệu. Nó là **tên tham chiếu tới một columnType đã đăng ký** trong `gridOptions.columnTypes`. f-sheet đăng ký đúng hai tên — bảng `FS_COLUMN_TYPES` ở đầu `scripts/fsheet.js` là nguồn duy nhất.
+
+Đặt một tên **chưa đăng ký** (`"date_time"`, `"currency"`, `"text"`, `"string"`, `"boolean"`…) thì:
+
+- AG Grid **bỏ qua hoàn toàn** và chỉ log `warning #36 colDef.type 'x' does not correspond to defined gridOptions.columnTypes` — cột chạy y hệt cột text thô, **không** format, **không** parse, **không** filter. Cấu hình trông như có tác dụng nhưng không có.
+- f-sheet phát thêm một `console.error` nêu đích danh tên cột + danh sách tên hợp lệ (quét cả colDef nằm trong `children` của column group). Dòng này **hiện lên trong `module_simulate({ renderUI: true })`** — warning gốc của AG Grid thì không.
+
+Cần một kiểu khác hai kiểu trên (tiền tệ, phần trăm, ngày-giờ…) thì **đừng đặt tên mới cho `type`** — khai thẳng `valueFormatter`/`valueParser`/`filter` trên colDef đó.
+
+### Cell renderer dựng sẵn (`cellRenderer`)
+
+f-sheet đăng ký sẵn 4 renderer — dùng ngay qua `"cellRenderer": "tênRenderer"` + `cellRendererParams`, không cần khai gì thêm trong `script.js`:
+
+| Renderer | Mục đích | `cellRendererParams` |
+|---|---|---|
+| `fsHtmlCellRenderer` | In `value` ra dạng HTML thô (giống `t-html` của f-table) | *(không cần)* |
+| `fsLinkCellRenderer` | Ô dạng link | `urlField`/`textField` (field khác trong dòng làm URL/nhãn, mặc định dùng `value`), `icon` (mdi, tuỳ chọn), `target` — `'dialog'` mở qua `openWindow({id: wid, title, url, onclose})`, còn lại là target của thẻ `<a>` (mặc định `_blank`) |
+| `fsButtonCellRenderer` | Ô dạng nút bấm nhỏ | `label`, `icon` (mdi, tuỳ chọn), `color` (mặc định `#1976d2`); bấm vào: có `url` → `openWindow({id: wid, title, url, onclose})`, không có `url` → `tableActionEvent({action, item: data})` (action đặt tên trong `action`) |
+| `fsMenuCellRenderer` | Nút `⋮` mở menu thả xuống theo dòng | `items` — mảng `{icon, text, color, action}` hoặc hàm `function(params)` trả về mảng đó (để tính động theo dòng); `icon` cho nút mở menu (mặc định `mdi-dots-vertical`). Bấm một item → `tableActionEvent({action: item.action, item: data})` |
+
+`fsButtonCellRenderer`/`fsMenuCellRenderer` dùng lại `openWindow`/`tableActionEvent` — 2 hàm global gốc của FUI (giống hệt cách `t-link`/`t-button`/`t-menu` của `f-table` hoạt động), không phải cơ chế riêng của f-sheet.
+
+**Tên hàm global tự viết** cũng dùng được trực tiếp cho cả `cellRenderer`/`cellEditor` lẫn `cellEditorParams`/`cellRendererParams` — khai hàm đó trong `script.js` của module rồi tham chiếu bằng tên (string). f-sheet tự nhận diện và đăng ký (kể cả khi colDef nằm trong `children` của một column group), không cần đăng ký thủ công.
+
+### Cột số — `"type": "number"`
+
+Khai `"type": "number"` là đủ, f-sheet tự gắn 4 thứ (mỗi thứ chỉ gắn khi colDef **chưa** tự khai, nên muốn khác mặc định thì cứ khai đè):
+
+| Tự gắn | Hành vi |
+|---|---|
+| `cellStyle` | Canh **phải** |
+| `valueFormatter` | Phân cách nghìn `toLocaleString('en-US', { maximumFractionDigits: 10 })` → `1,234,567.89`. Chỉ áp lúc **hiển thị** — click vào ô sửa vẫn thấy số thô |
+| `valueParser` | Parse khi rời ô sửa: rỗng/`null`/`undefined` → `null` thật (không phải `""`), chuỗi số → `Number`, chuỗi hỏng → `null`. Áp cho cả paste-từ-Excel |
+| `filter` | `agNumberColumnFilter` (lọc lớn hơn/nhỏ hơn/bằng thay vì lọc text) |
+
+### Cột ngày — `"type": "date"`
+
+Khai `"type": "date"` là đủ, f-sheet tự gắn 4 thứ (mỗi thứ chỉ gắn khi colDef **chưa** tự khai):
+
+| Tự gắn | Hành vi |
+|---|---|
+| `cellStyle` | Canh **giữa** |
+| `valueFormatter` | Hiển thị `dd/mm/yyyy`. Giá trị không phải ngày → in **chuỗi thô** (để dữ liệu rác hiện ra, không biến ô thành trống) |
+| `valueParser` | Nhận `dd/mm/yyyy`, `dd-mm-yyyy`, `yyyy-mm-dd` và ISO datetime `2026-08-15T00:00:00` → lưu `yyyy-mm-dd`. Rỗng → `null`. Sai → `null`. Áp cho cả paste-từ-Excel |
+| `filter` | `agDateColumnFilter` (lọc trước/sau/bằng ngày) |
+
+**Hợp đồng giá trị — đây là thứ quyết định SP nhận được gì:** ô ngày luôn giữ chuỗi **`yyyy-mm-dd`** (hoặc `null`). Khớp thẳng với `f-date` (cũng emit `yyyy-mm-dd`) và với `OPENJSON ... NgayX date '$.NgayX'` phía tAPI — không phải convert gì thêm.
+
+- **Ngày không hợp lệ về `null`, ô thành rỗng** — giống hệt cột số. `31/02/2026` và `15/13/2026` bị từ chối (không âm thầm cuộn sang `03/03/2026` / `15/01/2027`).
+- **Copy và Xuất Excel lấy giá trị thô** ⇒ ra `2026-08-15`, không phải `15/08/2026`. Cố ý: dán ngược vào lưới thì parse lại được, round-trip không mất mát.
+
+#### Muốn có date picker
+
+`type: "date"` lo hiển thị/parse/lọc, **không tự gắn editor** — sửa ô vẫn là gõ text. Cần picker thì khai thêm:
+
+```json
+{ "field": "NgayThi", "headerName": "Ngày thi", "type": "date", "cellEditor": "agDateStringCellEditor" }
+```
+
+`agDateStringCellEditor` là editor **có sẵn của AG Grid**, không cần đăng ký gì. Nhưng nó đọc **giá trị thô** chứ không qua `valueFormatter`, nên ô đang giữ ISO datetime (`2026-08-15T00:00:00`) sẽ mở ra **rỗng** cho tới khi được sửa một lần. Cho SP trả `CONVERT(date, NgayThi)` là hết — cũng là lý do f-sheet không gắn editor này mặc định (gắn ngầm thì bấm Enter là ghi `null` đè lên ngày đang có).
+
+> **Không có editor nào tên `fsheetDate`.** Tên đó **từng tồn tại** trong `componentTable*.js` rồi `fsheet.js` và **đã bị gỡ**. Module cũ còn khai `"cellEditor": "fsheetDate"` thì đổi sang `"type": "date"` (thêm `agDateStringCellEditor` nếu cần picker). Luật nền cần nhớ: `cellEditor`/`cellRenderer` dạng string chỉ resolve được khi `window[tên]` là một function — tên không tồn tại thì f-sheet **im lặng** bỏ qua và AG Grid rơi về editor text, không lỗi, không cảnh báo.
+
+### Chiều cao — `:height`
+
+| Giá trị | Hành vi |
+|---|---|
+| *(bỏ trống)* | **Tự giãn theo số dòng** — AG Grid `domLayout: 'autoHeight'`, lưới cao bằng đúng nội dung, không có thanh cuộn riêng |
+| `<= 0` | **Fill tới đáy màn hình, chừa `abs(height)` px** |
+| `> 0` | px cố định (vd `":height": 300`) |
+
+Chế độ `<=0` **đo `getBoundingClientRect().top` thật** của phần tử lưới sau khi layout xong rồi tính `window.innerHeight - top - abs(height)` (sàn tối thiểu 200px), và đăng ký `window.resize` để tự cập nhật. Nghĩa là **không cần biết** header/toolbar/breadcrumb phía trên cao bao nhiêu — chỉ khai khoảng hở muốn chừa ở đáy.
+
+- **Bảng chính của module**: khai `":height": -16` — cuộn data chỉ cuộn trong lưới, trang không cuộn (lint D9). Thiếu `:height` sẽ bị D9 cảnh báo.
+- **Trong dialog**: dùng số **dương** (px cố định), vì lưới không nằm sát đáy viewport.
+- **Bảng ngắn/lookup ít dòng**: bỏ trống `:height` để tự giãn — hợp lệ, bỏ qua D9.
+- ⚠ Chế độ tự giãn **render toàn bộ dòng** (AG Grid không ảo hoá được khi không có chiều cao cố định). Vài trăm dòng trở lên thì phải khai `:height` để lấy lại virtual scrolling.
+- ⚠ Số âm **không** có nghĩa "viewport trừ đi N". Module cũ khai `":height": -220` phải sửa thành `-16`, nếu không lưới hụt mất ~200px.
+
+---
+
+## Wiring API — hợp đồng response
+
+`update-api` và `delete-api` được gọi bằng `ajaxCALL(api, { ...saveExtra, ...row })`. **SP nên trả về một dòng** dạng:
+
+```
+SELECT Success = 1, Message = N'Đã lưu'      -- hoặc Success = 0 khi lỗi nghiệp vụ
+```
+
+f-sheet đọc `res.data[0]` → hiện snackbar `Message`; `Success` quyết định đánh dấu thành công. Xem quy ước SP: [tapi-reference.md](tapi-reference.md).
+
+- **Dòng mới**: nhận khóa **âm** tạm (−1, −2…) và tô nền **xanh nhạt**; khi lưu, khóa âm được đặt `0` trong payload → SP hiểu là INSERT.
+- **Ô đã sửa**: tô nền **vàng nhạt**; "N dòng thay đổi" hiển thị trên toolbar.
+- Lưu chạy **từng dòng song song**; xong hết & không lỗi → làm mới baseline, xoá đánh dấu, emit `saved`.
+- Xoá nhiều dòng đã tồn tại (đã khai `delete-api`) → hỏi `confirm` trước rồi mới gọi API cho từng dòng; **chưa khai `delete-api`** thì xoá cục bộ ngay, không hỏi. Dòng mới (khóa âm) luôn xoá cục bộ ngay, không hỏi, không gọi API.
+
+---
+
+## Tính năng có sẵn (không cần tự code)
+
+- **Sửa inline** + theo dõi thay đổi (vàng nhạt = ô đã đổi, xanh nhạt = dòng mới).
+- **Chọn nhiều ô kiểu Excel**: kéo chuột hoặc Shift+click để chọn một khối ô liên tục.
+- **Fill handle**: kéo núm vuông ở góc dưới-phải vùng đang chọn để điền lặp lại khối nguồn sang các ô lân cận (theo chiều kéo dài hơn — ngang hoặc dọc).
+- **Copy/Cut/Paste dạng TSV** (tương thích Excel/Google Sheets): phím tắt Ctrl+C/Ctrl+X/Ctrl+V khi đang focus trong lưới, hoặc menu chuột phải (Cut/Copy/Copy with Headers/Paste).
+- **Phím Escape** bỏ vùng đang chọn.
+- Toolbar: **Xuất Excel** (luôn có, dùng `jsonToExcel`) · **Thêm** (`allow-add`) · **Lưu** (hiện khi có dòng đổi, `disabled` nếu chưa khai `update-api`) · **Huỷ thay đổi** (hiện khi có dòng đổi) · **Xoá đã chọn** (`allow-delete`, multi-select, chỉ hiện khi có dòng đang chọn).
+
+## Events & method (`$refs`)
+
+- Emit: `change(data, field, value)` (mỗi lần một ô đổi giá trị) · `save(rows)` (bấm Lưu, trước khi gọi API) · `saved` (lưu thành công toàn bộ).
+- Method: `getChangedRows()` · `addRow()` · `deleteRow(row)` · `deleteSelected()` · `discardAll()` · `exportExcel()`.
+
+---
+
+## Ví dụ trong module.json (controls)
+
+```json
+{
+  "el": "f-sheet",
+  "w": 12,
+  "attr": {
+    "label": "Bảng điểm",
+    ":items": "dsDiem",
+    "row-key": "DiemID",
+    ":columns": [
+      { "field": "MaSV",  "headerName": "Mã SV",  "editable": false, "width": 120, "pinned": "left" },
+      { "field": "HoTen", "headerName": "Họ tên", "editable": false },
+      { "field": "Diem",  "headerName": "Điểm",   "type": "number" },
+      { "field": "NgayThi","headerName": "Ngày thi", "type": "date" },
+      { "field": "GhiChu","headerName": "Ghi chú" }
+    ],
+    ":allow-add": true,
+    ":allow-delete": true,
+    "update-api": "Diem_Save",
+    "delete-api": "Diem_Delete",
+    ":save-extra": { "LopID": "vueData.lopID" },
+    ":default-item": { "Diem": 0 },
+    ":height": -16
+  }
+}
+```
+
+- `dsDiem` được nạp trước bằng một action trong `data[]` (`API`/`OUT`).
+- `Diem_Save`/`Diem_Delete` là SP tAPI trả `{ Success, Message }` mỗi dòng.
+- Kết hợp mở cửa sổ chi tiết: nút/menu trong toolbar hoặc cột gọi `openWindow` — xem [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md) §5.
+
+## Checklist
+
+1. Đã `file_import_new` đủ **2 file AG Grid**, đúng thứ tự (`ag-grid-community.min.js` trước, `fsheet.js` sau).
+2. `row-key` trỏ đúng khóa chính; SP `update-api`/`delete-api` trả `{ Success, Message }`.
+3. Cần tuỳ biến cột → dùng colDef AG Grid; ô dạng link/nút/menu → 4 cell renderer dựng sẵn (`fsHtmlCellRenderer`/`fsLinkCellRenderer`/`fsButtonCellRenderer`/`fsMenuCellRenderer`); số → `type: "number"`, ngày → `type: "date"` (không tự khai `cellStyle`/`valueFormatter`/`valueParser` tay nữa). `type` **chỉ** nhận đúng 2 tên đó — kiểu khác thì khai thẳng `valueFormatter`/`valueParser`, đừng đặt tên `type` mới.
+4. `:height` — bảng chính khai `-16`; trong dialog dùng số **dương**; bỏ trống = tự giãn (chỉ hợp cho bảng ngắn). Số âm = khoảng chừa ở đáy, **không phải** "viewport trừ N".
+5. Đừng tự dựng lại grid/CSS — mọi cấu hình lưới đi qua `columns` (AG Grid); chọn vùng/fill/copy-paste đã có sẵn, không tự viết thêm.

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

@@ -0,0 +1,351 @@
+# 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).
+
+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.
+
+---
+
+## Bước 1 — Phân tích yêu cầu
+
+Trước khi viết bất kỳ dòng code nào, xác định rõ:
+
+**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 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 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
+
+**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).
+
+---
+
+## Bước 1b — Design Review Gate (bắt buộc, trước khi viết dòng code đầu tiên)
+
+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.
+
+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).
+
+**Chọn phương án dựng UI:**
+
+| 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)). |
+
+> 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.
+
+**Ư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)
+
+**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)
+
+**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.
+
+---
+
+## Bước 2 — Dựng UI với dữ liệu cứng
+
+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.
+
+```json
+"data": [
+  { "keyword": "" },
+  { "classId": "" },
+  { "studentList": [
+      { "StudentID": "SV001", "FullName": "Nguyễn Văn A", "ClassID": "C01", "ClassName": "Lớp 10A", "GPA": 8.5 },
+      { "StudentID": "SV002", "FullName": "Trần Thị B", "ClassID": "C02", "ClassName": "Lớp 10B", "GPA": 7.2 }
+  ] },
+  { "form": {} },
+  { "dialogOpen": false }
+]
+```
+
+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).
+
+**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.
+
+**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.
+
+---
+
+## 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
+
+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}`.
+
+**Bảng mapping thường gặp:**
+
+| 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`):
+
+```
+spAPI_StudentList       -- danh sách, lọc theo ClassID + Keyword — trả đúng các cột đã hiển thị ở bước 2
+spAPI_StudentGet        -- chi tiết theo url1=StudentID
+spAPI_StudentInsert     -- thêm mới
+spAPI_StudentUpdate     -- cập nhật
+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.
+
+---
+
+## Bước 4 — Viết 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).
+
+**Template SP SELECT (danh sách):**
+
+```sql
+CREATE PROCEDURE spAPI_StudentList
+    @Keyword    nvarchar(200) = NULL,
+    @ClassID    varchar(20)   = NULL,
+    @sys_UserID varchar(9)
+AS BEGIN
+    SELECT s.StudentID, s.FullName, s.ClassID, c.ClassName, s.GPA
+    FROM tblStudent s
+    JOIN tblClass c ON s.ClassID = c.ClassID
+    WHERE (@Keyword IS NULL OR s.FullName LIKE '%' + @Keyword + '%')
+      AND (@ClassID IS NULL OR s.ClassID = @ClassID)
+    ORDER BY s.FullName
+END
+```
+
+**Template SP INSERT:**
+
+```sql
+CREATE PROCEDURE spAPI_StudentInsert
+    @StudentID  varchar(9),
+    @FullName   nvarchar(100),
+    @ClassID    varchar(20),
+    @sys_UserID varchar(9)
+AS BEGIN
+    IF EXISTS (SELECT 1 FROM tblStudent WHERE StudentID = @StudentID)
+    BEGIN
+        RAISERROR(N'Mã sinh viên đã tồn tại', 16, 1)
+        RETURN
+    END
+    INSERT INTO tblStudent (StudentID, FullName, ClassID, CreateUser, CreateTime)
+    VALUES (@StudentID, @FullName, @ClassID, @sys_UserID, GETDATE())
+    SELECT mess = N'Thêm thành công', id = @StudentID
+END
+```
+
+**Template SP DELETE:**
+
+```sql
+CREATE PROCEDURE spAPI_StudentDelete
+    @url1_StudentID varchar(9),
+    @sys_UserID     varchar(9)
+AS BEGIN
+    DELETE FROM tblStudent WHERE StudentID = @url1_StudentID
+    SELECT mess = N'Đã xoá', id = @url1_StudentID
+END
+```
+
+**Template SP GET (chi tiết, dùng convert_to_object):**
+
+```sql
+CREATE PROCEDURE spAPI_StudentGet
+    @url1_StudentID varchar(9),
+    @sys_UserID     varchar(9)
+AS BEGIN
+    SELECT convert_to_object = '',
+           s.StudentID, s.FullName, s.ClassID, c.ClassName, s.GPA, s.Email
+    FROM tblStudent s
+    JOIN tblClass c ON s.ClassID = c.ClassID
+    WHERE s.StudentID = @url1_StudentID
+END
+```
+
+> Dùng `convert_to_object = ''` khi SP trả về đúng một record → response dạng object thay vì `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).
+
+**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.
+
+`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ả:
+
+- `✓ [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**.
+
+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.
+
+**Output bước 4:** Toàn bộ SQL script đã deploy cho các SP thiết kế ở bước 3.
+
+---
+
+## Bước 5 — Thay dữ liệu cứng bằng binding API
+
+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.
+
+**5.1 Khai báo action thay cho data cứng**
+
+```json
+"data": [
+  { "keyword": "" },
+  { "classId": "" },
+  { "studentList": [] },
+
+  {
+    "fetchStudents": {
+      "API": "/{apiName}/StudentList",
+      "IN": { "Keyword": "vueData.keyword", "ClassID": "vueData.classId" },
+      "OUT": "studentList"
+    }
+  },
+  {
+    "saveStudent": {
+      "API": "/{apiName}/StudentInsert",
+      "IN": {
+        "StudentID": "vueData.form.StudentID",
+        "FullName":  "vueData.form.FullName",
+        "ClassID":   "vueData.form.ClassID"
+      },
+      "CALLBACK": [
+        { "CALL": "vueData.fetchStudents" },
+        { "MESS": "Thêm thành công" },
+        { "EXE":  "vueData.dialogOpen = false" }
+      ]
+    }
+  },
+  {
+    "deleteStudent": {
+      "API": "/{apiName}/StudentDelete/`{{vueData.selectedID}}",
+      "CONFIRM": "Bạn có chắc muốn xoá sinh viên này?",
+      "CALLBACK": { "CALL": "vueData.fetchStudents" }
+    }
+  }
+]
+```
+
+**5.2 Khai báo watch để tự load khi filter thay đổi**
+
+```json
+"watch": {
+  "keyword": { "CALL": "vueData.fetchStudents" },
+  "classId":  { "CALL": "vueData.fetchStudents" }
+}
+```
+
+**5.3 Thêm `{ "CALL": "vueData.fetchStudents" }` cuối `data[]`** để auto-load khi module mở.
+
+**Output bước 5:** `module.json` đã wiring API đầy đủ, layout không đổi so với bước 2.
+
+---
+
+## Bước 6 — Kiểm chứng tĩnh và hoàn thiện
+
+Checklist trước khi publish — **không bước nào gọi API/SP/DML thật**:
+
+**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
+
+**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
+
+**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`.
+
+**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.
+
+---
+
+## Ví dụ đầu ra hoàn chỉnh
+
+### SP cần tạo (bước 4 output)
+
+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.
+
+```sql
+-- 1. Danh sách  (file spAPI_StudentList.sql)
+CREATE PROCEDURE spAPI_StudentList @Keyword nvarchar(200), @ClassID varchar(20), @sys_UserID varchar(9)
+AS BEGIN
+    SELECT s.StudentID, s.FullName, s.ClassID, s.GPA
+    FROM tblStudent s WHERE (@Keyword = '' OR s.FullName LIKE '%'+@Keyword+'%') AND (@ClassID = '' OR s.ClassID = @ClassID)
+END
+```
+
+```sql
+-- 2. Thêm mới  (file spAPI_StudentInsert.sql)
+CREATE PROCEDURE spAPI_StudentInsert @StudentID varchar(9), @FullName nvarchar(100), @ClassID varchar(20), @sys_UserID varchar(9)
+AS BEGIN
+    INSERT INTO tblStudent(StudentID, FullName, ClassID, CreateUser, CreateTime) VALUES(@StudentID, @FullName, @ClassID, @sys_UserID, GETDATE())
+    SELECT mess = N'Thêm thành công'
+END
+```
+
+### module.json actions (bước 5 output)
+
+```json
+"fetchStudents": { "API": "/me/StudentList", "IN": { "Keyword": "vueData.keyword" }, "OUT": "studentList" },
+"addStudent":    { "API": "/me/StudentInsert", "IN": { "StudentID": "vueData.form.StudentID", "FullName": "vueData.form.FullName", "ClassID": "vueData.form.ClassID" }, "CALLBACK": [ { "CALL": "vueData.fetchStudents" }, { "MESS": "Đã thêm" } ] }
+```
+
+---
+
+## Lưu ý quan trọng
+
+- **`{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`.