@ngockhoale/ukit 1.1.6

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

@@ -0,0 +1,520 @@
+# DuraOne Workflow Reference
+## Luồng Hoạt Động Toàn Bộ Dự Án
+
+> Mô tả cách một tính năng đi từ ý tưởng → SQL → Backend → Frontend → Deploy.
+> Đọc file này khi thiết kế tính năng mới hoặc cần hiểu toàn bộ data flow.
+
+---
+
+## MỤC LỤC
+1. [Kiến Trúc Tổng Quan](#1-kiến-trúc-tổng-quan)
+2. [Data Flow: FE → BE → DB](#2-data-flow)
+3. [Luồng Tạo Tính Năng Mới](#3-luồng-tạo-tính-năng-mới)
+4. [Luồng CRUD Chuẩn](#4-luồng-crud-chuẩn)
+5. [Luồng Approval / Workflow Status](#5-luồng-approval--workflow-status)
+6. [Luồng Upload File](#6-luồng-upload-file)
+7. [Luồng Authentication](#7-luồng-authentication)
+8. [Luồng Deploy QAS → PRD](#8-luồng-deploy-qas--prd)
+9. [Environment Switch](#9-environment-switch)
+10. [Checklist Tạo Tính Năng](#10-checklist-tạo-tính-năng)
+
+---
+
+## 1. Kiến Trúc Tổng Quan
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     BROWSER / MOBILE                         │
+│                   Nuxt 3 (Vue 3 Options API)                 │
+│                   - pages/                                   │
+│                   - components/Control, Grid, Panel          │
+│                   - composables/ (auto-imported)             │
+└──────────────────────────┬──────────────────────────────────┘
+                           │ HTTPS + GZIP compression
+                           │ Axios → useRequest.js
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    PYTHON SANIC API                          │
+│                   app.py + mainapp/lib/                      │
+│                                                             │
+│   Generic:  /api/select /api/save /api/delete /api/run_proc │
+│   Custom:   /api/[feature]/[action]                         │
+│   Auth:     /user/login                                     │
+└──────────────────────────┬──────────────────────────────────┘
+                           │ asyncpg (connection pool + SSL)
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    POSTGRESQL                               │
+│   Schema: qas (test)  |  Schema: prd (production)          │
+│                                                             │
+│   Tables    — raw data storage                              │
+│   Views     — v_* (read layer, computed fields, joins)      │
+│   Functions — fn_* (filtered queries, complex logic)        │
+│   Procs     — sp_* (running numbers, cascades, audits)     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Data Flow
+
+### READ (FE → DB)
+
+```
+Vue Page (created/mounted)
+  │
+  ├── get_data() gọi request("/select", data, "get")
+  │     data = { schema: get_schema(), table: "v_entity", conditions: JSON.stringify({...}), order_by: [...] }
+  │
+  ├── useRequest.js: GZIP compress → Axios GET → Sanic /api/select
+  │
+  ├── Sanic: parse request → build SQL → asyncpg.fetch()
+  │     SELECT * FROM {schema}.{table} WHERE {conditions} ORDER BY {order_by}
+  │
+  ├── PostgreSQL: execute query on view → return rows
+  │
+  ├── Sanic: GZIP compress response → return JSON
+  │
+  └── Vue: decompress → this.rows = result
+```
+
+### WRITE (FE → DB)
+
+```
+Vue Page (save button click)
+  │
+  ├── validate() — check required fields
+  │
+  ├── request("/save", { table, key_array, ...workingObj })
+  │
+  ├── Sanic /api/save:
+  │     IF id_field == '': DB_Helper.insert(table, obj)   ← uuid varchar default ''
+  │     IF id_field != '': DB_Helper.update(table, obj, key_field)
+  │
+  └── PostgreSQL: INSERT or UPDATE → return new id
+```
+
+### RUN PROCEDURE (FE → DB)
+
+```
+request("/run_proc", { schema, proc_name, params: { ... } })
+  │
+  ├── Sanic /api/run_proc
+  │
+  └── PostgreSQL: SELECT * FROM {schema}.{proc_name}($1, $2, ...)
+```
+
+---
+
+## 3. Luồng Tạo Tính Năng Mới
+
+### Bước 1: Thiết Kế DB Layer
+
+```
+a) Tạo/update table nếu cần (xem chi tiết template tại references/sql.md → mục 7):
+   -- Chỉ dùng varchar / numeric / boolean. Không NULL, luôn có default.
+   create table qas.[entity] (
+     id_[entity] varchar default uuid_in(overlay(
+         overlay(md5(random()::text || ':' || random()::text) placing '4' from 13) placing
+         to_hex(floor(random() * (11 - 8 + 1) + 8)::int)::text from 17)::cstring)
+         constraint [entity]_pkey primary key,
+     -- business fields (varchar/numeric/boolean)
+     is_deleted  boolean default false,
+     created_by  varchar default '',
+     created_at  varchar default TO_CHAR(date_trunc('second', now() AT TIME ZONE 'Asia/Ho_Chi_Minh'),
+                                         'YYYY-MM-DD HH24:MI:SS')::character varying
+   );
+
+b) Tạo view (luôn cần):
+   CREATE OR REPLACE VIEW qas.v_[entity] AS
+   SELECT
+     e.*,
+     -- computed fields
+     -- joined fields
+     -- boolean flags (can_edit, is_locked, etc.)
+     -- json aggregation cho sub-records
+   FROM qas.[entity] e
+   LEFT JOIN ... ON ...
+   WHERE e.is_deleted = FALSE;
+
+c) Tạo function nếu cần filter phức tạp:
+   CREATE OR REPLACE FUNCTION qas.fn_get_[entity](_param VARCHAR)
+   RETURNS SETOF qas.v_[entity] AS ...
+
+d) Tạo stored proc nếu cần business logic:
+   CREATE OR REPLACE FUNCTION qas.sp_[action]_[entity](_id VARCHAR)
+   RETURNS JSON AS ...
+
+e) Mirror sang prd schema (thay qas. → prd.)
+```
+
+### Bước 2: Backend (chỉ khi cần custom)
+
+```
+Nếu generic /api/select, /api/save, /api/delete đủ dùng → SKIP
+
+Nếu cần custom:
+a) Thêm route vào mainapp/lib/v2_api.py:
+   @b_api.route("/api/[feature]/[action]", methods=["POST"])
+   async def [action](request):
+       ...
+
+b) Business logic trong route handler
+c) Gọi db.execute() hoặc db.execute_void()
+```
+
+### Bước 3: Frontend
+
+```
+a) masterApi.js — thêm get functions:
+   export const get_[entity]_by_id = async (id) => { ... }
+   export const get_[entity]_list_dropdown = async () => { ... }
+
+b) Tạo page files:
+   pages/[Feature]/[EntityList].vue    — danh sách
+   pages/[Feature]/[EntityForm].vue    — form detail/edit
+
+c) Trong page:
+   - created(): auth check → load data
+   - data(): workingObj, rows, dropdowns, flags
+   - computed: is_locked, can_save, etc.
+   - methods: get_data, save, validate, load_dropdowns
+
+d) Reuse Control components (KHÔNG tự tạo input raw)
+e) Reuse GridAG cho danh sách
+```
+
+### Bước 4: Route & Menu
+
+```
+a) Thêm menu item trong state.js → menu()
+b) Thêm authorization rule nếu cần
+c) Test auth redirect
+```
+
+---
+
+## 4. Luồng CRUD Chuẩn
+
+### CREATE (New Record)
+
+```
+FE: workingObj.id_[entity] = ''  (default trong data() — uuid varchar)
+    ↓ user fills form
+    ↓ save() → validate() → request("/save", { id_[entity]: '', ... })
+BE: detect id == '' → DB_Helper.insert()
+DB: INSERT → uuid auto-generated → RETURNING id_[entity]
+FE: redirect to form với id mới hoặc show success
+```
+
+### READ (Load Record)
+
+```
+FE: created() → load_by_id(this.$route.query.id)
+    ↓ get_[entity]_by_id(id) trong masterApi.js
+    ↓ request("/select", { table: "v_[entity]", conditions: { id_[entity]: id } }, "get")
+DB: SELECT * FROM qas.v_[entity] WHERE id_[entity] = ?
+FE: this.workingObj = result[0] || {}
+```
+
+### UPDATE (Save Existing)
+
+```
+FE: workingObj.id_[entity] != '' (loaded từ DB — uuid string)
+    ↓ user edits
+    ↓ save() → validate() → request("/save", { id_[entity]: 'uuid-...', ... })
+BE: detect id != '' → DB_Helper.update()
+DB: UPDATE [entity] SET ... WHERE id_[entity] = 'uuid-...'
+FE: show_message("success", "Saved!")
+```
+
+### DELETE (Soft Delete — preferred)
+
+```
+FE: confirm dialog → onConfirmDelete()
+    ↓ request("/save", { table: "[entity]", key_array: ["id_[entity]"], id_[entity]: id, is_deleted: true })
+DB: UPDATE [entity] SET is_deleted = TRUE WHERE id_[entity] = ?
+FE: reload list
+```
+
+---
+
+## 5. Luồng Approval / Workflow Status
+
+Pattern cho các tính năng có trạng thái (draft → pending → approved/rejected):
+
+```
+Status Flow:
+  draft ──► pending_approval ──► approved
+                │                   │
+                └──► rejected ◄─────┘
+                         │
+                         └──► draft (resubmit)
+```
+
+**DB Design:**
+```sql
+-- View: boolean flags từ status
+CASE WHEN status = 'draft' THEN TRUE ELSE FALSE END AS can_edit,
+CASE WHEN status = 'draft' THEN TRUE ELSE FALSE END AS can_submit,
+CASE WHEN status = 'pending_approval' THEN TRUE ELSE FALSE END AS can_approve,
+CASE WHEN status = 'approved' THEN TRUE ELSE FALSE END AS is_locked,
+```
+
+**FE Pattern:**
+```javascript
+computed: {
+  is_locked() {
+    return !this.workingObj.can_edit;
+  },
+  show_submit_btn() {
+    return this.workingObj.can_submit;
+  },
+  show_approve_btn() {
+    return this.workingObj.can_approve;
+  },
+},
+methods: {
+  async submit() {
+    await request("/save", {
+      table: "[entity]",
+      key_array: ["id_[entity]"],
+      id_[entity]: this.workingObj.id_[entity],
+      status: "pending_approval",
+    });
+    await this.load_by_id(this.workingObj.id_[entity]);  // reload
+  },
+  async approve() {
+    await request_origin("/api/[entity]/approve", {
+      id_[entity]: this.workingObj.id_[entity],
+      schema: get_schema(),
+      username: state.username,  // ✅ luôn truyền username cho custom approve endpoints
+    });
+    await this.load_by_id(this.workingObj.id_[entity]);
+  },
+}
+```
+
+---
+
+## 6. Luồng Upload File
+
+```
+FE:
+  1. User selects file → fileInput change event
+  2. preview (optional)
+  3. upload_file(file, folder)
+     ↓ FormData.append("file", file)
+     ↓ requestForm("/api/upload_to_cloud", formData)
+  4. save URL vào workingObj.file_url
+
+BE:
+  /api/upload_to_cloud
+  ↓ request.files.get("file")
+  ↓ google_storage.upload_blob(...)
+  ↓ return { url: "https://storage.googleapis.com/..." }
+
+FE after upload:
+  workingObj.file_url = result.url
+  ↓ save workingObj (URL stored in DB)
+```
+
+**Multiple Files Pattern:**
+```javascript
+data() {
+  return {
+    fileListToUpload: {
+      0: [],  // indexed by media type
+      1: [],
+      2: [],
+    }
+  }
+},
+methods: {
+  async upload_all_files() {
+    for (const [index, files] of Object.entries(this.fileListToUpload)) {
+      for (const file of files) {
+        const url = await this.upload_file(file, `entity/${index}`);
+        await request("/save", {
+          table: "[entity]_file",
+          key_array: ["id_file"],
+          id_file: '',
+          id_entity: this.workingObj.id_entity,
+          file_type: index,
+          file_url: url,
+        });
+      }
+    }
+  }
+}
+```
+
+---
+
+## 7. Luồng Authentication
+
+```
+Login:
+  FE: ms_authen/login.vue → requestLogin({ username, password })
+  BE: /user/login → verify → return { token, username, usergroup, ... }
+  FE: setSession("user_data", response.data) → redirect to homepage
+
+Every Request:
+  useRequest.js: read session → attach token to headers
+  Sanic middleware: verify token
+  If invalid: return 401 → FE redirect to login
+
+Per-page Auth:
+  created() {
+    if (!authorize_menu(this.$route.fullPath)) {
+      this.$router.push(state.homepage);
+    }
+  }
+
+authorize_menu():
+  - reads state.usergroup
+  - checks menu() structure for allowed paths per group
+  - returns true/false
+```
+
+---
+
+## 8. Luồng Deploy QAS → PRD
+
+```
+1. Test on QAS:
+   - Run SQL on qas schema: psql $QAS -f *.sql
+   - Deploy BE to QAS server: ./deploy_qas.sh
+   - Deploy FE to QAS: yarn generate → upload to GCS/CDN
+   - Test all features
+
+2. Deploy to PRD:
+   - Run SQL on prd schema (same files, different schema)
+   - Deploy BE: ./deploy_prd.sh
+   - Deploy FE: APP_ENV=prd yarn generate → upload
+   - Smoke test
+
+3. Rollback khi deploy lỗi:
+   SQL (view / function / stored proc):
+     - Chạy lại file SQL version cũ — CREATE OR REPLACE nên safe
+     - psql $PRD_CONN -f SQL/duraone/prd/view/v_entity_OLD.sql
+
+   SQL (ALTER TABLE — table schema change):
+     ⚠️ PHẢI backup trước khi ALTER:
+       pg_dump -t prd.table_name $PRD_CONN > backup_table_name_$(date +%Y%m%d).sql
+     Nếu lỗi → reverse bằng ALTER TABLE ngược lại
+
+   BE (Docker / Cloud Run):
+     Rollback về image tag trước:
+       gcloud run deploy duraone-prd --image=gcr.io/project/duraone-prd:PREV_TAG
+
+   FE (GCS / CDN):
+     Re-upload build cũ từ artifact storage hoặc re-deploy commit trước
+
+Deploy Script Pattern:
+  deploy_qas.sh:
+    export APP_ENV=qas
+    docker build -t duraone-qas .
+    docker push gcr.io/project/duraone-qas
+    gcloud run deploy duraone-qas --image=...
+
+SQL Deploy Pattern:
+  # Apply theo thứ tự: table → view → function → stored proc
+  psql $CONN -f SQL/duraone/qas/view/v_entity.sql
+  psql $CONN -f SQL/duraone/qas/function/fn_get_entity.sql
+  psql $CONN -f SQL/duraone/qas/store/sp_action_entity.sql
+```
+
+---
+
+## 9. Environment Switch
+
+```javascript
+// FE: state.js
+export const get_schema = () => {
+  // ✅ Ưu tiên 1: Nuxt runtime config (RECOMMENDED — không phụ thuộc hostname)
+  //    Setup trong nuxt.config.ts:
+  //      runtimeConfig: { public: { appEnv: process.env.APP_ENV || 'qas' } }
+  //    Deploy PRD: set env var APP_ENV=prd
+  try {
+    const runtimeConfig = useRuntimeConfig();
+    if (runtimeConfig?.public?.appEnv === 'prd') return 'prd';
+  } catch (_) { /* ignore nếu useRuntimeConfig chưa sẵn */ }
+
+  // Ưu tiên 2: Hostname detection (fallback — chỉ đáng tin khi domain chứa "prd")
+  // ⚠️ CẢNH BÁO: Nếu domain PRD không chứa "prd" hay "production" → sẽ trả về "qas"
+  //    → query sai schema mà không có lỗi. Luôn set APP_ENV thay vì dựa vào hostname.
+  const hostname = window.location.hostname;
+  if (hostname.includes("prd") || hostname.includes("production")) {
+    return "prd";
+  }
+  return "qas";  // default
+};
+
+export const baseurl = () => {
+  const hostname = window.location.hostname;
+  if (hostname === "localhost" || hostname === "127.0.0.1") {
+    return "http://localhost:8000/";
+  }
+  return "/";  // relative path cho production
+};
+```
+
+```typescript
+// nuxt.config.ts — cần thêm config này để get_schema() hoạt động đúng trên PRD
+export default defineNuxtConfig({
+  runtimeConfig: {
+    public: {
+      appEnv: process.env.APP_ENV || 'qas',  // set APP_ENV=prd khi deploy PRD
+    },
+  },
+});
+```
+
+```python
+# BE: config.py
+def get_schema() -> str:
+    env = os.environ.get("APP_ENV", "local")
+    return "prd" if env == "prd" else "qas"
+```
+
+---
+
+## 10. Checklist Tạo Tính Năng
+
+Dùng checklist này mỗi khi tạo tính năng mới:
+
+### DB Layer
+- [ ] Table đã có `id_[entity]`, audit fields (`created_by`, `created_at`, `is_deleted`)
+- [ ] View `qas.v_[entity]` có `COALESCE` cho numeric, boolean flags (`can_edit`, `is_locked`)
+- [ ] View có JSON aggregation cho sub-records nếu cần
+- [ ] Function `fn_get_*` nếu cần filter phức tạp
+- [ ] Stored proc `sp_*` nếu cần running number / cascade
+- [ ] Mirror sang `prd` schema
+
+### Backend
+- [ ] Generic endpoints đủ dùng? (thường là có)
+- [ ] Custom endpoint nếu cần business logic đặc biệt
+- [ ] Error handling trả về `{ success, message }`
+
+### Frontend
+- [ ] `masterApi.js` có `get_[entity]_by_id()` và `get_[entity]_list_dropdown()`
+- [ ] List page: filter + GridAG + on_row_click navigate
+- [ ] Form page: workingObj, validate(), save(), is_locked computed
+- [ ] Auth check ở `created()`
+- [ ] `state.page_header` set ở `created()`
+- [ ] Dùng Control components (KHÔNG raw input)
+- [ ] Dropdown data format: `{ value, label }` — load qua `get*List()` pattern với `convertToDropdownValue()`
+- [ ] **Datetime dùng `dayjs()`** — KHÔNG dùng `new Date()`, `Date.now()`, `.getFullYear()`
+- [ ] Boolean flags từ DB (`can_edit`, `is_locked`) drive UI state
+- [ ] File upload nếu cần
+
+### Menu & Auth
+- [ ] Menu item thêm vào `state.js → menu()`
+- [ ] Permission rules cho usergroup
+
+### Test
+- [ ] Test trên QAS schema
+- [ ] Test create, read, update, delete
+- [ ] Test approval flow nếu có
+- [ ] Test file upload nếu có

package/templates/.claude/skills/executing-plans/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: executing-plans
+description: Use when partner provides a complete implementation plan to execute in controlled batches with review checkpoints - loads plan, reviews critically, executes tasks in batches, reports for review between batches
+---
+
+# Executing Plans
+
+## Overview
+
+Load plan, review critically, execute tasks in batches, report for review between batches.
+
+**Core principle:** Batch execution with checkpoints for architect review.
+
+**Announce at start:** "I'm using the executing-plans skill to implement this plan."
+
+## The Process
+
+### Step 1: Load and Review Plan
+1. Read plan file
+2. Review critically - identify any questions or concerns about the plan
+3. If concerns: Raise them with your human partner before starting
+4. If no concerns: Create TodoWrite and proceed
+
+### Step 2: Execute Batch
+**Default: First 3 tasks**
+
+For each task:
+1. Mark as in_progress
+2. Follow each step exactly (plan has bite-sized steps)
+3. Run verifications as specified
+4. Mark as completed
+
+### Step 3: Report
+When batch complete:
+- Show what was implemented
+- Show verification output
+- Say: "Ready for feedback."
+
+### Step 4: Continue
+Based on feedback:
+- Apply changes if needed
+- Execute next batch
+- Repeat until complete
+
+### Step 5: Complete Development
+
+After all tasks complete and verified:
+- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
+- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
+- Follow that skill to verify tests, present options, execute choice
+
+## When to Stop and Ask for Help
+
+**STOP executing immediately when:**
+- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
+- Plan has critical gaps preventing starting
+- You don't understand an instruction
+- Verification fails repeatedly
+
+**Ask for clarification rather than guessing.**
+
+## When to Revisit Earlier Steps
+
+**Return to Review (Step 1) when:**
+- Partner updates the plan based on your feedback
+- Fundamental approach needs rethinking
+
+**Don't force through blockers** - stop and ask.
+
+## Remember
+- Review plan critically first
+- Follow plan steps exactly
+- Don't skip verifications
+- Reference skills when plan says to
+- Between batches: just report and wait
+- Stop when blocked, don't guess