@fui-org/fui-cli 1.3.2 → 2.1.0

package/skills/fui-skill/references/tapi-file-api.md

@@ -1,23 +1,19 @@
 # tAPI — File API (GET / UPLOAD)
 
-> File này sở hữu: **API file qua SP: `spAPIFILE_*`, `tblFileData`, alias `fileContent`, `@sys_FileContent`/`@sys_FileName`**.
-
-SP GET và UPLOAD file qua tAPI: prefix `spAPIFILE_`, cột binary alias `fileContent`, params `@sys_FileContent`/`@sys_FileName`, bảng chuẩn `tblFileData`. Load file này khi module cần upload/download/xem file. **Không tự suy từ training data** — tAPI có quy ước riêng.
-
-> Nền tảng SP (naming, params, response): xem [tapi-reference.md](tapi-reference.md).
+> Owns: **file APIs via SP: `spAPIFILE_*`, `tblFileData`, alias `fileContent`, `@sys_FileContent`/`@sys_FileName`**. Load when a module needs upload/download/view of files. **Never infer from training data** — tAPI has its own conventions. SP basics (naming, params, response): [tapi-reference.md](tapi-reference.md).
 
 ---
 
 ## GET file
 
-SP phải SELECT **tối thiểu 3 cột bắt buộc** (có thể thêm cột metadata tùy ý):
+SP must SELECT **at least 3 required columns** (extra metadata columns allowed):
 
-| Cột | Bắt buộc | Ý nghĩa |
-|---|---|---|
-| `FileName` | ✅ | Tên file trả về — có thể là biểu thức, ví dụ `FileName + FileType` |
-| `ContentType` | ✅ | MIME type (vd: `application/pdf`, `image/png`) |
-| `fileContent` | ✅ | Binary content — alias từ cột kiểu **`image` hoặc `varbinary`**. tAPI nhận diện đây là nội dung file cần stream qua kiểu dữ liệu này |
-| cột khác | ❌ | Metadata tùy chọn, ví dụ `Modified`, `FileSize` — phải là kiểu thông thường (không phải binary) |
+| Column        | Required | Meaning                                                                                                                   |
+| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `FileName`    | ✅       | Returned file name — may be an expression, e.g. `FileName + FileType`                                                     |
+| `ContentType` | ✅       | MIME type (e.g. `application/pdf`, `image/png`)                                                                           |
+| `fileContent` | ✅       | Binary content — alias of an **`image` or `varbinary`** column. tAPI detects the file content to stream by this data type |
+| other columns | ❌       | Optional metadata, e.g. `Modified`, `FileSize` — must be normal (non-binary) types                                        |
 
 ```sql
 -- Ví dụ thực tế: FileName ghép đuôi, thêm cột Modified, binary aliased từ FileContentBIN
@@ -34,17 +30,17 @@ AS BEGIN
 END
 ```
 
-> `fileContent` phải alias từ cột kiểu `image` hoặc `varbinary(max)` — tAPI dùng kiểu dữ liệu này để nhận biết và stream nội dung file. Tên cột trong bảng tùy ý (`FileContentBIN`, `BinaryContent`, ...).  
-> `FileName` nên bao gồm cả phần đuôi file (`.pdf`, `.xlsx`...) để browser nhận đúng kiểu.
+> `fileContent` must alias an `image` or `varbinary(max)` column — tAPI uses the type to detect and stream the file. Table column name is free (`FileContentBIN`, `BinaryContent`, ...).
+> `FileName` should include the extension (`.pdf`, `.xlsx`...) so the browser detects the type.
 
-**Tham số URL — `@fileID` và `@filename`:**
+**URL params — `@fileID` and `@filename`:**
 
-| Param | Bắt buộc | Nguồn | Ý nghĩa |
-|---|---|---|---|
-| `@fileID varchar(...)` | ✅ | Segment đầu tiên sau FunctionName | ID của file cần lấy |
-| `@filename varchar(...)` | ❌ | Segment CUỐI cùng trong URL | Phần tên file hiển thị trong URL (browser/download manager dùng để đặt tên khi tải) |
+| Param                    | Required | Source                           | Meaning                                                                              |
+| ------------------------ | -------- | -------------------------------- | ------------------------------------------------------------------------------------ |
+| `@fileID varchar(...)`   | ✅       | First segment after FunctionName | ID of the file                                                                       |
+| `@filename varchar(...)` | ❌       | LAST URL segment                 | Display file name in the URL (browser/download manager uses it to name the download) |
 
