@fui-org/fui-cli 1.2.1 → 1.3.2

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

@@ -0,0 +1,225 @@
+# SQL CLR Functions — DLL-backed SQL Server functions
+
+> Owns: **SQL CLR functions: httpCall, sendMail, ImageResize, FileReader, RegexMatch...**
+
+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#.
+
+A needed function is not in the DB → **do not invent it**; tell the user the DB lacks it.
+
+---
+
+## 1. `SQLImageHelper` — images
+
+### `dbo.ImageResize`
+
+```sql
+dbo.ImageResize(@extension nvarchar(10), @OriginalImage varbinary(max), @maxWidth int, @maxHeight int, @preserverAspectRatio bit, @quality int)
+RETURNS varbinary(max)
+```
+
+Resizes to at most `@maxWidth` x `@maxHeight`.
+
+| 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)                                            |
+
+Returns resized `varbinary` — write to a `varbinary` column/file or return via tAPI File.
+
+### `dbo.ImageCrop`
+
+```sql
+dbo.ImageCrop(@OriginalImage varbinary(max), @StartAtX int, @StartAtY int, @Width int, @Height int)
+RETURNS varbinary(max)
+```
+
+Crops a `@Width` x `@Height` rectangle starting at `(@StartAtX, @StartAtY)`.
+
+---
+
+## 2. `SQLHttpHelper` — HTTP, public value store, mail
+
+### `dbo.publicValueUUID` / `publicValueGet` / `publicValueSet`
+
+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
+dbo.publicValueGet(@name nvarchar(max)) RETURNS nvarchar(max)   -- đọc value theo key
+dbo.publicValueSet(@name nvarchar(max), @Data nvarchar(max)) RETURNS int   -- ghi value theo key
+```
+
+### `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` has the **identical** signature (different internals): use `httpAPI` for internal tAPI calls, `httpCall` for general outbound HTTP.
+
+| 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 |
+
+**Example:**
+
+```sql
+SELECT dbo.httpCall('POST', 'https://tapi.example.vn/me/auth/ApplicationList', '', '')
+```
+
+#### `@Header` syntax — pipe-delimited `Key: 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"
+```
+
+Header names are **case-insensitive**; special handling:
+
+| 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                                                                        |
+
+**Bearer token + custom header:**
+
+```sql
+SELECT dbo.httpCall(
+  'POST',
+  'https://api.example.com/data',
+  'Authorization: Bearer abc123xyz|Content-Type: application/json; charset=utf-8',
+  '{"key":"value"}'
+)
+```
+
+**Joining headers:** exactly one `|` between pairs, no extra/missing `|`. A pair without `:` is **silently skipped** (no error).
+
+#### `httpCall`/`httpAPI` response
+
+- 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>" }
+  ```
+  → 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`
+
+```sql
+dbo.sendMail(@email_to nvarchar(max), @subject nvarchar(max), @content nvarchar(max), @from nvarchar(max), @fromDisplayName nvarchar(max), @smtp_server nvarchar(max), @smtp_port int, @userName nvarchar(max), @Password nvarchar(max), @EnableSSL bit)
+RETURNS nvarchar(max)
+```
+
+Sends email over SMTP from T-SQL.
+
+| 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)
+```
+
+> **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` — server files
+
+```sql
+dbo.FileCreateFolder(@Path nvarchar(max)) RETURNS nvarchar(max)
+dbo.FileReader(@Path nvarchar(max)) RETURNS varbinary(max)
+dbo.FileWriter(@Content varbinary(max), @Path nvarchar(max)) RETURNS nvarchar(max)
+dbo.FileExists(@Path nvarchar(max)) RETURNS bit
+dbo.FileDelete(@Path nvarchar(max)) RETURNS nvarchar(max)
+dbo.FileMove(@SourceFileName nvarchar(max), @DestFileName nvarchar(max)) RETURNS nvarchar(max)
+```
+
+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.
+
+| 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`             |
+
+> 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 & string compare
+
+```sql
+dbo.RegexReplace(@Input nvarchar(max), @Pattern nvarchar(1000), @Replacement nvarchar(4000)) RETURNS nvarchar(max)
+dbo.RegexIsMatch(@Input nvarchar(max), @Pattern nvarchar(1000)) RETURNS bit
+dbo.RegexMatch(@Input nvarchar(max), @Pattern nvarchar(1000)) RETURNS nvarchar(max)
+dbo.RegexMatchArray(@Input nvarchar(max), @Pattern nvarchar(1000)) RETURNS nvarchar(max)
+dbo.CompareWord(@String1 nvarchar(max), @String2 nvarchar(max)) RETURNS int
+```
+
+| 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` 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.
+
+#### `RegexMatchArray` shape — JSON object, not array
+
+Flat object (`{...}`, not `[...]`), keys `"M{m}G{g}"`:
+
+- `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.
+
+`RegexMatchArray('SDT: 0901 - 0902', '(\d{4})')` (one group) returns:
+
+```json
+{ "M1G1": "0901", "M1G2": "0901", "M2G1": "0902", "M2G2": "0902" }
+```
+
+(G1 = G2 here because the whole match equals the only group; with no groups each match yields only `G1`.)
+
+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. When to use them in SPs
+
+- 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-cli/references/system-design.md

