@fui-org/fui-cli 0.2.0 → 0.3.0

package/skills/fui-skill/examples/project-patterns.json

@@ -0,0 +1,222 @@
+{
+    "_comment": "Project Config Patterns Reference — Tổng hợp cấu trúc project.json và quan hệ với module.json set. Dùng làm tài liệu tham chiếu khi thiết kế hoặc cập nhật cấu hình project.",
+    "_patterns": {
+        "project_json_fields": [
+            "ProjectName — tên project hiển thị",
+            "title — tiêu đề mặc định cho các trang",
+            "apiDomain — base URL tAPI kèm apiName, ví dụ: https://tapi.example2.vn/ hoặc https://tapi.example.vn/acc/",
+            "login — URL trang đăng nhập",
+            "userInfo — endpoint lấy thông tin user đã đăng nhập",
+            "apiFile — endpoint upload file (tùy chọn)",
+            "menuStyle — màu sắc topmenu/leftmenu",
+            "menu — false (ẩn header) hoặc array (menu ngang trên header)",
+            "menuLeft — array menu sidebar trái",
+            "menuComponent — component tùy chỉnh nhúng vào vùng menu",
+            "domainSetting — override config theo từng domain (đa domain)"
+        ],
+        "menu_item_fields": [
+            "name — tên hiển thị (bắt buộc)",
+            "url — đường dẫn module, bỏ qua nếu chỉ là nhóm cha",
+            "icon — Material Design icon (mdi-*)",
+            "submenu — mảng menu con (cùng cấu trúc)",
+            "right — điều kiện hiển thị; thiếu = hiển thị cho tất cả user đã đăng nhập"
+        ],
+        "right_rules": [
+            "SystemRight: [1,2,3,9] — user.SystemRight phải nằm trong mảng này",
+            "FunctionRight: ['10','20'] — user.FunctionRight phải chứa ít nhất một code",
+            "Khi cả hai cùng có: user phải thỏa ĐồNG THỜI cả SystemRight VÀ FunctionRight",
+            "Không khai báo right — hiển thị cho tất cả user đã đăng nhập"
+        ],
+        "set_override": [
+            "module.json set kế thừa project.json data làm mặc định",
+            "effective = { ...project.json data, ...module.json set } — module set được ưu tiên",
+            "Chỉ khai báo field cần override, không cần lặp lại toàn bộ project config",
+            "menu: false trong set — ẩn header menu chỉ cho trang đó",
+            "title: 'Tên trang' trong set — đổi tiêu đề riêng cho trang"
+        ],
+        "domain_setting": [
+            "Key là hostname domain (ví dụ: sec.example.vn)",
+            "Runtime tự phát hiện domain hiện tại và áp dụng override tương ứng",
+            "Mỗi domain có thể có apiDomain, fileDomain, login, userInfo riêng"
+        ]
+    },
+
+    "_note_structure": "project.json chứa một object 'data' duy nhất (khác với module.json có 4 section data/watch/controls/set)",
+
+    "data_single_domain": {
+        "_note": "Pattern 1 — Project một domain (phổ biến)",
+        "ProjectName": "Tên Project",
+        "title": "TIÊU ĐỀ HIỂN THỊ",
+        "apiDomain": "https://tapi.example.vn/acc/",
+        "login": "https://app.example.vn/",
+        "userInfo": "https://tapi.example.vn/acc/UserInfo/acc",
+        "apiFile": "https://file.example.vn/acc/upload/FileData",
+        "menuStyle": {
+            "_note": "Tùy chỉnh màu menu — bỏ qua nếu dùng màu mặc định",
+            "topmenu": {
+                "bgcolor": "#217D46",
+                "textcolor": "white"
+            },
+            "leftmenu": {
+                "bgcolor": "#217D46",
+                "textcolor": "white"
+            }
+        },
+        "menu": false,
+        "_note_menu_false": "menu: false = ẩn hoàn toàn header menu; thay bằng array nếu muốn menu ngang",
+        "menuLeft": [
+            {
+                "_note": "Item đơn — không có submenu",
+                "name": "Trang chủ",
+                "icon": "mdi-home",
+                "url": "/trang-chu"
+            },
+            {
+                "_note": "Item nhóm — có submenu, right cho cả nhóm",
+                "name": "Quản lý dữ liệu",
+                "icon": "mdi-database",
+                "right": {
+                    "SystemRight": [1, 2, 3, 5, 9]
+                },
+                "submenu": [
+                    {
+                        "name": "Danh sách",
+                        "url": "/danh-sach"
+                    },
+                    {
+                        "_note": "Submenu item có right riêng — phải thỏa right nhóm CHA trước",
+                        "name": "Quản trị",
+                        "url": "/quan-tri",
+                        "right": {
+                            "SystemRight": [3, 5, 9]
+                        }
+                    }
+                ]
+            },
+            {
+                "_note": "Item yêu cầu cả SystemRight VÀ FunctionRight cùng lúc",
+                "name": "Cấp 1 - Giáo viên",
+                "icon": "mdi-human-male-board",
+                "right": {
+                    "FunctionRight": ["10"],
+                    "SystemRight": [1, 2, 5, 9]
+                },
+                "submenu": [
+                    { "name": "Danh sách học sinh", "url": "/ds-hoc-sinh?capid=1" },
+                    {
+                        "name": "Nhập điểm",
+                        "url": "/nhap-diem?capid=1",
+                        "right": { "SystemRight": [1, 2, 5, 9] }
+                    }
+                ]
+            },
+            {
+                "_note": "URL ngoài — link tuyệt đối",
+                "name": "Hướng dẫn sử dụng",
+                "icon": "mdi-book",
+                "url": "https://docs.example.com/huong-dan"
+            },
+            {
+                "_note": "Item không có url, không có submenu — placeholder/disabled",
+                "name": "Hỗ trợ sự cố",
+                "icon": "mdi-help-circle-outline",
+                "url": "/support"
+            }
+        ],
+        "menuComponent": [
+            {
+                "_note": "Component nhúng vào vùng menu — ví dụ: dropdown chọn niên khóa, chọn vai trò",
+                "el": "uc-nien-khoa"
+            },
+            {
+                "el": "uc-vaitro"
+            }
+        ]
+    },
+
+    "data_multi_domain": {
+        "_note": "Pattern 2 — Project chạy trên nhiều domain, mỗi domain một DB/tAPI riêng",
+        "ProjectName": "Security Manager",
+        "title": "Quản lý phân quyền",
+        "login": "https://login.fui.vn",
+        "apiDomain": "https://api.fui.vn/fp/",
+        "userInfo": "https://api.fui.vn/fp/UserInfo/fp",
+        "_note_domain": "domainSetting override config khi user truy cập từ domain tương ứng",
+        "domainSetting": {
+            "sec.example3.vn": {
+                "login": "https://login.example3.vn",
+                "apiDomain": "https://api.example3.vn/acc/",
+                "fileDomain": "https://file.example3.vn/acc/",
+                "userInfo": "https://api.example3.vn/acc/UserInfo/acc"
+            },
+            "sec.example.vn": {
+                "login": "https://app.example.vn",
+                "apiDomain": "https://tapi.example.vn/acc/",
+                "fileDomain": "https://file.example.vn/acc/",
+                "userInfo": "https://tapi.example.vn/acc/UserInfo/acc"
+            },
+            "sec.example2.vn": {
+                "login": "https://login.example2.vn",
+                "apiDomain": "https://tapi.example2.vn/acc/",
+                "fileDomain": "https://file.example2.vn/acc/",
+                "userInfo": "https://tapi.example2.vn/acc/UserInfo/acc"
+            }
+        },
+        "menu": [
+            {
+                "_note": "menu (array) = header ngang — khác với menuLeft (sidebar)",
+                "name": "Users",
+                "right": { "SystemRight": [1, 2, 3, 9] },
+                "url": "/UserManager"
+            },
+            {
+                "name": "Permission",
+                "right": { "SystemRight": [2, 3, 9] },
+                "url": "/Permission"
+            },
+            {
+                "_note": "Menu ngang cũng có thể có submenu",
+                "name": "Rights",
+                "right": { "SystemRight": [2, 3, 9] },
+                "submenu": [
+                    { "name": "System Right", "url": "/SystemRight" },
+                    { "name": "Function Right", "url": "/FunctionRight" }
+                ]
+            }
+        ]
+    },
+
+    "module_set_examples": {
+        "_note": "Các ví dụ về module.json set — override project config cho từng trang riêng",
+
+        "set_hide_menu": {
+            "_note": "Trang ẩn header menu (ví dụ: trang nhúng, trang in, landing page)",
+            "set": {
+                "menu": false
+            }
+        },
+
+        "set_custom_title": {
+            "_note": "Trang có tiêu đề riêng",
+            "set": {
+                "title": "Nhập điểm Tiểu học - Cấp 1"
+            }
+        },
+
+        "set_no_menu_at_all": {
+            "_note": "Trang ẩn hoàn toàn cả header lẫn sidebar (module con mở qua openWindow)",
+            "set": {
+                "menu": false,
+                "menuLeft": []
+            }
+        },
+
+        "set_override_api": {
+            "_note": "Trang dùng apiDomain khác project (hiếm, nhưng có thể override)",
+            "set": {
+                "title": "Trang đặc biệt",
+                "apiDomain": "https://other-api.example.com/apiName/"
+            }
+        }
+    }
+}

