@fui-org/fui-cli 0.2.0 → 0.4.0

package/skills/fui-skill/references/coding-standards.md

@@ -0,0 +1,112 @@
+# FUI Coding Standards
+
+> File này sở hữu: **chuẩn code chung: đặt tên, quy ước `<style scoped>` trong `.vue` (scope thủ công), cấm backtick trong `<template>`, reusable API**. Quy tắc thiết kế component chi tiết xem [component-design.md](component-design.md).
+
+## 1. Naming Conventions
+
+### Components (`components/`)
+-   **Prefix**: Use `uc-` (User Component) for custom module components to distinguish from standard FUI components (`f-`, `t-`).
+-   **Format**: Kebab-case (e.g., `uc-trangthai-sukien.vue`, `uc-user-profile.vue`).
+-   **Props**: Use camelCase in script, kebab-case in templates (e.g., `userProfile` -> `:user-profile`).
+-   **Prefer reusable APIs**: Default to generic props, emits, and slots so the component can be reused across modules or screens.
+-   **Avoid overfitting names**: Prefer neutral contracts like `items`, `value`, `label`, `loading`, `readonly`, `disabled`, `options`, `config` unless the business domain truly requires a specific prop name.
+-   **Push orchestration upward**: Keep API calls, route changes, and page-specific coordination in `module.json` or the parent when possible. Let the component focus on presentation and local interaction.
+-   **Emit upward**: Prefer `$emit(...)` for `input`, `change`, `select`, `submit`, `remove`, or explicit action events rather than mutating parent-owned state.
+
+### CSS Classes
+-   **`<style scoped>` in `.vue` is allowed** (saved server-side as `ComCSS`), but `scoped` has **no real scoping effect** — FUI only concatenates `ComCSS` from every component in the module into one global stylesheet (`ComponentCSSBuild()`), no AST transform, no `data-v-xxxx` attribute injection. **Every selector must be manually scoped**: give the component's root template element a unique class matching the component name (kebab-case, e.g. `uc-invoice-list`), then write every rule as a descendant selector starting from that class (`.uc-invoice-list__title`, never a bare `.title`). See [component-design.md](component-design.md) for a full example.
+-   **Style Placement**: Component-local CSS → `<style scoped>` in the `.vue` file (with manual scoping above). Module-wide CSS → `style.css` (publish via `module_publish_css`). `header.html` is still valid for CSS but no longer the only option.
+-   **Vuetify Utilities**: Prioritize Vuetify helper classes (e.g., `ma-2`, `pa-0`, `d-flex`, `primary--text`).
+-   **Custom Classes**: Use meaningful prefixed names (e.g., `ep-hero`, `ep-field-grid`). Avoid generic names like `.box` or `.red`.
+-   **State Classes**: Use descriptive names for state (e.g., `.is-active`, `.has-error`).
+
+### Action Keys (`module.json`)
+-   **API Actions**: Predix with `api` (e.g., `apiGetDSSuKien`, `apiUpdateUser`).
+-   **Event Handlers**: Prefix with `handle` (e.g., `handleOpenReport`, `handleSubmit`).
+-   **Dialog Actions**: Prefix with verb (e.g., `openUploadDialog`, `closeSettings`).
+
+## 2. Menu Configuration (`set.menu`)
+
+Define the application menu in the `set` object of `module.json`.
+
+```json
+"menu": [
+  {
+    "name": "Main Group",
+    "icon": "mdi-home",    // Material Design Icons
+    "url": "/dashboard",   // Route
+    "right": {             // Permission check
+      "SystemRight": [1, 2] // Array of allowed Right IDs
+    }
+  },
+  {
+    "name": "Management",
+    "icon": "mdi-cog",
+    "submenu": [           // Nested menu items
+      {
+        "name": "Users",
+        "url": "/users"
+      },
+      {
+        "name": "Settings",
+        "url": "/settings"
+      }
+    ]
+  }
+]
+```
+
+## 3. Project Structure
+
+-   **Canonical module structure**: Follow [module-structure.md](module-structure.md) as the default module layout in both workspace and chat contexts. In workspace-aware environments, apply it to real local files. In chat contexts, use it to virtualize the same module structure in the response.
+-   **Required core files**: Keep `_info.json` and `module.json` at module root.
+-   **`components/`**: Only place `.vue` files here. Do not sub-folder unless strictly necessary (FUI auto-scans this root).
+-   **`components/_components.json`**: Maintain component registry when using `uc-*` components.
+-   **`header.html`**: Still valid for CSS, but component CSS should prefer `<style scoped>` in the `.vue` (manually scoped) and module-wide CSS should prefer `style.css`.
+-   **`module.json`**: Keep this file clean. Move large static lists to the database or separate JSON files if supported.
+
+## 4. Best Practices
+
+-   **Data Binding**: Avoid complex logic in JSON attributes. Use computed properties in components or simpler `vueData` structures.
+-   **Event Handling**: Use `CALL(vueData.actionName)` for all complex interactions. Avoid inline JS like `vueData.count++` for anything beyond simple toggles.
+-   **Mobile Responsiveness**: Always configure `configForm.xs` and `configForm.md` for responsive form widths.
+
+## 5. Component Registration (`_components.json`)
+
+Components are registered using an **upsert pattern**:
+
+-   **New component** (before publish): Only `comName` is required. Do NOT manually assign `comID`.
+    ```json
+    [
+      { "comName": "hr-employee-profile" }
+    ]
+    ```
+-   **After publish & sync**: The server auto-assigns `comID`. The file gets updated on sync:
+    ```json
+    [
+      { "comID": 7813, "comName": "hr-employee-profile" }
+    ]
+    ```
+
+> **Rule**: Never manually create or modify `comID`. It is server-generated.
+
+## 6. Vue Component Design
+
+Xem toàn bộ quy tắc thiết kế `uc-*.vue` component tại [component-design.md](component-design.md), bao gồm:
+- Không dùng `components: {}` để đăng ký
+- `<style scoped>` trong file `.vue` phải tự scope thủ công (xem mục CSS Classes ở trên)
+- Không dùng backtick trong `<template>`
+- Không dùng `v-dialog` — dùng cấu trúc `v-overlay` thay thế
+- Cấu trúc bắt buộc cho dialog component
+
+## 7. Complex Module Architecture
+
+When a module's `module.json` controls exceed ~200 lines:
+
+-   **Extract to Vue component**: Move the UI into a `.vue` component. Keep `module.json` lean (data/API only + a single component call in `controls`).
+-   **Props binding**: Pass all data from `module.json` via props. Use kebab-case for prop names in templates (`:nhan-vien="nhanVien"`).
+-   **Design for reuse first**: Before naming props or methods, check whether the component can be expressed as a generic list, card, dialog body, filter panel, summary block, or form section reused by other modules.
+-   **Configurable states**: Expose loading, empty, disabled, and readonly behavior through props or slots instead of hardcoding one workflow.
+-   **Sticky headers**: When combining multiple sticky elements (e.g., hero + tabs), wrap them in **one parent div** with `position: sticky` instead of making each element sticky individually.
+-   **Tab navigation vs Accordion**: For 5+ sections of data, prefer horizontal `v-tabs` over `v-expansion-panels`. Tabs show one section at a time, reduce cognitive overload, and support swipe gestures on mobile.
+-   **Swipe gestures**: Attach `touchstart`/`touchend` listeners on the **outermost wrapper** (not on content area) so swipe works regardless of content height.

