@ngockhoale/ukit 1.1.6

package/templates/.claude/skills/duraone/references/frontend.md

@@ -0,0 +1,1506 @@
+# DuraOne Frontend Reference
+## Vue 3 / Nuxt 3 — Options API Style
+
+> **NGUYÊN TẮC CỐT LÕI**: Tận dụng tối đa những gì đã có sẵn trong `components/` và `composables/`.
+> KHÔNG tự tạo input thô — LUÔN dùng Control components. KHÔNG import composables — Nuxt auto-import.
+
+---
+
+## MỤC LỤC
+1. [Cấu trúc thư mục FE](#1-cấu-trúc-thư-mục-fe)
+2. [Cấu trúc Vue Component (Options API)](#2-cấu-trúc-vue-component)
+3. [Naming Conventions](#3-naming-conventions)
+4. [CONTROL COMPONENTS — Dùng Tối Đa](#4-control-components)
+   - [ControlInput](#controlinput)
+   - [ControlDropdownlist](#controldropdownlist)
+   - [ControlDatetime](#controldatetime)
+   - [ControlCheckbox](#controlcheckbox)
+   - [ControlCheckButton](#controlcheckbutton)
+   - [ControlTag](#controltag)
+   - [ControlButton](#controlbutton)
+   - [ControlButtonBar](#controlbuttonbar)
+   - [ControlButtonFloat](#controlbuttonfloat)
+   - [ControlLabel](#controllabel)
+   - [ControlBox](#controlbox)
+   - [ControlUpload](#controlupload)
+   - [ControlMasterBoxColumn](#controlmasterboxcolumn)
+5. [POPUP COMPONENTS](#5-popup-components)
+   - [ControlPopupConfirm](#controlpopupconfirm)
+   - [ControlPopupConfirmReject](#controlpopupconfirmreject)
+   - [ControlPopupReject](#controlpopupreject)
+   - [ControlPopupInfo](#controlpopupinfo)
+   - [ControlPopupModalInfo](#controlpopupmodalinfo)
+6. [GRID COMPONENTS](#6-grid-components)
+   - [GridAG](#gridag)
+   - [GridAntTable](#gridanttable)
+   - [GridHtmlTable](#gridhtmltable)
+7. [PANEL COMPONENTS](#7-panel-components)
+8. [COMPOSABLES — Dùng Trực Tiếp (Auto-Import)](#8-composables)
+   - [dayjs — DATETIME STANDARD](#dayjs--datetime-standard)
+   - [Dropdown Loading Pattern](#dropdown-loading-pattern)
+9. [API Call Patterns](#9-api-call-patterns)
+10. [Pattern: Trang Danh Sách](#10-pattern-trang-danh-sách)
+11. [Pattern: Trang Form](#11-pattern-trang-form)
+12. [Routing & Navigation](#12-routing--navigation)
+13. [Validation Pattern](#13-validation-pattern)
+14. [Đề Xuất Components Mới](#14-đề-xuất-components-mới)
+
+---
+
+## 1. Cấu Trúc Thư Mục FE
+
+### 1.1. Cấu Trúc Gốc Nuxt Project
+
+```
+FE_DuraOne/
+├── assets/               # Tài nguyên tĩnh (SCSS, fonts, images) — được Nuxt xử lý qua build pipeline
+├── components/           # Tất cả Vue components — Nuxt auto-import, KHÔNG cần import thủ công
+├── composables/          # Logic dùng chung — Nuxt auto-import, KHÔNG cần import thủ công
+├── dist/                 # Output build production (do Nuxt generate) — KHÔNG chỉnh sửa thủ công
+├── docs/                 # Tài liệu dự án, hướng dẫn, ghi chú kỹ thuật
+├── layouts/              # Layout wrappers (default, admin, blank...) — bọc ngoài mỗi page
+├── middleware/           # Route middleware (auth check, permission guard) — chạy trước khi vào page
+├── node_modules/         # Dependencies (do yarn install) — KHÔNG chỉnh sửa, KHÔNG commit
+├── pages/                # Các trang Vue — cấu trúc thư mục = routing tự động của Nuxt
+├── plugins/              # Nuxt plugins (Ant Design Vue, ECharts, dayjs, v.v.) — chạy khi app khởi tạo
+├── public/               # File tĩnh phục vụ trực tiếp (favicon, robots.txt) — KHÔNG qua build pipeline
+│
+├── .gitignore            # Danh sách file/folder git bỏ qua
+├── AGENTS.md             # Hướng dẫn cho AI agents làm việc với project
+├── api.http              # File test API thủ công (dùng với REST Client extension)
+├── app.vue               # Root component của Nuxt app — entry point, chứa <NuxtLayout> + <NuxtPage>
+├── CLAUDE.md             # Hướng dẫn riêng cho Claude AI khi làm việc với project
+├── nuxt.config.ts        # Cấu hình Nuxt (modules, runtime config, CSS, vite options)
+├── package.json          # Dependencies + scripts (dev, build, generate)
+├── tsconfig.json         # Cấu hình TypeScript (Nuxt tự extend)
+└── yarn.lock             # Lock file dependencies — KHÔNG chỉnh sửa thủ công
+```
+
+### 1.2. Chi Tiết Bên Trong `components/` và `composables/`
+
+```
+components/
+│   ├── Control/          # Form controls — LUÔN dùng thay vì raw input
+│   │   ├── Box.vue
+│   │   ├── Button.vue
+│   │   ├── ButtonBar.vue
+│   │   ├── ButtonFloat.vue
+│   │   ├── CheckButton.vue
+│   │   ├── Checkbox.vue
+│   │   ├── Datetime.vue
+│   │   ├── Dropdownlist.vue
+│   │   ├── Input.vue
+│   │   ├── Label.vue
+│   │   ├── Tag.vue
+│   │   ├── Upload.vue
+│   │   ├── Master/BoxColumn.vue
+│   │   └── Popup/
+│   │       ├── Confirm.vue
+│   │       ├── ConfirmReject.vue
+│   │       ├── Info.vue
+│   │       ├── ModalInfo.vue
+│   │       └── Reject.vue
+│   ├── ControlMobile/    # Mobile variants
+│   │   ├── PagingBar.vue
+│   │   └── UploadImage.vue
+│   ├── Grid/
+│   │   ├── AG.vue        # Main grid — dùng cho mọi danh sách
+│   │   ├── AntTable.vue
+│   │   └── HtmlTable.vue
+│   ├── Panel/
+│   │   └── FormView.vue  # Auto CRUD form
+│   ├── Partial/          # Layout partials (Header, Sidebar, Footer)
+│   └── PDFViewer.vue
+
+composables/               # Auto-imported bởi Nuxt — KHÔNG import thủ công
+│   ├── masterApi.js      # Domain API functions (get data cho nhiều trang)
+│   ├── useRequest.js     # HTTP wrapper + GZIP compression — MỌI API call phải qua đây
+│   ├── useSession.js     # localStorage session management
+│   ├── useTranslation.js # i18n — hàm t() để đa ngôn ngữ
+│   ├── useWebSocket.js   # WebSocket connection
+│   ├── state.js          # Global reactive state (user, loading, language...)
+│   ├── utils.js          # Utility functions (format, convert, validate dùng chung)
+│   ├── userObj.js        # User-related helpers
+│   └── indexDBStore.js   # IndexedDB storage
+```
+
+---
+
+## 2. Cấu Trúc Vue Component
+
+**⚠️ LUÔN dùng Options API. KHÔNG dùng `<script setup>`. KHÔNG import composables.**
+
+```vue
+<template>
+  <!-- HTML -->
+</template>
+
+<script>
+// ⚠️ KHÔNG import — Nuxt 3 auto-import tất cả từ /composables/
+// state, get_schema, request, formatDate, show_message, t(), get_*... đều sẵn dùng
+
+export default {
+  props: {
+    propName: { type: String, default: "" },
+  },
+  data() {
+    return {
+      workingObj: {},
+      rows: [],
+      // dropdowns
+      branchList: [],
+      // ui flags
+      is_saving: false,
+      show_confirm_delete: false,
+    };
+  },
+  computed: {
+    is_locked() {
+      return !this.workingObj.can_edit;
+    },
+  },
+  watch: {
+    "workingObj.id_branch"(newVal) {
+      this.on_branch_change(newVal);
+    },
+  },
+  async created() {
+    if (!authorize_menu(this.$route.fullPath)) {
+      this.$router.push(state.homepage);
+      return;
+    }
+    state.page_header = t("Page Title");
+    await this.init();
+  },
+  methods: {
+    async init() {
+      await Promise.all([this.get_data(), this.load_dropdowns()]);
+    },
+    async get_data() { /* ... */ },
+    async load_dropdowns() { /* ... */ },
+    async save() { /* ... */ },
+    validate() { /* ... */ },
+  },
+};
+</script>
+
+<style scoped></style>
+```
+
+---
+
+## 3. Naming Conventions
+
+| Loại | Convention | Ví dụ |
+|------|-----------|-------|
+| Page files | PascalCase | `AgreementList.vue`, `UserForm.vue` |
+| Page folders | PascalCase | `Agreement/`, `Master/Users/` |
+| Component files | PascalCase | `ControlInput.vue`, `GridAG.vue` |
+| Composables | camelCase | `masterApi.js`, `useRequest.js` |
+| JS variables | camelCase | `workingObj`, `branchList` |
+| DB field keys | snake_case | `id_agreement`, `created_at` |
+| ID fields | `id_` prefix | `id_agreement`, `id_user` |
+| Boolean fields | `can_`/`is_`/`has_`/`show_` | `can_edit`, `is_locked`, `show_confirm` |
+| Data methods | `get_` / `load_` | `get_data()`, `load_dropdowns()` |
+| Action methods | verb | `save()`, `approve()`, `delete_record()` |
+| Event handlers | `on_` | `on_row_click()`, `on_branch_change()` |
+
+---
+
+## 4. CONTROL COMPONENTS
+
+> **KHÔNG tự tạo `<input>`, `<select>`, `<button>` raw** — luôn dùng những component dưới đây.
+
+---
+
+### ControlInput
+
+Text, number, password, textarea — tất cả đều qua component này.
+
+```vue
+<!-- Text -->
+<ControlInput
+  v-model="workingObj.agreement_number"
+  name="Agreement Number"
+  type="text"
+  :required="true"
+  :disabled="is_locked"
+  placeholder="Enter number..."
+/>
+
+<!-- Textarea -->
+<ControlInput
+  v-model="workingObj.note"
+  name="Note"
+  type="textarea"
+  :rows="4"
+  :disabled="is_locked"
+/>
+
+<!-- Number -->
+<ControlInput
+  v-model="workingObj.amount"
+  name="Amount"
+  type="number"
+  :required="true"
+  :disabled="is_locked"
+/>
+
+<!-- Password -->
+<ControlInput
+  v-model="form.password"
+  name="Password"
+  type="password"
+  :required="true"
+/>
+
+<!-- Search (emit onSearch khi nhấn Enter/button) -->
+<ControlInput
+  v-model="keyword"
+  name=""
+  type="search"
+  placeholder="Search..."
+  @onSearch="get_data"
+/>
+```
+
+**Props:** `modelValue`, `name` (label), `type` (text|number|password|textarea|search), `placeholder`, `required`, `disabled`, `rows` (cho textarea), `classes`, `label_classes`, `id`
+
+---
+
+### ControlDropdownlist
+
+Select đơn hoặc multiple — có search, có hỗ trợ show_key.
+
+```vue
+<!-- Dropdown đơn -->
+<ControlDropdownlist
+  v-model="workingObj.id_branch"
+  name="Branch"
+  :list="branchList"
+  :required="true"
+  :disabled="is_locked"
+  placeholder="Select branch..."
+/>
+
+<!-- Multiple select -->
+<ControlDropdownlist
+  v-model="workingObj.id_tags"
+  name="Tags"
+  :list="tagList"
+  :multiple="true"
+  :disabled="is_locked"
+/>
+
+<!-- Hiển thị value kèm label -->
+<ControlDropdownlist
+  v-model="workingObj.status"
+  name="Status"
+  :list="statusList"
+  :show_key="true"
+/>
+```
+
+**Props:** `modelValue`, `name`, `list` (Array `[{value, label}]`), `required`, `disabled`, `multiple`, `placeholder`, `show_key`, `icon`, `classes`, `id`
+
+**Lưu ý:** `list` phải có format `{ value: ..., label: ... }` — không đổi key.
+
+---
+
+### ControlDatetime
+
+Date picker, month picker, hoặc year picker.
+
+```vue
+<!-- Date -->
+<ControlDatetime
+  v-model="workingObj.start_date"
+  name="Start Date"
+  type="date"
+  :required="true"
+  :disabled="is_locked"
+  :maxDate="workingObj.end_date"
+/>
+
+<!-- Date + Time -->
+<ControlDatetime
+  v-model="workingObj.appointment_time"
+  name="Appointment"
+  type="date"
+  :show_time="true"
+  :required="true"
+/>
+
+<!-- Month picker -->
+<ControlDatetime
+  v-model="filter_month"
+  name="Month"
+  type="month"
+/>
+
+<!-- Year picker -->
+<ControlDatetime
+  v-model="filter_year"
+  name="Year"
+  type="year"
+/>
+```
+
+**Props:** `modelValue`, `name`, `type` (date|month|year), `show_time`, `required`, `disabled`, `minDate`, `maxDate`, `classes`, `id`
+
+**Emit:** `update:modelValue` với format `YYYY-MM-DD`
+
+---
+
+### ControlCheckbox
+
+Boolean checkbox với label.
+
+```vue
+<ControlCheckbox
+  v-model="workingObj.is_active"
+  label="Active"
+  :disabled="is_locked"
+/>
+
+<ControlCheckbox
+  v-model="workingObj.has_vat"
+  label="Include VAT"
+/>
+```
+
+**Props:** `modelValue`, `label`, `disabled`
+
+---
+
+### ControlCheckButton
+
+Checkbox styled như button — dùng khi cần toggle nổi bật hơn.
+
+```vue
+<ControlCheckButton
+  v-model="filter_is_urgent"
+  label="Urgent Only"
+/>
+
+<ControlCheckButton
+  v-model="workingObj.is_adhoc"
+  label="Ad-hoc"
+  :disabled="is_locked"
+/>
+```
+
+**Props:** `modelValue`, `label`, `disabled`, `id`
+
+---
+
+### ControlTag
+
+Multi-tag input — nhập nhiều giá trị tự do.
+
+```vue
+<ControlTag
+  v-model="workingObj.keywords"
+  name="Keywords"
+  placeholder="Add keyword, press Enter..."
+  :disabled="is_locked"
+/>
+```
+
+**Props:** `modelValue` (Array), `name`, `placeholder`, `required`, `disabled`, `classes`, `label_classes`, `id`
+
+---
+
+### ControlButton
+
+Button chính — có loading state tự động (1 giây sau click).
+
+```vue
+<!-- Primary -->
+<ControlButton name="Save" type="primary" @onClick="save" />
+
+<!-- Danger -->
+<ControlButton name="Delete" type="danger" @onClick="show_confirm_delete = true" />
+
+<!-- Secondary -->
+<ControlButton name="Back" type="secondary" @onClick="go_back" />
+
+<!-- Success -->
+<ControlButton name="Approve" type="success" @onClick="approve" />
+
+<!-- Custom color -->
+<ControlButton name="Export" color="#6c5ce7" @onClick="export_data" />
+```
+
+**Props:** `name` (label), `type` (primary|secondary|danger|success|warning), `color` (custom hex), `classes`
+
+**Emit:** `onClick`
+
+---
+
+### ControlButtonBar
+
+Group nhiều button liền nhau.
+
+```vue
+<ControlButtonBar
+  :button_list="[
+    { name: 'Close', type: 'secondary' },
+    { name: 'Delete', type: 'danger' },
+    { name: 'Save', type: 'success' },
+  ]"
+  @clickClose="close"
+  @clickDelete="show_confirm_delete = true"
+  @clickSave="save"
+/>
+```
+
+**Props:** `button_list` (Array `[{name, type}]`)
+
+**Emit:** `click{ButtonName}` — dynamic theo tên button (e.g. `clickSave`, `clickDelete`)
+
+---
+
+### ControlButtonFloat
+
+Floating action button cố định góc dưới phải — dùng cho trang danh sách để "Add New".
+
+```vue
+<ControlButtonFloat name="Add New" @clickButtonFloat="go_to_form" />
+```
+
+**Props:** `name`
+
+**Emit:** `clickButtonFloat`
+
+---
+
+### ControlLabel
+
+Label riêng — dùng khi cần label mà không kèm input.
+
+```vue
+<ControlLabel name="Section Title" :required="false" />
+<ControlLabel name="Email" icon="fas fa-envelope" :required="true" />
+```
+
+**Props:** `name`, `required`, `icon` (FontAwesome class), `classes`
+
+---
+
+### ControlBox
+
+Container có header + màu sắc theo loại — dùng để group fields.
+
+```vue
+<!-- Info box -->
+<ControlBox title="Agreement Info" type="info" :col="12">
+  <div class="row">
+    <div class="col-md-6">
+      <ControlInput v-model="workingObj.agreement_number" name="Number" />
+    </div>
+  </div>
+</ControlBox>
+
+<!-- Success status box -->
+<ControlBox title="Approval" type="success" :col="6">
+  <ControlLabel :name="workingObj.approved_by" />
+</ControlBox>
+
+<!-- Warning box -->
+<ControlBox title="Attention" type="warning" :col="12">
+  <p>Please review before submitting.</p>
+</ControlBox>
+```
+
+**Props:** `title`, `type` (info|success|danger|warning), `col` (3|4|6|12), `show_icon`
+
+---
+
+### ControlUpload
+
+File upload với drag-and-drop, tối đa 3 file, 10MB/file.
+
+```vue
+<ControlUpload
+  v-model="fileList"
+  label="Click or drag file to upload"
+  hint="Max 3 files, 10MB each"
+  @uploadFinish="on_upload_finish"
+/>
+```
+
+```javascript
+methods: {
+  on_upload_finish(file) {
+    this.workingObj.file_url = file.url || file.name;
+  }
+}
+```
+
+**Props:** `modelValue` (Array), `label`, `hint`, `required`
+
+**Emit:** `uploadFinish(file)`
+
+---
+
+### ControlMasterBoxColumn
+
+Layout wrapper tự điều chỉnh col width theo số item — dùng trong PanelFormView.
+
+```vue
+<!-- item.position.length = 1 → col-md-12 -->
+<!-- item.position.length = 2 → col-md-6  -->
+<!-- item.position.length = 3 → col-md-4  -->
+<!-- item.position.length = 4 → col-md-3  -->
+<ControlMasterBoxColumn :item="field">
+  <ControlInput v-model="obj[field.key]" :name="field.title" />
+</ControlMasterBoxColumn>
+```
+
+---
+
+## 5. POPUP COMPONENTS
+
+---
+
+### ControlPopupConfirm
+
+Confirm dialog đơn giản — Yes/No.
+
+```vue
+<ControlPopupConfirm
+  :visible="show_confirm_delete"
+  title="Confirm Delete"
+  message="Are you sure you want to delete this record?"
+  @onConfirm="on_confirm_delete"
+  @onClose="show_confirm_delete = false"
+/>
+```
+
+```javascript
+data() {
+  return { show_confirm_delete: false };
+},
+methods: {
+  async on_confirm_delete() {
+    this.show_confirm_delete = false;
+    await request("/delete", { table: "agreement", id_agreement: this.workingObj.id_agreement });
+    show_message("success", t("Deleted successfully"));
+    this.$router.push("/Agreement/AgreementList");
+  }
+}
+```
+
+**Props:** `visible`, `title`, `message` (HTML supported)
+
+**Emits:** `onConfirm`, `onClose`
+
+---
+
+### ControlPopupConfirmReject
+
+Popup confirm có checkbox Adhoc/OnPlan + textarea lý do — dùng cho approval flow.
+
+```vue
+<ControlPopupConfirmReject
+  :visible="show_confirm_approve"
+  title="Classify Agreement"
+  message="Please classify this agreement type"
+  @onConfirm="on_confirm_approve"
+  @onClose="show_confirm_approve = false"
+/>
+```
+
+```javascript
+// onConfirm nhận (reason, is_adhoc, is_onplan)
+async on_confirm_approve(reason, is_adhoc, is_onplan) {
+  await request("/save", {
+    table: "agreement",
+    key_array: ["id_agreement"],
+    id_agreement: this.workingObj.id_agreement,
+    status: "approved",
+    approve_reason: reason,
+    is_adhoc,
+    is_onplan,
+  });
+}
+```
+
+**Props:** `visible`, `title`, `message`
+
+**Emits:** `onConfirm(reason, is_adhoc, is_onplan)`, `onClose`
+
+---
+
+### ControlPopupReject
+
+Popup từ chối có Adhoc/OnPlan checkbox + lý do — dùng cho rejection flow.
+
+```vue
+<ControlPopupReject
+  :visible="show_reject"
+  title="Reject Agreement"
+  message="Please provide rejection reason"
+  @onConfirm="on_reject"
+  @onClose="show_reject = false"
+/>
+```
+
+```javascript
+async on_reject(reason, is_adhoc, is_onplan) {
+  await request("/save", {
+    table: "agreement",
+    key_array: ["id_agreement"],
+    id_agreement: this.workingObj.id_agreement,
+    status: "rejected",
+    reject_reason: reason,
+  });
+}
+```
+
+**Props:** `visible`, `title`, `message`
+
+**Emits:** `onConfirm(reason, is_adhoc, is_onplan)`, `onClose`
+
+---
+
+### ControlPopupInfo
+
+Info modal hiển thị kết quả thao tác.
+
+```vue
+<ControlPopupInfo
+  :visible="show_result"
+  status="success"
+  title="Saved Successfully"
+/>
+```
+
+**Props:** `visible`, `status` (success|error|warning|info), `title`
+
+---
+
+### ControlPopupModalInfo
+
+Modal chứa GridAG — hiển thị danh sách chi tiết trong popup.
+
+```vue
+<ControlPopupModalInfo
+  :visible="show_detail_popup"
+  title="Transaction History"
+  :rows="transaction_rows"
+  :columns="transaction_columns"
+/>
+```
+
+**Props:** `visible`, `title`, `rows`, `columns`
+
+---
+
+## 6. GRID COMPONENTS
+
+---
+
+### GridAG
+
+**Component chính cho mọi danh sách dữ liệu** — AG Grid với đầy đủ tính năng.
+
+```vue
+<GridAG
+  :rows="rows"
+  :columns="columns"
+  :can_add="true"
+  :can_delete="false"
+  :can_export="true"
+  :can_search="true"
+  :can_refresh="true"
+  height="500px"
+  @onAdd="go_to_new_form"
+  @onClickDetail="go_to_edit_form"
+  @reloadData="get_data"
+/>
+```
+
+**Column Definition:**
+```javascript
+columns: [
+  // Text
+  { key: "request_no",   title: t("Request No"),  type: "text",   width: 150 },
+  // Number (auto format)
+  { key: "amount",       title: t("Amount"),       type: "number", width: 120 },
+  // Date (auto format DD/MM/YYYY)
+  { key: "created_at",   title: t("Date"),         type: "date",   width: 110 },
+  // Date + Time
+  { key: "updated_at",   title: t("Updated"),      type: "datetime", width: 140 },
+  // HTML render
+  { key: "status_html",  title: t("Status"),       type: "html",   width: 100 },
+  // Checkbox (read-only)
+  { key: "is_active",    title: t("Active"),       type: "checkbox", width: 80 },
+  // Editable dropdown
+  {
+    key: "status",
+    title: t("Status"),
+    type: "dropdown",
+    can_edit: true,
+    dropdown_list: [
+      { value: "draft",    label: "Draft" },
+      { value: "approved", label: "Approved" },
+    ],
+    width: 120,
+  },
+  // Sum aggregation
+  { key: "amount", title: t("Amount"), type: "number", aggFunc: "sum", width: 120 },
+],
+```
+
+**Props đầy đủ:**
+- `rows` (Array) — data
+- `columns` (Array) — column defs
+- `can_add` (Boolean, default: true)
+- `can_search` (Boolean, default: true)
+- `can_edit` (Boolean, default: true) — hiện nút Edit/Detail
+- `can_delete` (Boolean, default: false)
+- `can_export` (Boolean, default: true)
+- `can_refresh` (Boolean, default: true)
+- `can_sync` (Boolean, default: false) — sync từ Excel
+- `can_upload` (Boolean, default: false)
+- `have_checkbox` (Boolean, default: false)
+- `show_total` (Boolean, default: false) — pinned bottom row
+- `height` (String, default: "600px")
+- `is_fix_height` (Boolean, default: false)
+- `is_loading` (Boolean, default: false)
+- `table` (String) — table name cho sync
+- `table_schema` (String)
+- `detail_button_list` (Array) — extra per-row buttons
+- `extra_button` (Array) — extra toolbar buttons
+
+**Emits:**
+- `onAdd` — Add button
+- `onClickDetail(row)` — Edit/Detail button
+- `onExtraDetailBtnClick(key, row)` — extra row button
+- `onCellValueChanged(event)` — inline edit
+- `reloadData()` — refresh
+- `getSelectedRows(key, rows)` — checkbox selection
+- `onDeleteRowIndex(index)` — delete row
+- `onExtraBtnClick(key)` — extra toolbar button
+
+---
+
+### GridAntTable
+
+Table đơn giản hơn GridAG — dùng khi cần pagination nhẹ.
+
+```vue
+<GridAntTable
+  :rows="rows"
+  :columns="columns"
+  :is_checkbox="false"
+  :is_edit="true"
+  :is_export="true"
+  @onClickDetail="on_click_detail"
+/>
+```
+
+**Props:** `rows`, `columns` (`[{title, dataIndex}]`), `is_checkbox`, `is_edit`, `is_export`
+
+**Emits:** `onClickDetail(row)`, `onClickEdit(row)`
+
+---
+
+### GridHtmlTable
+
+Table HTML thuần — dùng cho print hoặc display đơn giản nhất.
+
+```vue
+<GridHtmlTable
+  :rows="rows"
+  :columns="[
+    { caption: 'Name', field: 'full_name' },
+    { caption: 'Amount', field: 'amount' },
+  ]"
+/>
+```
+
+---
+
+## 7. PANEL COMPONENTS
+
+### PanelFormView
+
+Form CRUD tự động — dùng cho Master Data (không cần business logic phức tạp).
+
+```vue
+<PanelFormView
+  :workingObj="currentRecord"
+  :rows="allRows"
+  :columns="formColumns"
+  table="branch"
+  table_schema="qas"
+  :allow_edit="true"
+  @reloadData="get_data"
+/>
+```
+
+**Column definition cho FormView:**
+```javascript
+formColumns: [
+  {
+    key: "id_branch",
+    title: "Branch ID",
+    type: "auto_generate",
+    primary: true,      // PK — disable khi update
+    show_form: false,   // ẩn khỏi form
+  },
+  {
+    key: "branch_name",
+    title: "Branch Name",
+    type: "input",
+    required: true,
+    show_form: true,
+    position: ["col1"], // position.length = 1 → col-12
+  },
+  {
+    key: "id_region",
+    title: "Region",
+    type: "dropdown",
+    required: true,
+    show_form: true,
+    position: ["col1", "col2"], // length = 2 → col-6
+    dropdown_info: {
+      schema: "qas",
+      table: "region",
+      field: { label: ["region_name"], value: ["id_region"] },
+    },
+  },
+  {
+    key: "id_country",
+    title: "Country",
+    type: "dropdown",
+    show_form: true,
+    position: ["col1", "col2"],
+    dropdown_info: {
+      schema: "qas",
+      table: "country",
+      field: { label: ["country_name"], value: ["id_country"] },
+      conditions: { id_region: "id_region" }, // dependent dropdown
+    },
+  },
+],
+```
+
+---
+
+## 8. COMPOSABLES
+
+> ⚠️ **KHÔNG import** — Nuxt 3 auto-import tất cả từ `/composables/`. Dùng trực tiếp.
+
+### useRequest.js
+
+> 🚫🚫🚫 **CẤM TUYỆT ĐỐI GỌI API RAW** 🚫🚫🚫
+>
+> **KHÔNG BAO GIỜ** dùng `fetch()`, `axios()`, `axios.get()`, `axios.post()`, `axios.put()`, `axios.delete()` hay bất kỳ HTTP client nào khác.
+>
+> MỌI request đến server **BẮT BUỘC** phải đi qua 3 hàm duy nhất bên dưới (đã auto-import từ `composables/useRequest.js`):
+> - `request(url, data, method)` — API chuẩn, có GZIP + loading state
+> - `requestForm(url, formData)` — Upload file (multipart/form-data)
+> - `request_origin(url, data)` — Custom endpoint (không qua `/api/select`)
+>
+> **Nếu code sinh ra chứa `fetch(`, `axios(`, `axios.get(`, `axios.post(` → CODE SAI, PHẢI SỬA LẠI NGAY.**
+> Không có ngoại lệ — kể cả "chỉ test nhanh", "gọi API bên ngoài", hay "chỉ 1 lần".
+
+```javascript
+// GET data (qua generic /api/select)
+const rows = await request("/select", {
+  schema: get_schema(),
+  table: "v_agreement",
+  conditions: JSON.stringify({ id_branch: 5, status: "active" }),
+  order_by: ["created_at desc"],
+  columns: "*",           // hoặc ["col1", "col2"]
+}, "get");
+
+// POST save (insert id='' hoặc update id=uuid)
+await request("/save", {
+  table: "agreement",
+  key_array: ["id_agreement"],
+  id_agreement: "",       // '' = insert, uuid = update
+  agreement_number: "AGR-001",
+  amount: 50000,
+});
+
+// Custom endpoint
+await request_origin("/api/agreement/approve", {
+  id_agreement: "uuid-here",
+  schema: get_schema(),
+});
+
+// Upload file
+const formData = new FormData();
+formData.append("file", fileObj);
+formData.append("folder", "agreements");
+await requestForm("/api/upload_to_cloud", formData);
+```
+
+### Dropdown Loading Pattern
+
+Dùng pattern này để load dropdown list. Gọi trong `load_dropdowns()` hoặc `init()`.
+
+```javascript
+// Pattern chuẩn:
+// 1. Dùng separate `let data = {}` object (không inline)
+// 2. Check resp.length > 0 trước khi gán
+// 3. Dùng convertToDropdownValue() để chuyển sang {value, label}
+
+async getAreaList() {
+  let data = {
+    schema: get_schema(),
+    table: "mkt_stock_area",
+  };
+  let resp = await request("/select", data, "get");
+  if (resp.length > 0) {
+    this.areaList = convertToDropdownValue(resp, "name", "name");
+  }
+},
+
+async getBranchList() {
+  let data = {
+    schema: get_schema(),
+    table: "branch",
+    conditions: JSON.stringify({ is_active: true }),
+    order_by: ["branch_name asc"],
+  };
+  let resp = await request("/select", data, "get");
+  if (resp.length > 0) {
+    this.branchList = convertToDropdownValue(resp, "id_branch", "branch_name");
+  }
+},
+```
+
+**Gọi đồng thời trong `load_dropdowns()`:**
+```javascript
+async load_dropdowns() {
+  await Promise.all([
+    this.getAreaList(),
+    this.getBranchList(),
+  ]);
+},
+```
+
+**`convertToDropdownValue(arr, valueField, labelField)`** — chuyển array thô thành `[{value, label}]`:
+```javascript
+// Khi value và label dùng cùng field (enum-style)
+convertToDropdownValue(resp, "name", "name")             // → [{ value: "Zone A", label: "Zone A" }]
+
+// Khi value và label khác field
+convertToDropdownValue(resp, "id_branch", "branch_name") // → [{ value: "uuid...", label: "Main Branch" }]
+```
+
+---
+
+### masterApi.js — Pattern
+
+```javascript
+// Get single record — trả về {} nếu không có
+export const get_agreement_by_id = async (id_agreement) => {
+  const result = await request("/select", {
+    schema: get_schema(),
+    table: "v_agreement",
+    conditions: JSON.stringify({ id_agreement }),
+  }, "get");
+  return result.length > 0 ? result[0] : {};
+};
+
+// Get dropdown list — trả về [{value, label}]
+export const get_branch_list_dropdown = async () => {
+  return await request("/select", {
+    schema: get_schema(),
+    table: "branch",
+    columns: ["id_branch as value", "branch_name as label"],
+    conditions: JSON.stringify({ is_active: true }),
+    order_by: ["branch_name asc"],
+  }, "get");
+};
+```
+
+### state.js
+
+```javascript
+state.page_header = t("Agreement Management");  // set page title
+state.username      // current user
+state.usergroup     // user group
+state.language      // current language
+state.loading       // boolean — auto-managed by request()
+state.loading_count // internal counter
+
+get_schema()        // → "qas" | "prd"
+baseurl()           // → base URL
+authorize_menu(path) // → boolean
+menu()              // → menu structure
+```
+
+### utils.js
+
+```javascript
+formatDate(date, "YYYY-MM-DD")         // "2024-01-15"
+formatDate(date, "DD/MM/YYYY")         // "15/01/2024"
+formatDate(date, "DD/MM/YYYY HH:mm")   // "15/01/2024 10:30"
+formatNumber(1234567.89, ".", 2)        // "1.234.567,89"
+check_is_null_or_blank(value)           // true nếu null/undefined/""/[]/{}
+                                        // → dùng cho MỌI loại: string, array, object
+                                        // check_is_null_or_blank("")     → true
+                                        // check_is_null_or_blank([])     → true  ← array rỗng
+                                        // check_is_null_or_blank({})     → true  ← object rỗng
+                                        // check_is_null_or_blank(null)   → true
+                                        // check_is_null_or_blank("abc")  → false
+                                        // check_is_null_or_blank([1])    → false
+check_is_zero(value)                    // true if 0/null/""
+convertToDropdownValue(arr, "id", "name") // [{value, label}]
+show_message("success", "Saved!")
+show_message("error", "Failed!")
+show_message("warning", "Check input!")
+go_to_page("/path", { id: "uuid" })
+go_back("/fallback")
+screen_height()                         // viewport height
+bodautiengviet(str)                     // remove Vietnamese diacritics
+```
+
+### useSession.js
+
+```javascript
+setSession("user_data", response.data, 86400000)  // expire 24h
+const userData = getSession("user_data")
+clearSession()
+refreshSession(86400000)
+```
+
+### useTranslation.js
+
+```javascript
+t("Field Name")        // → translated string
+t("Save")              // → "บันทึก" | "Lưu" | "Save"
+```
+
+> **Lưu ý dùng `t()` trong `data()`:** OK vì Nuxt 3 auto-import composables trước khi `data()` chạy.
+> Dùng bình thường cho column definitions, label mặc định, v.v.
+
+### dayjs — DATETIME STANDARD
+
+> **QUY TẮC BẮT BUỘC**: Mọi biến liên quan đến datetime PHẢI dùng `dayjs()`.
+> KHÔNG dùng `new Date()`, `Date.now()`, `.getFullYear()`, `.getMonth()`, v.v.
+> `dayjs` có sẵn qua composables (auto-import) — dùng trực tiếp, không cần import.
+
+```javascript
+// ── Tạo giá trị mặc định cho filter/date fields ──────────────────
+dayjs().format("YYYY-MM-DD")                            // "2024-03-26"
+dayjs().format("YYYY-MM-DD HH:mm:ss")                   // "2024-03-26 10:30:00"
+dayjs().startOf("month").format("YYYY-MM-DD")           // "2024-03-01"
+dayjs().endOf("month").format("YYYY-MM-DD")             // "2024-03-31"
+dayjs().subtract(1, "month").startOf("month").format("YYYY-MM-DD")  // đầu tháng trước
+dayjs().subtract(1, "month").endOf("month").format("YYYY-MM-DD")    // cuối tháng trước
+
+// ── Lấy thành phần từ ngày ────────────────────────────────────────
+dayjs().year()                                          // 2024  ← THAY new Date().getFullYear()
+dayjs().month() + 1                                     // 3     ← month() trả về 0-indexed
+dayjs().date()                                          // 26
+
+// ── Tính toán, so sánh ───────────────────────────────────────────
+dayjs("2024-01-15").isAfter(dayjs("2024-01-01"))        // true
+dayjs("2024-01-15").isBefore(dayjs("2024-12-31"))       // true
+dayjs("2024-01-15").diff(dayjs("2024-01-01"), "day")    // 14
+dayjs().add(7, "day").format("YYYY-MM-DD")              // 7 ngày sau
+
+// ── Parse và format ──────────────────────────────────────────────
+dayjs("2024-01-15 10:30:00").format("DD/MM/YYYY")       // "15/01/2024"
+dayjs("2024-01-15").isValid()                           // true — check hợp lệ trước dùng
+```
+
+**Pattern trong `data()` — dùng dayjs cho mọi default date:**
+```javascript
+data() {
+  return {
+    from_date: dayjs().startOf("month").format("YYYY-MM-DD"),
+    to_date:   dayjs().endOf("month").format("YYYY-MM-DD"),
+    filter_year:  dayjs().year(),
+    filter_month: dayjs().format("YYYY-MM"),
+  };
+},
+```
+
+---
+
+## 9. API Call Patterns
+
+### Đọc danh sách (dùng view)
+```javascript
+async get_data() {
+  this.rows = await request("/select", {
+    schema: get_schema(),
+    table: "v_agreement",          // LUÔN dùng view, không phải table thô
+    conditions: JSON.stringify({
+      created_at_from: this.from_date,
+      created_at_to: this.to_date,
+      status: this.filter_status || undefined,
+    }),
+    order_by: ["created_at desc"],
+  }, "get");
+},
+```
+
+### Lưu (insert/update)
+```javascript
+async save() {
+  if (!this.validate()) return;
+  this.is_saving = true;
+  await request("/save", {
+    table: "agreement",
+    key_array: ["id_agreement"],
+    ...this.workingObj,
+  });
+  this.is_saving = false;
+  show_message("success", t("Saved successfully"));
+},
+```
+
+### Xóa mềm (soft delete — preferred)
+```javascript
+async delete_record() {
+  await request("/save", {
+    table: "agreement",
+    key_array: ["id_agreement"],
+    id_agreement: this.workingObj.id_agreement,
+    is_deleted: true,
+  });
+  show_message("success", t("Deleted"));
+  this.$router.push("/Agreement/AgreementList");
+},
+```
+
+### Chạy Stored Procedure
+```javascript
+await request("/run_proc", {
+  schema: get_schema(),
+  proc_name: "sp_generate_running_no",
+  params: { prefix: "AGR", year: dayjs().year() },  // ✅ dayjs, KHÔNG dùng new Date()
+});
+```
+
+---
+
+## 10. Pattern: Trang Danh Sách
+
+```vue
+<template>
+  <div>
+    <!-- Filter -->
+    <div class="row mb-3">
+      <div class="col-md-3">
+        <ControlDatetime v-model="from_date" name="From" type="date" />
+      </div>
+      <div class="col-md-3">
+        <ControlDatetime v-model="to_date" name="To" type="date" />
+      </div>
+      <div class="col-md-3">
+        <ControlDropdownlist v-model="filter_status" name="Status" :list="statusList" placeholder="All" />
+      </div>
+      <div class="col-md-3 d-flex align-items-end gap-2">
+        <ControlButton name="Search" type="primary" @onClick="get_data" />
+      </div>
+    </div>
+
+    <!-- Grid -->
+    <GridAG
+      :rows="rows"
+      :columns="columns"
+      :can_add="true"
+      :can_export="true"
+      @onAdd="() => $router.push('/Agreement/AgreementForm')"
+      @onClickDetail="(row) => $router.push({ path: '/Agreement/AgreementForm', query: { id: row.id_agreement } })"
+      @reloadData="get_data"
+    />
+
+    <!-- Floating add button (mobile/alternative) -->
+    <ControlButtonFloat name="New" @clickButtonFloat="() => $router.push('/Agreement/AgreementForm')" />
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      from_date: dayjs().subtract(1, "month").startOf("month").format("YYYY-MM-DD"),
+      to_date: dayjs().endOf("month").format("YYYY-MM-DD"),
+      filter_status: "",
+      statusList: [
+        { value: "draft",    label: "Draft" },
+        { value: "approved", label: "Approved" },
+        { value: "rejected", label: "Rejected" },
+      ],
+      rows: [],
+      columns: [
+        { key: "request_no", title: t("No."),     type: "text",   width: 150 },
+        { key: "created_at", title: t("Date"),    type: "date",   width: 110 },
+        { key: "branch_name",title: t("Branch"),  type: "text",   width: 150 },
+        { key: "amount",     title: t("Amount"),  type: "number", width: 120, aggFunc: "sum" },
+        { key: "status",     title: t("Status"),  type: "text",   width: 100 },
+      ],
+    };
+  },
+  async created() {
+    if (!authorize_menu(this.$route.fullPath)) { this.$router.push(state.homepage); return; }
+    state.page_header = t("Agreement List");
+    await this.get_data();
+  },
+  methods: {
+    async get_data() {
+      this.rows = await request("/select", {
+        schema: get_schema(),
+        table: "v_agreement",
+        conditions: JSON.stringify({
+          from_date: this.from_date,
+          to_date: this.to_date,
+          status: this.filter_status || undefined,
+        }),
+        order_by: ["created_at desc"],
+      }, "get");
+    },
+  },
+};
+</script>
+```
+
+---
+
+## 11. Pattern: Trang Form
+
+```vue
+<template>
+  <div>
+    <ControlBox title="Agreement Information" type="info" :col="12">
+      <div class="row">
+        <div class="col-md-6">
+          <ControlInput v-model="workingObj.agreement_number" name="Agreement Number"
+            :required="true" :disabled="is_locked" />
+        </div>
+        <div class="col-md-6">
+          <ControlDropdownlist v-model="workingObj.id_branch" name="Branch"
+            :list="branchList" :required="true" :disabled="is_locked" />
+        </div>
+        <div class="col-md-4">
+          <ControlDatetime v-model="workingObj.start_date" name="Start Date"
+            type="date" :required="true" :disabled="is_locked" />
+        </div>
+        <div class="col-md-4">
+          <ControlDatetime v-model="workingObj.end_date" name="End Date"
+            type="date" :required="true" :disabled="is_locked"
+            :minDate="workingObj.start_date" />
+        </div>
+        <div class="col-md-4">
+          <ControlInput v-model="workingObj.amount" name="Amount"
+            type="number" :required="true" :disabled="is_locked" />
+        </div>
+        <div class="col-md-12">
+          <ControlInput v-model="workingObj.note" name="Note"
+            type="textarea" :rows="3" :disabled="is_locked" />
+        </div>
+      </div>
+    </ControlBox>
+
+    <!-- Action Buttons -->
+    <div class="row mt-3">
+      <div class="col-12">
+        <ControlButton v-if="workingObj.can_edit" name="Save" type="primary" @onClick="save" />
+        <ControlButton v-if="workingObj.can_submit" name="Submit" type="success" @onClick="submit" />
+        <ControlButton v-if="workingObj.can_approve" name="Approve" type="success"
+          @onClick="show_confirm_approve = true" />
+        <ControlButton v-if="workingObj.can_reject" name="Reject" type="danger"
+          @onClick="show_reject = true" />
+        <ControlButton name="Back" type="secondary" @onClick="$router.go(-1)" />
+      </div>
+    </div>
+
+    <!-- Popups -->
+    <ControlPopupConfirm :visible="show_confirm_delete" title="Delete?"
+      message="Are you sure?" @onConfirm="delete_record" @onClose="show_confirm_delete = false" />
+    <ControlPopupConfirmReject :visible="show_confirm_approve" title="Approve"
+      @onConfirm="on_approve" @onClose="show_confirm_approve = false" />
+    <ControlPopupReject :visible="show_reject" title="Reject"
+      @onConfirm="on_reject" @onClose="show_reject = false" />
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      workingObj: { id_agreement: "", agreement_number: "", id_branch: "",
+                    start_date: "", end_date: "", amount: 0, note: "",
+                    can_edit: true, can_submit: false, can_approve: false,
+                    can_reject: false, is_deleted: false },
+      branchList: [],
+      show_confirm_delete: false,
+      show_confirm_approve: false,
+      show_reject: false,
+    };
+  },
+  computed: {
+    is_locked() { return !this.workingObj.can_edit; },
+  },
+  async created() {
+    if (!authorize_menu(this.$route.fullPath)) { this.$router.push(state.homepage); return; }
+    state.page_header = t("Agreement Form");
+    const id = this.$route.query.id;
+    await Promise.all([
+      id ? this.load_by_id(id) : Promise.resolve(),
+      this.load_dropdowns(),
+    ]);
+  },
+  methods: {
+    async load_by_id(id) {
+      this.workingObj = await get_agreement_by_id(id);
+    },
+    async load_dropdowns() {
+      this.branchList = await get_branch_list_dropdown();
+    },
+    async save() {
+      if (!this.validate()) return;
+      await request("/save", { table: "agreement", key_array: ["id_agreement"], ...this.workingObj });
+      show_message("success", t("Saved successfully"));
+    },
+    async delete_record() {
+      this.show_confirm_delete = false;
+      await request("/save", { table: "agreement", key_array: ["id_agreement"],
+        id_agreement: this.workingObj.id_agreement, is_deleted: true });
+      this.$router.push("/Agreement/AgreementList");
+    },
+    async on_approve(reason, is_adhoc, is_onplan) {
+      this.show_confirm_approve = false;
+      await request_origin("/api/agreement/approve", {
+        schema: get_schema(),
+        id_agreement: this.workingObj.id_agreement,
+        username: state.username,   // ✅ luôn truyền username cho custom approve endpoints
+        reason, is_adhoc, is_onplan,
+      });
+      await this.load_by_id(this.workingObj.id_agreement);
+    },
+    async on_reject(reason, is_adhoc, is_onplan) {
+      this.show_reject = false;
+      await request("/save", { table: "agreement", key_array: ["id_agreement"],
+        id_agreement: this.workingObj.id_agreement, status: "rejected", reject_reason: reason });
+      await this.load_by_id(this.workingObj.id_agreement);
+    },
+    validate() {
+      const required = [
+        { key: "agreement_number", name: t("Agreement Number") },
+        { key: "id_branch",        name: t("Branch") },
+        { key: "start_date",       name: t("Start Date") },
+      ];
+      for (const f of required) {
+        if (check_is_null_or_blank(this.workingObj[f.key])) {
+          show_message("error", `${f.name} ${t("is required")}`); return false;
+        }
+      }
+      return true;
+    },
+  },
+};
+</script>
+```
+
+---
+
+## 12. Routing & Navigation
+
+```javascript
+// Navigate with query
+this.$router.push({ path: "/Agreement/AgreementForm", query: { id: row.id_agreement } });
+
+// Get params
+const id = this.$route.query.id;
+
+// Back
+this.$router.go(-1);
+this.$router.push("/Agreement/AgreementList");
+
+// Utility (từ utils.js — auto-imported)
+go_to_page("/Agreement/AgreementForm", { id: "uuid" });
+go_back("/Agreement/AgreementList");
+```
+
+---
+
+## 13. Validation Pattern
+
+```javascript
+validate() {
+  // Required fields
+  const required = [
+    { key: "agreement_number", name: t("Agreement Number") },
+    { key: "id_branch",        name: t("Branch") },
+    { key: "start_date",       name: t("Start Date") },
+  ];
+  for (const f of required) {
+    if (check_is_null_or_blank(this.workingObj[f.key])) {
+      show_message("error", `${f.name} ${t("is required")}`);
+      return false;
+    }
+  }
+
+  // Business rules
+  if (this.workingObj.end_date && this.workingObj.start_date) {
+    if (this.workingObj.end_date < this.workingObj.start_date) {
+      show_message("error", t("End date must be after start date"));
+      return false;
+    }
+  }
+
+  if (check_is_zero(this.workingObj.amount)) {
+    show_message("error", t("Amount must be greater than 0"));
+    return false;
+  }
+
+  return true;
+},
+```
+
+---
+
+## 14. Đề Xuất Components Mới
+
+> **Lưu ý:** Chỉ liệt kê những component thực sự chưa có.
+> - Number input → dùng `ControlInput type="number"`
+> - Search input → dùng `ControlInput type="search"`
+> - Radio group → dùng `ControlCheckbox` với layout ngang là đủ
+
+---
+
+### 🔮 Tạo khi thực sự cần dùng
+
+#### `ControlStatusBadge` — Hiển thị status với màu sắc theo map
+```vue
+<ControlStatusBadge :status="row.status"
+  :map="{
+    draft:    { label: 'Draft',    color: 'gray'  },
+    approved: { label: 'Approved', color: 'green' },
+    rejected: { label: 'Rejected', color: 'red'   },
+  }"
+/>
+```
+
+#### `ControlFileList` — Hiển thị + download danh sách files đã upload
+```vue
+<ControlFileList
+  :files="workingObj.file_list"
+  :can_delete="workingObj.can_edit"
+  @onDelete="remove_file"
+/>
+```
+
+#### `ControlSummaryCard` — KPI/summary card cho dashboard
+```vue
+<ControlSummaryCard title="Total Amount" :value="total_amount" format="number" color="primary" />
+```
+
+#### `GridCardList` — Hiển thị dạng card thay vì table (mobile / dashboard)
+```vue
+<GridCardList :rows="rows" :fields="['name', 'amount', 'status']" @onCardClick="go_to_detail" />
+```