@fui-org/fui-cli 1.3.2 → 2.0.0

package/skills/fui-skill/references/tapi-reference.md

@@ -1,59 +1,49 @@
 # tAPI Reference — Transparent Query API (Core)
 
-> File này sở hữu: **quy ước tAPI: đặt tên SP (`spAPI_*`/`spAPI_AUTH_*`/`spAPIFILE_*`), params, URL, response contract, route `/help`**. Quy trình deploy xem [db-workflow.md](db-workflow.md).
+> Owns: **tAPI conventions: SP naming (`spAPI_*`/`spAPI_AUTH_*`/`spAPIFILE_*`), params, URL, response contract, `/help` route**. Deploy workflow: [db-workflow.md](db-workflow.md).
 
-tAPI tự sinh API từ SQL Stored Procedures. Tên SP quyết định endpoint URL, kiểu xác thực, và quyền truy cập. Không cần viết controller hay route — chỉ cần đặt tên SP đúng quy tắc.
+tAPI auto-generates APIs from SQL SPs; the SP name sets URL, auth type and access (no controllers/routes). Accepts **GET and POST** — don't specify a method in the SP; module.json picks it. Load as needed:
 
-tAPI hỗ trợ cả **GET và POST** — không cần chỉ định HTTP method khi viết SP. FUI module.json tự quyết định method dựa trên cách gọi.
+| Topic                                                                           | File                                                       |
+| ------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| Permission checks in SP body (5 patterns, `@sys_SystemRight`, `getSystemRight`) | [tapi-permission-patterns.md](tapi-permission-patterns.md) |
+| File API — GET/UPLOAD, `spAPIFILE_`, `fileContent`, `tblFileData`               | [tapi-file-api.md](tapi-file-api.md)                       |
 
-File này là **core**: naming, params, URL, response format, error handling, SP design rules, checklist. Hai chủ đề chuyên sâu đã tách ra — load thêm khi cần:
+> Image processing, outbound HTTP, email, server file I/O, regex → first check for an existing **SQL CLR function** (`httpCall`, `sendMail`, `ImageResize`, `FileWriter`, `RegexMatch`...): [sql-clr-functions.md](sql-clr-functions.md).
 
-| Chủ đề | File |
-|---|---|
-| Kiểm tra quyền trong thân SP (5 pattern, `@sys_SystemRight`, `getSystemRight`) | [tapi-permission-patterns.md](tapi-permission-patterns.md) |
-| File API — GET/UPLOAD, `spAPIFILE_`, `fileContent`, `tblFileData` | [tapi-file-api.md](tapi-file-api.md) |
-
-> Nếu SP cần xử lý ảnh, gọi HTTP ra ngoài, gửi email, đọc/ghi file trên server, hoặc regex — kiểm tra xem DB đã có sẵn **SQL CLR function** (`httpCall`, `sendMail`, `ImageResize`, `FileWriter`, `RegexMatch`...) chưa trước khi viết logic thủ công. Xem [sql-clr-functions.md](sql-clr-functions.md).
-
-## 1. Quy tắc đặt tên SP
-
-### Cấu trúc tên
+## 1. SP naming
 
 ```
 spAPI_[AUTH_]FunctionName
 ```
 
-| Phần | Bắt buộc | Ý nghĩa |
-|---|---|---|
-| `spAPI_` | ✅ | Đánh dấu SP được phép gọi qua API. Thiếu prefix này → API không gọi được |
-| `AUTH_` | ❌ | Không yêu cầu xác thực. Bỏ qua → bắt buộc phải có token hợp lệ |
-| `FunctionName` | ✅ | Tên hàm API, dùng trong URL. Ví dụ: `MessageHome`, `UserSetting` |
-
-**Ví dụ tên SP:**
+| Part           | Required | Meaning                                                          |
+| -------------- | -------- | ---------------------------------------------------------------- |
+| `spAPI_`       | ✅       | Marks SP as API-callable. Missing → API cannot call it           |
+| `AUTH_`        | ❌       | No auth required. Omitted → valid token mandatory                |
+| `FunctionName` | ✅       | API function name used in URL, e.g. `MessageHome`, `UserSetting` |
 
 ```sql
 spAPI_MessageHome       -- có auth
 spAPI_AUTH_SelectChat   -- không cần auth
 ```
 
-### File API
+File API:
 
 ```
 spAPIFILE_Document         -- SP để GET file
 spAPIFILE_UPLOAD_Document  -- SP để nhận file upload
 ```
 
-> Chi tiết File API: xem [tapi-file-api.md](tapi-file-api.md).
+Details: [tapi-file-api.md](tapi-file-api.md).
 
 ---
 
-## 2. Tham số SP
-
-Ba loại tham số:
+## 2. SP parameters
 
-### `@url1_`, `@url2_`, `@url3_`... — Route params
+### `@url1_`, `@url2_`, `@url3_`... — route params
 
-Giá trị lấy trực tiếp từ URL theo thứ tự:
+Taken from URL segments in order:
 
 ```
 https://api.domain.vn/app/FunctionName/value1/value2
@@ -64,22 +54,21 @@ https://api.domain.vn/app/FunctionName/value1/value2
 @url2_Mode    varchar(50),  -- nhận "value2"
 ```
 
