@fui-org/fui-cli 0.2.0 → 0.4.0

package/skills/fui-skill/references/pdfmake.md

@@ -0,0 +1,60 @@
+# PDF Generation với pdfmake
+
+> File này sở hữu: **`f-pdfmake`: docDefinition, font tiếng Việt, in/tải PDF**.
+
+Kỹ thuật tạo PDF phức tạp bằng thư viện `pdfmake` trong FUI (dùng qua component `f-pdfmake`).
+
+## Dynamic Tables
+
+Map mảng dữ liệu thành rows trong bảng:
+
+```javascript
+body: [
+    [{ text: 'STT', bold: true }, { text: 'Name', bold: true }],
+    ...data.items.map(item => ([
+        item.index,
+        item.name
+    ]))
+]
+```
+
+## SVG Checkboxes
+
+Ký tự Unicode (☑/☐) có thể không render được trong một số font PDF. Dùng SVG path thay thế:
+
+```javascript
+const checkedSvg = '<svg ...>...</svg>';
+const uncheckedSvg = '<svg ...>...</svg>';
+
+{
+    svg: item.isChecked ? checkedSvg : uncheckedSvg,
+    width: 14
+}
+```
+
+## Complex Layouts
+
+Dùng `columns` cho layout mà table thông thường không xử lý được (ví dụ checkbox cạnh text):
+
+```javascript
+{
+    columns: [
+        { svg: checkedSvg, width: 14 },
+        { text: ' Label text', width: '*' }
+    ]
+}
+```
+
+## Signature Section Table
+
+Dùng nested table để tạo khối chữ ký căn chỉnh đúng:
+
+```javascript
+table: {
+    widths: ['16%', '16%', '16%', '16%', '16%', '16%'],
+    body: [
+        [{ text: 'Title', colSpan: 3 }, {}, {}, { text: 'Title', colSpan: 3 }, {}, {}],
+        ['Sign 1', 'Sign 2', 'Sign 3', 'Sign 4', 'Sign 5', 'Sign 6']
+    ]
+}
+```

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

