@fui-org/fui-cli 1.2.1 → 1.3.2

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

@@ -0,0 +1,269 @@
+# FUI Platform Architecture
+
+> Owns: **FUI structure and Project→Module hierarchy: how import/component/set merge, `vueData`/`v_Set`, runtime lifecycle**.
+
+Source of truth (not training data): runtime `scripts/fastproject.js` (main), `defaultfunction.js` (shared functions), `component.js`/`componentTable.js` (V3: `componentTable-3.0.js`) — core components (`f-table`, `t-*`, dialog, editor...). `f-echart` (`fechart.js`) and `f-sheet` (`fsheet.js`) are **separate files loaded via imports declared in module/project**, not auto-loaded.
+
+> Read BEFORE designing a system/module. Then: per-part config → [module-json-anatomy.md](module-json-anatomy.md); project.json & set → [project-config.md](project-config.md); UI patterns → [ui-patterns.md](ui-patterns.md) (high priority, battle-tested).
+
+## 1. What FUI is
+
+Metadata-driven low-code: each page (module) declares UI + logic in `module.json`; `fastproject.js` builds the Vue 2 + Vuetify DOM from it. Declare only — never hand-write a Vue component per page.
+
+Page load order (pre-bundled, **never re-import**):
+
+1. jQuery, Lodash (`_`), Moment, Numeral, Vuetify, vue-toast, jquery-confirm
+2. `defaultfunction.js` — utilities (`openWindow`, `CALL`, `confirm`, `showMessage`, `ajaxCALL`, `jsonToExcel`...)
+3. `component.js` + `componentTable.js` — register all `f-*` / `t-*`
+4. `fastproject.js` — read `module.json`, merge config, build DOM, run actions, attach watch
+5. Page data: `$projectData` (project.json), `$moduleUI` (module.json), `$projectGroupSetting`
+
+## 2. Project → Module hierarchy (merge rules — most important)
+
+**Project** (shared) parts auto-merge into every **Module** (one page); on conflict **Module wins**.
+
+### 2.1 `set`
+
+Effective config `v_Set` (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])
+```
+
+Priority (later overrides earlier):
+
+```
+$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 inherits all project config (menu, apiDomain, style, login...); declare `set` only for differences. A normal page has **no `set`**. Properties: [project-config.md](project-config.md).
+
+### 2.2 `imports` — appended, not replaced
+
+Project and module imports both load. `addImport`: `.css` → `<link>`; else `<script>`.
+
+Order is **not** framework → project → module: server (`spA_FUI_ModuleDataSelect`) UNIONs framework (per V2/V3), project (`ModuleID IS NULL`) and module scopes, then sorts **once** by `FileSort, FileName`. A module import with small `FileSort` loads **before** a project import. Express order dependencies (e.g. `echarts.min.js` before `fechart.js`) with `FileSort`, never via scope.
+
+Framework uses `FileSort` ~1-10. `fui import new`/`fui import update` guard this in code (`resolveImportSort`, `src/tools/module.ts`): empty sort → scope default (project ≥ 20, module ≥ 50); lower value → raised, with an `ℹ️` note in output. They cannot place an import before the framework — if truly needed, deploy via a route outside fui.
+
+- Project-scope: shared libs for all modules.
+- Module-scope: that page only (e.g. `echarts.min.js` + `fechart.js` for `f-echart`).
+- `imports/_imports.json` = `[]` is normal when only bundled libs are used.
+
+> Adding/removing a component that needs imports (f-echart, f-file-upload, f-editor...) → always `fui import list`, then `fui import new`/`fui import delete`. Import table: [component-quickref.md](component-quickref.md).
+
+#### Import kinds by `ContentType`
+
+| Kind                    | `ContentType`                  | Source                                                    | Edit with                                            |
+| ----------------------- | ------------------------------ | --------------------------------------------------------- | ---------------------------------------------------- |
+| **CDN / URL reference** | empty or not JS/CSS            | External URL (jsdelivr, cdnjs, custom...) — no local file | `fui import update` (metadata only: url, sort, name) |
+| **Uploaded content**    | `text/javascript` / `text/css` | Stored on FUI server; has `fileID` and local `filePath`   | `fui import upload` (overwrite content)              |
+
+User attaches a JS/CSS file and asks for an import:
+
+```
+❌ WRONG: fui import new --content-type link --name "<some url>"
+   → creates a CDN reference; file.js is never stored on the server
+
+✅ RIGHT:
+  1. fui import new ... --content-type text/javascript   → metadata (name, sort, scope)
+  2. fui import upload <fileId> -f file.js                → upload content to FUI server
+```
+
+(Flags: `fui import new --help`.)
+
+- `fui import upload` syncs to **every local `imports/`** declaring that `fileID` — no per-scope repeat.
+- CDN imports: change URL/sort/name via `fui import update`; content **cannot** be uploaded into them.
+- `fui import get` shows the kind (`ContentType`, `FilePath`); `fui import list` shows `ContentType` for all — check it first to pick the next command.
+
+### 2.3 `components`
+
+- `component.js` registers all `f-*`/`t-*` **globally**.
+- Project-scope `uc-*.vue` (`{projectId}/components/`) → auto-loaded globally in **every** module, used by name (no `components:{}`).
+- Module-scope `uc-*.vue` (`{moduleId}/components/`) → that module only.
+- Same name → module-scope wins in that module.
+
+> Design & scope: [component-design.md](component-design.md).
+
+### 2.4 Summary
+
+| Part             | Project provides                              | Merge                           | On conflict         |
+| ---------------- | --------------------------------------------- | ------------------------------- | ------------------- |
+| **set / config** | `project.json` (`data`)                       | Into `v_Set`, then `module.set` | **Module.set wins** |
+| **imports**      | project `_imports.json`                       | **Appended** to module imports  | Both load           |
+| **components**   | project-scope `uc-*.vue` + global `f-*`/`t-*` | Global in every module          | Module-scope wins   |
+
+## 3. Built-in state (`vueData`)
+
+Pre-initialized; use directly in `module.json`/`script.js`:
+
+| Variable                         | Meaning                                                                                |
+| -------------------------------- | -------------------------------------------------------------------------------------- |
+| `user`                           | Logged-in user (from `v_Set.userInfo`)                                                 |
+| `v_Set`                          | Effective page config (§2.1) — [project-config.md](project-config.md)                  |
+| `p_domain`                       | Hostname (e.g. `tsa.example.vn`)                                                       |
+| `p_router` / `p_routers`         | Path (`/manager/schedule-assignment`) / segments (`["manager","schedule-assignment"]`) |
+| `p_params`                       | Query string (`?...`)                                                                  |
+| `p_urlReferrer`                  | Referrer URL                                                                           |
+| `v_Loading` / `v_LoadingOverlay` | API loading state (self-managed)                                                       |
+| `v_containerOn`                  | Toggle main content area                                                               |
+
+Real `vueData` (trimmed) — use for exact paths:
+
+```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"
+    }
+  }
+}
+```
+
+`user` fields depend on the `userInfo` endpoint; usually `UserID`, `UserName`, `LastName`, `FirstName`, `Phone`, `Email`, `GroupID`, `DepartmentID`, `ClassID`, `SystemRight` (int), `FunctionRight` (**string array**, e.g. `["10","14"]`), `LastLogin`; some systems add `Sex`.
+
+> `user.SystemRight` is a **number** (compare `>= 2`); `user.FunctionRight` is a **string array** (`.includes('10')` or `rightTest`). In controls: `vueData.user.UserID`, `vueData.user.SystemRight`, `vueData.v_Set.apiDomain`...
+
+### userInfo endpoint
+
+Permission DB is reached via **apiName/Alias `acc`**:
+
+```
+{apiDomain}/acc/userinfo/{project_apiName}
+```
+
+- `{apiDomain}` — tAPI domain (`vueData.v_Set.apiDomain`)
+- `acc` — fixed permission-DB alias
+- `userinfo` — API name
+- `{project_apiName}` — project apiName/code (admin-set, e.g. `quansinh`, `ts`, `qlsv`)
+
+Declare `userInfo` in `set` of `project.json` or `module.json`; FUI fetches it on load into `vueData.user`.
+
+```json
+// project.json → set
+{
+  "userInfo": "https://tapi.example.vn/acc/userinfo/quansinh"
+}
+```
+
+```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ị
+```
+
+In controls (`v-if` by right):
+
+```json
+{ "col": { "v-if": "vueData.user.SystemRight >= 5" } }
+{ "col": { "v-if": "vueData.user.FunctionRight.includes('10')" } }
+```
+
+In action `IN`:
+
+```json
+{ "API": "SP_GetDuLieu", "IN": { "UserID": "vueData.user.UserID", "DeptID": "vueData.user.DepartmentID" } }
+```
+
+> tAPI auto-injects `@sys_UserID`, `@sys_UserName`, `@sys_GroupID`... into every SP — never pass them via `IN`. Use `vueData.user.*` only for client-side JS/Vue logic.
+
+### URL params → `vueData`
+
+`buildParamURL()` sets `vueData[key] = value` for each `?key=value` **before** `data[]` runs. A child module opened via `openWindow`/`redirect` just declares same-named variables and ends `data[]` with `{ "CALL": "apiLoad" }` ([ui-crosswindow-patterns.md](ui-crosswindow-patterns.md)).
+
+### User rights
+
+Two independent kinds, both in the central permission DB (alias `acc`, `{project_apiName}` = project APIName in `tblModules`): `SystemRight` (rank on project, int) and `FunctionRight` (per function, string array). Use in `v-if` and menu `right`; `rightTest({ SystemRight:[...], FunctionRight:[...] })` checks intersection.
+
+Concepts, `tblSysRight`/`tblFunction`, managing definitions (`fui right system|function list|new|update|delete`): [permission-system.md](permission-system.md).
+
+## 4. Page init lifecycle (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)
+```
+
+- `data[]` runs top to bottom: state init first, auto-startup `{ "CALL": ... }` last.
+- Put `#PARENT.*` / URL variable assignments **before** fetch CALLs.
+
+## 5. Action keys (quick ref)
+
+Handled by `runAction`/`vueAction`. Patterns + value resolution: **[controls-patterns.md](controls-patterns.md)**.
+
+| Key                            | Effect                                                                                     |
+| ------------------------------ | ------------------------------------------------------------------------------------------ |
+| `API`                          | Call endpoint (POST default). Path without `http` → `v_Set.apiDomain` prepended (`fixURL`) |
+| `IN`                           | Params (mapped from `vueData`)                                                             |
+| `OUT`                          | Result target. Response with only key `data` + string `OUT` → auto-unwrap `d.data`         |
+| `METHOD`                       | Override HTTP method (default POST)                                                        |
+| `HEADER`                       | Override header (default `authorization: Bearer awt`)                                      |
+| `MESS`                         | Success toast                                                                              |
+| `MESSBOX`                      | Message dialog (`showMessage`)                                                             |
+| `CALLBACK`                     | Runs after API/FUN finishes                                                                |
+| `ERROROUT` / `ERRORCALLBACK`   | Error branch                                                                               |
+| `CALL`                         | Call another named action                                                                  |
+| `CONFIRM` / `CANCEL`           | Confirm first; cancel branch                                                               |
+| `IF` / `THEN` / `ELSE`         | Branch (JS expression on vueData)                                                          |
+| `FUN` (+`IN`/`OUT`/`CALLBACK`) | Global function (`openWindow`, `jsonToExcel`, `printPDF`...)                               |
+| `EXE`                          | Raw JS (sparingly)                                                                         |
+| _(plain object)_               | Assigned into `vueData`                                                                    |
+
+`json_data_parse` auto-parses `json_data:Field` response columns into objects ([tapi-reference.md](tapi-reference.md)).
+
+## 6. Entry points
+
+- `f-*` / `t-*` list + required imports → [component-quickref.md](component-quickref.md).
+- Global utilities (`openWindow`, `CALL`, `confirm`, `showMessage`, `ajaxCALL`, `jsonToExcel`, `groupBy`, `pushRouter`, `rightTest`, `printPDF`, `webSocket_Send`...) → [default-function.md](default-function.md).
+- Global libs (`$`, `_`, `moment`, `numeral`, `Vue.$toast`) → [script-map.md](script-map.md) §0 — read before adding any CDN.
+
+## 7. Design rules
+
+- Project provides the frame (menu, apiDomain, style, shared components); Module declares only differences — never repeat project config per module.
+- Component used by >1 module → project-scope, never copied per module.
+- Declare imports only where used; shared component → project-scope import.
+- Everything runs on `vueData`; reference state with the `vueData.` prefix in controls/attrs.

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