package/skills/fui-skill/metadata.json

@@ -0,0 +1,75 @@
+{
+  "name": "fui-skill",
+  "version": "1.5.0",
+  "description": "AI operating manual for FUI (Framework UI) low-code module development. Covers module.json authoring, action engine, UI layout system, component selection, tAPI SP design, MCP tool workflows, and publish safety protocols. Documentation-only manifest — the server reads SKILL.md + references/ directly, not this file.",
+  "authoring_rule": "Mỗi reference mở đầu bằng một dòng '> File này sở hữu: ...' khai báo phạm vi (canonical owner). Một sự thật chỉ được viết đầy đủ ở đúng một file; nơi khác chỉ để link + 1 câu tóm tắt. SKILL.md là văn bản chính sách (quy tắc cứng + cổng quyết định), KHÔNG dạy cách làm — mọi hướng dẫn nằm ở references/, tra qua references/INDEX.md.",
+  "activation_triggers": [
+    "module", "module.json", "fui", "f-table", "f-dialog", "f-echart",
+    "controls", "data", "watch", "CALL", "API", "CALLBACK", "OUT",
+    "menuChucNang", "ctrl-update", "hidden-container",
+    "spAPI_", "stored procedure", "tAPI",
+    "session_set", "module_get", "module_publish_html",
+    "websocket", "webSocket_Send", "webSocketJoinGroup", "signalr", "real-time",
+    "httpCall", "httpAPI", "sendMail", "SQL CLR", "ImageResize", "ImageCrop",
+    "FileReader", "FileWriter", "RegexMatch", "RegexReplace"
+  ],
+  "context_loading": {
+    "router": "references/INDEX.md",
+    "tier1_always": [
+      "SKILL.md",
+      "references/controls-patterns.md",
+      "references/module-structure.md",
+      "references/INDEX.md"
+    ],
+    "tier3_on_demand": {
+      "platform": "references/platform-architecture.md, references/module-json-anatomy.md, references/module-data-patterns.md",
+      "system_design": "references/system-design.md",
+      "design_system": "references/design-modes.md, references/controls-styling-vocabulary.md",
+      "ui_patterns": "references/ui-patterns.md, references/ui-table-cell-patterns.md, references/ui-dialog-patterns.md, references/ui-crosswindow-patterns.md, references/ui-layout-patterns.md",
+      "ui_review": "references/ui-screenshot-review.md",
+      "component_selection": "references/component-quickref.md, references/components-input.md, references/components-display.md, references/components-dialog.md, references/component-table.md",
+      "component_design": "references/component-design.md, references/coding-standards.md",
+      "charts": "references/components-echart.md, references/echart-templates.md",
+      "spreadsheet": "references/fsheet.md",
+      "tapi_sp": "references/tapi-reference.md, references/tapi-permission-patterns.md, references/tapi-file-api.md",
+      "permissions": "references/permission-system.md",
+      "database": "references/db-workflow.md, references/db-table-design.md",
+      "project_provisioning": "references/project-provisioning.md",
+      "fullstack": "references/fullstack-workflow.md",
+      "project_config": "references/project-config.md",
+      "pdf_generation": "references/pdfmake.md",
+      "advanced_scripting": "references/advanced-techniques.md, references/default-function.md, references/script-map.md, references/fastproject.md",
+      "watcher_patterns": "references/watcher-patterns.md",
+      "realtime_messaging": "references/websocket-realtime.md",
+      "sql_clr_functions": "references/sql-clr-functions.md",
+      "tool_safety": "references/tools-registry.md",
+      "new_session": "references/new-session.md",
+      "definition_of_done": "references/verification.md",
+      "templates": "references/ui-templates.md, examples/"
+    }
+  },
+  "tool_safety": {
+    "registry": "references/tools-registry.md",
+    "default_stance": "RequiresConfirm",
+    "destructive_tools": [
+      "module_publish_html",
+      "module_delete",
+      "db_sp_deploy",
+      "db_sp_delete",
+      "db_sql_execute_nonquery",
+      "file_import_delete",
+      "component_delete"
+    ],
+    "mandatory_workflows": {
+      "module_publish_html": "module_preview → user approves → module_publish_html",
+      "module_delete": "show summary → explicit user confirmation → module_delete",
+      "db_sp_deploy": "show summary → explicit user confirmation → db_sp_deploy"
+    }
+  },
+  "verification": {
+    "checklist": "references/verification.md",
+    "gates": ["module_structure", "action_correctness", "sp_naming", "component_api", "publish_workflow"]
+  },
+  "maintainer": "FUI MCP Team",
+  "last_updated": "2026-07-29"
+}

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