@@ -0,0 +1,169 @@
+# Hệ thống phân quyền FUI — SystemRight & FunctionRight
+
+> File này sở hữu: **khái niệm `SystemRight` vs `FunctionRight`, `rightTest`, gác `v-if`/menu, 8 tool quản lý định nghĩa quyền**. Kiểm quyền trong thân SP xem [tapi-permission-patterns.md](tapi-permission-patterns.md).
+
+FUI có **2 loại quyền độc lập, không thay thế nhau**. Nhầm lẫn hai loại này là lỗi thường gặp khi thiết kế `v-if`, menu `right`, hoặc kiểm tra quyền trong SP.
+
+> Kiểm tra quyền **trong thân SP** (pattern SQL cụ thể): xem [tapi-permission-patterns.md](tapi-permission-patterns.md). File này tập trung vào khái niệm + 8 tool quản lý định nghĩa quyền.
+
+---
+
+## Khi user hỏi về "phân quyền"/"quyền" trong hệ thống — quy trình bắt buộc
+
+Không trả lời chỉ dựa vào suy đoán hoặc code/schema đã đọc từ trước — luôn lấy dữ liệu **thật** tại thời điểm hỏi:
+
+1. Gọi `right_system_list` + `right_function_list` để lấy đúng định nghĩa `SystemRight`/`FunctionRight` **hiện tại** của project (không đoán theo tên biến hay comment cũ).
+2. Gọi `db_schema_read` (search theo từ khóa liên quan như `right`/`quyen`/`role`/`permission`/`phanquyen`) để kiểm tra project có **bảng phân quyền riêng** trong DB của chính nó hay không — khác với `acc.tblSysRight`/`acc.tblFunction` (đó là DANH MỤC định nghĩa quyền dùng chung mọi project, không phải bảng gán quyền chi tiết). Nhiều project tự dựng thêm bảng gán quyền theo module/màn hình/thao tác (CRUD) riêng ngoài 2 loại quyền chuẩn — phải kiểm tra trước khi kết luận hệ thống "chỉ có SystemRight/FunctionRight".
+3. Tổng hợp cả 2 nguồn (định nghĩa quyền chuẩn từ `acc` + bảng phân quyền riêng của project nếu có) trước khi trả lời hoặc thiết kế logic kiểm tra quyền.
+
+---
+
+## 🔴 Bắt buộc: mã quyền phải TỒN TẠI trước khi đem gác
+
+Viết `"v-if": "vueData.user.FunctionRight.includes('42')"` hay `"right": {"FunctionRight": ["42"]}` **không tạo ra** mã 42. Nếu 42 chưa có trong `tblFunction` của project thì không user nào được cấp nó → `rightTest()` (dùng `_.intersection`) luôn trả `false` → **nút/menu biến mất, không lỗi JS, không `[Vue warn]`**. Không có gì đỏ lên; chỉ có người dùng báo "không thấy nút".
+
+Ba cạm bẫy làm lỗi này sống sót qua mọi tầng kiểm chứng:
+
+1. **Preview nói dối.** `module_simulate` và `renderUI` **cấp cho user preview đúng những mã quét được từ chính module** (để menu không biến mất oan) — nghĩa là mã bịa ra vẫn hiện đúng trong ảnh render. Nay hai tool đó đối chiếu với cache và in dòng `🚨 FunctionRight CHƯA ĐƯỢC ĐỊNH NGHĨA…`; **đọc dòng đó, đừng chỉ nhìn ảnh**.
+2. **SP không cứu được.** `@sys_FunctionRight` chỉ chứa mã user **thật sự được cấp**; mã không tồn tại đơn giản là không bao giờ khớp.
+3. **Không suy ra mã từ tên/comment cũ.** Nguồn sự thật duy nhất là `right_function_list` / `right_system_list`.
+
+**Quy trình:**
+
+| Khi | Làm gì |
+|---|---|
+| Bắt đầu làm việc với quyền trên một project | `right_function_list` + `right_system_list` — ngoài việc in danh sách, hai tool này ghi cache `{projectId}/_db/rights.json` **dưới khoá `apiName`**, thứ duy nhất cho phép các tool no-live-call đối chiếu. Project nhiều alias thì **chạy cho từng alias**: mục của alias này không bao giờ được đem ra kiểm cho alias kia |
+| Thiết kế module/menu cần một quyền chưa có | `right_function_new({ functionCode, functionName })` (hoặc `right_system_new`) **trước**, rồi mới gác — không viết mã "để đó rồi tạo sau" |
+| Sau khi sửa module.json có gác quyền | `module_validate` — mã không có trong cache ra **warning** kèm sẵn lệnh `right_function_new` để copy |
+
+`module_validate` chỉ đọc file local (no-live-call): **chưa chạy `right_*_list` lần nào thì chưa có cache, và nó nói thẳng là không kiểm được** thay vì im lặng báo hợp lệ. `SystemRight 9` (Project Admin) là hằng của nền tảng — luôn hợp lệ, không bao giờ bị cảnh báo.
+
+---
+
+## 2 loại quyền — phân biệt rõ
+
+| | `SystemRight` | `FunctionRight` |
+|---|---|---|
+| **Bản chất** | **Cấp bậc** của user khi vào một project | **Quyền theo từng chức năng** cụ thể |
+| **Kiểu dữ liệu** | 1 số nguyên `0–9` | Mảng mã chức năng (string[]) |
+| **Trả lời câu hỏi** | "Bạn là ai trong hệ thống này?" (Users, Managers, Administrators, Project Admin...) | "Bạn được phép làm việc gì?" (xem báo cáo, đặt hàng, thanh toán...) |
+| **Định nghĩa ở đâu** | `tblSysRight` — mỗi mức có `Note` (tên cấp bậc) do project tự đặt | `tblFunction` — mỗi chức năng có `FunctionCode` (số) + `FunctionName` |
+| **Gán cho user** | 1 mức duy nhất trên project đó | 0..N mã, độc lập với cấp bậc |
+| **Runtime (client)** | `vueData.user.SystemRight` (số) | `vueData.user.FunctionRight` (mảng chuỗi) |
+| **SP-side** | `@sys_SystemRight` | `@sys_FunctionRight` (chuỗi dạng `[10][20]`) |
+
+**Ví dụ dễ hình dung:** `SystemRight` giống chức vụ ("Nhân viên" = 1, "Quản lý" = 5, "Project Admin" = 9 — cố định). `FunctionRight` giống checklist quyền hạn cụ thể được cấp riêng cho từng người, bất kể chức vụ — một Nhân viên vẫn có thể được cấp quyền "Thanh toán" nếu công việc yêu cầu, một Quản lý có thể KHÔNG có quyền "Xóa dữ liệu" nếu không cần.
+
+**Khi nào dùng loại nào:**
+- Ẩn/hiện cả một khu vực UI theo "đẳng cấp" tổng quát (khu vực quản trị, mục chỉ admin thấy) → `SystemRight`
+- Bật/tắt một nút hoặc luồng nghiệp vụ cụ thể (nút "Duyệt", nút "Xuất báo cáo") mà không phụ thuộc cấp bậc → `FunctionRight`
+- Nhiều màn hình dùng **cả hai cùng lúc** (AND) — xem ví dụ `right` trong `project-config.md`.
+
+---
+
+## Lưu trữ — database phân quyền trung tâm (alias `acc`)
+
+Mọi project FUI dùng chung 1 database phân quyền trung tâm, alias tAPI là `acc`:
+
+- **`tblModules`** — mỗi project là 1 dòng, nhận diện qua `APIName` (= apiName/alias của project)
+- **`tblSysRight`** — định nghĩa các mức `SystemRight` (0–9) của **một project cụ thể**, kèm `Note` (tên cấp bậc); `9` luôn cố định là **Project Admin**
+- **`tblFunction`** — định nghĩa các `FunctionRight` (`FunctionCode` số + `FunctionName`) của **một project cụ thể** — đây là danh mục "chức năng có thể gán quyền", không phải bảng gán quyền cho từng user
+
+> Việc **gán** một mức `SystemRight`/`FunctionRight` cụ thể cho từng user là thao tác quản trị riêng (ngoài phạm vi 8 tool bên dưới — các tool này chỉ quản lý **định nghĩa** danh mục quyền của project, không gán quyền cho user).
+
+### ⚠️ Đừng nhầm với `UserRight` — quyền SỬA PROJECT trong IDE FUI
+
+Có một hệ thống quyền **thứ hai** tên nghe rất giống: `UserRight` trong `tblA_UserProject` — quyền **sửa project trong IDE FUI**.
+
+| | `SystemRight` / `FunctionRight` (file này) | `UserRight` |
+|---|---|---|
+| Phạm vi | **Toàn bộ một app** — một mức cho một user trên app đó | **Từng project một** |
+| Lưu ở | `acc.tblSysRight` / `acc.tblFunction` | `tblA_UserProject` (DB nền tảng FUI, không phải `acc`) |
+| Runtime đọc bằng | `vueData.user.SystemRight` / `.FunctionRight` | (không có — chỉ IDE FUI dùng) |
+| Tool | 8 tool `right_*` dưới đây | 5 tool `project_user_*` → [project-provisioning.md](project-provisioning.md) §Bước 6 |
+
+**Điểm dễ hiểu sai:** IDE FUI *bản thân nó cũng là một app FUI* (project `fp`). Nên `SystemRight` **trên `fp`** chính là quyền của lập trình viên trong IDE — không phải chỉ là "quyền người dùng cuối". Hai trục **AND với nhau**, đọc từ thân SP thật:
+
+| Thao tác trong IDE | Điều kiện |
+|---|---|
+| Tạo project (`project_new`) | `SystemRight >= 3` trên `fp` |
+| Sửa metadata project (`project_update`) | `SystemRight >= 2` **và** `UserRight > 2` |
+| Publish `project.json` (`project_publish_config`) | `SystemRight >= 2` **và** `UserRight > 2` |
+| Tạo/sửa module, publish module (`module_*`) | `SystemRight >= 2` **và** `UserRight > 1` |
+
+Có `UserRight = 3` mà `SystemRight = 1` thì vẫn không sửa được gì, và ngược lại. Cấp nhầm trục là cấp quyền ở sai nơi rồi kết luận "cấp rồi mà không có tác dụng".
+
+---
+
+## Runtime (client-side)
+
+Sau khi khai báo `userInfo` (xem [platform-architecture.md](platform-architecture.md)), FUI tự fetch và gán:
+
+```js
+vueData.user.SystemRight     // số, vd: 5
+vueData.user.FunctionRight   // mảng chuỗi, vd: ["10", "20"]
+```
+
+**Dùng trong `v-if` (ẩn/hiện theo quyền):**
+
+```json
+{ "col": { "v-if": "vueData.user.SystemRight >= 5" } }
+{ "col": { "v-if": "vueData.user.FunctionRight.includes('10')" } }
+```
+
+**Dùng trong menu `right`** (xem chi tiết [project-config.md](project-config.md)):
+
+```json
+"right": { "SystemRight": [1, 2, 5, 9], "FunctionRight": ["10", "20"] }
+```
+- `SystemRight`: `user.SystemRight` phải **nằm trong** mảng mới thấy
+- `FunctionRight`: `user.FunctionRight` phải **giao ít nhất 1 mã** với mảng mới thấy
+- Có cả hai key → **AND** (phải thỏa cả hai)
+
+**Hàm `rightTest`** kiểm tra giao quyền (dùng trong menu/logic JS):
+
+```js
+rightTest({ SystemRight: [5, 9], FunctionRight: ['10'] })
+```
+
+---
+
+## SP-side (Stored Procedure)
+
+tAPI tự inject `@sys_SystemRight` và `@sys_FunctionRight` vào mọi SP — không cần client truyền lên. **5 pattern kiểm tra quyền trong thân SP** (chặn truy cập, kiểm tra 2 tầng module admin, kiểm tra `FunctionRight`...): xem [tapi-permission-patterns.md](tapi-permission-patterns.md).
+
+---
+
+## 8 MCP tools — quản lý định nghĩa quyền của project
+
+Các tool này thao tác trực tiếp lên database `acc` (4 API `SM_SystemRight_Select/Update`, `SM_FunctionRight_Select/Update`), dùng **userToken** của dev (đã được cấp quyền vào `acc`) lấy từ `_db/_connections.json` của project hiện tại — không cần cấu hình kết nối riêng.
+
+Project nối nhiều database thì token được lấy từ **kết nối khớp `apiName` đang thao tác** (không khớp thì kết nối mặc định) — thiếu `userToken` ở đúng kết nối đó là tool quyền không chạy được, dù kết nối khác đã có token. Xem `db_config_read` để biết kết nối nào đã có token.
+
+Tạo / sửa / xóa là **ba tool riêng**: xóa là thao tác 🔴 không hoàn tác, không được nằm chung schema với thao tác thường dưới dạng một boolean dễ truyền nhầm.
+
+| Tool | Vai trò | Params chính | Ghi chú an toàn |
+|---|---|---|---|
+| `right_system_list` | Liệt kê định nghĩa `SystemRight` (0–9 + Note) của project | `apiName?`, `projectId?` | Read-only, an toàn |
+| `right_system_new` | Định nghĩa một mức `SystemRight` **chưa có** | `sysRight` (0–9), `note?` (≤50 ký tự, bỏ qua nếu `sysRight=9`), `apiName?`, `projectId?` | Khoá do người dùng chọn (không có ID tự sinh) → tool hỏi `SM_SystemRight_Select` trước; mức đã có = **lỗi cứng**, trỏ sang `right_system_update` |
+| `right_system_update` | **Chỉ sửa** mức `SystemRight` đã có | `sysRight` (**bắt buộc**, lấy từ `right_system_list`), `note?`, `apiName?`, `projectId?` | ⚠️ Ghi đè note hiện tại |
+| `right_system_delete` | Xóa định nghĩa một mức `SystemRight` | `sysRight` (**bắt buộc**), `apiName?`, `projectId?` | 🔴 **Server tự chặn** nếu còn user đang giữ mức quyền đó |
+| `right_function_list` | Liệt kê định nghĩa `FunctionRight` (FunctionID/Code/Name) của project | `apiName?`, `projectId?` | Read-only, an toàn — nguồn duy nhất lấy `functionId` thật |
+| `right_function_new` | Tạo `FunctionRight` mới | `functionCode` (số, unique/project), `functionName?` (≤100 ký tự), `apiName?`, `projectId?` | Gửi `FunctionID: 0` (lệnh INSERT của SP); server từ chối nếu `functionCode` trùng |
+| `right_function_update` | **Chỉ sửa** `FunctionRight` đã có | `functionId` (**bắt buộc**, lấy từ `right_function_list`), `functionCode`, `functionName?`, `apiName?`, `projectId?` | ⚠️ Không còn `?? 0` — quên `functionId` là lỗi, không âm thầm biến thành tạo mới |
+| `right_function_delete` | Xóa 1 `FunctionRight` | `functionId` (**bắt buộc**), `apiName?`, `projectId?` | 🔴 Xóa function **KÈM toàn bộ phân quyền user** đã gán mã đó — không khôi phục được |
+
+**Quy tắc dùng:**
+1. Trước khi gọi `right_system_delete`/`right_function_delete` — luôn tóm tắt rõ hậu quả và chờ user xác nhận (destructive, không hoàn tác).
+2. Tạo mới thì dùng `right_*_new`; sửa thì **bắt buộc** có định danh (`functionId` / `sysRight`) lấy từ `right_*_list` — không tool nào upsert ngầm.
+3. Cả 8 tool đều lấy `apiName`/`projectId` mặc định từ project đang active trong session nếu không truyền — truyền `apiName` khi cần thao tác lên project **khác**, hoặc khi project hiện tại có **nhiều kết nối** và quyền cần sửa thuộc alias không phải mặc định.
+4. Server tự kiểm tra quyền người gọi: Select cần `SystemRight >= 2` trên hệ thống `acc`; Update cần cao hơn hoặc là admin (`9`) của project đích.
+
+**API nền tảng** (tham khảo, thường không cần gọi trực tiếp — dùng 8 tool ở trên):
+
+```
+POST {apiDomain}/acc/SM_SystemRight_Select     { ModuleID | APIName }
+POST {apiDomain}/acc/SM_SystemRight_Update     { ModuleID | APIName, SysRight, Note, Delete }
+POST {apiDomain}/acc/SM_FunctionRight_Select   { ModuleID | APIName }
+POST {apiDomain}/acc/SM_FunctionRight_Update   { FunctionID, ModuleID | APIName, FunctionCode, FunctionName, Delete }
+```