package/skills/fui-skill/references/component-design.md

@@ -0,0 +1,455 @@
+# FUI Vue Component Design Rules
+
+> File này sở hữu: **quy tắc viết `uc-*.vue`: scope module/project, cấm `name:`/`components:{}`, props/emits/slots, cấm `_injectStyle`, quy tắc scope thủ công cho `<style scoped>`, quy trình kiểm chứng component (`component_preview` + luật push component cấp project trước khi render module), và quy ước `{projectId}/COMPONENTS.md` (tra component project-scope đã có + vòng tích luỹ)**. Bộ class/prop được duyệt xem [controls-styling-vocabulary.md](controls-styling-vocabulary.md).
+
+Quy tắc bắt buộc khi viết bất kỳ Vue component nào (`uc-*.vue`) trong hệ thống FUI. Áp dụng cho cả component thông thường lẫn dialog component.
+
+---
+
+## 1. Hai cấp component: module-scope vs project-scope
+
+| | Module-scope | Project-scope (global) |
+|---|---|---|
+| **Vị trí file** | `{projectId}/modules/{moduleId}/components/uc-*.vue` | `{projectId}/components/uc-*.vue` |
+| **Registry** | `modules/{moduleId}/components/_components.json` | `{projectId}/components/_components.json` |
+| **Phạm vi** | Chỉ trong module đó | **Tất cả modules trong project** |
+| **Auto-load** | Trong module đã có component | Tự động — **không cần khai báo gì thêm** |
+| **Khi nào dùng** | Component chỉ dùng ở một module | Component dùng lại ở nhiều module |
+
+> **Project-scope component được FUI tự động load ở cấp global** — bất kỳ module nào trong project đều dùng được `<uc-*>` ngay, không cần tạo lại hay khai báo thêm.
+
+### Quy tắc chọn scope
+
+```
+Component này sẽ dùng ở nhiều module? → project-scope
+Component chỉ dùng trong một module?   → module-scope
+```
+
+### Bảng thao tác theo scope
+
+| Thao tác | Module-scope | Project-scope (global) |
+|---|---|---|
+| **Tạo mới** (chưa có trên server) | `component_new(componentName)` — dùng session.moduleId | `component_new(componentName, projectId=<pid>)` — KHÔNG có moduleId |
+| **Cập nhật** (đã có trên server) | `component_update(componentName)` — dùng session.moduleId | `component_update(componentName, projectId=<pid>)` — KHÔNG có moduleId |
+| **Xóa** | `component_delete(componentName)` — dùng session.moduleId | `component_delete(componentName, projectId=<pid>)` — KHÔNG có moduleId |
+| **Đọc source** | `component_get(projectId, moduleId, componentName)` | `component_get(projectId, componentName)` — bỏ moduleId |
+| **Sync danh sách** | `component_list(projectId, moduleId)` | `component_list(projectId)` — bỏ moduleId |
+| **File trong workspace** | `{moduleDir}/components/uc-foo.vue` | `{projectDir}/components/uc-foo.vue` |
+
+**Quy tắc duy nhất:** `moduleId` có → module-scope · `moduleId` vắng, chỉ `projectId` → project-scope
+
+**Tạo và cập nhật là HAI tool riêng — không có upsert ngầm.** Cả hai đọc file `.vue` **local** (file phải tồn tại sẵn trên đĩa) và tự suy `ComID` từ `_components.json`, không truyền tay:
+
+- `component_new` — chỉ INSERT. Làm mới `_components.json` **từ server trước** rồi mới kiểm tra tên; trùng tên = **lỗi cứng**. (Cache cũ mà cứ INSERT thì server sinh **hai record cùng tên**, không sửa được từ MCP.) Sau khi tạo tự sync lại để lấy `ComID` thật.
+- `component_update` — chỉ UPDATE. Không tra được `ComID` = **lỗi cứng**, không âm thầm tạo mới: hoặc component chưa từng được tạo (→ `component_new`), hoặc cache local cũ (→ `component_list` rồi thử lại).
+
+**`component_delete` tự lookup ComID** từ `_components.json` local. Nếu danh sách lệch, chạy `component_list` trước.
+
+**`module_publish_html` không bao gồm project-scope component** — nếu có thay đổi component global, phải gọi `component_new`/`component_update` riêng trước hoặc sau.
+
+---
+
+## 1a. Tra cứu component project-scope đã có — `{projectId}/COMPONENTS.md`
+
+Trước khi thiết kế một component cấp project mới, **phải kiểm tra `{projectId}/COMPONENTS.md`** (nếu có) — file này liệt kê các `uc-*.vue` cấp project đã tồn tại, kèm tóm tắt mục đích và props chính. Dựng lại component đã có chỉ gây trùng lặp và khó bảo trì.
+
+```
+{FUI_MCP_WORKDIR}/{projectId}/COMPONENTS.md    ← kiểm tra TRƯỚC khi tạo component project-scope mới
+```
+
+**Vòng tích luỹ:** sau khi tạo/cập nhật một component cấp project có ý định dùng lại ở nhiều module, nối thêm một mục vào `{projectId}/COMPONENTS.md`. Chưa có file thì tạo mới theo khuôn:
+
+```markdown
+# {projectId} — Danh sách component project-scope
+
+## uc-ten-component
+
+**Mục đích:** mô tả ngắn gọn component dùng để làm gì  
+**Props:** `propA` (kiểu, mặc định) · `propB` (kiểu, mặc định)  
+**Events:** `@eventName` — khi nào phát  
+**Ghi chú:** điều gì cần biết khi dùng (nếu có)
+```
+
+> Khuôn này theo đúng `{projectId}/DESIGN.md` (vòng tích luỹ quy tắc thẩm mỹ — xem [design-modes.md](design-modes.md) §2-3). File `COMPONENTS.md` **không bao giờ tự xoá mục** — xoá khi đã dùng `component_delete` bỏ component đó khỏi server.
+
+---
+
+## 2. Đặt tên và cấu trúc file
+
+- **Prefix bắt buộc**: `uc-` (User Component) — phân biệt với `f-*` (FUI runtime) và `v-*` (Vuetify)
+- **Format**: kebab-case — ví dụ `uc-trangthai-sukien.vue`, `uc-user-profile.vue`
+- **Vị trí**: chỉ đặt trong `components/` ở root module hoặc root project, không tạo subfolder
+- **Registry**: khai báo trong `components/_components.json` (chỉ cần `comName`, không tự đặt `comID`)
+
+---
+
+## 3. Đăng ký component — KHÔNG dùng `components: {}`, KHÔNG dùng `name:`
+
+FUI tự động scan và đăng ký toàn bộ `uc-*.vue` ở cấp **global**. Tuyệt đối không khai báo `components: { ... }` bên trong một component — nó không hoạt động trong môi trường FUI.
+
+Không khai báo thuộc tính `name:` trong `export default` — FUI tự xử lý tên component từ tên file khi tạo script, khai báo thêm là thừa và có thể gây xung đột:
+
+```js
+// ❌ SAI — không cần và có thể gây xung đột
+export default {
+  name: 'uc-user-card',
+  props: { ... }
+}
+
+// ✅ ĐÚNG — bỏ name, FUI tự resolve từ tên file
+export default {
+  props: { ... }
+}
+```
+
+```js
+// ❌ SAI — không dùng trong FUI
+export default {
+  components: { 'uc-user-card': UcUserCard },
+}
+
+// ✅ ĐÚNG — dùng trực tiếp tag trong template
+// <uc-user-card :data="data" />
+```
+
+---
+
+## 4. Props
+
+- Khai báo trong `script`: camelCase (`userName`, `itemList`)
+- Dùng trong `template`: kebab-case (`:user-name="userName"`)
+- Default của Array/Object phải dùng `function()`, không dùng arrow function:
+
+```js
+// ❌ SAI
+props: { items: { default: () => [] } }
+
+// ✅ ĐÚNG
+props: { items: { default: function() { return [] } } }
+```
+
+- Ưu tiên tên props trung lập và tái sử dụng được: `items`, `value`, `label`, `loading`, `readonly`, `disabled`, `options`, `config`
+- Không đặt tên props gắn chặt với một màn hình cụ thể nếu component có thể dùng lại
+
+---
+
+## 5. Emits
+
+- Luôn emit lên parent thay vì mutate trực tiếp state của parent
+- Các event chuẩn: `input`, `change`, `select`, `submit`, `remove`, `action`
+- Dialog component luôn emit `('input', false)` để đóng — tương thích với `v-model` Vue 2
+
+---
+
+## 6. Template syntax — các ràng buộc bắt buộc
+
+### Không dùng backtick trong `<template>`
+
+Template strings (backtick) không hoạt động đúng trong Vue 2 template. Dùng string concatenation:
+
+```html
+<!-- ❌ SAI -->
+:label="`Total (${items.length})`"
+
+<!-- ✅ ĐÚNG -->
+:label="'Total (' + items.length + ')'"
+```
+
+### Không dùng `@` shorthand cho events trong JSON
+
+Trong `module.json` luôn dùng `v-on:click`, không dùng `@click`. Trong `.vue` template thì `@click` vẫn hợp lệ.
+
+### Vue 2 yêu cầu một root element duy nhất
+
+```html
+<!-- ✅ ĐÚNG -->
+<template>
+  <div>
+    <!-- nội dung -->
+  </div>
+</template>
+```
+
+---
+
+## 7. Style & class — ƯU TIÊN class Vuetify có sẵn, KHÔNG tự chế
+
+**Quy tắc: dùng class tiện ích Vuetify có sẵn cho MỌI nhu cầu spacing/flex/text/màu/kích thước. Chỉ định nghĩa class mới khi thật đặc biệt** (hiệu ứng/layout Vuetify không có). AI hay lạm dụng class tự chế → lãng phí, phá tính nhất quán, khó bảo trì.
+
+### ❌ TUYỆT ĐỐI KHÔNG inject CSS bằng JavaScript
+
+Không tạo `<style>` bằng JS rồi chèn vào `document.head` (kiểu `_injectStyle`) — đây là anti-pattern nặng (vừa lách luật no-`<style>`, vừa tạo hàng chục class tự chế):
+
+```js
+// ❌ SAI NGHIÊM TRỌNG — không bao giờ làm thế này trong .vue
+methods: {
+  _injectStyle: function() {
+    var s = document.createElement('style')
+    s.textContent = ['.smg-root{...}', '.smg-card{...}', '.smg-badge{...}', ...].join('')
+    document.head.appendChild(s)   // ❌ bơm CSS + hàng loạt class tự chế
+  }
+}
+```
+
+`<style scoped>` trong `.vue` được phép dùng cho CSS tùy chỉnh (hiếm khi cần) — nhưng `scoped` **không có tác dụng scoping thật**: FUI chỉ nối text `ComCSS` của mọi component trong module thành MỘT stylesheet chung (`ComponentCSSBuild()`), không compile SFC, không gắn `data-v-xxxx`. Vì vậy **bắt buộc tự scope thủ công**:
+
+1. Thẻ gốc trong `<template>` mang một class định danh duy nhất theo tên component (kebab-case) — ví dụ component `uc-invoice-list` thì thẻ gốc `class="uc-invoice-list"`.
+2. MỌI selector trong `<style scoped>` phải là descendant bắt đầu từ class đó — **không viết selector trần** (`.title`, `.header`...) vì sẽ leak sang mọi component khác cùng module.
+
+```vue
+<template>
+  <div class="uc-invoice-list">
+    <div class="uc-invoice-list__toolbar">
+      <span class="uc-invoice-list__title">{{ title }}</span>
+    </div>
+    <f-table class="uc-invoice-list__table" :items="rows"></f-table>
+  </div>
+</template>
+
+<style scoped>
+.uc-invoice-list__toolbar { display: flex; align-items: center; justify-content: space-between; }
+.uc-invoice-list__title { font-weight: 600; font-size: 14px; }
+.uc-invoice-list__table { margin-top: 8px; }
+</style>
+```
+
+```vue
+<!-- ❌ SAI — selector trần, đụng với component khác cùng module có class .title/.toolbar -->
+<style scoped>
+.title { font-weight: 600; }
+.toolbar { display: flex; }
+</style>
+```
+
+CSS toàn-module (không gắn riêng component nào) → đặt trong `style.css` (publish qua `module_publish_css`), không phải `header.html`. `header.html` vẫn hợp lệ nhưng không còn là lựa chọn duy nhất.
+
+### Trước khi đặt một class mới → tra bộ từ vựng đã duyệt
+
+Bảng đầy đủ class/prop Vuetify được phép dùng (spacing, flex, text, màu, bo góc, elevation,
+breakpoint, kích thước) + thứ tự ưu tiên + điều kiện được định nghĩa class riêng:
+→ [controls-styling-vocabulary.md](controls-styling-vocabulary.md) §3.
+
+Bộ từ vựng đó áp dụng y nguyên trong `<template>` của `.vue` — **khác biệt duy nhất**: trong `.vue`
+không có `w`/`col` của grid FUI (đó là cú pháp của `module.json`, runtime FUI dịch ra class), nên
+phải viết grid Vuetify trực tiếp.
+
+**Cú pháp grid KHÁC NHAU giữa hai framework** — FUI V2 dùng Vuetify 1.5, FUI V3 dùng Vuetify 3
+(canonical: [controls-patterns.md](controls-patterns.md) §Vuetify version):
+
+| | V2 (Vuetify 1.5) | V3 (Vuetify 3) |
+|---|---|---|
+| Cách chia cột | `v-layout` > `v-flex xs8` | `v-row` > `v-col cols="8"` |
+| `v-flex` | ✅ | ❌ **không tồn tại** — thẻ rơi xuống thành phần tử HTML trơ: không lỗi, không `[Vue warn]`, chỉ là **layout mất hẳn** |
+| `v-layout` | ✅ hàng của grid | ⚠️ **có tồn tại nhưng nghĩa khác hẳn**: là wrapper bố cục ứng dụng (đi với `v-main`, như `fastproject-3.0.js` dùng), KHÔNG phải hàng của grid. Dùng nó thay `v-row` thì được một flex container không có gutter/breakpoint của grid |
+| prop trần `shrink` | ✅ (prop của `v-flex`) | ❌ không có prop đó → rơi thành attribute DOM trơ. Dùng `class="shrink"` |
+
+Template chuẩn ở mục 8 ngay dưới viết theo **V3** (`v-row`/`v-col`). Component viết cho project V2 thì
+đổi sang `v-layout`/`v-flex` tương ứng.
+
+Đây là lỗi hỏng-âm-thầm theo cả hai chiều: component dùng `v-flex` đưa sang project V3 sẽ **hiện đủ
+nội dung nhưng sai bố cục**, và không tầng nào báo. Sửa component cũ thì kiểm bằng `component_preview`
+ở **đúng framework của project** trước khi push.
+
+CSS tùy chỉnh riêng component (nếu thật sự cần) đặt trong `<style scoped>` của chính `.vue` đó, tự
+scope thủ công theo quy tắc ở mục 7 phía trên — không đặt trong `header.html` trừ khi CSS đó dùng
+chung cho nhiều component/toàn module.
+
+---
+
+## 8. Dialog chuẩn trong Vue component (`uc-*.vue`) — TEMPLATE CHUẨN HOÁ
+
+Dùng `v-dialog` + `v-card` với **quy ước spacing/size cố định** dưới đây cho MỌI dialog form. Chỉ dùng class tiện ích Vuetify — không tự chế class, không `style`.
+
+```html
+<v-dialog v-model="editDialog" max-width="600">
+  <v-card>
+    <!-- Tiêu đề: px-3 pt-2 pb-3, subtitle-1 font-weight-bold, nút X bên phải -->
+    <v-card-title class="d-flex align-center px-3 pt-2 pb-3 subtitle-1 font-weight-bold">
+      {{ editItem.RoundID ? 'Chỉnh sửa vòng thi' : 'Thêm vòng thi mới' }}
+      <v-spacer></v-spacer>
+      <v-btn icon @click="editDialog = false"><v-icon>mdi-close</v-icon></v-btn>
+    </v-card-title>
+
+    <!-- Nội dung: px-3 py-1; field dùng outlined dense hide-details, chia cột bằng v-row/v-col -->
+    <v-card-text class="px-3 py-1">
+      <v-row>
+        <v-col cols="8">
+          <v-text-field v-model="editItem.RoundName" label="Tên vòng thi"
+                        hide-details outlined dense></v-text-field>
+        </v-col>
+        <v-col cols="4">
+          <v-text-field v-model.number="editItem.RoundOrder" label="Thứ tự" type="number"
+                        hide-details outlined dense></v-text-field>
+        </v-col>
+      </v-row>
+    </v-card-text>
+
+    <!-- Hàng cuối: action căn phải, button rộng tự nhiên; action phụ text, action chính primary -->
+    <v-card-actions class="pa-3">
+      <v-spacer></v-spacer>
+      <v-btn text @click="resetForm">Đặt lại</v-btn>
+      <v-btn color="primary" elevation="0" :loading="saving" @click="saveRound">Lưu</v-btn>
+    </v-card-actions>
+  </v-card>
+</v-dialog>
+```
+
+### Quy ước bắt buộc (không đổi tuỳ tiện)
+
+| Phần | Class/prop chuẩn | Ghi chú |
+|---|---|---|
+| `v-dialog` | `max-width="600"` | 600 cho form thường; 400 nhỏ; 800–900 form rộng |
+| `v-card-title` | `d-flex align-center px-3 pt-2 pb-3 subtitle-1 font-weight-bold` | Tiêu đề gọn + nút X (`v-btn icon` → `mdi-close`) bên phải qua `v-spacer` |
+| `v-card-text` | `px-3 py-1` | Padding nội dung nhất quán |
+| Field nhập | `outlined dense hide-details` | Gọn, cùng chiều cao; chia cột bằng `v-row` + `v-col cols="N"` |
+| `v-card-actions` | Là **hàng cuối**; `pa-3` + `v-spacer` trước nhóm nút | Toàn bộ action căn phải |
+| Chiều ngang nút | Không đặt `block`, `width`, class grow hay bọc trong cột giãn | Giữ chiều ngang tự nhiên theo nhãn |
+| Nút chính | Tối đa một nút dùng `color="primary" elevation="0"` + `:loading="saving"` | Có nền để thể hiện ưu tiên; `:loading` khi đang gọi API |
+| Nút phụ | `text`, không `color` nền | Dùng cho action ít quan trọng; giao diện nhã nhặn, tối giản |
+
+- Tiêu đề động theo chế độ: `{{ editItem.ID ? 'Chỉnh sửa' : 'Thêm mới' }}`.
+- Số nhập dùng `v-model.number` + `type="number"`.
+- Đóng dialog: `@click="dialogVar = false"`; sau khi lưu thành công cũng set `false` trong callback.
+- Icon giữ kích thước mặc định; không tự thêm `small`/`:small` cho `v-icon` hoặc nút icon.
+
+### Biến thể
+
+- **Toolbar header** (khi cần màu/icon nổi bật): thay `v-card-title` bằng `v-toolbar dense flat` + `v-toolbar-title`.
+- **Fullscreen** (form lớn/nhiều vùng): `<v-dialog v-model="..." fullscreen>` + `v-toolbar` header, nội dung trong `v-container class="grid-list-md"`.
+
+---
+
+## 9. Thiết kế cho tái sử dụng
+
+- Kiểm tra xem component có thể là: list, card, dialog body, filter panel, summary block, form section không
+- Expose loading/empty/disabled/readonly qua props hoặc slots thay vì hardcode một workflow
+- Giữ API calls, routing, permissions trong `module.json` hoặc parent — component chỉ lo presentation
+- Khi module.json `controls` vượt ~200 dòng: extract UI sang Vue component, giữ module.json chỉ có data/API
+
+---
+
+## 10. Không nhúng `f-dialog` vào template component
+
+`f-dialog` chỉ hoạt động khi khai báo trực tiếp trong `controls` JSON của module. Nếu cần dialog trong một `uc-*.vue`, dùng cấu trúc v-dialog ở mục 7 thay thế.
+
+---
+
+## 11. Giới hạn cú pháp trong `<script>` của component
+
+### Không dùng `async / await / finally`
+
+FUI parser không hỗ trợ các keyword này bên trong file `.vue`. Dùng callback thay thế:
+
+```js
+// ❌ SAI
+async mounted() {
+    const res = await fetch(url)
+}
+
+// ✅ ĐÚNG
+mounted() {
+    ajaxCALL(url, {}, function(res) { ... })
+}
+```
+
+### Không dùng template literals (backtick) trong `<script>`
+
+Backtick chỉ hoạt động trong `script.js` độc lập, không dùng được trong file `.vue`:
+
+```js
+// ❌ SAI — trong .vue <script>
+var url = `/api/Student/${this.studentID}`
+
+// ✅ ĐÚNG
+var url = '/api/Student/' + this.studentID
+```
+
+---
+
+## 12. Tận dụng hàm có sẵn trong `defaultfunction.js` — KHÔNG viết lại
+
+FUI đã cung cấp sẵn nhiều hàm global. **Trước khi tự viết logic (gọi API, xác nhận, thông báo, format, group, copy...) → kiểm tra [default-function.md](default-function.md) xem đã có chưa.** Chỉ tự viết khi hàm có sẵn không đáp ứng được. Viết lại thứ đã có = lãng phí + không nhất quán.
+
+### Gọi API — dùng `ajaxCALL` (KHÔNG `fetch`/`axios`/`$.ajax` thủ công)
+
+`fetch` bị lỗi CORS/credentials sang domain khác. `ajaxCALL` tự xử lý credentials, token (Bearer), và base domain (`v_Set.apiDomain`) — không cần ghép domain.
+
+```js
+// ❌ SAI
+fetch(url, { method: 'POST', body: JSON.stringify(data) })
+    .then(r => r.json()).then(res => { ... })
+
+// ✅ ĐÚNG — ajaxCALL(URL, DATA, successCb, errorCb, header)
+ajaxCALL('spAPI_RoundList', { ContestID: this.contestID }, function(res) {
+    // res đã parse JSON (json_data tự parse)
+}, function(err) {
+    // tuỳ chọn — mặc định ajaxCALL đã showMessage lỗi
+})
+```
+
+### Xác nhận — dùng `confirm` (KHÔNG `window.confirm`)
+
+```js
+confirm({
+    title: 'Xác nhận xoá',
+    message: 'Bạn có chắc muốn xoá vòng thi này?',
+    action: function() { ajaxCALL('spAPI_RoundDelete', { RoundID: id }, function(){ ... }); }
+});
+```
+
+### Thông báo — dùng `showMessage` hoặc `Vue.$toast`
+
+```js
+showMessage({ title: 'Đã lưu thành công' });              // hộp thoại
+showMessage({ title: 'Lỗi', message: '...', type: 'red' });
+Vue.$toast.success('Đã lưu', { position: 'top' });         // toast góc màn hình
+```
+
+### Các hàm hay dùng khác (đừng viết lại)
+
+`groupBy` · `findInArray` · `jsonToExcel` (xuất Excel) · `printPDF` · `copyToClipboard` · `openWindow` · `pushRouter` · `rightTest` (kiểm tra quyền) · `generateID` · `capacityText` · `buildHeader` (tự sinh headers f-table). Chi tiết: [default-function.md](default-function.md).
+
+> Thư viện toàn cục cũng có sẵn — dùng thay vì tự cài: `_` (Lodash: `_.groupBy`, `_.sumBy`, `_.cloneDeep`...), `moment` (ngày giờ), `numeral` (format số). Không thêm CDN cho các thư viện này.
+
+---
+
+## 13. Kiểm chứng component — `component_preview` TRƯỚC khi ráp vào module
+
+Một `uc-*.vue` là đơn vị đầy đủ (template + script + style) nhưng nếu chỉ nhìn thấy nó sau khi đã ráp vào module thì lỗi của component và lỗi lắp ráp trộn lẫn — mất thời gian khoanh vùng. `component_preview` render **đúng một component** trên một trang riêng, bằng file `.vue` **local** (chưa cần push), với dữ liệu mẫu bạn truyền thẳng trong tham số.
+
+```
+component_preview({
+  componentName: "uc-invoice-list",
+  projectId: "...",              // chỉ projectId → project-scope
+  // moduleId: "..."             // có moduleId → module-scope (suy luận y hệt component_new/component_update)
+  cases: [
+    { name: "danh sách rỗng",  props: { items: [] } },
+    { name: "có dữ liệu",      props: { items: [ {...}, {...} ], title: "Hoá đơn" } },
+    { name: "click chọn dòng", props: { items: [...] },
+      scenario: [ { click: "Xem" }, { assert: "vueData.selected != null" } ] }
+  ],
+  devices: ["desktop", "mobile"]   // mặc định
+})
+```
+
+- **Props**: mảng/object cứ truyền **giá trị thật** — tool tự đẩy vào `data[]` và bind `:prop`. Chuỗi thành attr tĩnh; key đã bắt đầu bằng `:`/`v-` giữ nguyên văn (dùng `v-on:`/`v-slot:`, **không** `@`/`#`).
+- **`cases × devices` ≤ 8**. Mỗi lần render là một phiên browser thật.
+- `slot` (nội dung `innerHTML`), `vueData`, `apiMocks`, `user` (test permission gate), `viewport` (ép chiều cao thấp để lộ component tự đo chiều cao) đều truyền được.
+- `scenario` dùng **đúng grammar renderUI trên DOM thật**: `set`/`click`/`call`/`exe`/`assert`, chọn dòng bằng `nth` (không có `item`/`index`).
+- **`style.css` của module KHÔNG được nạp** — đó chính là ý nghĩa "không gian riêng": component phải tự đứng được bằng `<style>` của chính nó + theme project.
+- Trả về: ảnh chụp (tối đa 4 inline, còn lại ghi đường dẫn) + JS error + `[Vue warn]` + DOM audit. **Đọc ảnh rồi tự sửa** trước khi push.
+
+### Component cấp project: BẮT BUỘC push trước khi render module dùng nó
+
+`module_simulate({ renderUI: true })` dựng tầng project bằng bundle **tải từ server**. Bản local chưa push sẽ **không xuất hiện** — ảnh render là bản cũ trên server, tức ảnh nói dối. Vì vậy renderUI **chặn cứng** (không có cờ bỏ qua) khi component cấp project ở local lệch với bundle server.
+
+```
+sửa uc-*.vue cấp project
+  → component_preview   (kiểm chứng bản local, chưa push)
+  → component_new       (lần đầu) hoặc component_update (các lần sau) — push lên server
+  → module_simulate({ renderUI: true })   ← chỉ chạy được sau khi đã push
+```
+
+Nếu bị chặn mà **bản trên server mới hơn** (ai đó vừa sửa trên web IDE): chạy `project_sync` để lấy về, **đừng push đè** — sẽ mất bài của người khác.
+
+Component **cấp module** không bị luật này: renderUI dựng tầng module từ file local nên sửa tới đâu render thấy tới đó.