-### `@sys_` — System params (tAPI tự inject, không cần truyền từ client)
+### `@sys_` — system params (injected by tAPI, never sent by client)
 
-| Tham số | Kiểu | Mô tả |
-|---|---|---|
-| `@sys_UserID` | varchar(9) | Mã người dùng đã xác thực |
-| `@sys_UserName` | varchar(50) | Tên đăng nhập |
-| `@sys_GroupID` | int | Nhóm của user |
-| `@sys_DepartmentID` | varchar(9) | Mã đơn vị |
-| `@sys_SystemRight` | int | Quyền phân tầng (1=thấp, 9=cao) |
-| `@sys_FunctionRight` | varchar(2000) | Quyền chức năng dạng `[AD][RPT][MGR]` |
-| `@sys_SessionID` | varchar(50) | Mã phiên xác thực |
-| `@sys_RawData` | nvarchar(max) | Toàn bộ JSON body từ client |
-| `@sys_header_{TênHeader}` | varchar(n) | **Một HỌ tham số, không phải một tên cố định** — đọc bất kỳ HTTP header nào; `NULL` khi client không gửi header đó. Quy tắc đặt tên ở mục ngay dưới |
+| Param                      | Type          | Meaning                                                                                                      |
+| -------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------ |
+| `@sys_UserID`              | varchar(9)    | Authenticated user ID                                                                                        |
+| `@sys_UserName`            | varchar(50)   | Login name                                                                                                   |
+| `@sys_GroupID`             | int           | User's group                                                                                                 |
+| `@sys_DepartmentID`        | varchar(9)    | Department ID                                                                                                |
+| `@sys_SystemRight`         | int           | Tiered right (1=low, 9=high)                                                                                 |
+| `@sys_FunctionRight`       | varchar(2000) | Function rights as `[AD][RPT][MGR]`                                                                          |
+| `@sys_SessionID`           | varchar(50)   | Auth session ID                                                                                              |
+| `@sys_RawData`             | nvarchar(max) | Full client JSON body                                                                                        |
+| `@sys_header_{HeaderName}` | varchar(n)    | **A family, not one fixed name** — reads any HTTP header; `NULL` if client didn't send it. Naming rule below |
 
-> **CRITICAL — Không truyền `@sys_` vào `IN` của module.json:**
-> tAPI backend tự gán toàn bộ tham số `@sys_*` từ session đã xác thực. Nếu client truyền vào `IN`, giá trị sẽ bị **bỏ qua hoặc ghi đè** bởi server — truyền vào là thừa và có thể gây nhầm lẫn.
+> **CRITICAL — never put `@sys_` in module.json `IN`.** tAPI fills all `@sys_*` from the session; client values are **ignored or overwritten**.
 >
 > ```json
 > // ❌ SAI — không đưa sys_ vào IN
@@ -88,45 +77,29 @@ https://api.domain.vn/app/FunctionName/value1/value2
 > // ✅ ĐÚNG — chỉ truyền custom params
 > "IN": { "ModuleID": "sModuleID" }
 > ```
->
-> `@sys_UserID`, `@sys_SystemRight`, `@sys_FunctionRight`... đều được tAPI tự điền — SP nhận đúng giá trị mà không cần client gửi.
 
-#### `@sys_header_*` — đọc HTTP header: thay mỗi dấu `-` bằng `_`
+#### `@sys_header_*` — read HTTP headers: replace each `-` with `_`
 
-Muốn đọc một HTTP header thì khai một tham số `@sys_header_{TênHeader}` — **bất kỳ header nào**, không
-giới hạn trong một danh sách cho sẵn. Nhưng tên header HTTP chứa dấu `-` (`User-Agent`,
-`Sec-Ch-Ua-Mobile`), mà **`-` không hợp lệ trong tên biến/tham số của SQL Server**. Viết thẳng tên
-header vào là script không biên dịch được:
+Works for **any** header. `-` is invalid in SQL Server param names, so the literal name won't compile:
 
 ```sql
 -- ❌ SAI — lỗi cú pháp ngay lúc CREATE PROCEDURE, không phải lỗi runtime
 @sys_header_User-Agent   varchar(500)
 ```
 
-**Không có cách bọc nào cứu được.** T-SQL không cho phép tên tham số dạng delimited identifier: cả
-`@[sys_header_User-Agent]` lẫn `@"sys_header_User-Agent"` đều không hợp lệ. Đừng mất thời gian thử —
-chuyển tên là con đường **duy nhất**.
+- **No quoting works**: `@[sys_header_User-Agent]` and `@"sys_header_User-Agent"` are both invalid. Renaming is the **only** way.
+- **Each `-` → one `_`.** 1-to-1: don't drop characters, change case, or merge segments.
 
-**Quy tắc chuyển: mỗi dấu `-` thành một dấu `_`.** Không bỏ bớt ký tự, không đổi hoa-thường, không ghép
-các đoạn lại với nhau — đây là phép thay thế 1-đổi-1, nên nhìn tên tham số là đọc ngược ra tên header
-ngay, không phải đoán ranh giới giữa các đoạn.
+| HTTP header        | SP param                                 |
+| ------------------ | ---------------------------------------- |
+| `User-Agent`       | `@sys_header_User_Agent`                 |
+| `Sec-Ch-Ua-Mobile` | `@sys_header_Sec_Ch_Ua_Mobile`           |
+| `X-Forwarded-For`  | `@sys_header_X_Forwarded_For`            |
+| `Accept-Language`  | `@sys_header_Accept_Language`            |
+| `Cookie`           | `@sys_header_Cookie` — no `-`, unchanged |
 
