@fui-org/fui-cli 1.3.2 → 2.0.0

package/skills/fui-skill/references/project-config.md

@@ -1,18 +1,14 @@
 # Project Config — project.json & module set
 
-> File này sở hữu: **`project.json`: menu, menuLeft, điều hướng, domainSetting, `right`, quan hệ với `set` của module**.
+> Owns: **`project.json`: menu, menuLeft, navigation, domainSetting, `right`, relation to module `set`**.
 
-> Cơ chế trộn nền tảng: [platform-architecture.md](platform-architecture.md) §2.1. File này là **danh mục thuộc tính** đầy đủ của project.json và `set`.
+> Platform merge mechanism: [platform-architecture.md](platform-architecture.md) §2.1. This file is the **full property catalog** for project.json and `set`.
 
-> **Sửa rồi đẩy lên thế nào:** `project.json` là **file-driven** như `module.json` — sửa file
-> `{projectId}/project.json` trong workspace, rồi gọi `project_publish_config({ projectId })`. Tool
-> không nhận config qua tham số, nên bản local không bao giờ lệch server sau khi publish. Lấy bản
-> mới nhất về trước khi sửa: `project_sync`. (`project_update` là chuyện khác — nó sửa **metadata**
-> project, không phải runtime config.)
+> **Edit and push:** `project.json` is **file-driven** like `module.json`: `fui project sync` (pull latest) → edit `{projectId}/project.json` → `fui project publish-config [-p project]`. It takes no config arguments, so local never drifts from server. (`fui project update` edits project **metadata**, not runtime config.)
 
-## Quan hệ project.json ↔ module.json `set`
+## project.json ↔ module.json `set`
 
-`project.json` là config mặc định cho toàn bộ project. Mỗi module có object `set` riêng — khi runtime render một module, `fastproject.js` merge **3 tầng** (tầng sau ghi đè tầng trước) rồi áp override theo domain:
+At render `fastproject.js` merges **3 layers** (later overrides earlier), then the domain override:
 
 ```
 $projectGroupSetting        (cấu hình nhóm project — thấp nhất)
@@ -24,34 +20,30 @@ module.json "set"           ← ưu tiên cao nhất
 domainSetting[domain hiện tại]   (nếu đang chạy trên domain đó)
 ```
 