-Ngoài hai tham số trên, có thể khai báo thêm `@sys_*` auth params nếu cần kiểm tra quyền.
+Extra `@sys_*` auth params may be declared for permission checks.
 
 ```sql
 CREATE PROCEDURE spAPIFILE_Document
@@ -57,7 +53,7 @@ AS BEGIN
 END
 ```
 
-**4 route pattern hỗ trợ:**
+**4 supported routes:**
 
 ```
 {domain}/{apiName}/{FunctionName}/{fileID}
@@ -66,25 +62,23 @@ END
 {domain}/{apiName}/viewer/{FunctionName}/{fileID}/{filename}
 ```
 
-`{FunctionName}` là phần tên sau prefix `spAPIFILE_`. Ví dụ SP `spAPIFILE_Document` → URL dùng `Document`.
-
-Route `/viewer/` dùng để xem trực tiếp trong browser (inline), `/download/` để tải về.
+`{FunctionName}` is the name after the `spAPIFILE_` prefix: SP `spAPIFILE_Document` → URL uses `Document`. `/viewer/` = view inline in browser; `/download/` = download.
 
-> **Lưu ý `@filename`:** Segment này trong URL thường là tên file gốc (ví dụ `BaoCao_2024.pdf`) — browser và download manager dùng nó để đặt tên file khi tải về, không nhất thiết phải khớp với `FileName` trong bảng DB. SP không khai báo `@filename` thì tAPI vẫn nhận route có segment đó — param đơn thuần bị bỏ qua.
+> **`@filename`:** usually the original name (e.g. `BaoCao_2024.pdf`) used by browser/download manager to name the file; need not match `FileName` in the DB. If the SP doesn't declare `@filename`, tAPI still accepts the route with that segment — the param is simply ignored.
 
 ## Upload file
 
-**Params đặc biệt do tAPI tự inject khi upload:**
+**Special params injected by tAPI on upload:**
 
-| Param | Kiểu | Mô tả |
-|---|---|---|
-| `@sys_FileContent` | varbinary(max) | Binary content của file |
-| `@sys_FileName` | nvarchar(200) | Tên file gốc |
-| `@sys_FileContentType` | varchar(100) | MIME type |
-| `@sys_FileSize` | int | Kích thước file (bytes) |
-| `@sys_UploadData` | nvarchar(max) | JSON data bổ sung truyền qua header |
+| Param                  | Type           | Meaning                           |
+| ---------------------- | -------------- | --------------------------------- |
+| `@sys_FileContent`     | varbinary(max) | File binary content               |
+| `@sys_FileName`        | nvarchar(200)  | Original file name                |
+| `@sys_FileContentType` | varchar(100)   | MIME type                         |
+| `@sys_FileSize`        | int            | File size (bytes)                 |
+| `@sys_UploadData`      | nvarchar(max)  | Extra JSON data passed via header |
 