-| HTTP header | Tham số trong SP |
-|---|---|
-| `User-Agent` | `@sys_header_User_Agent` |
-| `Sec-Ch-Ua-Mobile` | `@sys_header_Sec_Ch_Ua_Mobile` |
-| `X-Forwarded-For` | `@sys_header_X_Forwarded_For` |
-| `Accept-Language` | `@sys_header_Accept_Language` |
-| `Cookie` | `@sys_header_Cookie` — không có `-` thì giữ nguyên |
-
-Chiều ngược lại (đọc SP có sẵn để biết nó lấy header nào): bỏ tiền tố `@sys_header_`, rồi đổi mọi `_`
-còn lại thành `-` — `@sys_header_Accept_Language` → `Accept-Language`.
-
-**Hoa-thường không quan trọng** — tAPI so khớp không phân biệt chữ hoa chữ thường, ở cả tiền tố lẫn tên
-header: `@sys_header_User_Agent`, `@sys_Header_User_Agent`, `@sys_header_USER_AGENT` đều tra đúng một
-header. (Đó là lý do `@sys_Header_RequestID` viết hoa chữ `H` trong bảng trên vẫn chạy.) Dù vậy **hãy
-viết đúng hoa-thường như tên header chuẩn** (`User-Agent`, không `USER_AGENT`): người đọc SP nhận ra
-ngay header nào, khỏi phải dịch. Thứ **bắt buộc** đúng vẫn chỉ là dấu `_` thay cho `-`.
+- Reverse (reading an existing SP): drop `@sys_header_`, turn remaining `_` into `-` — `@sys_header_Accept_Language` → `Accept-Language`.
+- Matching is **case-insensitive** (prefix and name): `@sys_header_User_Agent`, `@sys_Header_User_Agent`, `@sys_header_USER_AGENT` are the same header (so `@sys_Header_RequestID` works). Still use standard casing (`User-Agent`, not `USER_AGENT`). Only `_` for `-` is mandatory.
 
 ```sql
 CREATE PROCEDURE spAPI_AuditLog_Insert
@@ -145,27 +118,15 @@ BEGIN
 END
 ```
 
-Ba điều đi kèm, đừng bỏ qua:
-
-- **Vẫn là `@sys_*`, nên vẫn theo mọi luật của họ đó:** tAPI tự điền, **không** đưa vào `IN` của
-  module.json, và **không được gán default value** (`= null` là lỗi cứng — `db_sp_deploy` chặn, xem mục
-  dưới).
-- **Client không gửi header thì tham số là `NULL`** (không phải chuỗi rỗng) — và header vắng mặt là
-  chuyện bình thường, không phải ca hiếm: lời gọi từ script/server-to-server thường không có
-  `User-Agent`. `NULL` kéo theo hai hệ quả im lặng của T-SQL, bọc bằng `ISNULL(...)` ngay tại chỗ dùng:
-  - **So sánh ra UNKNOWN, không ra TRUE/FALSE.** `WHERE @sys_header_User_Agent <> 'bot'` **loại luôn**
-    dòng khi header vắng — ngược hẳn điều người viết mong đợi.
-  - **Nối chuỗi bằng `+` biến cả chuỗi thành `NULL`.** Một header vắng đủ để xoá trắng nguyên câu log.
-- **Dữ liệu header do client tự khai, KHÔNG tin được.** `User-Agent`, `X-Forwarded-For` giả được hết —
-  dùng để ghi log/thống kê thì hợp lý, lấy làm căn cứ phân quyền thì không. Quyền lấy từ
-  `@sys_UserID`/`@sys_SystemRight` (tAPI dựng từ token đã xác thực), không lấy từ header.
+- **Still `@sys_*`:** auto-filled, **not** in `IN`, **no default** (`= null` is a hard error; `fui sp deploy` blocks it, see below).
+- **Missing header → `NULL`** (not `''`) — normal, e.g. script/server-to-server calls often lack `User-Agent`. Wrap in `ISNULL(...)` at use: comparisons give UNKNOWN (`WHERE @sys_header_User_Agent <> 'bot'` **drops** the row), and `+` concatenation gives `NULL` (blanks the whole log string).
+- **Untrusted (client-supplied, spoofable).** Log/stats only, never authorization; take rights from `@sys_UserID`/`@sys_SystemRight` (from the verified token).
 
-Không chắc tAPI có nhận đúng tên mình vừa đặt không → `db_sp_help({ name })` in ra danh sách tham số
-đầu vào mà tAPI thực sự thấy (xem §3.1).
+Check the name tAPI sees: `fui sp help <name>` (§3.1).
 
-### Custom params — Tham số nghiệp vụ do lập trình viên định nghĩa
+### Custom params — business params
 
-Tên tham số = tên field trong JSON body gửi lên:
+Param name = JSON body field name:
 
 ```sql
 @StudentID  varchar(9),
@@ -173,36 +134,14 @@ Tên tham số = tên field trong JSON body gửi lên:
 @Keyword    nvarchar(200)
 ```
 
