@ngockhoale/ukit 1.1.6

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

@@ -0,0 +1,636 @@
+# DuraOne Backend Reference
+## Python Sanic + PostgreSQL (asyncpg)
+
+> Nguồn sự thật cho phong cách code backend của LeNK.
+> Stack: Python, Sanic (async web framework), asyncpg, psycopg2+pandas
+
+---
+
+## MỤC LỤC
+1. [Cấu trúc thư mục BE](#1-cấu-trúc-thư-mục-be)
+2. [Sanic App Setup (app.py)](#2-sanic-app-setup)
+3. [Blueprint API Pattern](#3-blueprint-api-pattern)
+4. [DB Helper — Async (v2_db.py)](#4-db-helper--async)
+5. [DB Helper — Sync (db.py)](#5-db-helper--sync)
+6. [Generic Endpoints (đã có sẵn)](#6-generic-endpoints)
+7. [Custom Endpoint Pattern](#7-custom-endpoint-pattern)
+8. [Config Management](#8-config-management)
+9. [Naming Conventions](#9-naming-conventions)
+10. [Error Handling](#10-error-handling)
+11. [Deploy](#11-deploy)
+
+---
+
+## 1. Cấu Trúc Thư Mục BE
+
+```
+BE_DuraOne/
+├── app.py                      # Main Sanic application entry point
+├── mainapp/
+│   ├── __init__.py
+│   ├── config.py               # Config loader (qas/prd/local)
+│   ├── helper.py               # Helper functions
+│   └── lib/
+│       ├── api.py              # API routes (sync version)
+│       ├── v2_api.py           # API routes (async version — dùng cái này)
+│       ├── db.py               # DB_Helper class (sync, psycopg2 + pandas)
+│       ├── v2_db.py            # DB_Helper class (async, asyncpg)
+│       ├── compress.py         # GZIP compression
+│       ├── google_storage.py   # GCS file operations
+│       ├── pandas_manage.py    # Pandas utilities
+│       ├── string_manage.py    # String utilities
+│       ├── log_manage.py       # Logging
+│       ├── pdf_manage.py       # PDF generation
+│       ├── file_handle.py      # File operations
+│       ├── chatgpt_func.py     # OpenAI integration
+│       └── send_noti.py        # Notifications (Line/email)
+│
+├── mainapp/SQL/
+│   └── duraone/
+│       ├── qas/                # QA/testing schema SQL
+│       │   ├── view/           # v_*.sql files
+│       │   ├── function/       # fn_*.sql files
+│       │   ├── store/          # sp_*.sql files
+│       │   └── [feature]/      # feature-specific SQL
+│       └── prd/                # Production schema SQL (mirrors qas)
+│
+├── config/
+│   ├── db_ssl/                 # PostgreSQL SSL certificates
+│   │   ├── ca.crt
+│   │   ├── client.crt
+│   │   └── client.key
+│   ├── fonts/
+│   └── config.ini              # DB credentials, paths
+│
+├── duraone_m/                  # Mobile app static files
+├── Dockerfile
+├── docker-compose.yml
+├── deploy_qas.sh
+└── deploy_prd.sh
+```
+
+---
+
+## 2. Sanic App Setup
+
+```python
+# app.py
+from sanic import Sanic
+from sanic_cors import CORS
+from mainapp.lib.v2_api import b_api
+from mainapp.lib.v2_db import DB_Helper
+
+app = Sanic(__name__)
+CORS(app, resources={r"/*": {"origins": [
+    "http://localhost:3000",
+    "https://your-domain.com",
+]}})
+
+# Register blueprint
+app.blueprint(b_api)
+
+# DB connection pool setup
+db = DB_Helper()
+
+@app.listener("before_server_start")
+async def setup_db(app, loop):
+    await db.connect_db()
+
+@app.listener("after_server_stop")
+async def close_db(app, loop):
+    if db._pool:
+        await db._pool.close()
+
+# Security headers
+@app.middleware("response")
+async def set_secure_headers(request, response):
+    response.headers["X-Content-Type-Options"] = "nosniff"
+    response.headers["X-Frame-Options"] = "SAMEORIGIN"
+
+# Static files
+PATH = os.path.dirname(os.path.abspath(__file__))
+app.static("/duraone_m", PATH + "/duraone_m")
+app.static("/static", PATH + "/www/static")
+
+# SPA fallback — serve index.html for all FE routes
+@app.route("/<path:path>", methods=["GET"])
+async def index(request, path):
+    return await response.file(PATH + "/www/index.html")
+
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=8000, workers=4, debug=False)
+```
+
+---
+
+## 3. Blueprint API Pattern
+
+```python
+# mainapp/lib/v2_api.py
+from sanic import Blueprint, response
+from mainapp.lib.v2_db import DB_Helper
+import json
+
+b_api = Blueprint("b_api")
+db = DB_Helper()
+
+# ──────────────────────────────────────────────
+# Pattern cho custom endpoint
+# ──────────────────────────────────────────────
+@b_api.route("/api/[feature]/[action]", methods=["POST", "GET"])
+async def feature_action(request):
+    try:
+        val = request.json or {}
+
+        # Extract params
+        id_record = val.get("id_record")
+        schema = val.get("schema", "qas")
+
+        # Business logic
+        query = f"""
+            SELECT * FROM {schema}.v_[entity]
+            WHERE id_record = $1
+        """
+        result = await db.execute(query, (id_record,))
+
+        return response.json(result)
+
+    except Exception as e:
+        return response.json({"success": False, "message": str(e)}, status=500)
+
+
+# ──────────────────────────────────────────────
+# Pattern chạy stored procedure
+# ──────────────────────────────────────────────
+@b_api.route("/api/run_proc", methods=["POST", "GET"])
+async def run_proc(request):
+    try:
+        val = request.json or {}
+        schema = val.get("schema", "qas")
+        proc_name = val.get("proc_name")
+        params = val.get("params", {})
+
+        # Build param list
+        param_values = list(params.values())
+        param_placeholders = ", ".join([f"${i+1}" for i in range(len(param_values))])
+
+        query = f"SELECT * FROM {schema}.{proc_name}({param_placeholders})"
+        result = await db.execute(query, param_values)
+
+        return response.json(result)
+
+    except Exception as e:
+        return response.json({"success": False, "message": str(e)}, status=500)
+```
+
+---
+
+## 4. DB Helper — Async
+
+```python
+# mainapp/lib/v2_db.py
+import asyncpg
+import json
+from decimal import Decimal
+from mainapp.config import get_config
+
+class DB_Helper:
+    _pool = None
+
+    async def connect_db(self):
+        """Create asyncpg connection pool with SSL"""
+        config = get_config()
+        self._pool = await asyncpg.create_pool(
+            host=config["host"],
+            port=config["port"],
+            database=config["database"],
+            user=config["user"],
+            password=config["password"],
+            ssl=self._get_ssl_context(),
+            min_size=2,
+            max_size=10,
+        )
+
+    async def execute(self, query: str, params: tuple = ()) -> list:
+        """Execute query and return list of dicts"""
+        async with self._pool.acquire() as conn:
+            rows = await conn.fetch(query, *params)
+            result = [dict(row) for row in rows]
+            return self.convert_to_serializable(result)
+
+    async def execute_one(self, query: str, params: tuple = ()):
+        """Execute query and return single dict or None"""
+        result = await self.execute(query, params)
+        return result[0] if result else None
+
+    async def execute_void(self, query: str, params: tuple = ()):
+        """Execute INSERT/UPDATE/DELETE with no return"""
+        async with self._pool.acquire() as conn:
+            await conn.execute(query, *params)
+
+    def convert_to_serializable(self, data):
+        """Convert Decimal, datetime to JSON-serializable types"""
+        if isinstance(data, list):
+            return [self.convert_to_serializable(item) for item in data]
+        if isinstance(data, dict):
+            return {k: self.convert_to_serializable(v) for k, v in data.items()}
+        if isinstance(data, Decimal):
+            return float(data)
+        if hasattr(data, "isoformat"):  # datetime, date
+            return data.isoformat()
+        return data
+
+    def check_form_json(self, v):
+        """Check if string is JSON array or object"""
+        if isinstance(v, str):
+            return v.startswith("[") or v.startswith("{")
+        return False
+
+    def _get_ssl_context(self):
+        """Load SSL context for PostgreSQL connection"""
+        import ssl
+        ctx = ssl.create_default_context(ssl.Purpose.SERVER_AUTH)
+        ctx.load_cert_chain("config/db_ssl/client.crt", "config/db_ssl/client.key")
+        ctx.load_verify_locations("config/db_ssl/ca.crt")
+        return ctx
+```
+
+---
+
+## 5. DB Helper — Sync
+
+```python
+# mainapp/lib/db.py — dùng khi cần pandas hoặc sync context
+import psycopg2 as pg
+import pandas as pd
+import json
+from mainapp.config import set_cdn
+
+class DB_Helper:
+
+    @staticmethod
+    def selectbyquery(query, params=None):
+        """Execute SELECT, return pandas DataFrame"""
+        connection = pg.connect(set_cdn())
+        try:
+            df = pd.read_sql(query, connection, params=params)
+            # Handle nulls
+            numeric_cols = df.select_dtypes(include=["number"]).columns
+            df[numeric_cols] = df[numeric_cols].fillna(0)
+            df = df.fillna("")
+            return df.to_dict("records")
+        except Exception as e:
+            print(f"DB Error: {e}")
+            return []
+        finally:
+            connection.close()
+
+    @staticmethod
+    def insert(table_name: str, obj: dict, pk_field: str = None) -> str:
+        """Insert record, return new id (UUID string).
+
+        ⚠️ DuraOne convention: PK field là id_[entity] (e.g. id_agreement), KHÔNG phải 'id'.
+        Luôn truyền pk_field='id_agreement' (hoặc tên PK thực tế) để loại bỏ PK khỏi INSERT.
+        Nếu không truyền pk_field, PK sẽ bị include vào INSERT statement.
+
+        Note: Sync DB_Helper này dùng trong context pandas/scripts.
+        Cho generic CRUD từ FE, dùng generic /api/save endpoint (async) thay thế.
+        """
+        connection = pg.connect(set_cdn())
+        try:
+            # Loại bỏ PK field (vì DB tự generate UUID default)
+            exclude = {pk_field} if pk_field else set()
+            keys = [k for k in obj.keys() if k not in exclude]
+            values = []
+            for k in keys:
+                v = obj[k]
+                if isinstance(v, (dict, list)):
+                    v = json.dumps(v, ensure_ascii=False)
+                values.append(v)
+
+            placeholders = ", ".join(["%s"] * len(keys))
+            columns = ", ".join(keys)
+            returning = pk_field if pk_field else "id"
+            query = f"INSERT INTO {table_name} ({columns}) VALUES ({placeholders}) RETURNING {returning}"
+
+            with connection.cursor() as cursor:
+                cursor.execute(query, values)
+                new_id = cursor.fetchone()[0]
+                connection.commit()
+                return str(new_id)
+        except Exception as e:
+            connection.rollback()
+            print(f"Insert Error: {e}")
+            return ""
+        finally:
+            connection.close()
+
+    @staticmethod
+    def update(table_name: str, obj: dict, key_field: str = "id"):
+        """Update record by key field.
+
+        ⚠️ DuraOne convention: PK field là id_[entity], KHÔNG phải 'id'.
+        Luôn truyền key_field='id_agreement' (hoặc tên PK thực tế).
+        Ví dụ: DB_Helper.update("agreement", obj, key_field="id_agreement")
+        """
+        connection = pg.connect(set_cdn())
+        try:
+            key_val = obj[key_field]
+            fields = {k: v for k, v in obj.items() if k != key_field}
+
+            set_clause = ", ".join([f"{k} = %s" for k in fields.keys()])
+            values = list(fields.values()) + [key_val]
+
+            query = f"UPDATE {table_name} SET {set_clause} WHERE {key_field} = %s"
+
+            with connection.cursor() as cursor:
+                cursor.execute(query, values)
+                connection.commit()
+        except Exception as e:
+            connection.rollback()
+            print(f"Update Error: {e}")
+        finally:
+            connection.close()
+
+    @staticmethod
+    def removebykey(table_name: str, key_field: str, key_value):
+        """Delete record by key"""
+        connection = pg.connect(set_cdn())
+        try:
+            query = f"DELETE FROM {table_name} WHERE {key_field} = %s"
+            with connection.cursor() as cursor:
+                cursor.execute(query, (key_value,))
+                connection.commit()
+        except Exception as e:
+            connection.rollback()
+        finally:
+            connection.close()
+```
+
+---
+
+## 6. Generic Endpoints (Đã Có Sẵn)
+
+Frontend dùng những endpoints này — KHÔNG cần tạo thêm cho CRUD thông thường:
+
+```
+POST/GET  /api/select          — Query data (qua table/view + conditions)
+POST      /api/save            — Insert hoặc Update (auto detect bằng id == '' → insert, id != '' → update)
+POST      /api/insert          — Force insert
+POST      /api/update          — Force update
+POST      /api/delete          — Delete by key
+POST/GET  /api/run_proc        — Run stored procedure
+GET       /api/clearcache      — Clear server cache
+POST      /user/login          — Authentication
+```
+
+**Request format cho /api/select:**
+```json
+{
+  "schema": "qas",
+  "table": "v_agreement",
+  "columns": "*",
+  "conditions": "{\"id_branch\": 5, \"status\": \"active\"}",
+  "order_by": ["created_at desc"],
+  "limit": 1000
+}
+```
+
+**Request format cho /api/save:**
+```json
+{
+  "table": "agreement",
+  "key_array": ["id_agreement"],
+  "id_agreement": "",
+  "agreement_number": "AGR-001",
+  "id_branch": 5,
+  "amount": 50000
+}
+```
+
+---
+
+## 7. Custom Endpoint Pattern
+
+Chỉ tạo custom endpoint khi có business logic đặc biệt không xử lý được bằng generic:
+
+```python
+# Naming: /api/[feature]/[action]
+@b_api.route("/api/agreement/approve", methods=["POST"])
+async def approve_agreement(request):
+    """Approve agreement — gửi notification + update status"""
+    try:
+        val = request.json or {}
+        schema = val.get("schema", "qas")
+        id_agreement = val.get("id_agreement")
+        # ✅ FE phải truyền: { username: state.username, ... }
+        # state.username là username của user đang login (từ session)
+        approved_by = val.get("username")
+
+        # 1. Update status
+        await db.execute_void(f"""
+            UPDATE {schema}.agreement
+            SET status = 'approved',
+                approved_by = $1,
+                approved_at = NOW()
+            WHERE id_agreement = $2
+        """, (approved_by, id_agreement))
+
+        # 2. Run stored procedure for post-processing
+        result = await db.execute(f"""
+            SELECT * FROM {schema}.sp_after_approve($1)
+        """, (id_agreement,))
+
+        # 3. Send notification
+        await send_line_notification(id_agreement, schema)
+
+        return response.json({"success": True, "data": result})
+
+    except Exception as e:
+        return response.json({"success": False, "message": str(e)}, status=500)
+
+
+# Pattern: upload file
+@b_api.route("/api/upload_to_cloud", methods=["POST"])
+async def upload_to_cloud(request):
+    try:
+        file = request.files.get("file")
+        folder = request.form.get("folder", "uploads")
+        schema = request.form.get("schema", "qas")
+
+        # Upload to GCS
+        from mainapp.lib.google_storage import upload_blob
+        url = await upload_blob(file.body, file.name, folder)
+
+        return response.json({"success": True, "url": url})
+    except Exception as e:
+        return response.json({"success": False, "message": str(e)}, status=500)
+```
+
+---
+
+## 8. Config Management
+
+```python
+# mainapp/config.py
+import configparser
+import os
+
+config = configparser.ConfigParser()
+config.read(os.path.join(os.path.dirname(__file__), "../config/config.ini"))
+
+def get_env() -> str:
+    """Get current environment: local | qas | prd"""
+    return os.environ.get("APP_ENV", "local")
+
+def get_config() -> dict:
+    env = get_env()
+    return {
+        "host":     config[env]["DB_HOST"],
+        "port":     int(config[env]["DB_PORT"]),
+        "database": config[env]["DB_NAME"],
+        "user":     config[env]["DB_USER"],
+        "password": config[env]["DB_PASSWORD"],
+    }
+
+def set_cdn() -> str:
+    """Return psycopg2 connection string"""
+    c = get_config()
+    return f"host={c['host']} port={c['port']} dbname={c['database']} user={c['user']} password={c['password']} sslmode=require"
+
+def get_schema() -> str:
+    """Return schema name: qas | prd"""
+    env = get_env()
+    return "prd" if env == "prd" else "qas"
+```
+
+```ini
+# config/config.ini
+[local]
+DB_HOST = localhost
+DB_PORT = 5432
+DB_NAME = duraone
+DB_USER = postgres
+DB_PASSWORD = password
+
+[qas]
+DB_HOST = <cloud-sql-host>
+DB_PORT = 5432
+DB_NAME = duraone
+DB_USER = duraone_user
+DB_PASSWORD = <secret>
+
+[prd]
+DB_HOST = <prd-cloud-sql-host>
+DB_PORT = 5432
+DB_NAME = duraone_prd
+DB_USER = duraone_prd_user
+DB_PASSWORD = <secret>
+```
+
+---
+
+## 9. Naming Conventions
+
+```python
+# ── Files: snake_case ──
+# v2_api.py, v2_db.py, string_manage.py, pdf_manage.py
+
+# ── Classes: PascalCase ──
+class DB_Helper: ...
+class GoogleStorage: ...
+
+# ── Functions: snake_case ──
+async def get_agreement_by_id(id_agreement: str): ...
+async def run_proc(schema: str, proc_name: str): ...
+def format_date(date_str: str) -> str: ...
+
+# ── Variables: snake_case ──
+id_agreement = val.get("id_agreement")
+schema = val.get("schema", "qas")
+result_list = []
+
+# ── Constants: UPPER_SNAKE ──
+DEFAULT_SCHEMA = "qas"
+MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
+
+# ── Route paths: lowercase + underscore ──
+# /api/agreement/get_list
+# /api/clearance/approve
+# /api/upload_to_cloud
+
+# ── Blueprint name ──
+b_api = Blueprint("b_api")
+```
+
+---
+
+## 10. Error Handling
+
+```python
+# Pattern chuẩn cho mọi endpoint
+@b_api.route("/api/feature/action", methods=["POST"])
+async def endpoint(request):
+    try:
+        val = request.json or {}
+        # ... logic ...
+        return response.json(result)
+
+    except ValueError as e:
+        # Input validation error
+        return response.json({"success": False, "message": str(e)}, status=400)
+    except Exception as e:
+        # Unexpected error — log và trả về 500
+        print(f"[ERROR] endpoint: {e}")
+        return response.json({"success": False, "message": "Internal server error"}, status=500)
+
+# DB error handling trong DB_Helper
+async def execute(self, query, params=()):
+    try:
+        async with self._pool.acquire() as conn:
+            rows = await conn.fetch(query, *params)
+            return [dict(row) for row in rows]
+    except asyncpg.PostgresError as e:
+        print(f"[DB ERROR] {e}")
+        return []
+```
+
+---
+
+## 11. Deploy
+
+```bash
+# deploy_qas.sh
+#!/bin/bash
+export APP_ENV=qas
+pip install -r requirements.txt
+python app.py
+
+# deploy_prd.sh
+#!/bin/bash
+export APP_ENV=prd
+# ... same pattern
+
+# Dockerfile pattern
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+COPY . .
+ENV APP_ENV=qas
+CMD ["python", "app.py"]
+```
+
+```yaml
+# docker-compose.yml pattern
+version: "3.8"
+services:
+  backend:
+    build: .
+    ports:
+      - "8000:8000"
+    environment:
+      - APP_ENV=qas
+    volumes:
+      - ./config:/app/config
+```