@fui-org/fui-cli 0.1.1 → 0.3.0

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

@@ -0,0 +1,191 @@
+# 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).
+
+---
+
+## 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 ý):
+
+| 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) |
+
+```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` 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.
+
+**Tham số URL — `@fileID` và `@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) |
+
+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.
+
+```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 route pattern hỗ trợ:**
+
+```
+{domain}/{apiName}/{FunctionName}/{fileID}
+{domain}/{apiName}/{FunctionName}/{fileID}/{filename}
+{domain}/{apiName}/download/{FunctionName}/{fileID}/{filename}
+{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ề.
+
+> **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.
+
+## Upload file
+
+**Params đặc biệt do tAPI tự inject khi 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 |
+
+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`.
+
+```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}...`
+
+## Bảng lưu trữ file chuẩn — `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.
+
+```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]
+```
+
+> **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.
+
+**Giải thích từng field:**
+
+| 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 |
+
+**SP GET file — map tới bảng:**
+
+```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
+```
+
+**SP UPLOAD — lưu vào bảng:**
+
+```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
+```
+
+> **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.

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

@@ -0,0 +1,158 @@
+# tAPI — Kiểm tra quyền người dùng (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).
+
+---
+
+## Tham số hệ thống liên quan đến quyền
+
+tAPI tự inject các tham số sau — không cần client truyền lên:
+
+| 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]` |
+
+**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ó):
+
+```sql
+CREATE PROCEDURE spAPI_EntityAction
+    @BusinessParam1 int,
+    @BusinessParam2 nvarchar(100),
+    @sys_UserID varchar(9),
+    @sys_SystemRight int
+AS
+```
+
+## Các mức `@sys_SystemRight`
+
+Ý 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:
+
+| 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) |
+
+## Helper function kiểm tra quyền theo module cụ thể
+
+```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.
+
+---
+
+## Pattern 1 — Chặn truy cập cơ bản (READ operations)
+
+Dùng cho mọi SP đọc dữ liệu cần đăng nhập. Yêu cầu ít nhất `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 — Chặn user hoàn toàn không có quyền (minimal check)
+
+Dùng khi muốn cho phép cả `SysRight = 1` thao tác, chỉ chặn `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 — Kiểm tra 2 tầng: global + module admin (WRITE operations)
+
+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 đó.
+
+```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 — Kiểm tra logic nghiệp vụ trước khi thực thi
+
+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).
+
+```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 — Kiểm tra `@sys_FunctionRight`
+
+Dùng khi phân quyền theo chức năng cụ thể (không chỉ theo mức số).
+
+```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
+```
+
+---
+
+## Quy tắc đặt thứ tự kiểm tra
+
+```
+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
+```
+
+## Quy ước thông báo lỗi
+
+| 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 |
+
+**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.