-#### Ghép tham số là KHOAN DUNG — thiếu hay thừa đều không lỗi
-
-Đây là hành vi nền tảng, quyết định cách đọc mọi mục còn lại của §2:
-
-| Tình huống | tAPI làm gì |
-|---|---|
-| Body **thiếu** một khoá mà SP có tham số | truyền **`NULL`** cho tham số đó |
-| Body **thừa** một khoá mà SP không có tham số | **bỏ qua im lặng** |
-
-**Không có ca nào báo lỗi.** Gõ sai tên khoá trong `IN` của module.json (`StudentId` thay vì
-`StudentID`) không làm request hỏng — SP chỉ nhận `NULL` và trả về kết quả rỗng hoặc sai, còn HTTP vẫn
-200. Đây là lớp lỗi hỏng-âm-thầm hay gặp nhất khi nối API.
+#### Param binding is LENIENT — never errors
 
-Hai hệ quả phải nhớ:
+- Body **lacks** a key → param gets **`NULL`**. Body has an **extra** key → **silently ignored**.
+- A typo in `IN` (`StudentId` vs `StudentID`) → SP gets `NULL`, empty/wrong data, HTTP 200. Most common silent wiring bug.
+- **Renaming/removing an SP param is a contract change with NO signal**: old modules keep sending old keys. Audit callers or compare with `fui sp help <name>` (§3.1).
+- **`NULL` follows T-SQL rules** (`<>` → UNKNOWN drops rows; `+` → `NULL`): wrap possibly-absent params in `ISNULL(...)` at use.
 
-- **Đổi/xoá tham số của SP là thay đổi contract KHÔNG phát tín hiệu.** Module cũ vẫn gửi khoá cũ, vẫn
-  chạy, chỉ là giá trị rơi vào hư không. Đừng trông chờ một lỗi để biết mình quên sửa nơi gọi — tự
-  soát, hoặc đối chiếu bằng `db_sp_help`.
-- **`NULL` lan theo luật T-SQL**: `WHERE @x <> 'y'` thành UNKNOWN nên loại luôn dòng, và `+` nối chuỗi
-  ra `NULL`. Tham số có thể vắng thì bọc `ISNULL(...)` ngay tại chỗ dùng.
-
-Kiểm tên khoá thật sự tới được SP: `db_sp_help({ name })` in danh sách tham số mà tAPI đang thấy
-(xem §3.1).
-
-> **CRITICAL — Không được gán giá trị mặc định cho bất kỳ tham số nào:**
-> tAPI **luôn truyền đủ mọi tham số của SP** — khoá nào client không gửi thì nó truyền `NULL`. Nên
-> `DEFAULT` trong khai báo SP **không bao giờ được dùng tới**: viết `@HeID int = 99` rồi không gửi
-> `HeID` thì nhận `NULL`, không phải `99`. Default ở đây là một lời hứa luôn bị phá, và nó im lặng.
-> Không gán `= value` hay `= null` cho bất kỳ tham số nào — kể cả `@sys_*`. **Đây không chỉ là quy ước**: `db_sp_deploy` chặn cứng (code-level, `detectDefaultApiParams()` trong `src/tools/db.ts`) mọi SP `spAPI_*`/`spAPIFILE_*` có tham số dạng này, và `db_sp_verify` cảnh báo sớm cùng lỗi trước cả khi deploy.
-> Cần một giá trị mặc định thì đặt **trong thân SP**: `SET @HeID = ISNULL(@HeID, 99)`.
+> **CRITICAL — no default value on any param** (`= value` or `= null`, including `@sys_*`). tAPI **always passes every param** (`NULL` if not sent), so `@HeID int = 99` silently gives `NULL`, not `99`. `fui sp deploy` hard-blocks it for `spAPI_*`/`spAPIFILE_*` (`detectDefaultApiParams()` in `src/tools/db.ts`); `fui sp verify` warns earlier. Set defaults **in the body**: `SET @HeID = ISNULL(@HeID, 99)`.
 >
 > ```sql
 > -- ❌ SAI
@@ -220,30 +159,26 @@ Kiểm tên khoá thật sự tới được SP: `db_sp_help({ name })` in danh
 >     @sys_SystemRight int
 > ```
 
-Client gửi: `POST /app/FunctionName` với body `{ "StudentID": "SV001", "SemesterID": 1 }`
+Client sends: `POST /app/FunctionName` with body `{ "StudentID": "SV001", "SemesterID": 1 }`
 
 ---
 
-## 3. URL gọi API
+## 3. API URL
 
 ```
 {domain}/{apiName}/{FunctionName}/{url1}/{url2}...
 {domain}/{apiName}/auth/{FunctionName}/{url1}/{url2}...
 ```
 