-Ngoài ra toàn bộ `@sys_` auth params cũng available: `@sys_UserID`, `@sys_UserName`, `@sys_SessionID`, `@sys_GroupID`, `@sys_DepartmentID`, `@sys_SystemRight`, `@sys_FunctionRight`.
+All `@sys_` auth params are also available: `@sys_UserID`, `@sys_UserName`, `@sys_SessionID`, `@sys_GroupID`, `@sys_DepartmentID`, `@sys_SystemRight`, `@sys_FunctionRight`.
 
 ```sql
 CREATE PROCEDURE spAPIFILE_UPLOAD_Attachment
@@ -103,9 +97,9 @@ END
 
 Route: `POST {domain}/{apiName}/upload/{spName}/{url1}/{url2}...`
 
-## Bảng lưu trữ file chuẩn — `tblFileData`
+## Standard file table — `tblFileData`
 
-Đây là cấu trúc bảng chuẩn để dùng chung với cả `spAPIFILE_` (GET) và `spAPIFILE_UPLOAD_` (POST). Khi thiết kế module có file, tạo bảng này (hoặc bảng tương tự) trước khi viết SP.
+Standard structure shared by `spAPIFILE_` (GET) and `spAPIFILE_UPLOAD_` (POST). For modules with files, create this table (or similar) before writing SPs.
 
 ```sql
 CREATE TABLE [dbo].[tblFileData](
@@ -129,23 +123,23 @@ ALTER TABLE [dbo].[tblFileData] ADD CONSTRAINT [DF_tblFileData_CreateTime]
 ALTER TABLE [dbo].[tblFileData] ADD CONSTRAINT [DF_tblFileData_ContentType]     DEFAULT ('')                                   FOR [ContentType]
 ```
 
-> **Lưu ý về DDL:** các câu `ALTER TABLE ... ADD CONSTRAINT` ở trên **chạy được qua tool** (ADD là thao tác cộng thêm). Riêng `CREATE TABLE` thì không — MCP chặn, phải do lập trình viên tự chạy. Đây là tài liệu tham chiếu cấu trúc.
+> **DDL:** the `ALTER TABLE ... ADD CONSTRAINT` statements **can run via fui** (ADD is additive). `CREATE TABLE` cannot — fui blocks it; the developer must run it. This is a structure reference.
 
-**Giải thích từng field:**
+**Fields:**
 
-| Field | Kiểu | Mô tả |
-|---|---|---|
-| `FileID` | char(36) PK | UUID tự sinh bằng `newid()` — dùng làm key trong URL |
-| `FileName` | nvarchar(200) | Tên file gốc khi upload |
-| `PhysicalName` | char(36) | UUID tự sinh — tên file thực tế lưu trên disk (tránh trùng tên) |
-| `PhysicalSegment` | char(10) | Subfolder phân tán theo ngày từ hàm `getPhysicalSegment(date)` |
-| `CreateTime` | datetime | Thời điểm tạo record, DEFAULT getdate() |
-| `WriteToDisk` | datetime NULL | Khi nào binary được ghi ra disk; `NULL` = chỉ lưu DB, chưa ra file system |
-| `BinaryContent` | image NULL | Nội dung binary của file — SP GET phải alias là `fileContent` |
-| `ContentType` | varchar(100) | MIME type, ví dụ `application/pdf`, `image/png` |
-| `Size` | int NULL | Kích thước bytes |
+| Field             | Type          | Meaning                                                                       |
+| ----------------- | ------------- | ----------------------------------------------------------------------------- |
+| `FileID`          | char(36) PK   | Auto UUID via `newid()` — used as the URL key                                 |
+| `FileName`        | nvarchar(200) | Original upload name                                                          |
+| `PhysicalName`    | char(36)      | Auto UUID — actual file name on disk (avoids collisions)                      |
+| `PhysicalSegment` | char(10)      | Date-based subfolder from `getPhysicalSegment(date)`                          |
+| `CreateTime`      | datetime      | Record creation time, DEFAULT getdate()                                       |
+| `WriteToDisk`     | datetime NULL | When the binary was written to disk; `NULL` = DB only, not on file system yet |
+| `BinaryContent`   | image NULL    | File binary — GET SP must alias it `fileContent`                              |
+| `ContentType`     | varchar(100)  | MIME type, e.g. `application/pdf`, `image/png`                                |
+| `Size`            | int NULL      | Size in bytes                                                                 |
 
-**SP GET file — map tới bảng:**
+**GET SP on the table:**
 
 ```sql
 CREATE PROCEDURE spAPIFILE_Document
@@ -162,7 +156,7 @@ AS BEGIN
 END
 ```
 
-**SP UPLOAD — lưu vào bảng:**
+**UPLOAD SP into the table:**
 
 ```sql
 CREATE PROCEDURE spAPIFILE_UPLOAD_Document
@@ -188,4 +182,4 @@ AS BEGIN
 END
 ```
 
-> **Lưu ý `BinaryContent [image]`**: Kiểu `image` là legacy của SQL Server nhưng vẫn hoạt động tốt với tAPI. Nếu muốn dùng kiểu mới hơn có thể dùng `varbinary(max)` — cả hai đều map được vào `fileContent` alias.
+> **`BinaryContent [image]`**: `image` is legacy SQL Server but works fine with tAPI. `varbinary(max)` also works — both map to the `fileContent` alias.

package/skills/fui-skill/references/tapi-permission-patterns.md

@@ -1,25 +1,20 @@
-# tAPI — Kiểm tra quyền người dùng (Permission Check Patterns)
+# tAPI — Permission Check Patterns
 
-> File này sở hữu: **5 pattern kiểm tra quyền trong thân SP (`@sys_SystemRight`, `getSystemRight`, RAISERROR)**. Khái niệm quyền xem [permission-system.md](permission-system.md).
-
-Các pattern kiểm tra quyền trong thân Stored Procedure tAPI. Load file này khi SP cần phân quyền.
-
-> Nền tảng SP (naming, params, response, RAISERROR): xem [tapi-reference.md](tapi-reference.md).
-> Khái niệm `SystemRight`/`FunctionRight`, cấu trúc `tblSysRight`/`tblFunction`, và 4 tool quản lý định nghĩa quyền: xem [permission-system.md](permission-system.md).
+> Owns: **5 permission-check patterns in SP bodies (`@sys_SystemRight`, `getSystemRight`, RAISERROR)**. Load when an SP needs authorization. SP basics (naming, params, response, RAISERROR): [tapi-reference.md](tapi-reference.md). `SystemRight`/`FunctionRight` concepts, `tblSysRight`/`tblFunction`, right-definition commands: [permission-system.md](permission-system.md).
 
 ---
 
-## Tham số hệ thống liên quan đến quyền
+## Permission-related system params
 
-tAPI tự inject các tham số sau — không cần client truyền lên:
+Injected by tAPI — the client never sends them:
 
-| Tham số | Kiểu | Mô tả |
-|---|---|---|
-| `@sys_UserID` | varchar(9) | Mã người dùng đang đăng nhập |
-| `@sys_SystemRight` | int | Mức quyền của user trên module hiện tại |
-| `@sys_FunctionRight` | varchar(2000) | Quyền chức năng dạng `[AD][RPT][MGR]` |
+| Param                | Type          | Meaning                               |
+| -------------------- | ------------- | ------------------------------------- |
+| `@sys_UserID`        | varchar(9)    | Logged-in user ID                     |
+| `@sys_SystemRight`   | int           | User's level on the current module    |
+| `@sys_FunctionRight` | varchar(2000) | Function rights like `[AD][RPT][MGR]` |
 
-**Khai báo trong SP** — luôn đặt cuối danh sách tham số, **không được gán default cho bất kỳ tham số nào, kể cả `@sys_*`** (xem [tapi-reference.md](tapi-reference.md) §2 — tAPI luôn truyền đủ mọi tham số, thiếu thì truyền `NULL`, nên `DEFAULT` không bao giờ được dùng tới; `db_sp_deploy` chặn cứng nếu có):
+**Declare** at the end of the param list. **No default on any param, including `@sys_*`** ([tapi-reference.md](tapi-reference.md) §2 — tAPI always passes every param, `NULL` when missing, so `DEFAULT` is never used; `fui sp deploy` hard-blocks it):
 
 ```sql
 CREATE PROCEDURE spAPI_EntityAction
@@ -30,31 +25,31 @@ CREATE PROCEDURE spAPI_EntityAction
 AS
 ```
 
-## Các mức `@sys_SystemRight`
+## `@sys_SystemRight` levels
 
-Ý nghĩa từng mức **do mỗi project tự định nghĩa** (`tblSysRight.Note`, quản lý qua `right_system_list`/`right_system_update` — xem [permission-system.md](permission-system.md)). Bảng dưới là quy ước phổ biến dùng khi viết pattern kiểm tra trong SP — không phải giá trị cố định của platform, ngoại trừ `9` luôn là Project Admin:
+Meaning is **defined per project** (`tblSysRight.Note`, managed via `fui right system list`/`update` — [permission-system.md](permission-system.md)). Common convention for SP checks — not platform-fixed, except `9` is always Project Admin:
 
-| Giá trị | Ý nghĩa thực tế (quy ước phổ biến) |
-|---|---|
-| `0` | Không có quyền / chưa được cấp quyền trên module |
-| `1` | Quyền xem cơ bản |
-| `2` | Quyền thao tác chuẩn (đọc, thêm, sửa thông thường) |
-| `3` | Quyền nâng cao (quản lý nội bộ, thao tác nhạy cảm) |
-| `9` | Module Admin / Project Admin (cố định trên toàn platform) |
+| Value | Common meaning                                     |
+| ----- | -------------------------------------------------- |
+| `0`   | No right / not granted on the module               |
+| `1`   | Basic view                                         |
+| `2`   | Standard operations (read, add, normal edit)       |
+| `3`   | Advanced (internal management, sensitive ops)      |
+| `9`   | Module Admin / Project Admin (fixed platform-wide) |
 
-## Helper function kiểm tra quyền theo module cụ thể
+## Helper: rights on a specific module
 
 ```sql
 dbo.getSystemRight(@ModuleID, @sys_UserID)
 ```
 
-Trả về mức `SysRight` mà user được assign cho một module xác định — dùng khi cần kiểm tra quyền trên module **khác** với module hiện tại.
+Returns the user's `SysRight` on a given module — use to check rights on a module **other than** the current one.
 
 ---
 
-## Pattern 1 — Chặn truy cập cơ bản (READ operations)
+## Pattern 1 — Basic access block (READ)
 
-Dùng cho mọi SP đọc dữ liệu cần đăng nhập. Yêu cầu ít nhất `SysRight = 2`.
+Every read SP that needs login. Requires `SysRight >= 2`.
 
 ```sql
 If @sys_SystemRight < 2
@@ -64,9 +59,9 @@ Begin
 End
 ```
 
-## Pattern 2 — Chặn user hoàn toàn không có quyền (minimal check)
+## Pattern 2 — Block only users with no right (minimal)
 
-Dùng khi muốn cho phép cả `SysRight = 1` thao tác, chỉ chặn `SysRight = 0`.
+Allows `SysRight = 1`; blocks only `SysRight = 0`.
 
 ```sql
 If @sys_SystemRight = 0
@@ -76,11 +71,12 @@ Begin
 End
 ```
 
-## Pattern 3 — Kiểm tra 2 tầng: global + module admin (WRITE operations)
+## Pattern 3 — 2-tier: global + module admin (WRITE)
+
+Writes affecting module config or other users' data. User must meet **either**:
 
-Dùng cho các thao tác ghi có tác động đến cấu hình module hoặc dữ liệu người dùng khác. User phải đạt **một trong hai điều kiện**:
-- `@sys_SystemRight >= 3` (quyền cao toàn hệ thống), **hoặc**
-- Là Module Admin (`getSystemRight >= 9`) của module đó.
+- `@sys_SystemRight >= 3` (high global right), **or**
+- Module Admin (`getSystemRight >= 9`) of that module.
 
 ```sql
 -- Tầng 1: phải có quyền cơ bản
@@ -98,9 +94,9 @@ Begin
 End
 ```
 
-## Pattern 4 — Kiểm tra logic nghiệp vụ trước khi thực thi
+## Pattern 4 — Business-rule check before executing
 
-Dùng khi thao tác hợp lệ về quyền nhưng vi phạm ràng buộc dữ liệu (ví dụ: xóa cha khi còn con).
+Authorized but violates a data constraint (e.g. deleting a parent that still has children).
 
 ```sql
 -- Kiểm tra ràng buộc trước khi xóa
@@ -113,9 +109,9 @@ End
 DELETE tblParent WHERE ParentID = @ParentID
 ```
 
-## Pattern 5 — Kiểm tra `@sys_FunctionRight`
+## Pattern 5 — `@sys_FunctionRight` check
 
-Dùng khi phân quyền theo chức năng cụ thể (không chỉ theo mức số).
+Authorization by specific function (not just numeric level).
 
 ```sql
 If CHARINDEX('[ADMIN]', @sys_FunctionRight) = 0
@@ -127,7 +123,7 @@ End
 
 ---
 
-## Quy tắc đặt thứ tự kiểm tra
+## Check order
 
 ```
 1. Kiểm tra quyền hệ thống (@sys_SystemRight)    ← luôn đầu tiên
@@ -136,23 +132,25 @@ End
 4. Kiểm tra ràng buộc nghiệp vụ                   ← sau cùng, trước khi ghi
 ```
 
-## Quy ước thông báo lỗi
+## Error message conventions
 
-| Tình huống | Message chuẩn |
-|---|---|
-| Thiếu quyền global | `N'[Unauthorized]Bạn không có quyền trên chức năng này.'` |
-| Thiếu quyền module | `N'[Unauthorized]Bạn không có quyền trên Module này.'` |
-| Thiếu quyền chức năng (`FunctionRight`) | `N'[Unauthorized]Bạn không có quyền thực hiện chức năng này.'` |
-| Vi phạm ràng buộc | Mô tả cụ thể, **không** có prefix: `N'Phải xóa X trước khi xóa Y.'` |
-| Dữ liệu không hợp lệ | `N'Dữ liệu không hợp lệ.'` hoặc mô tả cụ thể, **không** có prefix |
+| Case                                     | Standard message                                                      |
+| ---------------------------------------- | --------------------------------------------------------------------- |
+| Missing global right                     | `N'[Unauthorized]Bạn không có quyền trên chức năng này.'`             |
+| Missing module right                     | `N'[Unauthorized]Bạn không có quyền trên Module này.'`                |
+| Missing function right (`FunctionRight`) | `N'[Unauthorized]Bạn không có quyền thực hiện chức năng này.'`        |
+| Constraint violation                     | Specific description, **no** prefix: `N'Phải xóa X trước khi xóa Y.'` |
+| Invalid data                             | `N'Dữ liệu không hợp lệ.'` or specific description, **no** prefix     |
+
+**Mandatory `RAISERROR` format:**
 
-**Format `RAISERROR` bắt buộc:**
 ```sql
 RAISERROR(N'Thông báo lỗi tiếng Việt.', 16, 1)
 RETURN
 ```
-- **Severity luôn là `16`** — áp dụng cho mọi loại lỗi (validation, unauthorized, business logic)
-- Prefix `N` bắt buộc cho Unicode tiếng Việt
-- `RETURN` bắt buộc ngay sau `RAISERROR` — thiếu `RETURN` SP tiếp tục chạy dù đã báo lỗi
-- Client nhận `{ "Message": "..." }` với nội dung thông báo
-- **Mọi lỗi thiếu quyền ở 5 pattern trên phải mở message bằng `[Unauthorized]`** (vd `N'[Unauthorized]Bạn không có quyền...'`) — tAPI dựa vào tiền tố này để trả HTTP status `401` thay vì mặc định, và tự cắt `[Unauthorized]` khỏi `Message` trước khi trả về client. Lỗi ràng buộc/nghiệp vụ (Pattern 4) **không** dùng prefix này — chi tiết cơ chế + cách client xử lý status 401 xem [tapi-reference.md](tapi-reference.md) §5.
+
+- **Severity always `16`** — every error kind (validation, unauthorized, business logic)
+- `N` prefix required for Vietnamese Unicode
+- `RETURN` required right after `RAISERROR` — without it the SP keeps running after the error
+- Client receives `{ "Message": "..." }`
+- **Every missing-right error in the 5 patterns must start with `[Unauthorized]`** (e.g. `N'[Unauthorized]Bạn không có quyền...'`) — tAPI uses this prefix to return HTTP `401` instead of the default, and strips `[Unauthorized]` from `Message` before returning. Constraint/business errors (Pattern 4) do **not** use it — mechanism + client 401 handling: [tapi-reference.md](tapi-reference.md) §5.