package/skills/fui-skill/references/component-quickref.md

@@ -0,0 +1,77 @@
+# FUI Component Quick Reference
+
+> File này sở hữu: **danh mục component FUI, bảng component cần import JS/CSS, quy trình thêm/bỏ import**. Chi tiết từng component xem file reference tương ứng ở cột phải.
+
+Tra cứu nhanh toàn bộ component có sẵn trong FUI runtime. Ưu tiên dùng `f-*` trước — chỉ dùng `v-*` khi không có FUI equivalent.
+
+| Component | Dùng khi nào | Reference |
+|---|---|---|
+| `f-table` | **Hiển thị dữ liệu dạng datatable** — cả CRUD qua dialog form lẫn chỉ xem (readonly = không khai `:update-api`); auto-build headers khi không truyền `:headers`; hàng tổng qua `sum-format` | [component-table.md](component-table.md) |
+| `f-dialog` | Modal dialog với form, watch, button | [components-dialog.md](components-dialog.md) |
+| `f-window` | Dialog mở URL trong iframe | [components-dialog.md](components-dialog.md) |
+| `f-button` | Nút bấm có action, hotkey, form validation | [components-input.md](components-input.md) |
+| `f-date` | Input ngày có date picker + typed mask | [components-input.md](components-input.md) |
+| `f-time` | Input giờ có time picker + typed mask | [components-input.md](components-input.md) |
+| `f-time-counter` | Đếm ngược / đồng hồ | [components-input.md](components-input.md) |
+| `f-search` | Autocomplete tìm kiếm qua API | [components-input.md](components-input.md) |
+| `f-menu` | Dropdown button menu có icon/action/link | [components-input.md](components-input.md) |
+| `f-radiobox` | Radio group từ array items | [components-input.md](components-input.md) |
+| `f-file-upload` | Upload file (Plupload, progress dialog) | [components-input.md](components-input.md) |
+| `f-image-update` | Upload + crop ảnh | [components-input.md](components-input.md) |
+| `f-excel-reader` | Đọc file Excel/CSV → JSON (chọn sheet, bỏ N dòng đầu, tự đặt tên cột) | [components-input.md](components-input.md) |
+| `f-qrcode` | Render mã QR | [components-input.md](components-input.md) |
+| `f-qrcode-reader` | Đọc QR bằng camera | [components-input.md](components-input.md) |
+| `f-editor` | Rich text editor (CKEditor 5) | [components-dialog.md](components-dialog.md) |
+| `f-editor-dialog` | Rich text editor trong modal | [components-dialog.md](components-dialog.md) |
+| `f-echart` | **Biểu đồ** — ECharts V5: bar, line, pie, scatter, gauge, radar, heatmap, sankey, tree, map, graph... | [components-echart.md](components-echart.md) · [echart-templates.md](echart-templates.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 (dựa trên AG Grid) — **cần import** | [fsheet.md](fsheet.md) |
+| `f-pdfmake` | Render PDF trong iframe | [components-display.md](components-display.md) · [pdfmake.md](pdfmake.md) |
+| `f-label` | Chip/badge hiển thị tag, trạng thái | [components-display.md](components-display.md) |
+| `f-box` | Hiển thị/chỉnh sửa key-value rows | [components-display.md](components-display.md) |
+| `f-header` | Tiêu đề lớn (display-1, primary color) | [components-display.md](components-display.md) |
+| `f-title` | Tiêu đề nhỏ (title, primary color) | [components-display.md](components-display.md) |
+| `f-slider` | Carousel ảnh | [components-display.md](components-display.md) |
+| `fp-profile` | Khối thông tin/hồ sơ user | [components-display.md](components-display.md) |
+
+### Component trong ô bảng (`t-*`) — dùng trong `headers` của f-table
+
+`t-html` · `t-label` · `t-num` · `t-time` · `t-boolean` · `t-check` (toggle) · `t-text` · `t-select` · `t-combobox` · `t-menu` (context menu) · `t-link` · `t-button` — chi tiết & ví dụ: [ui-table-cell-patterns.md](ui-table-cell-patterns.md).
+
+> `header-bar` và `f-window` là component nội bộ do runtime tự dựng (menu header, cửa sổ `openWindow`) — không đặt trực tiếp trong `controls`.
+
+## Components cần import JS/CSS
+
+Một số component yêu cầu import thêm thư viện — **phải gọi `file_import_list` để kiểm tra và thêm/xóa import tương ứng khi thêm hoặc bỏ component**.
+
+| Component | Import bắt buộc |
+|---|---|
+| `f-pdfmake` | `/include/pdfmake/pdfmake.min.js` · `/include/pdfmake/print.min.js` · `/include/pdfmake/vfs_fonts.js` |
+| `f-file-upload` | `/include/plupload-2.3.7/plupload.full.min.js` |
+| `f-image-update` | `/include/vue-advanced-cropper/index.umd.js` · `/include/vue-advanced-cropper/style.css` |
+| `f-qrcode` | `/include/qrcode/qrcode.min.js` |
+| `f-qrcode-reader` | `/include/qrcode/qrcode-reader.min.js` |
+| `f-echart` | `/include/chart/echarts.min.js` · `/include/chart/fechart.js` (**theo thứ tự này**) — nền tảng Apache ECharts |
+| `f-sheet` | `/include/ag-grid/ag-grid-community.min.js` · `/include/ag-grid/fsheet.js` (**theo thứ tự này**) — nền tảng AG Grid |
+| `f-editor` | `/include/ckeditor5/build/ckeditor.js` |
+| `f-editor-dialog` | `/include/ckeditor5/build/ckeditor.js` |
+
+> **Bundled sẵn, KHÔNG cần import thêm:** `v-*` (Vuetify) · `f-table` · `f-dialog` · `f-button` ·
+> `f-date` · `f-time` · `f-search` · `f-menu` · `f-radiobox` · `f-box` · `f-label` · `f-header` ·
+> `f-title` · `f-slider` · `f-excel-reader` — và mọi component không có tên trong bảng trên.
+
+**Quy trình khi thêm component có import:**
+1. `file_import_list` (projectId + moduleId) — kiểm tra import hiện có
+2. Nếu chưa có → `file_import_new` để thêm từng file
+3. Nếu bỏ component → kiểm tra import đó còn dùng ở chỗ nào khác không; nếu không → `file_import_delete`
+
+---
+
+## Quy tắc chọn nhanh
+
+- `f-button` thay `v-btn` khi cần action FUI (CALL, hotkey, form validation)
+- `f-date` / `f-time` thay `v-text-field` + manual date parsing
+- `f-search` thay `v-autocomplete` khi cần search qua API
+- `f-menu` thay `v-menu + v-btn` khi cần dropdown actions
+- `f-table` thay `v-data-table` cho MỌI bảng — CRUD lẫn chỉ xem (readonly = không khai `:update-api`)
+- `f-echart` cho mọi loại biểu đồ (bar, line, pie, gauge, scatter, radar, sankey, tree, map...)
+- Dialog: `ctrl-update` của `f-table` cho CRUD inline; dialog riêng → dựng `v-dialog` thủ công theo anatomy chuẩn (`design_read("fui")` §4 + `ui-dialog-patterns.md`); `f-dialog` chỉ cho form rất nhỏ