-| Phần | Ý nghĩa |
-|---|---|
-| `domain` | Domain API, ví dụ `https://api.example.vn` |
-| `apiName` | Tên apiName của ứng dụng: `me`, `congvan`, `calen`... — cũng chính là **alias kết nối DB** trong workspace (`_db/{apiName}/`) |
-| `auth` | Thêm segment này khi SP có `AUTH_` (không cần token) |
-| `FunctionName` | Phần tên sau prefix của SP |
-| `url1`, `url2`... | Route params tương ứng `@url1_`, `@url2_` |
-
-**Một project có thể có NHIỀU `apiName`** — tức nhiều database, mỗi cái một alias. `"API": "/{alias}/Ten"`
-trong module.json là thứ nói SP đó nằm ở database nào; MCP dùng đúng alias ấy làm tên thư mục
-`_db/{alias}/` và làm tham số `db` của các DB tool (xem [db-workflow.md](db-workflow.md) §1, §4).
+| Part              | Meaning                                                                                                         |
+| ----------------- | --------------------------------------------------------------------------------------------------------------- |
+| `domain`          | API domain, e.g. `https://api.example.vn`                                                                       |
+| `apiName`         | App apiName: `me`, `congvan`, `calen`... — also the **DB connection alias** in the workspace (`_db/{apiName}/`) |
+| `auth`            | Add when SP has `AUTH_` (no token)                                                                              |
+| `FunctionName`    | SP name after the prefix                                                                                        |
+| `url1`, `url2`... | Route params for `@url1_`, `@url2_`                                                                             |
 
-**Ví dụ:**
+**A project can have MANY `apiName`s** (one DB alias each). `"API": "/{alias}/Ten"` in module.json names the SP's database; fui uses that alias for `_db/{alias}/` and as `--db` of DB commands ([db-workflow.md](db-workflow.md) §1, §4).
 
 ```
 SP:  spAPI_AUTH_Select_Chat
@@ -256,8 +191,7 @@ SP:  spAPI_GetStudentDetail  (@url1_StudentID)
 URL: https://api.example.vn/me/GetStudentDetail/SV001
 ```
 
-> **CRITICAL — lỗi ghép URL hay gặp: thiếu dấu `/` giữa `domain` và `apiName`.**
-> `domain` KHÔNG BAO GIỜ tự có dấu `/` ở cuối — phải tự chèn đúng MỘT dấu `/` trước `apiName` khi ghép. Gõ tắt bằng tay rất dễ dính lỗi này vì mắt đọc lướt không phân biệt được đâu là phần domain, đâu là phần apiName trong một chuỗi liền.
+> **CRITICAL — common bug: missing `/` between `domain` and `apiName`.** `domain` NEVER ends with `/`; insert exactly ONE `/` before `apiName`.
 >
 > ```
 > domain=tapi.lhu.edu.vn, apiName=ts, function=TS_Report_HeXetTuyenSelectAll
@@ -266,32 +200,30 @@ URL: https://api.example.vn/me/GetStudentDetail/SV001
 > ✅ ĐÚNG:                                   https://tapi.lhu.edu.vn/ts/TS_Report_HeXetTuyenSelectAll
 > ```
 >
-> **Đừng tự ghép chuỗi bằng tay/trí nhớ.** `db_sp_verify` (dòng `Wiring URL: ...`) và `db_sp_help` đã tự tính URL đúng cho từng SP — copy nguyên văn dòng đó thay vì gõ lại.
+> **Don't build URLs by hand/memory** — copy the `Wiring URL: ...` line from `fui sp verify` (or `fui sp help`) verbatim.
 
-### 3.1 Cache tham số & route `/help`
+### 3.1 Param cache & `/help` route
 
-tAPI **cache chữ ký tham số** (danh sách tên/kiểu param) của mỗi hàm sau lần gọi đầu tiên. Sau khi ALTER một SP `spAPI_*`/`spAPIFILE_*` để **thêm/bớt/đổi tên/đổi kiểu tham số**, endpoint thật vẫn phục vụ theo chữ ký **cũ** cho tới khi cache được xoá.
-
-Route xoá cache = URL gọi API thật, chèn thêm `/help` ngay sau domain (trước `apiName`):
+tAPI **caches each function's param signature** after the first call. After ALTERing a `spAPI_*`/`spAPIFILE_*` SP's params (add/remove/rename/retype), the live endpoint keeps the **old** signature until cleared. Route = API URL with `/help` right after domain:
 
 ```
 {domain}/help/{apiName}/{FunctionName}          ← xoá cache + trả về tham số của hàm
 {domain}/help/{apiName}/auth/{FunctionName}
 ```
 
-Gọi route này có hai tác dụng đồng thời: **(a) xoá cache tham số** của hàm đó và **(b) trả về danh sách tham số đầu vào** — hữu ích để tra cứu trước khi wire `IN` vào module.json mà không chắc SP đang nhận params nào.
+It **(a) clears the cache** and **(b) returns the input params** (useful before wiring `IN`).
+
+**Mandatory after every SP ALTER/UPDATE** (else old signature → param errors even with a correct SP):
 
