@fui-org/fui-cli 1.3.1 → 2.0.0

package/skills/fui-skill/references/sql-clr-functions.md

@@ -1,14 +1,14 @@
-# SQL CLR Functions — Hàm mở rộng nhúng DLL trong SQL Server
+# SQL CLR Functions — DLL-backed SQL Server functions
 
-> File này sở hữu: **hàm SQL CLR: httpCall, sendMail, ImageResize, FileReader, RegexMatch...**
+> Owns: **SQL CLR functions: httpCall, sendMail, ImageResize, FileReader, RegexMatch...**
 
-Database của project có thể đã cài sẵn các **SQL CLR scalar function** (hàm SQL được backing bởi DLL .NET biên dịch sẵn, đăng ký qua `CREATE ASSEMBLY` + `CREATE FUNCTION ... EXTERNAL NAME`). Khi thấy các hàm này trong `db_schema_read` hoặc trong định nghĩa SP hiện có, có thể **gọi trực tiếp trong T-SQL** như hàm built-in bình thường — không cần cài đặt lại, không cần biết code C# bên trong.
+A project DB may have **SQL CLR scalar functions** (precompiled .NET DLL, registered via `CREATE ASSEMBLY` + `CREATE FUNCTION ... EXTERNAL NAME`). If they appear in `fui schema` or in an existing SP definition, **call them directly in T-SQL** like built-ins — no install, no need to know the C#.
 
-Nếu hàm cần dùng không có trong danh sách dưới đây (không tồn tại trong DB), **không tự bịa ra** — báo cho user biết là DB chưa có hàm này.
+A needed function is not in the DB → **do not invent it**; tell the user the DB lacks it.
 
 ---
 
-## 1. `SQLImageHelper` — Xử lý ảnh
+## 1. `SQLImageHelper` — images
 
 ### `dbo.ImageResize`
 