package/skills/fui-skill/references/platform-architecture.md

@@ -0,0 +1,294 @@
+# FUI Platform Architecture — Cấu tạo & cơ chế phân cấp
+
+> File này sở hữu: **cấu tạo FUI và phân cấp Project→Module: import/component/set trộn thế nào, `vueData`/`v_Set`, vòng đời runtime**.
+
+Hiểu FUI vận hành thế nào **dưới nắp** để thiết kế đúng ngay từ đầu. Nội dung ở đây rút trực tiếp từ runtime `scripts/fastproject.js` (file chính của nền tảng), `defaultfunction.js` (hàm dùng chung), `component.js`/`componentTable.js` (V3: `componentTable-3.0.js`) — đăng ký component lõi có sẵn (`f-table`, `t-*`, dialog, editor...). `f-echart` (`fechart.js`) và `f-sheet` (`fsheet.js`) là hai component **tách file riêng, nạp qua import khai trong module/project**, không tự động load như phần lõi. Đây là **nguồn sự thật** — không suy từ training data.
+
+> Đọc file này TRƯỚC khi thiết kế hệ thống/module. Sau đó: cấu hình từng phần → [module-json-anatomy.md](module-json-anatomy.md); project.json & set → [project-config.md](project-config.md); pattern UI thực tế → [ui-patterns.md](ui-patterns.md) (ưu tiên cao — đã tinh chỉnh qua thực chiến).
+
+---
+
+## 1. FUI là gì
+
+FUI (Framework UI) là nền tảng low-code **metadata-driven**: mỗi trang (module) mô tả UI + logic bằng JSON (`module.json`), runtime `fastproject.js` đọc JSON đó và tự dựng DOM Vue 2 + Vuetify. Không viết Vue component thủ công cho từng trang — chỉ khai báo.
+
+Một trang FUI khi chạy nạp theo thứ tự (đã bundle sẵn, **không import lại**):
+1. Thư viện nền: jQuery, Lodash (`_`), Moment, Numeral, Vuetify, vue-toast, jquery-confirm
+2. `defaultfunction.js` — hàm tiện ích (`openWindow`, `CALL`, `confirm`, `showMessage`, `ajaxCALL`, `jsonToExcel`...)
+3. `component.js` + `componentTable.js` — đăng ký toàn bộ component `f-*` / `t-*`
+4. `fastproject.js` — engine: đọc `module.json`, merge config, dựng DOM, chạy action, gắn watch
+5. Data của trang: `$projectData` (project.json), `$moduleUI` (module.json), `$projectGroupSetting`
+
+---
+
+## 2. Phân cấp Project → Module (CƠ CHẾ TRỘN — quan trọng nhất)
+
+FUI có hai cấp: **Project** (dùng chung) và **Module** (một trang). Ba thành phần của Project **tự động nhúng/trộn xuống** mọi Module; khi trùng, **Module chi phối (override)**.
+
+### 2.1 `set` — project.json trộn vào `set` của module
+
+Runtime tính config hiệu lực `v_Set` bằng (fastproject.js):
+
+```js
+$.extend(vueData.v_Set, $projectGroupSetting, $projectData, $moduleUI.set);
+// rồi nếu có: $.extend(v_Set, v_Set.domainSetting[domain hiện tại])
+```
+
+Thứ tự ưu tiên (sau ghi đè trước):
+
+```
+$projectGroupSetting   (cấu hình nhóm project — thấp nhất)
+   ⤵ bị override bởi
+$projectData           = project.json (khối "data")
+   ⤵ bị override bởi
+$moduleUI.set          = "set" trong module.json   ← ƯU TIÊN CAO NHẤT
+   ⤵ cuối cùng override bởi
+v_Set.domainSetting[domain]   (nếu đang chạy trên domain đó)
+```
+
+→ Module **kế thừa toàn bộ** config project (menu, apiDomain, style, login...) và chỉ cần khai báo `set` cho những gì khác biệt. Đây là lý do `module.json` của một trang bình thường **không có `set`** (kế thừa hết từ project).
+
+Chi tiết các thuộc tính của `set`/`v_Set` và project.json: [project-config.md](project-config.md).
+
+### 2.2 `imports` — project imports **nối** với module imports
+
+Import (JS/CSS) khai báo ở cấp project **và** cấp module đều được nạp — không thay thế nhau. Runtime (`addImport`): file `.css` → thêm `<link>`; file khác → nạp như `<script>`.
+
+Thứ tự nạp **không phải** "framework rồi project rồi module": server (`spA_FUI_ModuleDataSelect`) UNION cả **ba** phạm vi — framework (theo V2/V3), project (`ModuleID IS NULL`), module — rồi sort **chung một lần** theo `FileSort, FileName`. Nên một import module-scope có `FileSort` nhỏ vẫn nạp **trước** import project-scope. Phụ thuộc thứ tự (vd `echarts.min.js` phải trước `fechart.js`) → phải thể hiện bằng `FileSort`, đừng trông vào phạm vi.
+
+Framework tự xưng `FileSort` thấp (~1-10). `file_import_new`/`file_import_update` tự bảo vệ ngưỡng này ở code level (`resolveImportSort`, `src/tools/module.ts`): `fileSort` bỏ trống → mặc định an toàn theo scope (project ≥ 20, module ≥ 50); truyền một giá trị thấp hơn ngưỡng đó → tự nâng lên, kèm ghi chú `ℹ️` trong kết quả tool. Không có cách nào truyền một `FileSort` đủ thấp để chen trước framework qua hai tool này — nếu thật sự cần thứ tự sát framework, phải deploy trực tiếp qua route khác ngoài MCP.
+
+- Import project-scope: dùng chung cho mọi module (thư viện chung).
+- Import module-scope: chỉ trang đó (vd `echarts.min.js` + `fechart.js` cho trang có `f-echart`).
+- Module thật thường có `imports/_imports.json` = `[]` khi chỉ dùng thư viện bundle sẵn.
+
+> Thêm/bỏ component cần import (f-echart, f-file-upload, f-editor...) → luôn `file_import_list` rồi `file_import_new`/`file_import_delete`. Bảng import: [component-quickref.md](component-quickref.md).
+
+#### Hai loại import: CDN/URL vs Nội dung upload (`ContentType`)
+
+Một import record trong FUI tồn tại dưới **một trong hai dạng** — phân biệt ngay ở `ContentType`:
+
+| Dạng | `ContentType` | Nguồn | Tool chỉnh sửa nội dung |
+|---|---|---|---|
+| **Tham chiếu CDN / URL** | rỗng hoặc không phải JS/CSS | URL ngoài (jsdelivr, cdnjs, custom server...) — không có file local | `file_import_update` (chỉ sửa metadata: url, sort, tên) |
+| **Nội dung đã upload** | `text/javascript` / `text/css` | File lưu trên server FUI, có `fileID` và `filePath` local | `file_import_upload_content` (ghi đè nội dung) |
+
+**Hệ quả thực tế — khi người dùng đính kèm file JS/CSS trong chat:**
+
+```
+User đính kèm file.js → nhờ AI tạo import
+
+❌ SAI: file_import_new({ url: "<url nào đó>" })
+   → tạo CDN reference, file.js không được lưu lên server
+
+✅ ĐÚNG:
+  1. file_import_new({ ... })           → tạo metadata (tên, sort, scope)
+  2. file_import_upload_content(fileId, nộidung)  → upload nội dung file lên server FUI
+```
+
+- `file_import_upload_content` đồng bộ nội dung tới **mọi thư mục `imports/` local** đang khai `fileID` đó — không cần gọi lại tool cho từng scope.
+- Import dạng CDN (URL ngoài): dùng `file_import_update` nếu muốn đổi URL, sort, hay tên — **không thể** upload content vào record này.
+- Dùng `file_import_get` để biết một import đang ở dạng nào (xem trường `ContentType` và `FilePath` trong kết quả).
+
+> Kiểm tra trước khi thao tác: `file_import_list` liệt kê mọi import kèm `ContentType` — nhìn vào đó là biết ngay nên gọi tool nào tiếp theo.
+
+### 2.3 `components` — component **dùng chung toàn project**
+
+- `component.js` đăng ký sẵn mọi component `f-*`/`t-*` **global**.
+- Custom `uc-*.vue` **project-scope** (`{projectId}/components/`) → FUI tự load **global ở MỌI module**, gọi thẳng bằng tên (không khai báo `components:{}`).
+- `uc-*.vue` **module-scope** (`{moduleId}/components/`) → chỉ dùng trong module đó.
+- Trùng tên → bản module-scope chi phối trong phạm vi module đó.
+
+> Component design & scope: [component-design.md](component-design.md).
+
+### 2.4 Bảng tóm tắt phân cấp
+
+| Thành phần | Project cung cấp | Trộn vào module thế nào | Khi trùng |
+|---|---|---|---|
+| **set / config** | `project.json` (khối `data`) | Trộn vào `v_Set`, rồi `module.set` | **Module.set thắng** |
+| **imports** | project `_imports.json` | **Nối thêm** vào import module | Cả hai đều nạp |
+| **components** | `uc-*.vue` project-scope + `f-*`/`t-*` global | Auto-load global mọi module | Module-scope thắng |
+
+---
+
+## 3. Runtime state có sẵn (`vueData`)
+
+`fastproject.js` khởi tạo sẵn các biến này trong `vueData` — dùng được ngay trong `module.json`/`script.js`, không cần khai báo:
+
+| Biến | Ý nghĩa |
+|---|---|
+| `user` | Thông tin user đăng nhập (fetch từ `v_Set.userInfo`) — xem cấu trúc bên dưới |
+| `v_Set` | Config hiệu lực của trang (mục 2.1) — xem [project-config.md](project-config.md) |
+| `p_domain` | Hostname hiện tại (vd `tsa.example.vn`) |
+| `p_router` / `p_routers` | Path hiện tại (`/manager/schedule-assignment`) / mảng segment (`["manager","schedule-assignment"]`) |
+| `p_params` | Query string (`?...`) |
+| `p_urlReferrer` | URL trang giới thiệu |
+| `v_Loading` / `v_LoadingOverlay` | Trạng thái loading khi gọi API (tự quản lý) |
+| `v_containerOn` | Bật/tắt vùng nội dung chính |
+
+### Cấu trúc `vueData` thực tế (mẫu)
+
+Runtime khởi tạo sẵn `p_*`, `user`, `v_Set`. Đây là một `vueData` thật (đã rút gọn) — dùng để biết chính xác đường dẫn khi tham chiếu:
+
+```json
+{
+  "p_domain": "tsa.example.vn",
+  "p_routers": ["manager", "schedule-assignment"],
+  "p_router": "/manager/schedule-assignment",
+  "p_params": "",
+  "user": {
+    "UserID": "NV0000001", "UserName": "nguyenvana",
+    "LastName": "Nguyễn Văn", "FirstName": "A",
+    "Phone": "09xxxxxxxx", "Email": "nguyenvana@example.vn",
+    "GroupID": 1, "DepartmentID": "BGH", "ClassID": null,
+    "SystemRight": 9, "LastLogin": "2026-06-05 09:16:42",
+    "FunctionRight": ["1","2","3","4","5","6","7","8","9","10","11","12","13","14"]
+  },
+  "v_Set": {
+    "title": "Hệ thống quản lý tuyển sinh",
+    "apiDomain": "https://tapi.example.vn/",
+    "login": "https://app.example.vn",
+    "userInfo": "https://tapi.example.vn/acc/userinfo/ts",
+    "logo": "https://.../Logo_ChimLac_W.png",
+    "ProjectName": "Tuyển Sinh",
+    "menuLeft": false,
+    "menu": [ { "name": "...", "right": { "FunctionRight": ["10"] }, "submenu": [ ... ] } ],
+    "userProfile": {
+      "color": "white",
+      "url-signout": "https://app.example.vn/Signout",
+      "url-change-password": "https://app.example.vn/ChangePassword",
+      "url-account": "https://app.example.vn",
+      "url-avatar": "https://file.example.vn/me/avatarOrigin/",
+      "url-app-list": "https://tapi.example.vn/me/auth/ApplicationList"
+    }
+  }
+}
+```
+
+**Trường của `user`** (thay đổi tùy `userInfo` endpoint, nhưng thường gồm): `UserID`, `UserName`, `LastName`, `FirstName`, `Phone`, `Email`, `GroupID`, `DepartmentID`, `ClassID`, `SystemRight` (int), `FunctionRight` (**mảng string**, vd `["10","14"]`), `LastLogin`. Một số hệ thống có thêm `Sex`.
+
+> **Lưu ý dùng:** `user.SystemRight` là **số** (so sánh `>= 2`); `user.FunctionRight` là **mảng chuỗi** (kiểm tra bằng `.includes('10')` hoặc `rightTest`). Tham chiếu trong controls: `vueData.user.UserID`, `vueData.user.SystemRight`, `vueData.v_Set.apiDomain`...
+
+### API lấy thông tin user (userInfo endpoint)
+
+FUI dùng database phân quyền riêng, truy cập qua **apiName/Alias `acc`**. Endpoint lấy thông tin user và quyền hạn trên một project có cấu trúc:
+
+```
+{apiDomain}/acc/userinfo/{project_apiName}
+```
+
+- `{apiDomain}` — domain tAPI của hệ thống (lấy từ `vueData.v_Set.apiDomain`)
+- `acc` — alias cố định cho database phân quyền (không đổi)
+- `userinfo` — tên API lấy thông tin user
+- `{project_apiName}` — apiName/code của project (do admin cấu hình, ví dụ: `quansinh`, `ts`, `qlsv`)
+
+**Cách dùng:** khai báo `userInfo` trong `project.json` (field `set`) hoặc `module.json` (field `set`). FUI tự fetch khi trang load và gán kết quả vào `vueData.user`.
+
+```json
+// project.json → set
+{
+  "userInfo": "https://tapi.example.vn/acc/userinfo/quansinh"
+}
+```
+
+Sau khi khai báo, toàn bộ thông tin user có sẵn trong `vueData.user`:
+
+```js
+vueData.user.UserID          // mã nhân viên/sinh viên
+vueData.user.UserName        // tên đăng nhập
+vueData.user.SystemRight     // quyền hệ thống (int 0–9)
+vueData.user.FunctionRight   // mảng quyền chức năng ["1","2","10",...]
+vueData.user.DepartmentID    // mã đơn vị
+```
+
+**Dùng trong controls (v-if ẩn/hiện theo quyền):**
+
+```json
+{ "col": { "v-if": "vueData.user.SystemRight >= 5" } }
+{ "col": { "v-if": "vueData.user.FunctionRight.includes('10')" } }
+```
+
+**Dùng trong action IN (truyền vào API):**
+
+```json
+{ "API": "SP_GetDuLieu", "IN": { "UserID": "vueData.user.UserID", "DeptID": "vueData.user.DepartmentID" } }
+```
+
+> **Lưu ý:** `@sys_UserID`, `@sys_UserName`, `@sys_GroupID`... được tAPI tự inject vào mọi SP — không cần truyền thủ công qua `IN`. Chỉ tham chiếu `vueData.user.*` khi cần dùng trong logic JS/Vue phía client.
+
+### Tham số URL tự inject vào `vueData`
+
+`buildParamURL()` đọc mọi query param `?key=value` và gán `vueData[key] = value` **trước khi** `data[]` chạy. → Module con mở qua `openWindow`/`redirect` chỉ cần khai báo biến trùng tên param rồi `{ "CALL": "apiLoad" }` ở cuối `data[]`. (Xem [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md).)
+
+### Quyền của user
+
+FUI có 2 loại quyền độc lập — `SystemRight` (cấp bậc trên project) và `FunctionRight` (quyền theo từng chức năng cụ thể), cả hai định nghĩa trong database phân quyền trung tâm (alias `acc`, `{project_apiName}` = APIName của project trong `tblModules`). Runtime: `vueData.user.SystemRight` (int)/`vueData.user.FunctionRight` (mảng string) dùng cho `v-if` và `right` trong menu; hàm `rightTest({ SystemRight:[...], FunctionRight:[...] })` kiểm tra giao quyền.
+
+**Khái niệm đầy đủ (SystemRight vs FunctionRight), cấu trúc `tblSysRight`/`tblFunction`, và 4 MCP tool quản lý định nghĩa quyền (`right_system_list/set`, `right_function_list/set`):** xem [permission-system.md](permission-system.md).
+
+---
+
+## 4. Vòng đời khởi tạo một trang (fastproject.js)
+
+```
+$(document).ready → loadModuleInfo()
+  1. Merge v_Set: $projectGroupSetting ← $projectData ← $moduleUI.set
+  2. Áp domainSetting[domain hiện tại] (nếu có)
+  3. buildParamURL(): query ?key=value → vueData[key]
+  4. Nếu v_Set.userInfo: fetch thông tin user → vueData.user
+  5. createModuleDom():
+     - runAction($moduleUI.data)        → khởi tạo state + chạy action/CALL đầu
+     - buildModuleUI($moduleUI.controls) → dựng DOM (container>rows>cols)
+     - createWatch_Data / createWatch($moduleUI.watch) → gắn watcher
+     - new Vue(...) với Vuetify(v_Set.themeStyle)
+     - Kết nối websocket nếu có vueData.webSocket
+     - Kiểm tra đăng nhập (v_Set.login)
+```
+
+Hệ quả thiết kế:
+- `data[]` chạy tuần tự trên xuống; đặt khởi tạo state trước, `{ "CALL": ... }` auto-startup ở cuối.
+- Đặt các gán `#PARENT.*` / biến từ URL **trước** các CALL fetch để dữ liệu sẵn sàng.
+
+---
+
+## 5. Action engine — các key trong một action (tham chiếu nhanh)
+
+`runAction`/`vueAction` xử lý một object action theo các key sau (nguồn: fastproject.js). Pattern chi tiết + value resolution: **[controls-patterns.md](controls-patterns.md)**.
+
+| Key | Tác dụng |
+|---|---|
+| `API` | Gọi endpoint (POST mặc định). Đường dẫn không `http` → tự prepend `v_Set.apiDomain` (`fixURL`) |
+| `IN` | Tham số gửi lên (map từ `vueData`) |
+| `OUT` | Nơi lưu kết quả. Nếu response chỉ có key `data` và `OUT` là string → tự unwrap `d.data` |
+| `METHOD` | Override HTTP method (mặc định POST) |
+| `HEADER` | Override header (mặc định `authorization: Bearer awt`) |
+| `MESS` | Toast thành công |
+| `MESSBOX` | Hộp thoại thông báo (`showMessage`) |
+| `CALLBACK` | Action chạy sau khi API/FUN xong |
+| `ERROROUT` / `ERRORCALLBACK` | Xử lý nhánh lỗi |
+| `CALL` | Gọi action đã đặt tên khác |
+| `CONFIRM` / `CANCEL` | Hỏi xác nhận trước, nhánh hủy |
+| `IF` / `THEN` / `ELSE` | Rẽ nhánh (điều kiện là JS expression trên vueData) |
+| `FUN` (+`IN`/`OUT`/`CALLBACK`) | Gọi hàm global (`openWindow`, `jsonToExcel`, `printPDF`...) |
+| `EXE` | Chạy JS thô (dùng dè xẻn) |
+| *(object thường)* | Gán trực tiếp vào `vueData` (state set) |
+
+`json_data_parse` tự parse cột `json_data:Field` trong response thành object (xem [tapi-reference.md](tapi-reference.md)).
+
+---
+
+## 6. Component & hàm dựng sẵn (điểm vào)
+
+- **Component `f-*` / `t-*`**: danh mục đầy đủ + import cần thiết → [component-quickref.md](component-quickref.md).
+- **Hàm tiện ích global** (`openWindow`, `CALL`, `confirm`, `showMessage`, `ajaxCALL`, `jsonToExcel`, `groupBy`, `pushRouter`, `rightTest`, `printPDF`, `webSocket_Send`...) → [default-function.md](default-function.md).
+- **Thư viện toàn cục** (`$`, `_`, `moment`, `numeral`, `Vue.$toast`) → [script-map.md](script-map.md) §0 "Thư viện đã bundled sẵn" — đọc trước khi định thêm CDN.
+
+---
+
+## 7. Ghi nhớ thiết kế
+
+- Project cung cấp khung (menu, apiDomain, style, component chung); Module chỉ khai báo phần khác biệt.
+- Đừng lặp lại config đã có ở project trong từng module.
+- Component dùng >1 module → đặt project-scope (global), không copy vào từng module.
+- Import chỉ khai báo ở nơi thực sự dùng; component dùng chung → import project-scope.
+- Mọi thứ chạy trên `vueData`; tham chiếu state bằng tiền tố `vueData.` trong controls/attr.