@@ -0,0 +1,144 @@
+# FUI Skill — Reference Router (INDEX)
+
+> File này sở hữu: **bảng định tuyến tình huống / component / từ khóa → file reference cần load**. Không chứa nội dung kỹ thuật — mọi quy tắc đều nằm ở file đích. *(Tier A — luôn nạp cùng `skill_get`.)*
+
+**Bản đồ tra cứu: tình huống / component / từ khóa → file cần load.** Đây là file luôn được nạp cùng `skill_get`. Trước khi xử lý bất kỳ việc gì, tra bảng dưới để biết cần `skill_reference_get({ refs: [...] })` file nào — **đừng dựa vào trí nhớ, hãy load đúng file**.
+
+> Cách dùng: `skill_reference_get({ refs: ["references/<tên-file>.md"] })`. Có thể load nhiều file một lần.
+
+---
+
+## Luôn có sẵn (Tier A — đã nạp cùng skill_get)
+
+| File | Nội dung |
+|---|---|
+| `controls-patterns.md` | Action engine (**§QUY TẮC NỀN: một `{}` = một lệnh; nhiều lệnh tuần tự = mảng `[{…},{…}]`**), value resolution, key notation, layout grid — **nền tảng** |
+| `module-structure.md` | Cấu trúc file module/project, layout rules |
+| `INDEX.md` | (file này) — bản đồ router |
+
+---
+
+## Hiểu nền tảng / cấu tạo FUI (đọc sớm)
+
+| Tình huống | Load file |
+|---|---|
+| Cấu tạo FUI, phân cấp Project→Module (import/component/set trộn thế nào), runtime, vueData/v_Set | `platform-architecture.md` |
+| 4 thành phần module.json (data/watch/controls/set) — vai trò, cấu hình, tương tác | `module-json-anatomy.md` |
+| **`HTMLOnly: true`** — server KHÔNG nhúng sẵn thư viện nào (Vue/Vuetify/jQuery/lodash/MDI/`projectdefaultstyle.css` đều vắng); cần gì phải tự khai trong chính module, và `script-map.md` KHÔNG áp dụng | `module-structure.md` §HTMLOnly=true: KHÔNG có thư viện nào được nhúng sẵn (Tier A, đã nạp sẵn) |
+
+## Thiết kế UI / chọn component
+
+| Tình huống | Load file |
+|---|---|
+| **Layout controls — class/prop/style ĐƯỢC DÙNG (đừng tự thêm style)** | `controls-styling-vocabulary.md` |
+| Bắt đầu thiết kế UI, chọn component nào | `component-quickref.md` |
+| Khai báo `data[]` — ba loại phần tử, thứ tự state → named action → auto-startup | `module-data-patterns.md` (value resolution + key lồng nhau: `controls-patterns.md` §0/§1, Tier A) |
+| Pattern UI thực tế (data/watch/toolbar/filter/permission) | `ui-patterns.md` |
+| **Hàng nhiều control / canh phải nhóm nút** — chuẩn `shrink` cho mọi cột trừ `v-spacer`; `w` px | `controls-patterns.md` (Tier A, đã nạp sẵn) |
+| **f-table** — **hiển thị dữ liệu dạng datatable** (list/CRUD qua form dialog, cả readonly lẫn có `:update-api`) + điều khiển trong ô: t-check/t-button/t-select/t-menu, ctrl-update, show-select, chip-group | `ui-table-cell-patterns.md` |
+| Bảng dữ liệu chuyên sâu (mọi props, header types, auto-headers khi bỏ `:headers`, **tổng cột `sum-format`** — object=hàng tổng trong bảng / string=dòng text dưới bảng, readonly table) | `component-table.md` |
+| **f-sheet** — **nhập liệu trực tiếp trên bảng kiểu Excel** (sửa ô tại chỗ, dán từ Excel, không qua dialog) — component có sẵn (nền tảng AG Grid), KHÔNG tự viết bảng nhập liệu bằng `uc-*.vue`; import, props, columns, wiring API | `fsheet.md` |
+| Dialog / form popup (hidden-container, mở dialog với row, checkbox-list) | `ui-dialog-patterns.md` |
+| Mở sub-window & trao đổi dữ liệu (`openWindow`, `#PARENT`/`#Win`) | `ui-crosswindow-patterns.md` |
+| Layout: page-container, master-detail, v-switch, date init, dynamic label | `ui-layout-patterns.md` |
+| Input controls (f-date, f-time, f-search, f-radiobox, text-field...) | `components-input.md` |
+| Display components (f-label, f-title, f-box, f-header, chip, badge...) | `components-display.md` |
+| Dialog components (f-dialog, v-dialog chi tiết) | `components-dialog.md` |
+| Custom Vue component (`uc-*.vue`) — scope, props/events, **ưu tiên class Vuetify có sẵn (cấm _injectStyle)**, dialog chuẩn hoá, tận dụng ajaxCALL/confirm/showMessage | `component-design.md` |
+| **Kiểm chứng `uc-*.vue` trong không gian riêng** (`component_preview`) + luật push component cấp project trước khi render module | `component-design.md` |
+| **Tra component project-scope đã có** trước khi tạo mới — quy ước `{projectId}/COMPONENTS.md` + vòng tích luỹ | `component-design.md` §1a |
+| Template/ví dụ tham chiếu nhanh | `ui-templates.md` + `examples/` |
+| **User gửi ảnh chụp màn hình giao diện** vào chat, hoặc đọc screenshot từ `renderUI` — đánh giá lỗi hiển thị, màu sắc, padding/margin, căn chỉnh, vị trí nút | `ui-screenshot-review.md` |
+
+## Biểu đồ / báo cáo / dashboard
+
+| Tình huống | Load file |
+|---|---|
+| Dùng f-echart (nền tảng Apache ECharts) — import, props, config, theme, DataView, `grid` padding, `boundaryGap`, lỗi | `components-echart.md` |
+| Chọn/vẽ loại chart cụ thể + pattern module.json | `echart-templates.md` |
+| Xuất PDF (f-pdfmake) | `pdfmake.md` |
+
+## API / Stored Procedure / tAPI
+
+| Tình huống | Load file |
+|---|---|
+| Đặt tên SP, params, URL, response format, error, wiring | `tapi-reference.md` |
+| **API trả 200 nhưng dữ liệu rỗng/sai**, hoặc sắp đổi/xoá tham số của một SP đã có module gọi — ghép tham số tAPI khoan dung (thiếu → `NULL`, thừa → bỏ qua, **không bao giờ báo lỗi**) | `tapi-reference.md` §2 |
+| **Đọc HTTP header trong SP** (`User-Agent`, `Cookie`, `X-Forwarded-For`, IP client, thiết bị/trình duyệt) — họ `@sys_header_*`, mỗi dấu `-` đổi thành `_` | `tapi-reference.md` §2 |
+| Kiểm tra quyền trong SP (5 pattern, `@sys_SystemRight`, `getSystemRight`) | `tapi-permission-patterns.md` |
+| Upload/download/xem file qua SP (`spAPIFILE_`, `fileContent`, `tblFileData`) | `tapi-file-api.md` |
+| Hàm SQL CLR: httpCall, sendMail, ImageResize, FileReader, RegexMatch... | `sql-clr-functions.md` |
+
+## Phân quyền người dùng
+
+| Tình huống | Load file |
+|---|---|
+| Khái niệm `SystemRight` (cấp bậc) vs `FunctionRight` (quyền theo chức năng), `v-if`/menu `right`, và 8 tool quản lý định nghĩa quyền (`right_system_list/new/update/delete`, `right_function_list/new/update/delete`) | `permission-system.md` |
+| **Sắp gác một control/menu/SP bằng mã quyền** — mã đó có tồn tại thật không, tạo thế nào | `permission-system.md` (§"mã quyền phải TỒN TẠI trước khi đem gác") |
+| Kiểm tra quyền trong thân SP (5 pattern SQL) | `tapi-permission-patterns.md` |
+
+## Database
+
+| Tình huống | Load file |
+|---|---|
+| **Database CHƯA tồn tại** — tạo DB SQL Server mới, hai loại tài khoản SQL, đăng ký alias tAPI vào `acc` | `project-provisioning.md` |
+| **Sắp chạy `CREATE DATABASE` / `CREATE LOGIN`** — kiểm quyền cấp máy chủ trước (`sysadmin`, hoặc `CREATE ANY DATABASE` + `ALTER ANY LOGIN`); thiếu quyền thì từ chối chứ đừng chạy thử | `project-provisioning.md` §Bước 0 |
+| Kết nối DB, dbToken, schema, workflow SP | `db-workflow.md` |
+| **Project gọi nhiều database** (module.json có `"API": "/{alias}/…"` với nhiều alias khác nhau) — mỗi alias một `db_connect`, tham số `db` chọn kết nối, tool trả MENU khi nhập nhằng | `db-workflow.md` (§1, §4) |
+| **SSO xuyên domain** — userToken cùng domain cha dùng được ngay, không cần hỏi lại hay xác minh | `db-workflow.md` §6a |
+| **Linked Server** — SP qua ranh giới linked server, quy ước đặt tên `spIO_IN_` / `spIO_OUT_` | `db-workflow.md` §8a |
+| Quy tắc thiết kế bảng (đặt tên, PK/FK, cột audit) | `db-table-design.md` |
+
+## Quy trình / thiết kế hệ thống
+
+| Tình huống | Load file |
+|---|---|
+| **"Tạo dự án mới" / "tạo DB + project FUI mới"** — dựng hạ tầng từ số 0: CREATE DATABASE, tài khoản ứng dụng vs dev, alias `acc`, `project_new`, cấp quyền quản trị. Làm TRƯỚC `system-design.md` | `project-provisioning.md` |
+| **Cấp/thu hồi quyền SỬA PROJECT trong IDE FUI** cho một lập trình viên (`UserRight`, 5 tool `project_user_*`) — khác hẳn quyền người dùng cuối ở `permission-system.md` | `project-provisioning.md` (§Bước 6) |
+| **Thiết kế cả app nhiều module từ mô tả** (phân rã, schema-first, menu, quyền) | `system-design.md` |
+| Tạo một module fullstack (UI + API) — quy trình 6 bước UI-first | `fullstack-workflow.md` |
+| Cấu hình project.json: menu, điều hướng, phân quyền, domain | `project-config.md` |
+
+## Scripting / kỹ thuật nâng cao
+
+| Tình huống | Load file |
+|---|---|
+| **Cần chạy nhiều lệnh có thứ tự** (reset state → reload → báo toast) trong `CALLBACK`/`:action`/`watch`/`THEN` | `controls-patterns.md` §QUY TẮC NỀN (Tier A, đã nạp sẵn) |
+| Watcher patterns (v_old, deep-watch, cascading) | `watcher-patterns.md` |
+| Kỹ thuật nâng cao (EXE, MAP, expression phức tạp) | `advanced-techniques.md` |
+| **Trang trắng / app rỗng dù 0 JS error, 0 Vue warn**, hoặc cần đặt logic phức tạp vào `:attr` `:option` `:config` | `advanced-techniques.md` §1 + chạy `module_validate` |
+| **`… is not defined` lúc render**, hoặc một `EXE`/`FUN` "chạy xong mà không làm gì" | `advanced-techniques.md` §2 (hàm phải có thật trong `script.js` — nhớ `module_publish_script`). ⚠️ `module_validate` KHÔNG bắt được ca này, phải `module_simulate({renderUI:true})` |
+| Hàm tiện ích FUI có sẵn (openWindow, ajaxCALL, jsonToExcel, groupBy...) | `default-function.md` |
+| **Thư viện đã bundled sẵn** (jQuery, lodash, moment, numeral, toast, jquery-confirm) — biết trước khi định thêm CDN. ⚠️ Chỉ đúng với `HTMLOnly=false` | `script-map.md` §0 |
+| Bản đồ script FUI (defaultfunction.js, component.js...) | `script-map.md` |
+| FUI project bootstrapper (fastproject) | `fastproject.md` |
+| Coding standards | `coding-standards.md` |
+| Real-time / SignalR (webSocketJoinGroup, webSocket_Send) | `websocket-realtime.md` |
+
+## Vận hành / publish / deploy
+
+| Tình huống | Load file |
+|---|---|
+| **"new session" / "phiên mới" / "cửa sổ mới"** — mở thêm một phiên Claude Code CLI ở cửa sổ terminal riêng (lấy workspace root động, KHÔNG hard-code đường dẫn) | `new-session.md` |
+| Mức độ an toàn của từng MCP tool (R/M, Safe/Confirm/Destructive), strict mode, `db_sp_verify`, error log | `tools-registry.md` |
+| Checklist definition-of-done trước khi publish (kèm bước `module_validate` + `module_outline` + `module_simulate` + `db_sp_verify` tĩnh) | `verification.md` |
+| **UI hỏng mà chưa biết vì sao — chọn tầng kiểm chứng nào cho rẻ nhất** (ma trận triệu chứng → tầng; đọc TRƯỚC khi chạy `renderUI`, và đọc lại khi đã render ≥2 lượt mà chưa khá hơn) | `verification.md` §Chọn tầng kiểm chứng |
+
+---
+
+## Design system
+
+**Hai chế độ tách bạch — xác định TRƯỚC khi viết controls. Chủ sở hữu: `design-modes.md`.**
+
+| Chế độ | Khi nào | Nguồn thẩm mỹ |
+|---|---|---|
+| **App-mode** (mặc định) | Phần mềm quản lý: CRUD, form, danh sách, dashboard nội bộ | **DUY NHẤT** `design_read("fui")` + `controls-styling-vocabulary.md` — CẤM brand DESIGN.md, CẤM style tự chế |
+| **Web-mode** | Landing page / trang giới thiệu / công khai (thường `HTMLOnly: true`) | `design_list` → `design_read("<brand>")` theo tone/ngành; CSS tự do trong header.html |
+
+| Tình huống | Load file |
+|---|---|
+| Chọn App-mode hay Web-mode, giới hạn `border-radius`, vòng tích luỹ `{projectId}/DESIGN.md` | `design-modes.md` |
+| Anatomy dialog/form/bảng màu chuẩn App-mode | tool `design_read("fui")` (không qua `skill_reference_get`) |
+
+- `{projectId}/DESIGN.md` (nếu có) **ghi đè** quy tắc cùng chủ đề của chế độ đang dùng — kiểm tra trước khi thiết kế.
+- User góp ý UI → ghi quy tắc vào `{projectId}/DESIGN.md` (vòng tích luỹ — `design-modes.md` §3).