-**Quy tắc bắt buộc — xoá cache sau mỗi lần ALTER/UPDATE SP:**
-- Dùng `db_sp_deploy`: tool tự gọi `/help` xoá cache. **Gọi đúng một lần theo URL chuẩn; hỏng thì bỏ qua** — SP đã deploy xong, đây chỉ là dọn cache.
-- Dùng `db_sql_execute_nonquery` để chạy `ALTER PROCEDURE` trực tiếp: **không có auto-clear** → **bắt buộc gọi `db_sp_help` thủ công** ngay sau khi ALTER thành công. Đây là ca duy nhất bắt buộc gọi tay.
-- Không xoá cache → endpoint thật tiếp tục phục vụ theo chữ ký **cũ**, có thể gây lỗi tham số ngay cả khi SP đã đúng.
-- **`/help` báo lỗi thì DỪNG, không thử URL biến thể.** Dạng URL (`/auth/` hay không) suy ra từ tên SP, không phải thứ để đoán; thử qua lại chỉ tốn lượt mà không đổi kết quả. Chỉ quay lại `db_sp_help` khi endpoint thật thực sự còn nhận tham số cũ.
+- `fui sp deploy` auto-calls `/help` **once, standard URL; ignore failure** (SP is already deployed).
+- `ALTER PROCEDURE` via `fui exec`: **no auto-clear → run `fui sp help` manually** right after. The only manual case.
+- **`/help` errors → STOP, no URL variants.** `/auth/` or not follows from the SP name; retrying changes nothing. Re-run `fui sp help` only if the live endpoint truly still takes old params.
 
 ---
 
-## 4. Format dữ liệu trả về
+## 4. Response format
 
-### 4.1 Một SELECT — trả về array
+### 4.1 One SELECT → array
 
 ```sql
 SELECT StudentID, FullName, GPA FROM tblStudent WHERE ClassID = @ClassID
@@ -301,14 +233,14 @@ SELECT StudentID, FullName, GPA FROM tblStudent WHERE ClassID = @ClassID
 {
   "data": [
     { "StudentID": "SV001", "FullName": "Nguyen Van A", "GPA": 3.5 },
-    { "StudentID": "SV002", "FullName": "Tran Thi B",   "GPA": 3.2 }
+    { "StudentID": "SV002", "FullName": "Tran Thi B", "GPA": 3.2 }
   ]
 }
 ```
 
-### 4.2 Nhiều SELECT — trả về array of arrays
+### 4.2 Multiple SELECTs → array of arrays
 
-Mỗi `SELECT` trong SP tạo thành một mảng con trong `data`:
+Each `SELECT` becomes one sub-array in `data`:
 
 ```sql
 SELECT TotalCount = COUNT(*) FROM tblStudent WHERE ClassID = @ClassID
@@ -327,23 +259,23 @@ SELECT StudentID, FullName FROM tblStudent WHERE ClassID = @ClassID
 }
 ```
 
-**Trong FUI module.json**, đọc từng mảng con qua index:
+In module.json, read sub-arrays by index:
+
 ```json
 "OUT": "studentList",
 "CALLBACK": { "EXE": "vueData.total = vueData.studentList[0][0].TotalCount; vueData.students = vueData.studentList[1]" }
 ```
 
-### 4.3 `convert_to_object` — convert một dòng thành object
+### 4.3 `convert_to_object` — row → object
 
-Dùng khi muốn trả về record dạng object thay vì array. Một SP có thể có **nhiều SELECT** dùng `convert_to_object` — tất cả được merge vào cùng một object response.
+Returns an object instead of an array. **Many SELECTs** may use it; all merge into one response object.
 
-> ⚠️ **Quy tắc quan trọng**: Khi SELECT có `convert_to_object` **và** cột `json_data` chứa JSON string, SELECT đó chỉ được trả về **đúng 1 dòng**. Nếu nhiều hơn 1 dòng → tAPI trả về `{}` (object rỗng).
+> ⚠️ When a SELECT has `convert_to_object` **and** a `json_data` column with a JSON string, it must return **exactly 1 row**. More than 1 → tAPI returns `{}`.
 
-**Hai dạng giá trị:**
-- `convert_to_object = 'key'` → tạo nested object với tên key đó
-- `convert_to_object = ''` → merge thẳng vào root object
+- `convert_to_object = 'key'` → nested object under that key
+- `convert_to_object = ''` → merged into root
 
-**Ví dụ 1 — Kết hợp named key và root merge:**
+**Ex 1 — named key + root merge:**
 
 ```sql
 SELECT convert_to_object = 'sinhvien',
@@ -365,7 +297,7 @@ SELECT convert_to_object = '',
 }
 ```
 
-**Ví dụ 2 — `json_data` override field cùng tên:**
+**Ex 2 — `json_data` overrides same-name fields** (parsed and merged after SQL columns, so `json_data` wins, e.g. `ProjectName`):
 
 ```sql
 SELECT convert_to_object = '',
@@ -385,9 +317,7 @@ SELECT convert_to_object = '',
 }
 ```
 
-> `json_data` được parse và merge sau — nếu có field trùng tên với cột SQL (`ProjectName`), **giá trị từ `json_data` sẽ override**.
-
-**Ví dụ 3 — Nhiều SELECT cùng `convert_to_object = ''` đều merge vào root:**
+**Ex 3 — multiple `convert_to_object = ''` SELECTs all merge into root:**
 
 ```sql
 SELECT convert_to_object = '',
@@ -412,18 +342,16 @@ SELECT convert_to_object = '',
 }
 ```
 
-Tất cả SELECT trong SP đều merge vào **cùng 1 object** — không tạo array như SELECT thông thường.
-
-### 4.4 `[json_data:FieldName]` — Convert chuỗi JSON thành object
+### 4.4 `[json_data:FieldName]` — JSON string column → object
 