@@ -0,0 +1,89 @@
+# System Design — Multi-Module App
+
+> 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).
+
+> 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).
+
+## Step 0 — Clarify scope
+
+Don't code yet. Confirm:
+
+- **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.
+
+Missing info → **ask**; never assume and build the wrong system.
+
+## Step 1 — Decompose into modules
+
+| 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.
+
+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.
+
+## Step 2 — Schema first
+
+Before any module.json:
+
+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).
+
+**Output:** tables + relations, user-confirmed.
+
+## Step 3 — SPs per entity
+
+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).
+
+- **Shared SPs** (catalogs, lookups) → neutral names.
+- Consistent authorization via `@sys_SystemRight`/`@sys_FunctionRight` ([tapi-permission-patterns.md](tapi-permission-patterns.md)).
+
+## Step 4 — Project structure (system level only)
+
+- **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
+
+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.
+
+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.
+
+## 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.
+
+Each module: full [fullstack-workflow.md](fullstack-workflow.md) — analyze → **Design Review Gate (§Step 1b)** → hard-coded UI → contract → SP → API wiring → static verification.
+
+## Checklist
+
+- [ ] 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

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

@@ -0,0 +1,185 @@
+# tAPI — File API (GET / UPLOAD)
+
+> 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 must SELECT **at least 3 required columns** (extra metadata columns allowed):
+
+| 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
+CREATE PROCEDURE spAPIFILE_moduleImportFile
+    @fileID varchar(50)
+AS BEGIN
+    SELECT
+        FileName    = FileName + FileType,
+        ContentType,
+        Modified    = ISNULL(UpdateTime, CreateTime),
+        fileContent = FileContentBIN
+    FROM tblA_ImportFile
+    WHERE fileID = LEFT(@fileID, 32)
+END
+```
+
+> `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.
+
+**URL params — `@fileID` and `@filename`:**
+
+| 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) |
+
+Extra `@sys_*` auth params may be declared for permission checks.
+
+```sql
+CREATE PROCEDURE spAPIFILE_Document
+    @fileID      varchar(50),   -- bắt buộc, inject từ URL
+    @filename    varchar(200),  -- tùy chọn — inject từ segment cuối URL; SP có thể dùng để
+                                --   ghi log, kiểm tra, hoặc override FileName trả về
+    @sys_UserID  varchar(9)     -- tùy chọn, inject từ token
+AS BEGIN
+    ...
+END
+```
+
+**4 supported routes:**
+
+```
+{domain}/{apiName}/{FunctionName}/{fileID}
+{domain}/{apiName}/{FunctionName}/{fileID}/{filename}
+{domain}/{apiName}/download/{FunctionName}/{fileID}/{filename}
+{domain}/{apiName}/viewer/{FunctionName}/{fileID}/{filename}
+```
+
+`{FunctionName}` is the name after the `spAPIFILE_` prefix: SP `spAPIFILE_Document` → URL uses `Document`. `/viewer/` = view inline in browser; `/download/` = download.
+
+> **`@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
+
+**Special params injected by tAPI on upload:**
+
+| 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 |
+
+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
+    @url1_SessionID      varchar(36),
+    @url2_Mode           varchar(20),
+    @sys_UserID          varchar(9),
+    @sys_FileContent     varbinary(max),
+    @sys_FileName        nvarchar(200),
+    @sys_FileContentType varchar(100),
+    @sys_FileSize        int
+AS BEGIN
+    INSERT INTO tblAttachFiles(FileName, Capacity, SessionID, CreateUser)
+    VALUES(@sys_FileName, @sys_FileSize, @url1_SessionID, @sys_UserID)
+END
+```
+
+Route: `POST {domain}/{apiName}/upload/{spName}/{url1}/{url2}...`
+
+## Standard file table — `tblFileData`
+
+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](
+    [FileID]          [char](36)      NOT NULL,   -- UUID, DEFAULT newid()
+    [FileName]        [nvarchar](200) NOT NULL,
+    [PhysicalName]    [char](36)      NOT NULL,   -- UUID, DEFAULT newid()
+    [PhysicalSegment] [char](10)      NOT NULL,   -- subfolder theo ngày, DEFAULT getPhysicalSegment(getdate())
+    [CreateTime]      [datetime]      NOT NULL,   -- DEFAULT getdate()
+    [WriteToDisk]     [datetime]      NULL,        -- null = chưa ghi ra disk
+    [BinaryContent]   [image]         NULL,        -- binary file content — alias là fileContent trong SP GET
+    [ContentType]     [varchar](100)  NULL,        -- MIME type, DEFAULT ''
+    [Size]            [int]           NULL,
+    CONSTRAINT [PK_tblFileData] PRIMARY KEY CLUSTERED ([FileID] ASC)
+) ON [PRIMARY] TEXTIMAGE_ON [PRIMARY]
+GO
+
+ALTER TABLE [dbo].[tblFileData] ADD CONSTRAINT [DF_tblFileData_FileID]          DEFAULT (newid())                              FOR [FileID]
+ALTER TABLE [dbo].[tblFileData] ADD CONSTRAINT [DF_tblFileData_PhysicalName]    DEFAULT (newid())                              FOR [PhysicalName]
+ALTER TABLE [dbo].[tblFileData] ADD CONSTRAINT [DF_tblFileData_PhysicalSegment] DEFAULT ([dbo].[getPhysicalSegment](getdate())) FOR [PhysicalSegment]
+ALTER TABLE [dbo].[tblFileData] ADD CONSTRAINT [DF_tblFileData_CreateTime]      DEFAULT (getdate())                            FOR [CreateTime]
+ALTER TABLE [dbo].[tblFileData] ADD CONSTRAINT [DF_tblFileData_ContentType]     DEFAULT ('')                                   FOR [ContentType]
+```
+
+> **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.
+
+**Fields:**
+
+| 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                                                                 |
+
+**GET SP on the table:**
+
+```sql
+CREATE PROCEDURE spAPIFILE_Document
+    @FileID          char(36),
+    @sys_UserID      varchar(9),
+    @sys_SystemRight int
+AS BEGIN
+    IF @sys_SystemRight < 1
+    BEGIN RAISERROR(N'[Unauthorized]Bạn không có quyền.', 16, 1) RETURN END
+
+    -- BinaryContent phải alias là fileContent — tAPI đọc đúng tên này
+    SELECT FileName, ContentType, fileContent = BinaryContent
+    FROM tblFileData WHERE FileID = @FileID
+END
+```
+
+**UPLOAD SP into the table:**
+
+```sql
+CREATE PROCEDURE spAPIFILE_UPLOAD_Document
+    @url1_RefID          varchar(50),
+    @sys_UserID          varchar(9),
+    @sys_SystemRight     int,
+    @sys_FileContent     varbinary(max),
+    @sys_FileName        nvarchar(200),
+    @sys_FileContentType varchar(100),
+    @sys_FileSize        int
+AS BEGIN
+    IF @sys_SystemRight < 2
+    BEGIN RAISERROR(N'[Unauthorized]Bạn không có quyền.', 16, 1) RETURN END
+
+    DECLARE @NewFileID char(36) = newid()  -- sinh UUID trước, dùng để SELECT lại sau
+
+    INSERT INTO tblFileData(FileID, FileName, BinaryContent, ContentType, Size)
+    VALUES(@NewFileID, @sys_FileName, @sys_FileContent, @sys_FileContentType, @sys_FileSize)
+
+    -- Trả về record vừa insert để client cập nhật danh sách
+    SELECT FileID, FileName, Size, ContentType, CreateTime
+    FROM tblFileData WHERE FileID = @NewFileID
+END
+```
+
+> **`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-cli/references/tapi-permission-patterns.md