-Kết quả lưu ở `vueData.v_Set` — mọi nơi trong trang đọc qua `vueData.v_Set.*`.
-
-**Kết quả:** Module kế thừa toàn bộ config project (menu, style, apiDomain...) nhưng có thể override bất kỳ field nào cho riêng trang đó. Trang bình thường **không cần `set`**.
-
-### Danh mục thuộc tính `v_Set` (project.json.data hoặc module.set)
-
-Runtime khởi tạo và sử dụng các field sau (nguồn: `fastproject.js`):
-
-| Field | Kiểu | Tác động |
-|---|---|---|
-| `title` | string | Tiêu đề trang (thanh header) |
-| `apiDomain` | string | Base URL tAPI — API path không `http` được prepend giá trị này |
-| `login` | string | URL trang đăng nhập; runtime tự mở khi thiếu token / 401 |
-| `userInfo` | string | Endpoint lấy thông tin user → `vueData.user`; rỗng = không fetch |
-| `menu` | `false` \| array | Menu header ngang; `false` = ẩn (cao 48px khi hiện) |
-| `menuLeft` | array | Menu sidebar trái |
-| `menuComponent` | array | Custom component nhúng vào vùng menu |
-| `menuStyle` | object | Màu top/left menu |
-| `logo` | string | URL logo trên header |
-| `userProfile` | object/string | Cấu hình khối profile user trên header |
-| `themeStyle` | object | Truyền vào `new Vuetify(...)` — theme màu Vuetify của trang |
-| `disableValidate` | boolean | `true` = bỏ qua validate form khi submit |
-| `authDomain` | string | Domain để xóa cookie khi `logout()` |
-| `fileDomain` | string | Base URL file server |
-| `domainSetting` | object | Override config theo domain (đa domain) |
-| `webSocket` | object | Cấu hình SignalR group real-time (xem [websocket-realtime.md](websocket-realtime.md)) |
-
-**Ví dụ:** Project có `menuLeft` dài, nhưng một trang landing page muốn ẩn menu:
+Result: `vueData.v_Set` (read via `vueData.v_Set.*`). Module inherits all project config and may override any field. Normal pages **need no `set`**.
+
+### `v_Set` properties (project.json.data or module.set; used by `fastproject.js`)
+
+| Field             | Type             | Effect                                                                          |
+| ----------------- | ---------------- | ------------------------------------------------------------------------------- |
+| `title`           | string           | Page title (header bar)                                                         |
+| `apiDomain`       | string           | tAPI base URL — prepended to API paths without `http`                           |
+| `login`           | string           | Login page URL; runtime opens it on missing token / 401                         |
+| `userInfo`        | string           | User info endpoint → `vueData.user`; empty = no fetch                           |
+| `menu`            | `false` \| array | Horizontal header menu; `false` = hidden (48px tall when shown)                 |
+| `menuLeft`        | array            | Left sidebar menu                                                               |
+| `menuComponent`   | array            | Custom components in the menu area                                              |
+| `menuStyle`       | object           | Top/left menu colors                                                            |
+| `logo`            | string           | Header logo URL                                                                 |
+| `userProfile`     | object/string    | Header user profile block                                                       |
+| `themeStyle`      | object           | Passed to `new Vuetify(...)` — page Vuetify theme                               |
+| `disableValidate` | boolean          | `true` = skip form validation on submit                                         |
+| `authDomain`      | string           | Domain whose cookies `logout()` clears                                          |
+| `fileDomain`      | string           | File server base URL                                                            |
+| `domainSetting`   | object           | Per-domain config override (multi-domain)                                       |
+| `webSocket`       | object           | SignalR real-time group config ([websocket-realtime.md](websocket-realtime.md)) |
+
+Example — only this landing page hides the header menu:
 
 ```json
 // module.json — set của trang đó
@@ -60,13 +52,9 @@ Runtime khởi tạo và sử dụng các field sau (nguồn: `fastproject.js`):
 }
 ```
 
-→ Trang này không hiển thị header menu, các trang khác vẫn bình thường.
+## project.json structure
 
----
-
-## Cấu trúc project.json
-
-`project.json` chứa một object `data` duy nhất (không phải array như module.json):
+`project.json` holds a single `data` object (not an array like module.json):
 
 ```json
 {
@@ -86,29 +74,23 @@ Runtime khởi tạo và sử dụng các field sau (nguồn: `fastproject.js`):
 }
 ```
 
-### Các field trong `data`
-
-| Field | Kiểu | Mô tả |
-|---|---|---|
-| `ProjectName` | string | Tên project hiển thị |
-| `title` | string | Tiêu đề mặc định cho các trang |
-| `logo` | string | URL ảnh logo trên thanh menu, ví dụ `"/images/fastUI_White.png"` |
-| `apiDomain` | string | Base URL tAPI kèm apiName, ví dụ `https://tapi.example2.vn/` hoặc `https://tapi.example.vn/acc/` |
-| `login` | string | URL trang đăng nhập |
-| `userInfo` | string | Endpoint lấy thông tin user đã đăng nhập. FUI public: `"https://api.fui.vn/fp/userinfo"` |
-| `apiFile` | string | Endpoint upload file (tùy chọn) |
-| `fileDomain` | string | Base URL file server (tùy chọn) |
-| `menuStyle` | object | Style cho menu top/left |
-| `menu` | `false` hoặc array | Menu header ngang — `false` = ẩn hoàn toàn |
-| `menuLeft` | array | Menu sidebar trái |
-| `menuComponent` | array | Component tùy chỉnh nhúng vào vùng menu |
-| `domainSetting` | object | Override config theo từng domain (đa domain) |
-
----
+### `data` fields
+
+Same meaning as the `v_Set` table above, plus:
+
+| Field         | Type   | Description                                                                                    |
+| ------------- | ------ | ---------------------------------------------------------------------------------------------- |
+| `ProjectName` | string | Display name                                                                                   |
+| `title`       | string | Default page title                                                                             |
+| `logo`        | string | Menu bar logo URL, e.g. `"/images/fastUI_White.png"`                                           |
+| `apiDomain`   | string | tAPI base URL with apiName, e.g. `https://tapi.example2.vn/` or `https://tapi.example.vn/acc/` |
+| `userInfo`    | string | Public FUI: `"https://api.fui.vn/fp/userinfo"`                                                 |
+| `apiFile`     | string | File upload endpoint (optional)                                                                |
+| `fileDomain`  | string | File server base URL (optional)                                                                |
 
 ## menuStyle
 