@@ -17,17 +17,17 @@ dbo.ImageResize(@extension nvarchar(10), @OriginalImage varbinary(max), @maxWidt
 RETURNS varbinary(max)
 ```
 
-Resize ảnh nhị phân về kích thước tối đa `@maxWidth` x `@maxHeight`.
+Resizes to at most `@maxWidth` x `@maxHeight`.
 
-| Tham số | Ý nghĩa |
-|---|---|
-| `@extension` | Định dạng ảnh output, ví dụ `'jpg'`, `'png'` |
-| `@OriginalImage` | Dữ liệu ảnh gốc dạng `varbinary` |
-| `@maxWidth`, `@maxHeight` | Kích thước tối đa (px) |
-| `@preserverAspectRatio` | `1` = giữ tỉ lệ khung hình, resize theo cạnh dài nhất; `0` = resize ép đúng `maxWidth`x`maxHeight` |
-| `@quality` | Chất lượng nén (thường 1-100) |
+| Param                     | Meaning                                                                        |
+| ------------------------- | ------------------------------------------------------------------------------ |
+| `@extension`              | Output format, e.g. `'jpg'`, `'png'`                                           |
+| `@OriginalImage`          | Source image `varbinary`                                                       |
+| `@maxWidth`, `@maxHeight` | Max size (px)                                                                  |
+| `@preserverAspectRatio`   | `1` = keep ratio, fit longest side; `0` = force exactly `maxWidth`x`maxHeight` |
+| `@quality`                | Compression quality (usually 1-100)                                            |
 
-Trả về `varbinary` — ảnh đã resize, ghi thẳng vào cột `varbinary`/file hoặc trả qua tAPI File.
+Returns resized `varbinary` — write to a `varbinary` column/file or return via tAPI File.
 
 ### `dbo.ImageCrop`
 
@@ -36,15 +36,15 @@ dbo.ImageCrop(@OriginalImage varbinary(max), @StartAtX int, @StartAtY int, @Widt
 RETURNS varbinary(max)
 ```
 
-Cắt (crop) một vùng chữ nhật từ ảnh gốc, bắt đầu tại `(@StartAtX, @StartAtY)`, kích thước `@Width` x `@Height`.
+Crops a `@Width` x `@Height` rectangle starting at `(@StartAtX, @StartAtY)`.
 
 ---
 
-## 2. `SQLHttpHelper` — HTTP call, public value store, gửi mail
+## 2. `SQLHttpHelper` — HTTP, public value store, mail
 
 ### `dbo.publicValueUUID` / `publicValueGet` / `publicValueSet`
 
-Một key-value store dùng chung ở tầng server (không phải bảng SQL) — hữu ích để lưu tạm state xuyên suốt nhiều lần gọi SP mà không cần tạo bảng.
+Server-level shared key-value store (not a SQL table) — keeps temp state across SP calls without a table.
 
 ```sql
 dbo.publicValueUUID() RETURNS nvarchar(max)          -- sinh 1 UUID mới, dùng làm key
@@ -52,50 +52,50 @@ dbo.publicValueGet(@name nvarchar(max)) RETURNS nvarchar(max)   -- đọc value
 dbo.publicValueSet(@name nvarchar(max), @Data nvarchar(max)) RETURNS int   -- ghi value theo key
 ```
 
-### `dbo.httpCall` / `dbo.httpAPI` — Gọi HTTP request từ T-SQL
+### `dbo.httpCall` / `dbo.httpAPI` — HTTP from T-SQL
 
 ```sql
 dbo.httpCall(@Method nvarchar(max), @URL nvarchar(max), @Header nvarchar(max), @Data nvarchar(max))
 RETURNS nvarchar(max)
 ```
 
-`httpAPI` có chữ ký tham số **giống hệt** `httpCall` (khác implementation nội bộ — dùng khi cần gọi API nội bộ tAPI, còn `httpCall` dùng cho HTTP tổng quát ra ngoài).
+`httpAPI` has the **identical** signature (different internals): use `httpAPI` for internal tAPI calls, `httpCall` for general outbound HTTP.
 
-| Tham số | Ý nghĩa |
-|---|---|
-| `@Method` | `'GET'`, `'POST'`, `'PUT'`, `'DELETE'`... (không phân biệt hoa thường, mặc định `GET` nếu rỗng) |
-| `@URL` | URL đầy đủ, phải là absolute URL hợp lệ |
-| `@Header` | Danh sách header, xem cú pháp bên dưới — truyền `''` nếu không cần custom header |
-| `@Data` | Body request dạng JSON string — **chỉ được gửi khi Method khác GET/HEAD**; luôn gửi dưới dạng `Content-Type: application/json` trừ khi `@Header` override lại |
+| Param     | Meaning                                                                                                                          |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `@Method` | `'GET'`, `'POST'`, `'PUT'`, `'DELETE'`... (case-insensitive; empty → `GET`)                                                      |
+| `@URL`    | Full, valid absolute URL                                                                                                         |
+| `@Header` | Header list, syntax below — `''` for none                                                                                        |
+| `@Data`   | JSON string body — **sent only when Method is not GET/HEAD**; always `Content-Type: application/json` unless `@Header` overrides |
 
-**Ví dụ:**
+**Example:**
 
 ```sql
 SELECT dbo.httpCall('POST', 'https://tapi.example.vn/me/auth/ApplicationList', '', '')
 ```
 
-#### Cú pháp `@Header` — pipe-delimited `Key: Value`
+#### `@Header` syntax — pipe-delimited `Key: Value`
 
-Đây là phần quan trọng nhất khi dùng `httpCall`/`httpAPI`. `@Header` là một chuỗi duy nhất, mỗi cặp header cách nhau bởi `|`, mỗi cặp có dạng `Key: Value` (tách bằng dấu `:` đầu tiên, phần còn lại — kể cả nếu chứa `:` — thuộc về value):
+Most important part. One string; pairs separated by `|`; each pair `Key: Value`, split on the **first** `:` (the rest, including further `:`, is the value):
 
 ```
 "Authorization: Bearer eyJhbGciOi...|X-Custom-Header: abc123"
 ```
 
-Implementation (C#) xử lý như sau — **không phân biệt hoa/thường tên header**, và một số tên có xử lý đặc biệt:
+Header names are **case-insensitive**; special handling:
 
-| Header name | Hành vi |
-|---|---|
-| `Authorization`, `X-*`, mọi tên khác | Add thẳng vào request headers (`TryAddWithoutValidation`) — dùng cho token, API key |
-| `referer` / `referrer` | Parse thành URI, set `request.Headers.Referrer` |
-| `user-agent` | Ghi đè `User-Agent` mặc định |
-| `accept` | Ghi đè `Accept` |
-| `accept-language` | Ghi đè `Accept-Language` |
-| `accept-encoding` | Ghi đè `Accept-Encoding` |
-| `content-type` | Nếu request có body (`Method` khác GET/HEAD) → set vào `Content.Headers.Content-Type` (ghi đè `application/json` mặc định); nếu không có body → set vào request headers thường |
-| Bất kỳ header nào bắt đầu bằng `content-` (khác `content-type`) | Nếu có body → route vào `Content.Headers` thay vì request headers (theo chuẩn HTTP — các header `Content-*` mô tả nội dung body) |
+| Header name                       | Behavior                                                                                                                                  |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `Authorization`, `X-*`, any other | Added to request headers as-is (`TryAddWithoutValidation`) — tokens, API keys                                                             |
+| `referer` / `referrer`            | Parsed to URI → `request.Headers.Referrer`                                                                                                |
+| `user-agent`                      | Overrides default `User-Agent`                                                                                                            |
+| `accept`                          | Overrides `Accept`                                                                                                                        |
+| `accept-language`                 | Overrides `Accept-Language`                                                                                                               |
+| `accept-encoding`                 | Overrides `Accept-Encoding`                                                                                                               |
+| `content-type`                    | With body (Method not GET/HEAD) → `Content.Headers.Content-Type` (overrides default `application/json`); no body → normal request headers |
+| Any other `content-*`             | With body → routed to `Content.Headers` instead of request headers                                                                        |
 
-**Ví dụ set Bearer token + custom header:**
+**Bearer token + custom header:**
 
 ```sql
 SELECT dbo.httpCall(
@@ -106,18 +106,18 @@ SELECT dbo.httpCall(
 )
 ```
 
-**Lưu ý khi ghép nhiều header:** không được có thêm dấu `|` thừa hoặc thiếu — mỗi cặp phải tách rõ bằng đúng 1 dấu `|`, thiếu `:` trong 1 cặp thì cặp đó bị bỏ qua (không lỗi, chỉ silent skip).
+**Joining headers:** exactly one `|` between pairs, no extra/missing `|`. A pair without `:` is **silently skipped** (no error).
 
-#### Response format của `httpCall`/`httpAPI`
+#### `httpCall`/`httpAPI` response
 
-- Nếu HTTP status = **200**: trả về **nguyên văn body** của response (không bọc thêm gì) — có thể là JSON, text thuần, hoặc bất kỳ định dạng nào server trả về.
-- Nếu HTTP status **khác 200** (400, 401, 404, 500...): trả về JSON dạng bọc lỗi:
+- Status **200**: raw response body verbatim (JSON, text, anything).
+- Status **not 200** (400, 401, 404, 500...): wrapped JSON:
   ```json
-  {"httpErrorCode": 404, "responseData": "<nội dung body, hoặc escaped string nếu không phải JSON>"}
+  { "httpErrorCode": 404, "responseData": "<nội dung body, hoặc escaped string nếu không phải JSON>" }
   ```
-  → khi parse kết quả trong SP, luôn kiểm tra xem response có field `httpErrorCode` không để biết là lỗi hay thành công.
-- Nếu URL không hợp lệ: trả về `{"httpErrorCode":0,"responseData":"Invalid URL"}`.
-- Timeout/exception khác: trả message lỗi dạng text (không phải JSON), nên khi dùng trong SP cần tự kiểm tra format trước khi `OPENJSON`.
+  → in SPs, always check for an `httpErrorCode` field to tell error from success.
+- Invalid URL: `{"httpErrorCode":0,"responseData":"Invalid URL"}`.
+- Timeout/other exception: plain-text error message (not JSON) — check the format before `OPENJSON`.
 
 ### `dbo.sendMail`
 
@@ -126,28 +126,28 @@ dbo.sendMail(@email_to nvarchar(max), @subject nvarchar(max), @content nvarchar(
 RETURNS nvarchar(max)
 ```
 
-Gửi email qua SMTP trực tiếp từ T-SQL.
+Sends email over SMTP from T-SQL.
 
-| Tham số | Ý nghĩa |
-|---|---|
-| `@email_to` | Địa chỉ người nhận |
-| `@subject` | Tiêu đề mail |
-| `@content` | Nội dung mail (HTML hoặc text) |
-| `@from` | Địa chỉ email gửi (phải khớp/được phép bởi SMTP account) |
-| `@fromDisplayName` | Tên hiển thị người gửi |
-| `@smtp_server`, `@smtp_port` | Ví dụ `'smtp.gmail.com'`, `587` |
-| `@userName`, `@Password` | Tài khoản SMTP dùng để auth |
-| `@EnableSSL` | `1` = bật SSL/TLS (bắt buộc với Gmail SMTP) |
+| Param                        | Meaning                                                    |
+| ---------------------------- | ---------------------------------------------------------- |
+| `@email_to`                  | Recipient                                                  |
+| `@subject`                   | Subject                                                    |
+| `@content`                   | Body (HTML or text)                                        |
+| `@from`                      | Sender address (must match/be allowed by the SMTP account) |
+| `@fromDisplayName`           | Sender display name                                        |
+| `@smtp_server`, `@smtp_port` | e.g. `'smtp.gmail.com'`, `587`                             |
+| `@userName`, `@Password`     | SMTP auth account                                          |
+| `@EnableSSL`                 | `1` = SSL/TLS (required for Gmail SMTP)                    |
 
 ```sql
 SELECT dbo.sendMail('user@example.vn','Tiêu đề','Nội dung','noreply@example.vn','My System','smtp.gmail.com',587,'noreply@example.vn','app-password',1)
 ```
 
-> **Bảo mật:** không hardcode `@Password` SMTP trực tiếp trong SP nếu tránh được — cân nhắc lưu qua `publicValueSet`/`publicValueGet` hoặc config bảng riêng có phân quyền, để không lộ credential khi ai đó xem definition của SP.
+> **Security:** avoid hardcoding the SMTP `@Password` in the SP — store it via `publicValueSet`/`publicValueGet` or a permission-restricted config table so it is not exposed in the SP definition.
 
 ---
 
-## 3. `SQLFileSystem` — Đọc/ghi file trên server
+## 3. `SQLFileSystem` — server files
 
 ```sql
 dbo.FileCreateFolder(@Path nvarchar(max)) RETURNS nvarchar(max)
@@ -158,22 +158,22 @@ dbo.FileDelete(@Path nvarchar(max)) RETURNS nvarchar(max)
 dbo.FileMove(@SourceFileName nvarchar(max), @DestFileName nvarchar(max)) RETURNS nvarchar(max)
 ```
 
-Thao tác trực tiếp trên filesystem của **máy SQL Server** (không phải máy client) — `@Path` là đường dẫn tuyệt đối trên server đó. Dùng khi SP cần lưu file kết quả (ví dụ ảnh đã resize bằng `ImageResize`, PDF xuất ra) vào một thư mục cố định để tAPI File API hoặc IIS phục vụ lại.
+Operates on the **SQL Server machine's** filesystem (not the client); `@Path` is an absolute server path. Use when an SP saves output (e.g. `ImageResize` result, exported PDF) to a fixed folder served by tAPI File API or IIS.
 
-| Hàm | Ý nghĩa |
-|---|---|
-| `FileCreateFolder` | Tạo thư mục (kể cả nested), trả message kết quả |
-| `FileReader` | Đọc toàn bộ nội dung file, trả `varbinary` |
-| `FileWriter` | Ghi `@Content` (varbinary) vào `@Path`, tạo mới hoặc ghi đè |
-| `FileExists` | Kiểm tra tồn tại, trả `bit` |
-| `FileDelete` | Xóa file |
-| `FileMove` | Di chuyển/đổi tên file từ `@SourceFileName` sang `@DestFileName` |
+| Function           | Meaning                                                       |
+| ------------------ | ------------------------------------------------------------- |
+| `FileCreateFolder` | Creates folder (nested too), returns result message           |
+| `FileReader`       | Reads whole file as `varbinary`                               |
+| `FileWriter`       | Writes `@Content` (varbinary) to `@Path`, create or overwrite |
+| `FileExists`       | Returns `bit`                                                 |
+| `FileDelete`       | Deletes file                                                  |
+| `FileMove`         | Moves/renames `@SourceFileName` → `@DestFileName`             |
 
-> Vì đây là thao tác trên đĩa server thật, cân nhắc quyền hạn (permission check trong SP) trước khi cho phép `FileDelete`/`FileWriter` chạy theo input từ client — tương tự nguyên tắc guard DDL/DML đã áp dụng cho `db_sql_execute_nonquery`.
+> Real server disk: add a permission check in the SP before letting client input drive `FileDelete`/`FileWriter` — same DDL/DML guard principle as `fui exec`.
 
 ---
 
-## 4. `SQLExpansionFunction` — Regex & so sánh chuỗi
+## 4. `SQLExpansionFunction` — regex & string compare
 
 ```sql
 dbo.RegexReplace(@Input nvarchar(max), @Pattern nvarchar(1000), @Replacement nvarchar(4000)) RETURNS nvarchar(max)
@@ -183,42 +183,43 @@ dbo.RegexMatchArray(@Input nvarchar(max), @Pattern nvarchar(1000)) RETURNS nvarc
 dbo.CompareWord(@String1 nvarchar(max), @String2 nvarchar(max)) RETURNS int
 ```
 
-| Hàm | Ý nghĩa |
-|---|---|
-| `RegexReplace` | Thay thế theo regex `.NET` — dùng khi T-SQL `REPLACE` không đủ (cần pattern, không phải literal string) |
-| `RegexIsMatch` | Kiểm tra `@Input` có khớp `@Pattern` không, trả `bit` — dùng validate format (email, phone, mã số...) ngay trong SP |
-| `RegexMatch` | Trả về **match đầu tiên** tìm được (`Match.Value` — toàn bộ chuỗi khớp, không tách group), rỗng nếu không khớp |
-| `RegexMatchArray` | Trả về **tất cả match, kèm từng capture group**, dạng **JSON object phẳng** (không phải array) — xem cấu trúc chi tiết bên dưới |
-| `CompareWord` | So sánh độ giống nhau giữa 2 chuỗi, trả `int` (thường là số ký tự khác biệt hoặc similarity score — kiểm tra thực tế qua `SELECT dbo.CompareWord('a','b')` nếu cần biết thang đo chính xác) |
+| Function          | Meaning                                                                                                                                      |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `RegexReplace`    | .NET regex replace — when T-SQL `REPLACE` (literal only) is not enough                                                                       |
+| `RegexIsMatch`    | `bit` match test — validate format (email, phone, codes...) in the SP                                                                        |
+| `RegexMatch`      | **First match** only (`Match.Value`, whole match, no groups); empty if none                                                                  |
+| `RegexMatchArray` | **All matches with each capture group**, as a **flat JSON object** (not array) — see below                                                   |
+| `CompareWord`     | Similarity of 2 strings as `int` (likely differing-char count or a score — check the scale with `SELECT dbo.CompareWord('a','b')` if needed) |
 
-`@Pattern` dùng cú pháp regex chuẩn .NET (`\d`, `\w`, `^$`, group `()`...), không phải T-SQL `LIKE` pattern. Cả 4 hàm regex đều **luôn bật cố định** `IgnoreCase | Multiline | Singleline` — nghĩa là mặc định **không phân biệt hoa/thường**, `^`/`$` khớp theo từng dòng, và `.` khớp cả ký tự xuống dòng — không có cách nào tắt các flag này qua tham số.
+`@Pattern` is standard .NET regex (`\d`, `\w`, `^$`, groups `()`...), not T-SQL `LIKE`. All 4 regex functions **always** use `IgnoreCase | Multiline | Singleline`: case-insensitive, `^`/`$` per line, `.` matches newlines — cannot be turned off.
 
-#### Cấu trúc thật của `RegexMatchArray` — JSON object, không phải array
+#### `RegexMatchArray` shape — JSON object, not array
 
-Dựa theo code C#, kết quả là một **object phẳng** (`{...}`), không phải `[...]`. Key có dạng `"M{m}G{g}"`:
+Flat object (`{...}`, not `[...]`), keys `"M{m}G{g}"`:
 
-- `m` = số thứ tự match (match thứ 1, 2, 3... trong `@Input`, đánh số từ 1)
-- `g` = số thứ tự group **trong chính match đó** (đánh số từ 1): `G1` luôn là **toàn bộ chuỗi khớp** (tương đương `Match.Groups[0]`, cũng là giá trị mà `RegexMatch` trả về), `G2`, `G3`... là các **capture group** `(...)` trong `@Pattern`, nếu có.
-- Nếu không có match nào, trả về object rỗng `"{}"`.
-- Giá trị mỗi key đã được loại bỏ tab/newline/carriage-return (`\t`, `\n`, `\r`) và escape dấu `"`.
+- `m` = match index in `@Input`, from 1.
+- `g` = group index **within that match**, from 1: `G1` is always the **whole match** (`Match.Groups[0]`, same as `RegexMatch`); `G2`, `G3`... are the capture groups `(...)` in `@Pattern`, if any.
+- No match → `"{}"`.
+- Values have tab/newline/CR (`\t`, `\n`, `\r`) removed and `"` escaped.
 
-Ví dụ: `RegexMatchArray('SDT: 0901 - 0902', '(\d{4})')` (pattern có 1 group) trả về:
+`RegexMatchArray('SDT: 0901 - 0902', '(\d{4})')` (one group) returns:
 
 ```json
-{"M1G1": "0901", "M1G2": "0901", "M2G1": "0902", "M2G2": "0902"}
+{ "M1G1": "0901", "M1G2": "0901", "M2G1": "0902", "M2G2": "0902" }
 ```
 
-(ở đây G1 = G2 vì toàn bộ match trùng với group con duy nhất — nếu pattern không có group con nào, mỗi match cũng chỉ sinh ra đúng 1 cặp `G1`.)
+(G1 = G2 here because the whole match equals the only group; with no groups each match yields only `G1`.)
 
-Vì đây là **object**, không phải array, nên khi parse trong T-SQL:
-- `OPENJSON(@result)` **không có `path` mặc định cho array** — vẫn chạy được nhưng trả về theo schema `key/value/type` (mỗi key `"M1G1"` là 1 row, cột `key` = tên, cột `value` = giá trị) chứ không phải mỗi match 1 row có cấu trúc lồng nhau.
-- Muốn lấy giá trị 1 match/group cụ thể theo tên biết trước, dùng `JSON_VALUE(@result, '$."M1G1"')`.
-- Muốn duyệt tất cả kết quả, dùng `OPENJSON(@result)` không truyền path, rồi tự parse tiền tố `M{m}G{g}` từ cột `key` nếu cần nhóm theo match.
+Parsing in T-SQL (it is an object):
+
+- `OPENJSON(@result)` still works but returns `key/value/type` rows (one row per key like `"M1G1"`), not one structured row per match.
+- One known match/group: `JSON_VALUE(@result, '$."M1G1"')`.
+- Iterate all: `OPENJSON(@result)` without path, parse the `M{m}G{g}` prefix from `key` to group by match.
 
 ---
 
-## 5. Khi nào dùng các hàm này trong SP
+## 5. When to use them in SPs
 
-- Luôn kiểm tra hàm đã tồn tại trong DB trước (`db_schema_read` filter theo `objectType` function, hoặc `SELECT * FROM sys.objects WHERE type='FS'`) — SQL CLR function chỉ dùng được nếu assembly đã được `CREATE ASSEMBLY` trên DB đó. Không phải DB nào cũng có.
-- Dùng trong `spAPI_*` khi nghiệp vụ cần: gọi API ngoài (`httpCall`), xử lý ảnh upload (`ImageResize`/`ImageCrop`), gửi email thông báo (`sendMail`), validate chuỗi bằng regex (`RegexIsMatch`), hoặc lưu file lên đĩa server (`FileWriter`).
-- Kết quả trả về `nvarchar(max)` dạng JSON (như `httpCall`, `RegexMatchArray`) nên dùng `OPENJSON`/`JSON_VALUE` để parse tiếp trong T-SQL trước khi trả ra ngoài qua tAPI.
+- Always confirm the function exists first (`fui schema` filtered to functions, or `SELECT * FROM sys.objects WHERE type='FS'`) — usable only if the assembly was `CREATE ASSEMBLY`'d on that DB. Not every DB has them.
+- Use in `spAPI_*` when needed: external API (`httpCall`), uploaded image processing (`ImageResize`/`ImageCrop`), notification email (`sendMail`), regex validation (`RegexIsMatch`), saving files to server disk (`FileWriter`).
+- JSON `nvarchar(max)` results (`httpCall`, `RegexMatchArray`) → parse with `OPENJSON`/`JSON_VALUE` in T-SQL before returning via tAPI.

package/skills/fui-skill/references/system-design.md

@@ -1,116 +1,91 @@
-# System Design — Thiết kế app FUI nhiều module từ đầu
+# System Design — Multi-Module App
 
-> File này sở hữu: **thiết kế app nhiều module từ mô tả: phân rã module, schema-first, menu, phân quyền**. Làm một module cụ thể xem [fullstack-workflow.md](fullstack-workflow.md).
+> Owns: **multi-module app design from a description: decomposition, schema-first, menu, permissions**. Use when the user describes a whole application, not one module. Each module still follows [fullstack-workflow.md](fullstack-workflow.md).
 
-Playbook cấp **hệ thống**: khi user mô tả cả một phần mềm (nhiều màn hình/chức năng) chứ không phải một module đơn lẻ. File này điều phối; mỗi module cụ thể vẫn theo [fullstack-workflow.md](fullstack-workflow.md).
+> Read order: this file → [db-table-design.md](db-table-design.md) (schema) → [tapi-reference.md](tapi-reference.md) (API) → [fullstack-workflow.md](fullstack-workflow.md) (per module) → [project-config.md](project-config.md) (menu/rights).
 
-> Đọc trước khi bắt tay: file này (phân rã hệ thống) → [db-table-design.md](db-table-design.md) (schema) → [tapi-reference.md](tapi-reference.md) (API) → [fullstack-workflow.md](fullstack-workflow.md) (từng module) → [project-config.md](project-config.md) (menu/quyền).
+## Step 0 — Clarify scope
 
----
+Don't code yet. Confirm:
 
-## Bước 0 — Làm rõ phạm vi trước khi thiết kế
+- **Users/roles** (admin, staff, customer...) → drives permissions & menu.
+- **Main end-to-end flows** (e.g. "create order → approve → ship").
+- **Core entities** + relations (1-n, n-n).
+- **Existing DB/project or fully new?**
+  - Existing → `fui project list`, `fui module list`, `fui schema` first.
+  - Fully new → do [project-provisioning.md](project-provisioning.md) **first** (no DB/project = nothing to design on); return once `fui db add-by-name` and `fui project new` succeed.
 
-Đừng code ngay. Xác nhận với user:
+Missing info → **ask**; never assume and build the wrong system.
 
-- **Ai dùng?** Vai trò người dùng (admin, nhân viên, khách...) → quyết định phân quyền & menu.
-- **Quy trình nghiệp vụ chính là gì?** Liệt kê các luồng end-to-end (ví dụ: "tạo đơn → duyệt → xuất kho").
-- **Dữ liệu cốt lõi (entity chính)?** Danh sách thực thể + quan hệ (1-n, n-n).
-- **Có sẵn DB/project chưa,** hay dựng mới hoàn toàn?
-  - **Có sẵn** → `project_list`, `module_list`, `db_schema_read` để nắm hiện trạng trước.
-  - **Dựng mới hoàn toàn** → làm [project-provisioning.md](project-provisioning.md) **trước file này**: chưa có database và chưa có project FUI thì không có gì để thiết kế lên. Quay lại Bước 1 sau khi `db_connect_by_name` và `project_new` đã chạy được.
+## Step 1 — Decompose into modules
 
-Nếu thiếu thông tin → **hỏi**, không tự giả định rồi dựng cả hệ thống sai hướng.
+| Principle                                   | Example                                                  |
+| ------------------------------------------- | -------------------------------------------------------- |
+| One module = one coherent screen/function   | "Student management", "Revenue report", "Order approval" |
+| Group by main entity                        | One entity's CRUD in one module (list + add/edit dialog) |
+| Split by role when flows differ             | Admin vs end-user screens → separate modules             |
+| Separate dashboards/reports from data entry | Chart summary page on its own, not inside CRUD           |
 
----
+**Output:** module table — name, purpose, entities, access roles.
 
-## Bước 1 — Phân rã hệ thống thành module
+All modules in a project follow the **same convention** (control naming, toolbar/filter/action placement); check existing ones with `fui module get` before inventing a style.
 
-Một "phần mềm" = nhiều module FUI. Quy tắc phân rã:
+## Step 2 — Schema first
 
-| Nguyên tắc | Áp dụng |
-|---|---|
-| Một module = một màn hình/chức năng mạch lạc | "Quản lý sinh viên", "Báo cáo doanh thu", "Duyệt đơn" — mỗi cái một module |
-| Nhóm theo entity chính | CRUD một entity thường gói trong một module (list + dialog thêm/sửa) |
-| Tách theo vai trò khi luồng khác nhau | Màn hình admin vs màn hình người dùng cuối → module riêng |
-| Dashboard/report tách khỏi màn nhập liệu | Trang tổng hợp (chart) riêng, không nhồi vào CRUD |
+Before any module.json:
 
-**Output:** bảng danh sách module — tên, mục đích, entity liên quan, vai trò truy cập.
+1. Tables + PK + FK for **all** entities. Per [db-table-design.md](db-table-design.md): `tbl` + PascalCase, PK `[Entity]ID`, audit `CreateUser/CreateTime/UpdateUser/UpdateTime`.
+2. n-n → junction table (e.g. `tblUserRole`).
+3. **`CREATE TABLE` is run by the developer** — fui blocks it; present DDL for review. Existing tables, gated by data loss: `ALTER TABLE ... ADD` and `DROP CONSTRAINT` run directly; `ALTER COLUMN` needs `--confirm-write`; `DROP COLUMN`/`DROP TABLE`/`SWITCH` hard-blocked.
+4. Design lookup/catalog tables early (shared dropdowns).
 
-Kiểm tra tính nhất quán: các module cùng project nên theo **cùng convention** (đặt tên control, vị trí toolbar/filter/action). Tham khảo module đã có bằng `module_get` trước khi tự sáng tạo kiểu khác.
+**Output:** tables + relations, user-confirmed.
 
----
+## Step 3 — SPs per entity
 
-## Bước 2 — Thiết kế database schema-first
+Each entity → standard set `List/Get/Insert/Update/Delete` + `AUTH_*Options` for dropdowns ([tapi-reference.md](tapi-reference.md) §1, [fullstack-workflow.md](fullstack-workflow.md) Steps 2-3).
 
-Trước khi viết bất kỳ module.json nào, chốt schema tổng thể:
+- **Shared SPs** (catalogs, lookups) → neutral names.
+- Consistent authorization via `@sys_SystemRight`/`@sys_FunctionRight` ([tapi-permission-patterns.md](tapi-permission-patterns.md)).
 
-1. Vẽ danh sách bảng + PK + FK cho **toàn bộ** entity (không chỉ một bảng). Theo quy ước [db-table-design.md](db-table-design.md): `tbl` + PascalCase, PK `[Entity]ID`, cột audit `CreateUser/CreateTime/UpdateUser/UpdateTime`.
-2. Xác định quan hệ n-n → bảng nối (ví dụ `tblUserRole`).
-3. **`CREATE TABLE` do lập trình viên tự chạy** — MCP chặn, AI trình bày DDL để user duyệt & chạy. Sửa bảng ĐÃ CÓ thì mở theo tiêu chí *mất dữ liệu hay không*: `ALTER TABLE ... ADD` và `DROP CONSTRAINT` chạy thẳng, `ALTER COLUMN` cần `confirmWrite`, còn `DROP COLUMN`/`DROP TABLE`/`SWITCH` vẫn chặn cứng.
-4. Danh mục/bảng tra cứu (lookup) thiết kế sớm — nhiều module sẽ dùng chung cho dropdown.
+## Step 4 — Project structure (system level only)
 
-**Output:** sơ đồ bảng + quan hệ, đã được user xác nhận.
+- **Menu & navigation:** `project.json` (menuLeft/menu/menuStyle) — [project-config.md](project-config.md), `examples/project-patterns.json`.
+- **Components shared across modules** → project scope `{projectId}/components/` (`fui component new`/`update` with a project, no module; see `fui component --help`) so they auto-load everywhere — [component-design.md](component-design.md).
+- **Cross-module navigation:** `pushRouter`/`openWindow` ([ui-crosswindow-patterns.md](ui-crosswindow-patterns.md)); pass IDs via URL, child module queries itself.
+- **Cross-module permissions:** unify `SystemRight`/`FunctionRight` by Step-0 roles; **define real codes before guarding** (Step 4b).
 
----
+## Step 4b — Create right DEFINITIONS before any guarded module.json
 
-## Bước 3 — Thiết kế API (SP) theo entity
+A code exists only as a row in the project's `acc.tblSysRight`/`acc.tblFunction`. `FunctionRight.includes('42')` **does not create** 42; a missing code silently hides the control ([permission-system.md](permission-system.md) §"Mandatory: a right code must EXIST before you guard with it"). Often forgotten: it is not in the project DB, schema, or any workspace file.
 
-Map mỗi entity → bộ SP tAPI chuẩn (`List/Get/Insert/Update/Delete` + `AUTH_*Options` cho dropdown). Xem [tapi-reference.md](tapi-reference.md) §1, [fullstack-workflow.md](fullstack-workflow.md) Bước 2-3.
+1. `fui right system list` + `fui right function list` — see what exists (new projects usually empty); writes cache `_db/rights.json` **keyed by `apiName`** for `fui module validate`. Multi-alias → run **per alias**; never reuse one alias's cache for another.
+2. Each Step-0 role → a `SystemRight` level (`fui right system new`, level + note). `9` = Project Admin exists already.
+3. Each separately toggled operation (approve, export, delete…) → a `FunctionRight` (`fui right function new`, code + name). Keep one `code → meaning` table in the design shared by all modules; no module invents numbers.
+4. Lock the table with the user **before** coding — changing codes after assigning real users is manual work outside fui.
 
-Ở cấp hệ thống, chú ý:
-- **SP dùng chung** (danh mục, lookup) → đặt tên trung tính, nhiều module gọi lại.
-- Phân quyền nhất quán qua `@sys_SystemRight`/`@sys_FunctionRight` — xem [tapi-permission-patterns.md](tapi-permission-patterns.md).
+## Step 5 — Build order (lowest risk first)
 
----
+0. **Infrastructure** (fully new only): database + two SQL accounts + alias `acc` + FUI project + admin rights — [project-provisioning.md](project-provisioning.md).
+1. **Schema + lookup data** — inspect with `fui query` (TOP 20).
+2. **Right definitions** (4b) — SP `@sys_FunctionRight` checks and `v-if` guards reference them; creating later means everything was written with non-existent codes.
+3. **Core-entity SPs**, statically verified with `fui sp verify` (reads body, no live call).
+4. **Main-entity CRUD module** — convention template for the rest.
+5. **Dependent modules** (reports, dashboards) once data exists.
+6. **Menu + shared components** last.
 
-## Bước 4 — Cấu trúc project: menu, điều hướng, component dùng chung
+Once the shared infrastructure (schema, rights, shared components) is settled in Steps 0-4b, modules that are INDEPENDENT of each other (steps 4-5 above) can be built **in parallel by several Claude Code sessions** instead of one after another in one session: one session per module, coordinated with `ListAgents`/`SendMessage`. How to open sessions and hand out work: → [new-session.md](new-session.md) §6.
 
-Đây là phần **chỉ có ở cấp hệ thống** (một module đơn lẻ không cần):
+Each module: full [fullstack-workflow.md](fullstack-workflow.md) — analyze → **Design Review Gate (§Step 1b)** → hard-coded UI → contract → SP → API wiring → static verification.
 
-- **Menu & điều hướng:** cấu hình trong `project.json` (menuLeft/menu/menuStyle). Xem [project-config.md](project-config.md) và `examples/project-patterns.json`.
-- **Component dùng chung nhiều module** → đặt project-scope (`{projectId}/components/`, gọi `component_new`/`component_update` với `projectId` không kèm `moduleId`) để auto-load ở mọi module. Xem [component-design.md](component-design.md).
-- **Điều hướng giữa module:** `pushRouter`/`openWindow` (xem [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md)); truyền ID qua URL, module con tự query.
-- **Phân quyền xuyên module:** thống nhất `SystemRight`/`FunctionRight` theo vai trò đã xác định ở Bước 0 — và **định nghĩa mã thật trước khi gác**, xem Bước 4b.
+## Checklist
 
----
-
-## Bước 4b — Tạo ĐỊNH NGHĨA quyền (làm TRƯỚC khi viết module.json nào có gác quyền)
-
-Vai trò xác định ở Bước 0 mới chỉ là ý định. Mã quyền chỉ tồn tại khi có dòng trong `acc.tblSysRight`/`acc.tblFunction` của project — viết `FunctionRight.includes('42')` **không tạo ra** mã 42, và mã không tồn tại làm control biến mất im lặng (chi tiết + lý do các tầng kiểm chứng không bắt được: [permission-system.md](permission-system.md) §"Bắt buộc: mã quyền phải TỒN TẠI trước khi đem gác").
-
-Hệ thống mới thường quên bước này vì nó không thuộc DB của project, không nằm trong schema, không có file nào trong workspace nhắc tới.
-
-1. `right_system_list` + `right_function_list` — xem project đã có gì (project mới thường trống; cũng ghi cache `_db/rights.json` **theo khoá `apiName`** để `module_validate` đối chiếu được. Hệ thống gọi nhiều alias thì chạy cho **từng alias**, cache của alias này không dùng cho alias kia).
-2. Map **mỗi vai trò** ở Bước 0 → một mức `SystemRight` (`right_system_new({ sysRight, note })`); `9` = Project Admin có sẵn, không cần tạo.
-3. Map **mỗi thao tác cần bật/tắt riêng** (duyệt, xuất báo cáo, xóa…) → một `FunctionRight` (`right_function_new({ functionCode, functionName })`). Đặt bảng `mã → ý nghĩa` vào phần thiết kế để mọi module dùng chung một bộ mã, không mỗi module bịa một dãy số.
-4. Chốt bảng đó với user **trước khi** code — đổi mã sau khi đã gán quyền cho user thật là việc phải làm tay ngoài MCP.
-
----
-
-## Bước 5 — Thứ tự triển khai
-
-Dựng theo thứ tự giảm rủi ro:
-
-0. **Hạ tầng** (chỉ khi dựng mới hoàn toàn): database + hai tài khoản SQL + alias `acc` + project FUI + quyền quản trị — [project-provisioning.md](project-provisioning.md).
-1. **Schema + lookup data** trước (mọi thứ phụ thuộc vào đây) — khảo sát bằng `db_sql_execute` (TOP 20).
-2. **Định nghĩa quyền** (Bước 4b) — SP kiểm `@sys_FunctionRight` và module gác `v-if` đều tham chiếu tới đây; tạo sau thì mọi thứ ở trên đã viết bằng mã chưa tồn tại.
-3. **SP cho entity cốt lõi**, kiểm chứng tĩnh bằng `db_sp_verify` (đọc thân SP + suy luận, không gọi endpoint sống).
-4. **Module CRUD entity chính** — dùng làm khuôn mẫu convention cho các module sau.
-5. **Module phụ thuộc** (báo cáo, dashboard) sau khi dữ liệu đã có.
-6. **Menu + component dùng chung** ráp cuối để nối các module.
-
-Mỗi module: theo trọn [fullstack-workflow.md](fullstack-workflow.md) — phân tích → **Design Review Gate (§Bước 1b)** → UI data cứng → chốt contract → SP → wiring API → kiểm chứng tĩnh.
-
----
-
-## Checklist cấp hệ thống
-
-- [ ] Đã liệt kê đầy đủ module + vai trò truy cập, user xác nhận phạm vi
-- [ ] Schema tổng thể (bảng + PK/FK + bảng nối + lookup) đã chốt trước khi code
-- [ ] Convention thống nhất giữa các module (tham khảo module đã có)
-- [ ] Component dùng chung đặt project-scope, không copy lặp
-- [ ] Menu/điều hướng cấu hình trong project.json
-- [ ] **Đã tạo định nghĩa quyền thật** (`right_system_new`/`right_function_new`) cho mọi vai trò/thao tác, có bảng `mã → ý nghĩa` user đã chốt — không module nào gác bằng mã chưa tồn tại
-- [ ] `module_validate` không còn warning về mã quyền (đã chạy `right_*_list` để có cache đối chiếu)
-- [ ] Phân quyền nhất quán theo vai trò xuyên suốt các SP
-- [ ] Thứ tự triển khai: schema → **định nghĩa quyền** → SP → module lõi → module phụ → menu
+- [ ] All modules + access roles listed; scope user-confirmed
+- [ ] Overall schema (PK/FK, junction, lookup) locked before coding
+- [ ] Same convention across modules
+- [ ] Shared components at project scope, not copied
+- [ ] Menu/navigation in project.json
+- [ ] **Real right definitions** (`fui right system new`/`fui right function new`) for every role/operation, user-locked `code → meaning` table — no guard uses a non-existent code
+- [ ] `fui module validate` shows no right-code warnings (`fui right * list` run for cache)
+- [ ] Permissions consistent by role across SPs
+- [ ] Order: schema → **right definitions** → SP → core module → dependent modules → menu