@ngockhoale/ukit 1.1.6

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

@@ -0,0 +1,631 @@
+# DuraOne SQL Reference
+## PostgreSQL — Views, Functions, Stored Procedures
+
+> Nguồn sự thật cho phong cách viết SQL của LeNK.
+> Database: PostgreSQL với 2 schema: `qas` (test) và `prd` (production)
+
+---
+
+## MỤC LỤC
+1. [Schema Organization](#1-schema-organization)
+2. [Data Types — Quy Tắc Bắt Buộc](#2-data-types)
+3. [Naming Conventions](#3-naming-conventions)
+4. [View Pattern (v_)](#4-view-pattern)
+5. [Function Pattern (fn_)](#5-function-pattern)
+6. [Stored Procedure Pattern (sp_)](#6-stored-procedure-pattern)
+7. [Table Design Conventions](#7-table-design-conventions)
+8. [Common SQL Patterns](#8-common-sql-patterns)
+9. [File Organization](#9-file-organization)
+
+---
+
+## 1. Schema Organization
+
+```
+PostgreSQL Database: duraone
+├── qas (schema — QA/Testing)
+│   ├── Tables
+│   ├── Views:     v_*
+│   ├── Functions: fn_*
+│   └── Procedures: sp_*
+│
+└── prd (schema — Production)
+    ├── Tables         (mirrors qas)
+    ├── Views:     v_*
+    ├── Functions: fn_*
+    └── Procedures: sp_*
+```
+
+**Quy tắc:**
+- Tất cả SQL objects LUÔN có schema prefix: `qas.` hoặc `prd.`
+- Không viết SQL mà không có schema prefix
+- Khi deploy, chạy SQL trên cả 2 schema (qas trước, prd sau)
+- View/Function/Procedure trong qas và prd có cùng tên, chỉ khác schema prefix
+
+---
+
+## 2. Data Types — QUY TẮC BẮT BUỘC
+
+**CHỈ dùng 3 data type này. KHÔNG dùng bất kỳ loại nào khác:**
+
+| Type | Khi nào dùng | Default |
+|------|-------------|---------|
+| `varchar` | Text, ngày tháng, UUID, enum, mọi thứ dạng chuỗi | `default ''` |
+| `numeric` | Số (integer, decimal, float, quantity) | `default 0` |
+| `boolean` | True/false flags | `default false` |
+
+**KHÔNG ĐƯỢC dùng:**
+- ❌ `integer`, `int`, `bigint`, `serial` — dùng `numeric` thay thế
+- ❌ `date`, `timestamp`, `timestamptz`, `datetime` — dùng `varchar` với format string
+- ❌ `text` — dùng `varchar`
+- ❌ `jsonb`, `json` — dùng `varchar` chứa JSON string
+- ❌ `uuid` — dùng `varchar` với UUID generator default
+- ❌ `NULL` — LUÔN có default value: `''` cho varchar, `0` cho numeric, `false` cho boolean
+
+**Ngày tháng lưu dạng varchar:**
+```sql
+-- created_at: varchar với timezone Asia/Ho_Chi_Minh
+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
+-- → lưu thành string "2024-01-15 10:30:00"
+```
+
+---
+
+## 3. Naming Conventions
+
+| Loại Object | Prefix | Ví dụ |
+|------------|--------|-------|
+| View | `v_` | `v_agreement`, `v_clearance_request` |
+| Function | `fn_` | `fn_get_agreement`, `fn_get_review_list` |
+| Stored Procedure | `sp_` | `sp_generate_running_no`, `sp_after_approve` |
+| Table | snake_case | `agreement`, `clearance_request`, `user` |
+| Global Function | `glb_fn_` | `glb_fn_convert_query_to_json` |
+| Column | snake_case | `id_agreement`, `created_at`, `is_active` |
+| ID Column | `id_` prefix | `id_agreement`, `id_user`, `id_type` |
+| Boolean Column | `is_`/`can_`/`has_` | `is_active`, `can_approve`, `has_file` |
+
+**File naming (SQL files):**
+```
+mainapp/SQL/duraone/qas/
+├── view/
+│   └── v_agreement.sql
+├── function/
+│   └── fn_get_agreement.sql
+└── store/
+    └── sp_generate_running_no.sql
+```
+
+---
+
+## 4. View Pattern (v_)
+
+View là layer chính để FE đọc data — luôn dùng view thay vì query raw table.
+
+```sql
+-- ──────────────────────────────────────────────
+-- TEMPLATE: View cơ bản
+-- ──────────────────────────────────────────────
+CREATE OR REPLACE VIEW qas.v_agreement AS
+SELECT
+    -- Primary key
+    a.id_agreement,
+
+    -- Core fields
+    a.agreement_number,
+    a.status,
+
+    -- Date fields — substring để lấy date part
+    a.created_at,
+    SUBSTRING(a.created_at::text, 1, 10) AS created_date,
+
+    -- Computed numeric — LUÔN COALESCE để tránh null
+    COALESCE(a.amount, 0)::numeric(16, 2) AS amount,
+    COALESCE(a.discount, 0)::numeric(16, 2) AS discount,
+    COALESCE(a.amount, 0) - COALESCE(a.discount, 0) AS net_amount,
+
+    -- Boolean flags — computed từ business logic
+    CASE WHEN a.status IN ('draft', 'rejected') THEN TRUE ELSE FALSE END AS can_edit,
+    CASE WHEN a.status = 'approved' THEN TRUE ELSE FALSE END AS is_locked,
+    FALSE AS can_delete,
+
+    -- Joined fields
+    b.branch_name,
+    u.fullname AS created_by_name,
+
+    -- JSON aggregation cho nested data
+    COALESCE(
+        (SELECT json_agg(json_build_object(
+            'id_media', m.id_media,
+            'media_name', m.media_name,
+            'amount', COALESCE(m.amount, 0)
+        ))
+        FROM qas.agreement_media m
+        WHERE m.id_agreement = a.id_agreement),
+        '[]'::json
+    ) AS media_list,
+
+    -- Count
+    (SELECT COUNT(*) FROM qas.agreement_media m
+     WHERE m.id_agreement = a.id_agreement) AS media_count
+
+FROM qas.agreement a
+LEFT JOIN qas.branch b ON b.id_branch = a.id_branch
+LEFT JOIN qas.user u ON u.username = a.created_by
+WHERE a.is_deleted = FALSE  -- soft delete pattern
+ORDER BY a.created_at DESC;
+```
+
+**Conventions trong View:**
+```sql
+-- ✅ LUÔN COALESCE numeric
+COALESCE(field, 0)::numeric(16, 2)
+
+-- ✅ LUÔN có boolean flags
+TRUE AS can_edit,
+FALSE AS can_delete,
+CASE WHEN status = 'approved' THEN TRUE ELSE FALSE END AS is_approved,
+
+-- ✅ Date format
+SUBSTRING(created_at::text, 1, 10) AS created_date  -- YYYY-MM-DD
+
+-- ✅ NULL-safe string concat
+COALESCE(first_name, '') || ' ' || COALESCE(last_name, '') AS full_name
+
+-- ✅ Soft delete filter trong view
+WHERE is_deleted = FALSE
+
+-- ✅ JSON array cho 1-to-many
+COALESCE(json_agg(...) FILTER (WHERE id IS NOT NULL), '[]'::json) AS items
+```
+
+---
+
+## 5. Function Pattern (fn_)
+
+Function dùng khi cần filter phức tạp hoặc business logic:
+
+```sql
+-- ──────────────────────────────────────────────
+-- TEMPLATE: Function trả về SETOF view
+-- ──────────────────────────────────────────────
+CREATE OR REPLACE FUNCTION qas.fn_get_agreement(
+    _username       VARCHAR DEFAULT NULL,
+    _from_date      DATE    DEFAULT NULL,
+    _to_date        DATE    DEFAULT NULL,
+    _status         VARCHAR DEFAULT NULL
+)
+RETURNS SETOF qas.v_agreement AS
+$$
+DECLARE
+    v_query TEXT;
+    v_conditions TEXT := 'WHERE TRUE';
+BEGIN
+    -- Build dynamic conditions
+    IF _username IS NOT NULL AND _username <> '' THEN
+        v_conditions := v_conditions || format(' AND created_by = %L', _username);
+    END IF;
+
+    IF _from_date IS NOT NULL THEN
+        v_conditions := v_conditions || format(' AND created_date >= %L', _from_date);
+    END IF;
+
+    IF _to_date IS NOT NULL THEN
+        v_conditions := v_conditions || format(' AND created_date <= %L', _to_date);
+    END IF;
+
+    IF _status IS NOT NULL AND _status <> '' THEN
+        v_conditions := v_conditions || format(' AND status = %L', _status);
+    END IF;
+
+    v_query := 'SELECT * FROM qas.v_agreement ' || v_conditions || ' ORDER BY created_at DESC';
+
+    RETURN QUERY EXECUTE v_query;
+END;
+$$ LANGUAGE plpgsql;
+
+
+-- ──────────────────────────────────────────────
+-- TEMPLATE: Function trả về SETOF TABLE (custom shape)
+-- ──────────────────────────────────────────────
+CREATE OR REPLACE FUNCTION qas.fn_get_summary_by_branch(
+    _from_date VARCHAR,
+    _to_date   VARCHAR
+)
+RETURNS TABLE(
+    id_branch       VARCHAR,
+    branch_name     VARCHAR,
+    total_amount    NUMERIC(16, 2),
+    total_count     NUMERIC
+) AS
+$$
+BEGIN
+    RETURN QUERY
+        SELECT
+            b.id_branch,
+            b.branch_name,
+            COALESCE(SUM(a.amount), 0)::numeric(16, 2) AS total_amount,
+            COUNT(a.id_agreement)::numeric AS total_count
+        FROM qas.branch b
+        LEFT JOIN qas.agreement a
+            ON a.id_branch = b.id_branch
+            AND a.created_date BETWEEN _from_date AND _to_date
+            AND a.is_deleted = FALSE
+        GROUP BY b.id_branch, b.branch_name
+        ORDER BY b.branch_name;
+END;
+$$ LANGUAGE plpgsql;
+```
+
+**Conventions trong Function:**
+```sql
+-- ✅ Parameter prefix _
+_username VARCHAR
+
+-- ✅ Variable prefix v_
+v_query TEXT;
+v_count NUMERIC;
+
+-- ✅ Default NULL cho optional params
+_status VARCHAR DEFAULT NULL
+
+-- ✅ Guard với IS NOT NULL AND <> ''
+IF _param IS NOT NULL AND _param <> '' THEN
+
+-- ✅ format() cho dynamic SQL (SQL injection safe)
+format(' AND field = %L', _value)
+format(' AND id = %s', _id::text)
+
+-- ✅ RETURN QUERY EXECUTE cho dynamic
+RETURN QUERY EXECUTE v_query;
+
+-- ✅ RETURN QUERY cho static
+RETURN QUERY SELECT ... FROM ...;
+```
+
+---
+
+## 6. Stored Procedure Pattern (sp_)
+
+Dùng cho business operations (running numbers, audit logs, cascade updates):
+
+```sql
+-- ──────────────────────────────────────────────
+-- TEMPLATE: Generate running number
+-- ──────────────────────────────────────────────
+CREATE OR REPLACE FUNCTION qas.sp_generate_running_no(
+    _prefix     VARCHAR,
+    _year       NUMERIC DEFAULT EXTRACT(YEAR FROM NOW())::NUMERIC
+)
+RETURNS VARCHAR AS
+$$
+DECLARE
+    v_running_no    NUMERIC;
+    v_result        VARCHAR;
+BEGIN
+    -- Lock table row để tránh concurrent issues
+    SELECT COALESCE(MAX(seq_no), 0) + 1
+    INTO v_running_no
+    FROM qas.running_number
+    WHERE prefix = _prefix
+      AND year = _year
+    FOR UPDATE;
+
+    -- Insert hoặc update sequence
+    INSERT INTO qas.running_number (prefix, year, seq_no)
+    VALUES (_prefix, _year, v_running_no)
+    ON CONFLICT (prefix, year)
+    DO UPDATE SET seq_no = v_running_no;
+
+    -- Format: PREFIX-YYYY-XXXXX
+    v_result := _prefix || '-' || _year::TEXT || '-' || LPAD(v_running_no::TEXT, 5, '0');
+
+    RETURN v_result;
+END;
+$$ LANGUAGE plpgsql;
+
+
+-- ──────────────────────────────────────────────
+-- TEMPLATE: After-approve procedure
+-- ──────────────────────────────────────────────
+CREATE OR REPLACE FUNCTION qas.sp_after_approve(
+    _id_agreement VARCHAR
+)
+RETURNS JSON AS
+$$
+DECLARE
+    v_agreement RECORD;
+    v_result    JSON;
+BEGIN
+    -- Get agreement data
+    SELECT * INTO v_agreement
+    FROM qas.agreement
+    WHERE id_agreement = _id_agreement;
+
+    IF NOT FOUND THEN
+        RETURN json_build_object('success', false, 'message', 'Agreement not found');
+    END IF;
+
+    -- Update related records
+    UPDATE qas.agreement_media
+    SET status = 'confirmed',
+        confirmed_at = NOW()
+    WHERE id_agreement = _id_agreement;
+
+    -- Create audit log
+    INSERT INTO qas.audit_log (
+        table_name, record_id, action, changed_at
+    ) VALUES (
+        'agreement', _id_agreement, 'approved', NOW()
+    );
+
+    RETURN json_build_object('success', true, 'id_agreement', _id_agreement);
+
+EXCEPTION WHEN OTHERS THEN
+    RETURN json_build_object('success', false, 'message', SQLERRM);
+END;
+$$ LANGUAGE plpgsql;
+```
+
+---
+
+## 7. Table Design Conventions
+
+```sql
+-- ──────────────────────────────────────────────
+-- TEMPLATE: Standard table
+-- Rules: chỉ varchar/numeric/boolean, không NULL
+-- ──────────────────────────────────────────────
+create table qas.agreement
+(
+    -- Primary Key: uuid varchar
+    id_agreement     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 agreement_pkey primary key,
+
+    -- Business fields — LUÔN có default
+    agreement_number varchar  default '',
+    status           varchar  default 'draft',
+    amount           numeric  default 0,
+    note             varchar  default '',
+
+    -- Foreign keys: id_ prefix (varchar)
+    id_branch        varchar  default '' references qas.branch (id_branch),
+    id_type          varchar  default '' references qas.agreement_type (id_type),
+
+    -- Data phụ (JSON string dạng varchar)
+    extra_data       varchar  default '',
+
+    -- Boolean flags: is_ prefix
+    is_active        boolean  default true,
+    is_deleted       boolean  default false,
+
+    -- Audit fields — varchar timezone VN
+    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,
+    updated_by       varchar  default '',
+    updated_at       varchar  default TO_CHAR(date_trunc('second', now() AT TIME ZONE 'Asia/Ho_Chi_Minh'),
+                                              'YYYY-MM-DD HH24:MI:SS')::character varying
+);
+
+create index if not exists idx_agreement_status  on qas.agreement (status);
+create index if not exists idx_agreement_branch  on qas.agreement (id_branch);
+create index if not exists idx_agreement_created on qas.agreement (created_at);
+```
+
+**UUID Generator Pattern — dùng cho mọi table:**
+```sql
+-- Macro UUID (copy nguyên cụm này cho mỗi PK mới)
+id_<table_name> 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 <table_name>_pkey primary key
+
+-- Ví dụ:
+id_user 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 user_pkey primary key,
+
+id_branch 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 branch_pkey primary key,
+```
+
+**Audit fields LUÔN có trong mọi table — varchar, timezone VN:**
+```sql
+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,
+updated_by  varchar  default '',
+updated_at  varchar  default TO_CHAR(date_trunc('second', now() AT TIME ZONE 'Asia/Ho_Chi_Minh'),
+                                     'YYYY-MM-DD HH24:MI:SS')::character varying
+```
+
+**Full Table Template với tất cả conventions:**
+```sql
+create table prd.table_name
+(
+    id_table_name 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 table_name_pkey primary key,
+
+    -- business fields — LUÔN plain varchar/numeric/boolean, LUÔN có default
+    field_name   varchar  default '',
+    amount       numeric  default 0,
+    status       varchar  default 'draft',
+    is_active    boolean  default true,
+    is_deleted   boolean  default false,
+
+    -- foreign keys (varchar UUID, default '')
+    id_parent    varchar  default '' references prd.parent_table (id_parent),
+
+    -- audit fields
+    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,
+    updated_by   varchar  default '',
+    updated_at   varchar  default TO_CHAR(date_trunc('second', now() AT TIME ZONE 'Asia/Ho_Chi_Minh'),
+                                          'YYYY-MM-DD HH24:MI:SS')::character varying
+);
+```
+
+> ⚠️ **Lưu ý `updated_at`:** `DEFAULT` chỉ chạy khi `INSERT`. Khi `UPDATE`, backend phải tự set tường minh:
+> ```sql
+> updated_at = TO_CHAR(NOW() AT TIME ZONE 'Asia/Ho_Chi_Minh', 'YYYY-MM-DD HH24:MI:SS'),
+> updated_by = _username
+> ```
+> Hoặc dùng `/api/save` generic endpoint — endpoint này tự inject `updated_at` / `updated_by` vào mọi UPDATE.
+
+---
+
+## 8. Common SQL Patterns
+
+### JSON Aggregation
+```sql
+-- Array of objects
+json_agg(json_build_object(
+    'id', m.id_media,
+    'name', m.media_name,
+    'amount', COALESCE(m.amount, 0)
+)) AS media_list
+
+-- Null-safe array
+COALESCE(
+    json_agg(obj) FILTER (WHERE obj IS NOT NULL),
+    '[]'::json
+) AS items
+```
+
+### Date Calculations
+
+> ⚠️ DuraOne lưu ngày tháng dạng **varchar** (`'2024-01-15'` hoặc `'2024-01-15 10:30:00'`).
+> Khi dùng date functions của PostgreSQL, cần cast sang `DATE` hoặc `TIMESTAMP` trước.
+
+```sql
+-- Lưu ý: cast varchar → DATE trước khi dùng date functions
+-- age()
+EXTRACT(YEAR  FROM age(end_date::DATE, start_date::DATE))  AS years
+EXTRACT(MONTH FROM age(end_date::DATE, start_date::DATE))  AS months
+
+-- Date truncation
+DATE_TRUNC('month', created_at::TIMESTAMP) AS month_start
+
+-- Date comparison — cast cả 2 vế
+created_at::DATE BETWEEN _from_date::DATE AND _to_date::DATE
+
+-- Hoặc dùng SUBSTRING (không cần cast — đơn giản hơn khi chỉ so sánh YYYY-MM-DD)
+SUBSTRING(created_at, 1, 10) BETWEEN _from_date AND _to_date
+```
+
+### Conditional Aggregation
+```sql
+-- Sum with filter
+SUM(amount) FILTER (WHERE status = 'approved') AS approved_amount
+COUNT(*) FILTER (WHERE is_active = TRUE) AS active_count
+```
+
+### CTEs (Common Table Expressions)
+```sql
+WITH monthly_data AS (
+    SELECT
+        DATE_TRUNC('month', created_at) AS month,
+        SUM(amount) AS total
+    FROM qas.agreement
+    WHERE is_deleted = FALSE
+    GROUP BY 1
+),
+cumulative AS (
+    SELECT
+        month,
+        total,
+        SUM(total) OVER (ORDER BY month) AS running_total
+    FROM monthly_data
+)
+SELECT * FROM cumulative ORDER BY month;
+```
+
+### Window Functions
+```sql
+-- Rank/Row Number
+ROW_NUMBER() OVER (PARTITION BY id_branch ORDER BY created_at DESC) AS row_num
+RANK() OVER (ORDER BY amount DESC) AS rank
+
+-- Running totals
+SUM(amount) OVER (ORDER BY created_at) AS running_total
+LAG(amount, 1) OVER (ORDER BY created_at) AS prev_amount
+```
+
+### String Operations
+```sql
+-- Concat with null safety
+COALESCE(first_name, '') || ' ' || COALESCE(last_name, '') AS full_name
+
+-- Format number
+TO_CHAR(amount, 'FM999,999,999.00') AS amount_formatted
+
+-- String array
+string_agg(tag_name, ', ' ORDER BY tag_name) AS tags
+```
+
+### Type Casting
+```sql
+-- Numeric với precision
+COALESCE(field, 0)::numeric(16, 2)
+
+-- Date extraction
+SUBSTRING(created_at::text, 1, 10)  -- → 'YYYY-MM-DD'
+
+-- Int
+-- Numeric (KHÔNG dùng ::INT)
+field::NUMERIC
+
+-- Boolean
+(status = 'active')::BOOLEAN AS is_active
+```
+
+---
+
+## 9. File Organization
+
+```
+mainapp/SQL/duraone/
+├── qas/
+│   ├── view/
+│   │   ├── v_agreement.sql
+│   │   ├── v_clearance_request.sql
+│   │   └── v_[entity].sql
+│   │
+│   ├── function/
+│   │   ├── fn_get_agreement.sql
+│   │   ├── fn_get_review_list.sql
+│   │   └── fn_[operation]_[entity].sql
+│   │
+│   ├── store/
+│   │   ├── sp_generate_running_no.sql
+│   │   ├── sp_after_approve.sql
+│   │   └── sp_[action]_[entity].sql
+│   │
+│   └── [feature]/          # Feature-specific (linechat, clearance, etc.)
+│       ├── view/
+│       ├── function/
+│       └── store/
+│
+└── prd/                    # Mirrors qas — same files, schema = prd
+    ├── view/
+    ├── function/
+    └── store/
+```
+
+**Cách chạy SQL khi deploy:**
+```bash
+# QAS
+psql $QAS_CONN -f mainapp/SQL/duraone/qas/view/v_agreement.sql
+
+# PRD (thay qas. → prd. trong file hoặc chạy riêng)
+psql $PRD_CONN -f mainapp/SQL/duraone/prd/view/v_agreement.sql
+```