@fui-org/fui-cli 2.1.3 → 2.2.0

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

@@ -1,156 +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.
+# 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.