-Tùy chỉnh màu sắc cho top menu và left menu:
+Top and left menu colors:
 
 ```json
 "menuStyle": {
@@ -123,14 +105,12 @@ Tùy chỉnh màu sắc cho top menu và left menu:
 }
 ```
 
----
-
 ## menu (top header)
 
-- `false` → ẩn hoàn toàn thanh header chứa menu
-- Array → danh sách menu item hiển thị ở thanh top
+- `false` → header bar with menu fully hidden
+- Array → top bar menu items
 
-**Chiều cao cố định: 48px.** Khi `menu` đang hiển thị (không phải `false`), thanh menu chiếm 48px trên đầu trang. Bất kỳ tính toán chiều cao "full màn hình" nào cho vùng nội dung (`calc(100vh - Npx)`, `$(window).height() - N`, CSS `height: 100vh` trên container...) đều phải cộng thêm 48px vào phần trừ đi để tránh tràn/scroll ngoài ý muốn:
+**Fixed height: 48px** when shown. Every "full screen" content height calc (`calc(100vh - Npx)`, `$(window).height() - N`, CSS `height: 100vh` on a container...) must also subtract 48px, or it overflows/scrolls:
 
 ```css
 /* Có menu hiển thị */
@@ -140,13 +120,11 @@ height: calc(100vh - 48px);
 height: 100vh;
 ```
 
-Áp dụng cho cả `module.json` (`:height` của `f-table`, `f-echart`...) lẫn CSS trong `header.html`/component cho trang `HTMLOnly=true`.
-
----
+Applies to `module.json` (`:height` of `f-table`, `f-echart`...) and to CSS in `header.html`/components for `HTMLOnly=true` pages.
 
 ## menuLeft (sidebar)
 
-Array các menu item hiển thị ở sidebar trái. Cấu trúc một item:
+Array of sidebar items. One item:
 
 ```json
 {
@@ -161,19 +139,19 @@ Array các menu item hiển thị ở sidebar trái. Cấu trúc một item:
 }
 ```
 
-### Cấu trúc menu item
+### Menu item fields
 
-| Field | Bắt buộc | Mô tả |
-|---|---|---|
-| `name` | ✅ | Tên hiển thị |
-| `url` | ❌ | Đường dẫn module (bỏ qua nếu chỉ là nhóm có submenu) |
-| `icon` | ❌ | Icon Material Design (`mdi-*`) |
-| `submenu` | ❌ | Mảng menu con (cùng cấu trúc) |
-| `right` | ❌ | Điều kiện hiển thị theo quyền — thiếu = hiển thị cho tất cả |
+| Field     | Required | Description                                      |
+| --------- | -------- | ------------------------------------------------ |
+| `name`    | ✅       | Display name                                     |
+| `url`     | ❌       | Module path (omit for a group with submenu only) |
+| `icon`    | ❌       | Material Design icon (`mdi-*`)                   |
+| `submenu` | ❌       | Child items (same structure)                     |
+| `right`   | ❌       | Visibility by right — missing = visible to all   |
 
-### Kiểm tra quyền hiển thị menu (`right`)
+### Menu visibility (`right`)
 
-> Phân biệt `SystemRight` (cấp bậc) vs `FunctionRight` (quyền theo chức năng) và cách quản lý định nghĩa quyền: xem [permission-system.md](permission-system.md).
+> `SystemRight` (rank) vs `FunctionRight` (per-function) and managing right definitions: [permission-system.md](permission-system.md).
 
 ```json
 "right": {
@@ -182,25 +160,26 @@ Array các menu item hiển thị ở sidebar trái. Cấu trúc một item:
 }
 ```
 