@@ -0,0 +1,303 @@
+# Project Config — project.json & module set
+
+> Owns: **`project.json`: menu, menuLeft, navigation, domainSetting, `right`, relation to module `set`**.
+
+> Platform merge mechanism: [platform-architecture.md](platform-architecture.md) §2.1. This file is the **full property catalog** for project.json and `set`.
+
+> **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.)
+
+## project.json ↔ module.json `set`
+
+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)
+  ⤵ override bởi
+project.json (khối "data")
+  ⤵ override bởi
+module.json "set"           ← ưu tiên cao nhất
+  ⤵ cuối cùng override bởi
+domainSetting[domain hiện tại]   (nếu đang chạy trên domain đó)
+```
+
+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 đó
+"set": {
+  "menu": false
+}
+```
+
+## project.json structure
+
+`project.json` holds a single `data` object (not an array like module.json):
+
+```json
+{
+  "data": {
+    "ProjectName": "...",
+    "title":       "...",
+    "apiDomain":   "...",
+    "login":       "...",
+    "userInfo":    "...",
+    "apiFile":     "...",
+    "menuStyle":   { ... },
+    "menu":        false | [ ... ],
+    "menuLeft":    [ ... ],
+    "menuComponent": [ ... ],
+    "domainSetting": { ... }
+  }
+}
+```
+
+### `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
+
+Top and left menu colors:
+
+```json
+"menuStyle": {
+  "topmenu": {
+    "bgcolor":   "#217D46",
+    "textcolor": "white"
+  },
+  "leftmenu": {
+    "bgcolor":   "#217D46",
+    "textcolor": "white"
+  }
+}
+```
+
+## menu (top header)
+
+- `false` → header bar with menu fully hidden
+- Array → top bar menu items
+
+**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ị */
+height: calc(100vh - 48px);
+
+/* menu: false → không trừ phần này */
+height: 100vh;
+```
+
+Applies to `module.json` (`:height` of `f-table`, `f-echart`...) and to CSS in `header.html`/components for `HTMLOnly=true` pages.
+
+## menuLeft (sidebar)
+
+Array of sidebar items. One item:
+
+```json
+{
+  "name": "Tên mục",
+  "icon": "mdi-folder-multiple",
+  "url":  "/duong-dan-module",
+  "submenu": [ ... ],
+  "right": {
+    "SystemRight":   [1, 2, 3, 5, 9],
+    "FunctionRight": ["10", "20"]
+  }
+}
+```
+
+### Menu item fields
+
+| 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   |
+
+### Menu visibility (`right`)
+
+> `SystemRight` (rank) vs `FunctionRight` (per-function) and managing right definitions: [permission-system.md](permission-system.md).
+
+```json
+"right": {
+  "SystemRight":   [1, 2, 5, 9],
+  "FunctionRight": ["10", "20"]
+}
+```
+
+- **`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:**
+
+```json
+{
+  "name": "DEV",
+  "right": { "UserID": ["NV0000177", "NV0001078", "NV0000605"] },
+  "submenu": [{ "name": "Tra cứu lịch sử OTP", "url": "/hoso-sms-history" }]
+}
+```
+
+> 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",
+  "icon": "mdi-account-tie",
+  "right": {
+    "FunctionRight": ["10"],
+    "SystemRight":   [5, 9]
+  },
+  "submenu": [ ... ]
+}
+```
+
+→ Visible only if `FunctionRight` contains `"10"` AND `SystemRight` is 5 or 9.
+
+## menuComponent
+
+Custom Vue components embedded in the menu area (e.g. school-year or role dropdown):
+
+```json
+"menuComponent": [
+  { "el": "uc-nien-khoa" },
+  { "el": "uc-vaitro" }
+]
+```
+
+Components must be registered in the project's `components/_components.json`.
+
+## userProfile (header account block)
+
+Header-right avatar/account block:
+
+```json
+"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"
+}
+```
+
+| 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` = no left sidebar (top menu only). `menuLeft: [ ... ]` = sidebar on.
+
+## domainSetting (multi-domain)
+
+Project on several domains (each with its own tAPI server and DB):
+
+```json
+"domainSetting": {
+  "sec.example.vn": {
+    "apiDomain":  "https://tapi.example.vn/acc/",
+    "fileDomain": "https://file.example.vn/acc/",
+    "login":      "https://app.example.vn",
+    "userInfo":   "https://tapi.example.vn/acc/UserInfo/acc"
+  },
+  "sec.example3.vn": {
+    "apiDomain":  "https://api.example3.vn/acc/",
+    "fileDomain": "https://file.example3.vn/acc/",
+    "login":      "https://login.example3.vn",
+    "userInfo":   "https://api.example3.vn/acc/UserInfo/acc"
+  }
+}
+```
+
+Key = hostname; runtime applies the current domain's override.
+
+## module.json `set` — per-page override
+
+`set` can override any project.json field. Common:
+
+```json
+"set": {
+  "title":    "Trang quản lý sinh viên",
+  "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": []`           |
+
+**Do not repeat unchanged fields** — declare only what differs from the project default.
+
+## File relation summary
+
+```
+project.json.data          ← config mặc định cho toàn project
+    ↓ bị override bởi
+module.json.set             ← config riêng cho từng trang
+
+Effective config = merge(project.json.data, module.json.set)
+                   (module.set được ưu tiên)
+```
+
+## openWindow — URL parameter rule
+
+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
+"url": "`/ContestDetail?ContestID={{sContestID}}"
+
+// ❌ Sai — truyền thừa field có thể tra từ DB
+"url": "`/ContestDetail?ContestID={{sContestID}}&ContestName={{sContestName}}"
+```
+
+Why: the child loads everything by ID; extra fields lengthen the URL, go stale, and couple the modules.