-Khi cột trong bảng lưu chuỗi JSON và cần trả về dạng object (không phải string), dùng alias `[json_data:FieldName]`:
+Return a JSON-string column as an object:
 
 ```sql
 SELECT PartID, PartName, [json_data:FileInfo] = FileInfo
 FROM tblPart WHERE PartID = @url1_PartID
 ```
 
-tAPI tự động parse cột có alias `json_data:FieldName` thành nested JSON object trong response:
+tAPI parses it into a nested object:
 
 ```json
 {
@@ -433,17 +361,15 @@ tAPI tự động parse cột có alias `json_data:FieldName` thành nested JSON
 }
 ```
 
-Không cần parse thủ công ở client. Cột DB vẫn lưu dạng string — chỉ response được convert.
-
-> Tên sau dấu `:` (`FileInfo`) là tên field trong response. Tên cột SQL (`FileInfo` trong `= FileInfo`) là tên cột thực trên bảng.
+DB column stays a string. Name after `:` = response field; after `=` = real column.
 
 ---
 
-## 5. Xử lý lỗi trong SP
+## 5. Error handling in SP
 
-Tất cả lỗi dùng `RAISERROR` với severity **16** — không dùng severity khác.
+All errors use `RAISERROR` with severity **16**.
 
-### Lỗi thông thường (validation, ràng buộc dữ liệu)
+### Normal errors (validation, data constraints)
 
 ```sql
 RAISERROR(N'Dữ liệu không hợp lệ', 16, 1)
@@ -454,7 +380,7 @@ RETURN
 { "Message": "Dữ liệu không hợp lệ" }
 ```
 
-### Lỗi Unauthorized (thiếu quyền) — prefix `[Unauthorized]` → HTTP 401
+### Unauthorized — prefix `[Unauthorized]` → HTTP 401
 
 ```sql
 IF @sys_SystemRight < 2
@@ -468,34 +394,33 @@ END
 { "Message": "Bạn không có quyền trên chức năng này." }
 ```
 
-**Quy tắc bắt buộc:**
-- Luôn dùng severity `16` — không dùng `11`, `14`, hay giá trị khác
-- Luôn có `RETURN` ngay sau `RAISERROR` để dừng SP
-- Prefix `N` bắt buộc cho Unicode tiếng Việt
-- **Mọi lỗi liên quan đến quyền (thiếu `SystemRight`/`FunctionRight`) phải mở message bằng `[Unauthorized]`** — tAPI đọc chuỗi này để trả HTTP status `401` thay vì `200`/`500` mặc định; client (`errorMess()` trong `fastproject.js`) rẽ nhánh xử lý riêng theo status `401` (redirect login nếu message chứa "token", ngược lại hiện lỗi quyền). tAPI tự cắt `[Unauthorized]` khỏi `Message` trả về client — text người dùng thấy không có tiền tố này. Lỗi validation/ràng buộc dữ liệu thông thường (ví dụ trên) **không** dùng prefix này.
+**Mandatory:**
 
-> **Kiểm tra quyền chi tiết (5 pattern, `getSystemRight`, thứ tự kiểm tra, quy ước message):** xem [tapi-permission-patterns.md](tapi-permission-patterns.md).
+- Always severity `16` — never `11`, `14` or anything else.
+- Always `RETURN` right after `RAISERROR`.
+- `N` prefix required for Vietnamese Unicode.
+- **Every permission error (missing `SystemRight`/`FunctionRight`) must start with `[Unauthorized]`** → HTTP `401` instead of `200`/`500`; client `errorMess()` (`fastproject.js`) redirects to login if message contains "token", else shows a permission error. tAPI strips the prefix from `Message`. Validation errors **don't** use it.
+
+> Detailed permission checks (5 patterns, `getSystemRight`, check order, message conventions): [tapi-permission-patterns.md](tapi-permission-patterns.md).
 
 ---
 
-## 6. Quy tắc thiết kế SP tốt
+## 6. SP design rules
 
-### Đặt tên SP
+### Naming
 
 ```
 spAPI_{Entity}{Action}
 ```
 
-| Action | Mô tả |
-|---|---|
-| `Select` / `List` | Truy vấn danh sách |
-| `Get` | Lấy chi tiết một bản ghi |
-| `Insert` / `Add` | Thêm mới |
-| `Update` / `Edit` | Cập nhật |
-| `Delete` / `Remove` | Xoá |
-| `AUTH_Select` | Truy vấn công khai (không cần token) |
-
-**Ví dụ chuẩn:**
+| Action              | Meaning                 |
+| ------------------- | ----------------------- |
+| `Select` / `List`   | List query              |
+| `Get`               | One record's detail     |
+| `Insert` / `Add`    | Create                  |
+| `Update` / `Edit`   | Update                  |
+| `Delete` / `Remove` | Delete                  |
+| `AUTH_Select`       | Public query (no token) |
 
 ```sql
 spAPI_StudentList          -- GET danh sách sinh viên
@@ -506,7 +431,7 @@ spAPI_StudentDelete        -- POST xoá (url1 = StudentID)
 spAPI_AUTH_CourseList      -- Danh sách môn học công khai
 ```
 