package/skills/fui-skill/references/advanced-techniques.md

@@ -0,0 +1,160 @@
+# Advanced FUI Techniques
+
+> File này sở hữu: **kỹ thuật nâng cao: `EXE`, `MAP`, expression phức tạp, luật expression thuần cho `:attr`, luật hàm gọi trong `EXE`/`FUN` phải tồn tại thật**. Action engine cơ bản xem [controls-patterns.md](controls-patterns.md).
+
+This document captures advanced patterns and techniques for FUI development, extracted from real-world implementations.
+
+---
+
+## 1. `:attr` CHỈ NHẬN EXPRESSION THUẦN — không bao giờ nhét statement
+
+**Luật cứng.** Mọi giá trị binding trong `module.json` — `:option`, `:config`, `:items`, `:headers`, `:style`, và mọi `v-bind:*` — đi **thẳng vào template compiler của Vue**, nơi chỉ chấp nhận **một biểu thức**. Tuyệt đối không được chứa:
+
+- `function(){ ... }` hay IIFE `(function(){...})()`
+- `return`
+- `var` / `let` / `const`
+- dấu `;` nối nhiều câu lệnh
+
+### Vì sao nghiêm trọng hơn vẻ ngoài của nó
+
+Statement trong `:attr` làm **compile template hỏng**, và Vue **nuốt lỗi đó**: kết quả là **trang trắng với 0 JS error, 0 `[Vue warn]`**. Không có stack trace, không có dòng nào để lần — chỉ mò ra được sau nhiều vòng `module_simulate({renderUI:true})`. Đây là lý do nó là **error** trong `module_validate` chứ không phải warning.
+
+> Khác hẳn `data[]` / `IN` / `{{ }}`: những chỗ đó đi qua `getVueData()` của FUI (xem [controls-patterns.md](controls-patterns.md) §0 Value Resolution) và có luật riêng. `:attr` **không** đi qua đó.
+
+### Được phép trong `:attr`
+
+| Dạng | Ví dụ |
+|---|---|
+| Object / array literal | `":config": "{ height: 300, legend: { show: true } }"` |
+| Ternary | `":color": "ok ? 'primary' : 'warning'"` |
+| Chuỗi arrow `.map` / `.filter` | `":items": "ds.filter(x => x.Active).map(x => x.Name)"` |
+| Truy cập thuộc tính / biến vueData | `":option": "optThe"` |
+
+### Logic phức tạp → chuyển sang `script.js` + `EXE`
+
+Nhiều bước biến đổi, biến trung gian, vòng lặp, điều kiện phức tạp → **đừng đặt trong `:attr`**. Bốn bước:
+
+1. Viết một hàm thường trong `script.js`: `function tenHam(){ ... }`
+2. Hàm **gán thẳng vào `vueData.xxx`** (không `return` giá trị cho JSON đọc)
+3. Gọi hàm qua `EXE` — thường trong `CALLBACK` của action nạp dữ liệu: `"EXE": "tenHam()"`
+4. `:attr` trong `module.json` chỉ trỏ tới biến đó: `":option": "optThe"`
+
+❌ **Sai** — IIFE trong `:attr`:
+```json
+":option": "(function(){ var src = vueData.ds.filter(r => r.id===1); return { series:[{data: src}] }; })();"
+```
+
+✅ **Đúng**:
+```javascript
+// script.js
+function buildChart() {
+    var src = vueData.ds.filter(function (r) { return r.id === 1; });
+    vueData.optThe = { series: [{ data: src }] };
+}
+```
+```json
+// module.json — action nạp dữ liệu
+"CALLBACK": { "EXE": "buildChart()" },
+// module.json — control
+":option": "optThe"
+```
+
+`:option` khai báo trong `data[]` là `{}` để lần render đầu không vỡ; `buildChart()` gán bản thật sau khi API trả về.
+
+### Chẩn đoán trang trắng khi "0 JS error, 0 Vue warn"
+
+Triệu chứng đó **không phải lỗi runtime** — nghi **compile template trong `:attr`** trước tiên, đừng đi tìm trong `script.js` hay action engine.
+
+Cách khoanh vùng nhanh: tạm thay biểu thức nghi ngờ bằng một giá trị tĩnh đơn giản (`":option": "{}"` hoặc bỏ hẳn attr đó) rồi render lại. **Trang hiện lại ⇒ chính biểu thức đó là thủ phạm.** Lặp lại cho từng `:attr` khả nghi cho tới khi khoanh đúng một cái.
+
+Chạy `module_validate` trước khi render sẽ bắt được hầu hết các ca này ở dạng error, không cần mò.
+
+---
+
+## 2. Hàm gọi trong `EXE` / `FUN` phải TỒN TẠI THẬT trong `script.js`
+
+**Luật cứng.** `"EXE": "buildChart()"` và `"FUN": "buildChart"` chỉ chạy được nếu `buildChart` là một hàm **toàn cục có thật** lúc runtime — nghĩa là khai trong `{moduleDir}/script.js`, trong một file import `.js`, hoặc là hàm sẵn có của nền tảng ([default-function.md](default-function.md), [script-map.md](script-map.md)).
+
+Đây là mặt kia của §1: §1 bảo *"logic phức tạp thì đẩy sang `script.js` rồi gọi qua `EXE`"* — và bước đẩy đó **rất hay bị quên nửa sau**. Module.json được sửa, `EXE` được viết, `module_publish_json` chạy xong; `script.js` thì không ai viết và `module_publish_script` không ai gọi.
+
+### Vì sao không có gì báo cho bạn biết
+
+Hai lệnh, hai kiểu hỏng, **cả hai đều không nói tên hàm ở chỗ dễ thấy**:
+
+| Lệnh | Cơ chế | Biểu hiện khi hàm thiếu |
+|---|---|---|
+| `EXE` | Chạy qua `templateCompiled(\`<% … %>\`)` — tức lodash `_.template`. Do lỗi toán tử phẩy ở `fastproject-3.0.js:490`, **object dữ liệu không bao giờ được truyền vào**, nên định danh trần trong chuỗi EXE phân giải thẳng vào **global** | `ReferenceError: buildChart is not defined` — chỉ lộ ra ở `module_simulate({renderUI:true})`, và ở đó nó chỉ là **"1 JS error"** trong một report dài |
+| `FUN` | `runFunction()` tra `window[obj.FUN]`, không thấy thì `console.log("Func:", …, "not found")` rồi **đi tiếp** | **Hỏng hoàn toàn im lặng.** Không error, không `[Vue warn]`, action vẫn "chạy xong" — chỉ là không làm gì cả |
+
+Giá thật đã đo trong log: một module tốn **36 lượt `renderUI` liên tiếp trong 5 ngày** vì đúng lớp lỗi này (`buildKPI8Columns is not defined`).
+
+### Tầng bắt được: **`module_simulate({ renderUI: true })`** — và chỉ tầng đó
+
+`module_validate` **KHÔNG** kiểm việc này: nó không đọc `script.js`. (Đã từng có một luật tĩnh làm việc đó, đã gỡ — để không báo oan, luật phải biết trước **mọi** hàm toàn cục của nền tảng, và danh sách đó không bao giờ nuôi đủ; mỗi tên bỏ sót là một lần chặn publish một module chạy được.) `module_simulate` ở chế độ vm cũng không phải tầng bắt được — nó không nạp `script.js` vào sandbox nên báo ReferenceError cho **mọi** module dùng hàm `script.js`, kể cả module đúng.
+
+Nên đường kiểm chứng là **renderUI**: trình duyệt thật ném `ReferenceError: buildChart is not defined`, và từ nay **mọi JS error đều làm tool trả `isError`** (không riêng lỗi lúc init — lỗi phát sinh khi bấm nút cũng tính). Câu lỗi nằm trong khối `═══ CHẨN ĐOÁN ═══` ở **đầu** report, dòng `[MODULE]`.
+
+⚠️ **Vế `FUN` thì renderUI cũng không bắt được** — `runFunction` không thấy hàm thì `console.log` rồi đi tiếp, không ném gì cả. Với `FUN` phải **tự soát tên hàm** đối chiếu `script.js`; triệu chứng duy nhất là "action chạy xong mà không có gì xảy ra".
+
+### Cách sửa
+
+1. Viết hàm trong `script.js`: `function buildChart(){ … vueData.optThe = …; }`
+2. **`module_publish_script`** — bước hay bị quên nhất. `module_publish_json` **không** đẩy `script.js`.
+3. Gõ nhầm tên thì sửa tên, đừng thêm hàm rỗng cho hết lỗi.
+
+---
+
+## 3. Advanced Logic & Scripting
+
+FUI's JSON-based logic has limitations. Use `script.js` for complex operations.
+
+### Computed Properties Workaround
+FUI `module.json` does not natively support computed properties. 
+**Solution:** Define calculation functions in `script.js` and call them directly in `module.json`.
+
+**script.js**:
+```javascript
+function getTongTien() {
+    return vueData.items.reduce((sum, item) => sum + (item.amount || 0), 0);
+}
+```
+
+**module.json**:
+```json
+{
+  "innerHTML": "Total: {{getTongTien().toLocaleString()}} VNĐ"
+}
+```
+
+### Complex Validation
+Avoid writing long logic strings in JSON. Move validation logic to `script.js`.
+
+**script.js**:
+```javascript
+function validateStep1() {
+    const d = vueData;
+    if (!d.name || !d.email) {
+        alert("Missing required fields!");
+        return false;
+    }
+    return true;
+}
+
+function nextStep() {
+    if (vueData.step === 1 && !validateStep1()) return;
+    vueData.step++;
+}
+```
+
+**module.json**:
+```json
+"v-on:click": "nextStep()"
+```
+
+### Action Binding
+You can bind direct JS functions to events instead of using the `CALL` action protocol if needed for simple UI logic.
+
+```json
+"v-on:click": "prevBuoc()"
+```
+