@fui-org/fui-cli 2.1.4 → 2.2.0

package/skills/{fui-skill → fui}/references/tapi-reference.md

@@ -1,474 +1,474 @@
-# tAPI Reference — Transparent Query API (Core)
-
-> Owns: **tAPI conventions: SP naming (`spAPI_*`/`spAPI_AUTH_*`/`spAPIFILE_*`), params, URL, response contract, `/help` route**. Deploy workflow: [db-workflow.md](db-workflow.md).
-
-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:
-
-| 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)                       |
-
-> 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).
-
-## 1. SP naming
-
-```
-spAPI_[AUTH_]FunctionName
-```
-
-| 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:
-
-```
-spAPIFILE_Document         -- SP để GET file
-spAPIFILE_UPLOAD_Document  -- SP để nhận file upload
-```
-
-Details: [tapi-file-api.md](tapi-file-api.md).
-
----
-
-## 2. SP parameters
-
-### `@url1_`, `@url2_`, `@url3_`... — route params
-
-Taken from URL segments in order:
-
-```
-https://api.domain.vn/app/FunctionName/value1/value2
-```
-
-```sql
-@url1_GroupID varchar(50),  -- nhận "value1"
-@url2_Mode    varchar(50),  -- nhận "value2"
-```
-
-### `@sys_` — system params (injected by tAPI, never sent by client)
-
-| 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 — 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
-> "IN": { "ModuleID": "sModuleID", "sys_UserID": "vueData.user.UserID" }
->
-> // ✅ ĐÚNG — chỉ truyền custom params
-> "IN": { "ModuleID": "sModuleID" }
-> ```
-
-#### `@sys_header_*` — read HTTP headers: replace each `-` with `_`
-
-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)
-```
-
-- **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.
-
-| 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 |
-
-- 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
-    @Action                     nvarchar(100),
-    @sys_UserID                 varchar(9),
-    @sys_header_User_Agent      nvarchar(500),
-    @sys_header_X_Forwarded_For varchar(200)
-AS
-BEGIN
-    -- ISNULL vì client không gửi header thì tham số là NULL, không phải chuỗi rỗng
-    INSERT INTO tblAuditLog (Action, UserID, UserAgent, ClientIP, CreateTime)
-    VALUES (@Action, @sys_UserID,
-            ISNULL(@sys_header_User_Agent, N'(không có)'),
-            ISNULL(@sys_header_X_Forwarded_For, ''),
-            GETDATE());
-END
-```
-
-- **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).
-
-Check the name tAPI sees: `fui sp help <name>` (§3.1).
-
-### Custom params — business params
-
-Param name = JSON body field name:
-
-```sql
-@StudentID  varchar(9),
-@SemesterID int,
-@Keyword    nvarchar(200)
-```
-
-#### Param binding is LENIENT — never errors
-
-- 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.
-
-> **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
-> CREATE PROCEDURE spAPI_TS_Report
->     @HeID          int = 99,
->     @NamHoc        int = 2024,
->     @sys_UserID    varchar(9) = null,
->     @sys_SystemRight int
->
-> -- ✅ ĐÚNG
-> CREATE PROCEDURE spAPI_TS_Report
->     @HeID          int,
->     @NamHoc        int,
->     @sys_UserID    varchar(9),
->     @sys_SystemRight int
-> ```
-
-Client sends: `POST /app/FunctionName` with body `{ "StudentID": "SV001", "SemesterID": 1 }`
-
----
-
-## 3. API URL
-
-```
-{domain}/{apiName}/{FunctionName}/{url1}/{url2}...
-{domain}/{apiName}/auth/{FunctionName}/{url1}/{url2}...
-```
-
-| 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_`                                                                             |
-
-**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
-URL: https://api.example.vn/me/auth/Select_Chat
-
-SP:  spAPI_GetStudentList
-URL: https://api.example.vn/me/GetStudentList
-
-SP:  spAPI_GetStudentDetail  (@url1_StudentID)
-URL: https://api.example.vn/me/GetStudentDetail/SV001
-```
-
-> **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
->
-> ❌ SAI (thiếu /, "ts" bị nuốt vào domain): https://tapi.lhu.edu.vnts/TS_Report_HeXetTuyenSelectAll
-> ✅ ĐÚNG:                                   https://tapi.lhu.edu.vn/ts/TS_Report_HeXetTuyenSelectAll
-> ```
->
-> **Don't build URLs by hand/memory** — copy the `Wiring URL: ...` line from `fui sp verify` (or `fui sp help`) verbatim.
-
-### 3.1 Param cache & `/help` route
-
-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}
-```
-
-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):
-
-- `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. Response format
-
-### 4.1 One SELECT → array
-
-```sql
-SELECT StudentID, FullName, GPA FROM tblStudent WHERE ClassID = @ClassID
-```
-
-```json
-{
-  "data": [
-    { "StudentID": "SV001", "FullName": "Nguyen Van A", "GPA": 3.5 },
-    { "StudentID": "SV002", "FullName": "Tran Thi B", "GPA": 3.2 }
-  ]
-}
-```
-
-### 4.2 Multiple SELECTs → array of arrays
-
-Each `SELECT` becomes one sub-array in `data`:
-
-```sql
-SELECT TotalCount = COUNT(*) FROM tblStudent WHERE ClassID = @ClassID
-SELECT StudentID, FullName FROM tblStudent WHERE ClassID = @ClassID
-```
-
-```json
-{
-  "data": [
-    [{ "TotalCount": 42 }],
-    [
-      { "StudentID": "SV001", "FullName": "Nguyen Van A" },
-      { "StudentID": "SV002", "FullName": "Tran Thi B" }
-    ]
-  ]
-}
-```
-
-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` — row → object
-
-Returns an object instead of an array. **Many SELECTs** may use it; all merge into one response object.
-
-> ⚠️ 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 `{}`.
-
-- `convert_to_object = 'key'` → nested object under that key
-- `convert_to_object = ''` → merged into root
-
-**Ex 1 — named key + root merge:**
-
-```sql
-SELECT convert_to_object = 'sinhvien',
-       sys_SystemRight = @sys_SystemRight,
-       sys_FunctionRight = @sys_FunctionRight
-
-SELECT convert_to_object = '',
-       ngaythang = GETDATE(), count = 10
-```
-
-```json
-{
-  "sinhvien": {
-    "sys_SystemRight": 9,
-    "sys_FunctionRight": "[11][3]"
-  },
-  "ngaythang": "2018-09-11T11:20:47.397",
-  "count": 10
-}
-```
-
-**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 = '',
-       ProjectName = N'abc',
-       stt = 123,
-       json_data = '{"ProjectName":"T-A-P-I","menu":[{"name":"Croatia","link":"vn"},{"name":"England","link":"/tuyensinh"}]}'
-```
-
-```json
-{
-  "ProjectName": "T-A-P-I",
-  "stt": 123,
-  "menu": [
-    { "name": "Croatia", "link": "vn" },
-    { "name": "England", "link": "/tuyensinh" }
-  ]
-}
-```
-
-**Ex 3 — multiple `convert_to_object = ''` SELECTs all merge into root:**
-
-```sql
-SELECT convert_to_object = '',
-       ProjectName = N'abc', stt = 123,
-       json_data = '{"ProjectName":"T-A-P-I","menu":[{"name":"Croatia","link":"vn"},{"name":"England","link":"/tuyensinh"}]}'
-
-SELECT convert_to_object = '',
-       TruyVan2 = N'Dữ liệu của truy vấn 2',
-       json_data = '{"TruyVan2_json_string": 99}'
-```
-
-```json
-{
-  "ProjectName": "T-A-P-I",
-  "stt": 123,
-  "menu": [
-    { "name": "Croatia", "link": "vn" },
-    { "name": "England", "link": "/tuyensinh" }
-  ],
-  "TruyVan2": "Dữ liệu của truy vấn 2",
-  "TruyVan2_json_string": 99
-}
-```
-
-### 4.4 `[json_data:FieldName]` — JSON string column → object
-
-Return a JSON-string column as an object:
-
-```sql
-SELECT PartID, PartName, [json_data:FileInfo] = FileInfo
-FROM tblPart WHERE PartID = @url1_PartID
-```
-
-tAPI parses it into a nested object:
-
-```json
-{
-  "PartID": "P001",
-  "PartName": "Tài liệu",
-  "FileInfo": { "fileName": "doc.pdf", "size": 1024 }
-}
-```
-
-DB column stays a string. Name after `:` = response field; after `=` = real column.
-
----
-
-## 5. Error handling in SP
-
-All errors use `RAISERROR` with severity **16**.
-
-### Normal errors (validation, data constraints)
-
-```sql
-RAISERROR(N'Dữ liệu không hợp lệ', 16, 1)
-RETURN
-```
-
-```json
-{ "Message": "Dữ liệu không hợp lệ" }
-```
-
-### Unauthorized — prefix `[Unauthorized]` → HTTP 401
-
-```sql
-IF @sys_SystemRight < 2
-BEGIN
-    RAISERROR(N'[Unauthorized]Bạn không có quyền trên chức năng này.', 16, 1)
-    RETURN
-END
-```
-
-```json
-{ "Message": "Bạn không có quyền trên chức năng này." }
-```
-
-**Mandatory:**
-
-- 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. SP design rules
-
-### Naming
-
-```
-spAPI_{Entity}{Action}
-```
-
-| 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
-spAPI_StudentGet           -- GET chi tiết (url1 = StudentID)
-spAPI_StudentInsert        -- POST thêm mới
-spAPI_StudentUpdate        -- POST cập nhật
-spAPI_StudentDelete        -- POST xoá (url1 = StudentID)
-spAPI_AUTH_CourseList      -- Danh sách môn học công khai
-```
-
-### Wiring in FUI module.json
-
-```json
-"fetchStudents": {
-  "API": "/me/StudentList",
-  "IN": { "Keyword": "vueData.keyword", "ClassID": "vueData.selectedClass" },
-  "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 thành công" } ]
-},
-"deleteStudent": {
-  "API": "/me/StudentDelete/`{{vueData.selectedID}}",
-  "CONFIRM": "Bạn có chắc muốn xoá?",
-  "CALLBACK": { "CALL": "vueData.fetchStudents" }
-}
-```
-
----
-
-## 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.
+# tAPI Reference — Transparent Query API (Core)
+
+> Owns: **tAPI conventions: SP naming (`spAPI_*`/`spAPI_AUTH_*`/`spAPIFILE_*`), params, URL, response contract, `/help` route**. Deploy workflow: [db-workflow.md](db-workflow.md).
+
+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:
+
+| 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)                       |
+
+> 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).
+
+## 1. SP naming
+
+```
+spAPI_[AUTH_]FunctionName
+```
+
+| 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:
+
+```
+spAPIFILE_Document         -- SP để GET file
+spAPIFILE_UPLOAD_Document  -- SP để nhận file upload
+```
+
+Details: [tapi-file-api.md](tapi-file-api.md).
+
+---
+
+## 2. SP parameters
+
+### `@url1_`, `@url2_`, `@url3_`... — route params
+
+Taken from URL segments in order:
+
+```
+https://api.domain.vn/app/FunctionName/value1/value2
+```
+
+```sql
+@url1_GroupID varchar(50),  -- nhận "value1"
+@url2_Mode    varchar(50),  -- nhận "value2"
+```
+
+### `@sys_` — system params (injected by tAPI, never sent by client)
+
+| 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 — 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
+> "IN": { "ModuleID": "sModuleID", "sys_UserID": "vueData.user.UserID" }
+>
+> // ✅ ĐÚNG — chỉ truyền custom params
+> "IN": { "ModuleID": "sModuleID" }
+> ```
+
+#### `@sys_header_*` — read HTTP headers: replace each `-` with `_`
+
+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)
+```
+
+- **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.
+
+| 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 |
+
+- 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
+    @Action                     nvarchar(100),
+    @sys_UserID                 varchar(9),
+    @sys_header_User_Agent      nvarchar(500),
+    @sys_header_X_Forwarded_For varchar(200)
+AS
+BEGIN
+    -- ISNULL vì client không gửi header thì tham số là NULL, không phải chuỗi rỗng
+    INSERT INTO tblAuditLog (Action, UserID, UserAgent, ClientIP, CreateTime)
+    VALUES (@Action, @sys_UserID,
+            ISNULL(@sys_header_User_Agent, N'(không có)'),
+            ISNULL(@sys_header_X_Forwarded_For, ''),
+            GETDATE());
+END
+```
+
+- **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).
+
+Check the name tAPI sees: `fui sp help <name>` (§3.1).
+
+### Custom params — business params
+
+Param name = JSON body field name:
+
+```sql
+@StudentID  varchar(9),
+@SemesterID int,
+@Keyword    nvarchar(200)
+```
+
+#### Param binding is LENIENT — never errors
+
+- 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.
+
+> **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_*`; `fui sp verify` warns earlier. Set defaults **in the body**: `SET @HeID = ISNULL(@HeID, 99)`.
+>
+> ```sql
+> -- ❌ SAI
+> CREATE PROCEDURE spAPI_TS_Report
+>     @HeID          int = 99,
+>     @NamHoc        int = 2024,
+>     @sys_UserID    varchar(9) = null,
+>     @sys_SystemRight int
+>
+> -- ✅ ĐÚNG
+> CREATE PROCEDURE spAPI_TS_Report
+>     @HeID          int,
+>     @NamHoc        int,
+>     @sys_UserID    varchar(9),
+>     @sys_SystemRight int
+> ```
+
+Client sends: `POST /app/FunctionName` with body `{ "StudentID": "SV001", "SemesterID": 1 }`
+
+---
+
+## 3. API URL
+
+```
+{domain}/{apiName}/{FunctionName}/{url1}/{url2}...
+{domain}/{apiName}/auth/{FunctionName}/{url1}/{url2}...
+```
+
+| 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_`                                                                             |
+
+**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
+URL: https://api.example.vn/me/auth/Select_Chat
+
+SP:  spAPI_GetStudentList
+URL: https://api.example.vn/me/GetStudentList
+
+SP:  spAPI_GetStudentDetail  (@url1_StudentID)
+URL: https://api.example.vn/me/GetStudentDetail/SV001
+```
+
+> **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
+>
+> ❌ SAI (thiếu /, "ts" bị nuốt vào domain): https://tapi.lhu.edu.vnts/TS_Report_HeXetTuyenSelectAll
+> ✅ ĐÚNG:                                   https://tapi.lhu.edu.vn/ts/TS_Report_HeXetTuyenSelectAll
+> ```
+>
+> **Don't build URLs by hand/memory** — copy the `url (reference only, not called; copy verbatim): ...` line from `fui sp verify` (or `fui sp help`) verbatim.
+
+### 3.1 Param cache & `/help` route
+
+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}
+```
+
+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):
+
+- `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. Response format
+
+### 4.1 One SELECT → array
+
+```sql
+SELECT StudentID, FullName, GPA FROM tblStudent WHERE ClassID = @ClassID
+```
+
+```json
+{
+  "data": [
+    { "StudentID": "SV001", "FullName": "Nguyen Van A", "GPA": 3.5 },
+    { "StudentID": "SV002", "FullName": "Tran Thi B", "GPA": 3.2 }
+  ]
+}
+```
+
+### 4.2 Multiple SELECTs → array of arrays
+
+Each `SELECT` becomes one sub-array in `data`:
+
+```sql
+SELECT TotalCount = COUNT(*) FROM tblStudent WHERE ClassID = @ClassID
+SELECT StudentID, FullName FROM tblStudent WHERE ClassID = @ClassID
+```
+
+```json
+{
+  "data": [
+    [{ "TotalCount": 42 }],
+    [
+      { "StudentID": "SV001", "FullName": "Nguyen Van A" },
+      { "StudentID": "SV002", "FullName": "Tran Thi B" }
+    ]
+  ]
+}
+```
+
+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` — row → object
+
+Returns an object instead of an array. **Many SELECTs** may use it; all merge into one response object.
+
+> ⚠️ 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 `{}`.
+
+- `convert_to_object = 'key'` → nested object under that key
+- `convert_to_object = ''` → merged into root
+
+**Ex 1 — named key + root merge:**
+
+```sql
+SELECT convert_to_object = 'sinhvien',
+       sys_SystemRight = @sys_SystemRight,
+       sys_FunctionRight = @sys_FunctionRight
+
+SELECT convert_to_object = '',
+       ngaythang = GETDATE(), count = 10
+```
+
+```json
+{
+  "sinhvien": {
+    "sys_SystemRight": 9,
+    "sys_FunctionRight": "[11][3]"
+  },
+  "ngaythang": "2018-09-11T11:20:47.397",
+  "count": 10
+}
+```
+
+**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 = '',
+       ProjectName = N'abc',
+       stt = 123,
+       json_data = '{"ProjectName":"T-A-P-I","menu":[{"name":"Croatia","link":"vn"},{"name":"England","link":"/tuyensinh"}]}'
+```
+
+```json
+{
+  "ProjectName": "T-A-P-I",
+  "stt": 123,
+  "menu": [
+    { "name": "Croatia", "link": "vn" },
+    { "name": "England", "link": "/tuyensinh" }
+  ]
+}
+```
+
+**Ex 3 — multiple `convert_to_object = ''` SELECTs all merge into root:**
+
+```sql
+SELECT convert_to_object = '',
+       ProjectName = N'abc', stt = 123,
+       json_data = '{"ProjectName":"T-A-P-I","menu":[{"name":"Croatia","link":"vn"},{"name":"England","link":"/tuyensinh"}]}'
+
+SELECT convert_to_object = '',
+       TruyVan2 = N'Dữ liệu của truy vấn 2',
+       json_data = '{"TruyVan2_json_string": 99}'
+```
+
+```json
+{
+  "ProjectName": "T-A-P-I",
+  "stt": 123,
+  "menu": [
+    { "name": "Croatia", "link": "vn" },
+    { "name": "England", "link": "/tuyensinh" }
+  ],
+  "TruyVan2": "Dữ liệu của truy vấn 2",
+  "TruyVan2_json_string": 99
+}
+```
+
+### 4.4 `[json_data:FieldName]` — JSON string column → object
+
+Return a JSON-string column as an object:
+
+```sql
+SELECT PartID, PartName, [json_data:FileInfo] = FileInfo
+FROM tblPart WHERE PartID = @url1_PartID
+```
+
+tAPI parses it into a nested object:
+
+```json
+{
+  "PartID": "P001",
+  "PartName": "Tài liệu",
+  "FileInfo": { "fileName": "doc.pdf", "size": 1024 }
+}
+```
+
+DB column stays a string. Name after `:` = response field; after `=` = real column.
+
+---
+
+## 5. Error handling in SP
+
+All errors use `RAISERROR` with severity **16**.
+
+### Normal errors (validation, data constraints)
+
+```sql
+RAISERROR(N'Dữ liệu không hợp lệ', 16, 1)
+RETURN
+```
+
+```json
+{ "Message": "Dữ liệu không hợp lệ" }
+```
+
+### Unauthorized — prefix `[Unauthorized]` → HTTP 401
+
+```sql
+IF @sys_SystemRight < 2
+BEGIN
+    RAISERROR(N'[Unauthorized]Bạn không có quyền trên chức năng này.', 16, 1)
+    RETURN
+END
+```
+
+```json
+{ "Message": "Bạn không có quyền trên chức năng này." }
+```
+
+**Mandatory:**
+
+- 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. SP design rules
+
+### Naming
+
+```
+spAPI_{Entity}{Action}
+```
+
+| 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
+spAPI_StudentGet           -- GET chi tiết (url1 = StudentID)
+spAPI_StudentInsert        -- POST thêm mới
+spAPI_StudentUpdate        -- POST cập nhật
+spAPI_StudentDelete        -- POST xoá (url1 = StudentID)
+spAPI_AUTH_CourseList      -- Danh sách môn học công khai
+```
+
+### Wiring in FUI module.json
+
+```json
+"fetchStudents": {
+  "API": "/me/StudentList",
+  "IN": { "Keyword": "vueData.keyword", "ClassID": "vueData.selectedClass" },
+  "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 thành công" } ]
+},
+"deleteStudent": {
+  "API": "/me/StudentDelete/`{{vueData.selectedID}}",
+  "CONFIRM": "Bạn có chắc muốn xoá?",
+  "CALLBACK": { "CALL": "vueData.fetchStudents" }
+}
+```
+
+---
+
+## 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.