@@ -0,0 +1,156 @@
+# tAPI — Permission Check Patterns
+
+> 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).
+
+---
+
+## Permission-related system params
+
+Injected by tAPI — the client never sends them:
+
+| 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]` |
+
+**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
+    @BusinessParam1 int,
+    @BusinessParam2 nvarchar(100),
+    @sys_UserID varchar(9),
+    @sys_SystemRight int
+AS
+```
+
+## `@sys_SystemRight` levels
+
+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:
+
+| 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: rights on a specific module
+
+```sql
+dbo.getSystemRight(@ModuleID, @sys_UserID)
+```
+
+Returns the user's `SysRight` on a given module — use to check rights on a module **other than** the current one.
+
+---
+
+## Pattern 1 — Basic access block (READ)
+
+Every read SP that needs login. Requires `SysRight >= 2`.
+
+```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
+```
+
+## Pattern 2 — Block only users with no right (minimal)
+
+Allows `SysRight = 1`; blocks only `SysRight = 0`.
+
+```sql
+If @sys_SystemRight = 0
+Begin
+    Raiserror(N'[Unauthorized]Bạn không có quyền trên chức năng này.', 16, 1)
+    Return
+End
+```
+
+## Pattern 3 — 2-tier: global + module admin (WRITE)
+
+Writes affecting module config or other users' data. User must meet **either**:
+
+- `@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
+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
+
+-- Tầng 2: phải là admin hệ thống hoặc admin của module đó
+If @sys_SystemRight < 3 and dbo.getSystemRight(@ModuleID, @sys_UserID) < 9
+Begin
+    Raiserror(N'[Unauthorized]Bạn không có quyền trên Module này.', 16, 1)
+    Return
+End
+```
+
+## Pattern 4 — Business-rule check before executing
+
+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
+If exists(Select * from tblChild WHERE ParentID = @ParentID)
+Begin
+    Raiserror(N'Phải xóa dữ liệu liên quan trước khi thực hiện thao tác này.', 16, 1)
+    Return
+End
+
+DELETE tblParent WHERE ParentID = @ParentID
+```
+
+## Pattern 5 — `@sys_FunctionRight` check
+
+Authorization by specific function (not just numeric level).
+
+```sql
+If CHARINDEX('[ADMIN]', @sys_FunctionRight) = 0
+Begin
+    Raiserror(N'[Unauthorized]Bạn không có quyền thực hiện chức năng này.', 16, 1)
+    Return
+End
+```
+
+---
+
+## Check order
+
+```
+1. Kiểm tra quyền hệ thống (@sys_SystemRight)    ← luôn đầu tiên
+2. Kiểm tra quyền module (getSystemRight)         ← nếu cần 2 tầng
+3. Kiểm tra quyền chức năng (@sys_FunctionRight)  ← nếu dùng FunctionRight
+4. Kiểm tra ràng buộc nghiệp vụ                   ← sau cùng, trước khi ghi
+```
+
+## Error message conventions
+
+| 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:**
+
+```sql
+RAISERROR(N'Thông báo lỗi tiếng Việt.', 16, 1)
+RETURN
+```
+
+- **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.