-- **`SystemRight`**: `user.SystemRight` (số) phải nằm trong mảng này mới thấy menu item
-- **`FunctionRight`**: `user.FunctionRight` (mảng chuỗi) phải giao với mảng này (có ít nhất một mã) mới thấy
-- **`UserID`**: chỉ các `UserID` liệt kê mới thấy — dùng cho menu nội bộ/DEV
-- Khi khai báo nhiều key: user phải thỏa **tất cả** (hàm `rightTest` kiểm tra giao từng key với `vueData.user[key]`)
-- Không khai báo `right` → item hiển thị cho tất cả user đã đăng nhập
+- **`SystemRight`**: `user.SystemRight` (number) must be in the array
+- **`FunctionRight`**: `user.FunctionRight` (string array) must intersect the array (at least one code)
+- **`UserID`**: only listed `UserID`s see it — for internal/DEV menus
+- Multiple keys: user must satisfy **all** (`rightTest` checks each key's intersection with `vueData.user[key]`)
+- No `right` → visible to every logged-in user
+
+**Real example — DEV menu for a few UserIDs:**
 
-**Ví dụ thực tế — menu DEV chỉ cho vài UserID:**
 ```json
 {
   "name": "DEV",
   "right": { "UserID": ["NV0000177", "NV0001078", "NV0000605"] },
-  "submenu": [
-    { "name": "Tra cứu lịch sử OTP", "url": "/hoso-sms-history" }
-  ]
+  "submenu": [{ "name": "Tra cứu lịch sử OTP", "url": "/hoso-sms-history" }]
 }
 ```
-> Menu top thường chỉ có `name` + `right` + `submenu` (không `url` ở cấp cha); `url` nằm ở từng mục `submenu`.
 
-**Ví dụ thực tế — menu chỉ cho Tổ trưởng/BGH cấp 1:**
+> Top menu parents usually have only `name` + `right` + `submenu` (no `url`); `url` sits on each `submenu` item.
+
+**Real example — menu for level-1 Team lead/BGH only:**
+
 ```json
 {
   "name": "Cấp 1 - Tổ trưởng",
@@ -212,13 +191,12 @@ Array các menu item hiển thị ở sidebar trái. Cấu trúc một item:
   "submenu": [ ... ]
 }
 ```
-→ Chỉ user có `FunctionRight` chứa `"10"` (cấp 1) VÀ `SystemRight` là 5 hoặc 9 mới thấy mục này.
 
----
+→ Visible only if `FunctionRight` contains `"10"` AND `SystemRight` is 5 or 9.
 
 ## menuComponent
 
-Mảng các custom Vue component được nhúng vào vùng menu (ví dụ: dropdown chọn niên khóa, chọn vai trò):
+Custom Vue components embedded in the menu area (e.g. school-year or role dropdown):
 
 ```json
 "menuComponent": [
@@ -227,13 +205,11 @@ Mảng các custom Vue component được nhúng vào vùng menu (ví dụ: drop
 ]
 ```
 
-Component phải được đăng ký trong `components/_components.json` của project.
-
----
+Components must be registered in the project's `components/_components.json`.
 
-## userProfile (khối tài khoản trên header)
+## userProfile (header account block)
 
-Cấu hình khối avatar/tài khoản góc phải header (đăng xuất, đổi mật khẩu, danh sách app):
+Header-right avatar/account block:
 
 ```json
 "userProfile": {
@@ -246,22 +222,20 @@ Cấu hình khối avatar/tài khoản góc phải header (đăng xuất, đổi
 }
 ```
 
-| Field | Ý nghĩa |
-|---|---|
-| `color` | Màu chữ/icon khối profile |
-| `url-signout` | URL đăng xuất |
-| `url-change-password` | URL đổi mật khẩu |
-| `url-account` | URL trang tài khoản |
-| `url-avatar` | Base URL ảnh đại diện (ghép `UserID`) |
-| `url-app-list` | Endpoint danh sách ứng dụng (menu chuyển app) |
+| Field                 | Meaning                             |
+| --------------------- | ----------------------------------- |
+| `color`               | Text/icon color                     |
+| `url-signout`         | Sign-out URL                        |
+| `url-change-password` | Change-password URL                 |
+| `url-account`         | Account page URL                    |
+| `url-avatar`          | Avatar base URL (`UserID` appended) |
+| `url-app-list`        | App list endpoint (app switcher)    |
 
-> `menuLeft: false` = không dùng sidebar trái (chỉ menu top). `menuLeft: [ ... ]` = bật sidebar.
+> `menuLeft: false` = no left sidebar (top menu only). `menuLeft: [ ... ]` = sidebar on.
 
----
+## domainSetting (multi-domain)
 
-## domainSetting (đa domain)
-
-Khi một project chạy trên nhiều domain khác nhau (mỗi domain có tAPI server và DB riêng), dùng `domainSetting` để override config theo domain:
+Project on several domains (each with its own tAPI server and DB):
 
 ```json
 "domainSetting": {
@@ -280,13 +254,11 @@ Khi một project chạy trên nhiều domain khác nhau (mỗi domain có tAPI
 }
 ```
 
-Key là hostname của domain. Runtime tự phát hiện domain hiện tại và áp dụng override tương ứng.
-
----
+Key = hostname; runtime applies the current domain's override.
 
-## module.json `set` — Override cho từng trang
+## module.json `set` — per-page override
 
-`set` trong module.json có thể override bất kỳ field nào từ project.json. Các field thường dùng:
+`set` can override any project.json field. Common:
 
 ```json
 "set": {
@@ -296,18 +268,16 @@ Key là hostname của domain. Runtime tự phát hiện domain hiện tại và
 }
 ```
 
-| Dùng `set` khi | Ví dụ |
-|---|---|
-| Trang có tiêu đề riêng | `"title": "Nhập điểm Tiểu học"` |
-| Trang ẩn menu header | `"menu": false` |
-| Trang cần menu sidebar khác | Override `"menuLeft"` với danh sách rút gọn |
-| Trang landing / public | `"menu": false, "menuLeft": []` |
+| Use `set` when                 | Example                                   |
+| ------------------------------ | ----------------------------------------- |
+| Page has its own title         | `"title": "Nhập điểm Tiểu học"`           |
+| Page hides header menu         | `"menu": false`                           |
+| Page needs a different sidebar | Override `"menuLeft"` with a shorter list |
+| Landing / public page          | `"menu": false, "menuLeft": []`           |
 
-**Không cần ghi lại các field không thay đổi** — module chỉ cần khai báo những gì khác với project default.
+**Do not repeat unchanged fields** — declare only what differs from the project default.
 
----
-
-## Tóm tắt quan hệ file
+## File relation summary
 
 ```
 project.json.data          ← config mặc định cho toàn project
@@ -318,11 +288,9 @@ Effective config = merge(project.json.data, module.json.set)
                    (module.set được ưu tiên)
 ```
 
----
-
-## openWindow — Quy tắc truyền tham số URL
+## openWindow — URL parameter rule
 
-Khi mở sub-window bằng `openWindow`, URL chỉ truyền **ID của record cha** mà module con thực sự dùng để query DB. Không truyền name, label hay field nào có thể tra lại từ DB trong module con.
+Pass in the `openWindow` URL **only the parent record ID** the child queries the DB with. Never pass names, labels or any field the child can look up.
 
 ```json
 // ✅ Đúng — chỉ truyền ID cần thiết
@@ -332,4 +300,4 @@ Khi mở sub-window bằng `openWindow`, URL chỉ truyền **ID của record ch
 "url": "`/ContestDetail?ContestID={{sContestID}}&ContestName={{sContestName}}"
 ```
 
-**Lý do:** Module con load dữ liệu đầy đủ từ DB theo ID — truyền thêm field thừa làm URL dài, dữ liệu có thể lỗi thời, và tạo dependency không cần thiết giữa 2 module.
+Why: the child loads everything by ID; extra fields lengthen the URL, go stale, and couple the modules.