-### Wiring trong FUI module.json
+### Wiring in FUI module.json
 
 ```json
 "fetchStudents": {
@@ -532,18 +457,18 @@ spAPI_AUTH_CourseList      -- Danh sách môn học công khai
 
 ---
 
-## 7. Checklist khi thiết kế SP
-
-1. Prefix `spAPI_` bắt buộc — thiếu là API không gọi được
-2. Thêm `AUTH_` nếu endpoint công khai (login page, lookup data)
-3. `@sys_UserID` luôn có trong SP có ghi dữ liệu (audit trail)
-4. Không dùng `SELECT *` — liệt kê cột cụ thể
-5. Kiểm tra quyền ở đầu SP nếu cần, dùng `RAISERROR` + `RETURN` — xem [tapi-permission-patterns.md](tapi-permission-patterns.md)
-6. Nhiều SELECT → client đọc theo index `data[0]`, `data[1]`
-7. Một record duy nhất → dùng `convert_to_object` thay vì `data[0][0]`
-8. **Không viết `GRANT EXECUTE` vào file .sql** — thân `CREATE PROCEDURE` kéo dài tới hết batch và tAPI không hỗ trợ `GO`, nên câu GRANT đặ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 lỗi nào nổi lên. `db_sp_deploy` tự cấp quyền cho procedure mới rồi xác nhận lại bằng `sys.database_permissions` — đọc dòng `✓`/`❗` trong kết quả (chi tiết: [verification.md](verification.md#security))
-9. **Không đưa tham số `sys_*` vào `IN` của module.json** — tAPI tự inject, truyền vào là thừa
-9b. **Đọc HTTP header** → `@sys_header_{TênHeader}` với **mỗi dấu `-` đổi thành `_`** (`User-Agent` → `@sys_header_User_Agent`). Giữ nguyên dấu `-` là **lỗi cú pháp lúc CREATE PROCEDURE**, và không bọc ngoặc vuông để né được — xem §2. Header do client tự khai nên chỉ dùng để log, không dùng để gác quyền
-9c. **Ghép tham số không bao giờ báo lỗi**: khoá thiếu → `NULL`, khoá thừa → bỏ qua. Gõ sai tên khoá trong `IN` cho ra HTTP 200 + dữ liệu rỗng/sai, không cho ra lỗi — đối chiếu tên bằng `db_sp_help` thay vì chờ hệ thống báo. Cũng vì vậy `DEFAULT` trong khai báo SP vô tác dụng (tAPI luôn truyền `NULL`); mặc định phải đặt trong thân: `SET @x = ISNULL(@x, <giá trị>)`
-10. **File GET/UPLOAD**: prefix `spAPIFILE_`, cột binary alias `fileContent`, params `@sys_FileContent`/`@sys_FileName`, bảng chuẩn `tblFileData` — xem [tapi-file-api.md](tapi-file-api.md). Không tự suy từ training data.
-11. **Mọi ALTER/UPDATE SP đã deploy** (đổi tham số, đổi logic, hay bất kỳ thay đổi nào) → **BẮT BUỘC xoá cache tAPI** qua `db_sp_help` sau khi deploy — nếu không endpoint thật vẫn phục vụ theo chữ ký cũ. `db_sp_deploy` tự làm (một lần, hỏng thì bỏ qua); chỉ khi ALTER qua `db_sql_execute_nonquery` mới phải gọi `db_sp_help` thủ công.
+## 7. SP design checklist
+
+1. `spAPI_` prefix mandatory — missing means API can't call it.
+2. Add `AUTH_` for public endpoints (login page, lookup data).
+3. Always include `@sys_UserID` in SPs that write data (audit trail).
+4. No `SELECT *` — list columns.
+5. Check permissions at SP start if needed, with `RAISERROR` + `RETURN` — see [tapi-permission-patterns.md](tapi-permission-patterns.md).
+6. Multiple SELECTs → client reads by index `data[0]`, `data[1]`.
+7. Single record → use `convert_to_object` instead of `data[0][0]`.
+8. **No `GRANT EXECUTE` in the .sql file** — the SP body runs to end of batch and tAPI has no `GO` support, so a GRANT after `END` is **swallowed into the SP body** (runs every call, grants nothing, no error). `fui sp deploy` grants and confirms via `sys.database_permissions` — read its `✓`/`❗` line ([verification.md](verification.md#security)).
+9. **Never put `sys_*` params in module.json `IN`** — tAPI injects them.
+   9b. **Headers** → `@sys_header_{HeaderName}`, **each `-` → `_`**; `-` is a syntax error, brackets don't help (§2). Log only, never gate permissions.
+   9c. **Binding never errors** (missing → `NULL`, extra → ignored): check `IN` names with `fui sp help`. `DEFAULT` is useless; use `SET @x = ISNULL(@x, <giá trị>)`.
+10. **File GET/UPLOAD**: prefix `spAPIFILE_`, binary column alias `fileContent`, params `@sys_FileContent`/`@sys_FileName`, standard table `tblFileData` — see [tapi-file-api.md](tapi-file-api.md). Don't infer from training data.
+11. **Any ALTER/UPDATE of a deployed SP** (params, logic, anything) → **MUST clear tAPI cache** via `fui sp help` (§3.1). `fui sp deploy` does it (once; ignore failure); only ALTER via `fui exec` needs it manually.