ai-developer-skill-os 9.3.1 → 10.2.0

package/.agents/skills/qk-api-data-discovery/references/discovery-report-template.md

@@ -0,0 +1,110 @@
+# API Discovery & Evidence Report: [<collection_name>]
+
+> **Status:** DISCOVERY_COMPLETED (Awaiting User Decision)
+> **Execution Date:** <ISO_TIMESTAMP>
+> **Environment:** <Staging / Production / Offline Logs>
+
+---
+
+## 1. Executive Summary
+- **Collection Name:** `<name>`
+- **Total Requests Analyzed:** `<total>`
+- **Requests Executed (Evidence Collected):** `<executed_count>` (Success: `<success>`, Failed: `<failed>`)
+- **Requests Not Executed:** `<skipped_count>` (Do phân loại rủi ro hoặc thiếu thông tin)
+- **Average Response Latency:** `<avg_ms> ms` (Min: `<min_ms>`, Max: `<max_ms>`)
+
+---
+
+## 2. Project Context & Detected Architecture
+- **Backend Stack:** `<stack hoặc None>`
+- **Data Pipeline Stack:** `<dbt / Airflow / Python scripts / Không có>`
+- **Existing Storage Zones:** `<Bronze/Silver/Gold folders hiện có>`
+- **Relevant Existing Modules:**
+  - `<file_link_1>`
+  - `<file_link_2>`
+
+---
+
+## 3. API Inventory & Risk Classification
+| # | Method | Endpoint Path | Risk Gate | Execution Status | HTTP Status | Response Time | Domain / Module |
+|---|---|---|---|---|---|---|---|
+| 1 | GET | `/api/v1/users` | AUTO | EXECUTED | 200 OK | 184 ms | User Management |
+| 2 | POST | `/api/v1/users` | CONFIRM | NOT_EXECUTED | — | — | User Management |
+| 3 | GET | `/api/v1/orders` | AUTO | EXECUTED | 200 OK | 340 ms | Order Processing |
+
+---
+
+## 4. Real API Evidence (Observed Responses)
+### Endpoint: `GET /api/v1/users`
+- **Execution Status:** EXECUTED
+- **HTTP Code:** `200 OK` | **Latency:** `184 ms`
+- **Observed Response Body (Raw Snippet):**
+```json
+{
+  "data": [
+    { "id": 1024, "name": "Nguyen Van A", "createdAt": "2026-09-15T10:20:00Z" }
+  ],
+  "pagination": { "page": 1, "pageSize": 20, "total": 128 }
+}
+```
+
+---
+
+## 5. Schema Discovery & API Data Dictionary
+### Entity: `users` (Derived from `GET /api/v1/users`)
+| Field Path | Data Type | Nullable | Sample Value | Evidence Confidence |
+|---|---|---|---|---|
+| `data[].id` | integer | No | `1024` | 100% (Observed) |
+| `data[].name` | string | No | `"Nguyen Van A"` | 100% (Observed) |
+| `data[].createdAt` | datetime | No | `"2026-09-15T10:20:00Z"` | 100% (Observed) |
+| `pagination.total` | integer | No | `128` | 100% (Observed) |
+
+---
+
+## 6. Data Engineering Assessment (Medallion Bronze Layer)
+- **Candidate Bronze Sources:**
+  - `GET /api/v1/users` → Bảng Bronze: `bronze_raw_users`
+  - `GET /api/v1/orders` → Bảng Bronze: `bronze_raw_orders`
+- **Khuyến nghị Chiến lược Ingestion:**
+  - Lưu trữ dưới dạng `NDJSON` (Newline Delimited JSON) theo từng batch chạy.
+  - Bổ sung Ingestion Metadata Header (`ingestion_id`, `ingested_at`, `status_code`, `latency_ms`).
+  - Không bóc tách mảng `data[]` ở Bronze; giữ nguyên toàn bộ payload để đảm bảo tính toàn vẹn (Immutability).
+
+---
+
+## 7. Existing Project Alignment
+- Codebase hiện đã có cấu trúc: `<liệt kê>`
+- **Phương án tích hợp khả thi:**
+  - Phương án 1: Tích hợp vào pipeline ingest sẵn có tại `<path>`.
+  - Phương án 2: Tạo module API ingestion độc lập tại `<path>`.
+
+---
+
+## 8. Key Findings & Anomalies
+- **F-001 (Pagination):** Endpoint `GET /api/v1/orders` dùng phân trang `page` & `pageSize`. Cần vòng lặp loop khi ingest toàn bộ.
+- **F-002 (Nested Structures):** Trường `customer.profile` trả về object lồng nhau 3 cấp. Khuyến nghị chuẩn hóa tại tầng Silver.
+- **F-003 (Rate Limiting):** API trả về header `X-RateLimit-Remaining: 60`. Cần cơ chế throttle delay 500ms giữa các batch.
+
+---
+
+## 9. Identified Risks
+- ⚠️ **R-01 (Token Expiration):** Bearer token hết hạn sau 30 phút. Cần cơ chế refresh token nếu crawl dữ liệu lớn.
+- ⚠️ **R-02 (Inconsistent Error Schema):** Endpoint trả về HTTP 404 có format khác với HTTP 500.
+
+---
+
+## 10. Recommended Next Actions & DECISION REQUIRED
+
+> ⛔ **AI ACTION STOPPED HERE — WAITING FOR USER INSTRUCTION**
+> AI **CHƯA THỰC HIỆN BẤT KỲ THAY ĐỔI MÃ NGUỒN HOẶC TẠO PIPELINE NÀO**. Xin vui lòng chọn 1 trong các định hướng sau:
+
+- **Option A — Bronze Ingestion Pipeline:**
+  Xây dựng pipeline thu thập và sinh file dữ liệu thô `api_responses.ndjson` + `ingestion_manifest.json` sẵn sàng nạp vào hồ dữ liệu.
+- **Option B — Postman Collection Standardization:**
+  Chuẩn hóa lại toàn bộ collection: gom nhóm folders theo Resource, gắn response mẫu thật, thiết lập biến môi trường và bổ sung bộ test scripts `pm.test`.
+- **Option C — Formal Data Contract:**
+  Sinh file đặc tả hợp đồng dữ liệu `api_schema.json` + `data_dictionary.md` + file contract YAML làm căn cứ kiểm định cho tầng Silver.
+- **Option D — Data Quality & Anomaly Assertions:**
+  Thiết lập bộ quy tắc kiểm tra chất lượng dữ liệu (Null checks, Uniqueness, Type assertions) cho các endpoint quan trọng.
+- **Option E — Deep Scenario Execution:**
+  Tiếp tục chạy thêm các kịch bản biên (Empty Result, Invalid Params, Unauthorized) để hoàn thiện bức tranh hành vi của API.

package/.agents/skills/qk-backend-data/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: qk-backend-data
+version: 10.2.0
+status: stable
+subtitle: "API & Database"
+description: "Kỹ sư Backend & Cơ sở dữ liệu toàn diện: Thiết kế Zero-Trust API, quản lý Schema Migration an toàn, phân quyền RBAC/ABAC, tối ưu SQL EXPLAIN/ANALYZE và xây dựng Data Pipeline. Dùng khi: viết api, tạo endpoint, sửa database, migration, thêm cột, rbac, abac, phân quyền, auth middleware, tối ưu query, query chậm, slow query, n+1 query, data pipeline, etl, dbt — TUYỆT ĐỐI KHÔNG dùng cho việc code UI/CSS (dùng qk-ui-engineer) hoặc cấu hình hạ tầng k8s/cluster (dùng qk-devops-release)."
+platforms: [antigravity, claude, opencode]
+runtime_version: 1
+tools:
+  - filesystem
+  - terminal
+rules:
+  - global
+  - coding-standards
+  - security
+workflow: feature-delivery
+triggers:
+  - "viết api"
+  - "tạo endpoint"
+  - "thiết kế api"
+  - "sửa database"
+  - "migration"
+  - "thêm cột"
+  - "db schema"
+  - "rbac"
+  - "abac"
+  - "phân quyền"
+  - "auth middleware"
+  - "tối ưu query"
+  - "query chậm"
+  - "slow query"
+  - "n+1 query"
+  - "data pipeline"
+  - "etl"
+  - "dbt"
+---
+
+# qk-backend-data — API & Database (Zero-Trust API & Data Architecture Engine)
+
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+---
+
+## Memory Workflow
+
+### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
+- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
+  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
+  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
+
+---
+
+### Pre-flight Retrieve (Trước khi thực thi)
+- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
+  bắt buộc tra cứu:
+  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
+
+- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
+  - Architecture
+  - Hard Bug
+  - Convention
+  - Pattern
+  - Tech Debt Pattern
+
+- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
+  Không được xem Memory là Source of Truth.
+  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
+
+---
+
+### Learning Flow (AI tự học có kiểm soát)
+- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
+  - Hard Bug có khả năng tái diễn.
+  - Pattern làm việc lặp lại trong dự án.
+  - Convention hoặc quy tắc kiến trúc mới.
+  - Quyết định Architecture quan trọng.
+  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
+
+- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
+- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
+- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+
+---
+
+### Post-flight Harvest (Đề xuất → Phê duyệt)
+Sau khi hoàn thành task:
+- AI đánh giá các Candidate Memory đã tạo.
+- Nếu phát hiện tri thức có giá trị tái sử dụng:
+  - Đề xuất người dùng xem xét.
+  - Gửi yêu cầu phê duyệt thông qua:
+    - `/learn`
+    - `qk-project-memory`
+- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
+
+```
+.ai-local/candidates/  ──(Approve)──>  .ai-local/knowledge/index.yaml
+```
+
+- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
+  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
+
+---
+
+### Ignore (Không đưa vào Memory)
+Không lưu:
+- Trace log của một session đơn lẻ.
+- Temporary debugging data.
+- Output của một lần chạy test/scan.
+- Report health tạm thời của một đợt kiểm tra.
+- Lỗi nhỏ chỉ xảy ra một lần.
+- Thông tin không có khả năng tái sử dụng.
+
+---
+
+### Golden Rule
+> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
+> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+
+---
+
+## 1. Nguyên Tắc Cốt Lõi & Luật Chống Over-Engineering
+
+> **Core Principle:** Data integrity and security are non-negotiable. Prefer simple, direct, type-safe queries over multi-layered abstractions. Every schema change must have a safe rollback path.
+> **Verification Principle:** PASS is a verified conclusion, never a target. Zero workarounds.
+
+### 🛡️ Anti-Overengineering Rule (CẤM TẠO LAYER RÁC)
+- **Không đẻ tầng lớp trung gian vô nghĩa:** Nếu dự án dùng ORM trực tiếp (Prisma, Drizzle, SQLAlchemy) hoặc Active Record, KHÔNG tự ý bọc thêm 3 tầng Interface, DAO, Repository rườm rà nếu codebase hiện tại không theo chuẩn Clean/Hexagonal Architecture. Viết code thẳng thắn, dễ đọc và dễ test.
+- **Không lạm dụng Message Broker:** Nếu chỉ là tác vụ xử lý thông thường, ưu tiên DB Transactions hoặc simple background queue thay vì đề xuất cài Kafka, RabbitMQ làm phức tạp hóa hệ thống.
+
+### 🔒 No Unrelated Changes Rule (CẤM SỬA LAN MAN)
+- Chỉ sửa đúng endpoints, schemas hoặc pipelines được phân công.
+- **CẤM** tiện tay sửa controller khác hoặc reformat toàn bộ schema không liên quan.
+- Nếu phát hiện endpoint cũ thiếu bảo mật: **Chỉ ghi nhận vào báo cáo kiểm toán**, không tự ý sửa nếu ngoài scope.
+
+### 🛡️ Anti-Fake-Pass Rule (CẤM ÉP PASS ẢO - R-G-14.5)
+- **CẤM** bypass auth middleware hoặc hardcode role Admin chỉ để test case vượt qua.
+- **CẤM** tắt các ràng buộc Foreign Key, Unique, NOT NULL chỉ để insert dữ liệu mẫu.
+- **CẤM** dùng `as any` để ép kiểu kết quả truy vấn database.
+- **CẤM** swallow DB exceptions (`try/catch {}` rỗng nuốt transaction rollback).
+
+### ⚖️ Verify Before Claim Rule (XÁC MINH TRƯỚC KHI BÁO CÁO)
+- **Cấm tuyên bố query đã tối ưu nếu chưa chạy EXPLAIN:** Nếu có database test, BẮT BUỘC chạy `EXPLAIN (ANALYZE)` để xem Execution Plan (Index Scan vs Seq Scan).
+- **Báo cáo trung thực:** Nếu không có DB live cục bộ để test, ghi rõ: `"Trạng thái: NOT VERIFIED — Đã rà soát cú pháp tĩnh và đặt Index hợp lý. Chưa chạy EXPLAIN ANALYZE thực tế"`.
+
+---
+
+## 2. Ranh Giới & Phạm Vi Kỹ Thuật (Hard Boundaries)
+
+### ✅ Việc skill này BẮT BUỘC làm:
+- **Zero-Trust API:** Mọi endpoint phải kiểm tra Auth & Input validation (Zod/Pydantic) trước khi vào logic nghiệp vụ. Chặn đứng IDOR bằng cách kiểm tra quyền sở hữu tài nguyên (`WHERE id = :id AND user_id = :current_user`).
+- **Expand and Contract Migrations:** Thêm cột mới dạng `NULLABLE` trước, migrate dữ liệu, sau đó mới siết ràng buộc NOT NULL. Tuyệt đối KHÔNG xóa/đổi tên cột trong một migration duy nhất.
+- **Diệt Trừ N+1 Queries:** Luôn sử dụng `eager loading` hoặc `DataLoader` khi truy vấn dữ liệu quan hệ (1-N).
+- **Idempotent Data Pipelines:** Pipeline ETL/dbt phải chạy lại được nhiều lần mà không sinh trùng lặp dữ liệu (sử dụng Upsert / Partition Overwrite).
+- **Planning Gate & Exceptions:** Với schema migration hoặc thay đổi model ảnh hưởng ≥ 2 files, BẮT BUỘC lập `implementation_plan.md` với `RequestFeedback: true` và dừng lại chờ phê duyệt. Ngoại lệ: query optimization đơn lẻ trong 1 file không cần qua gate.
+
+### ❌ Việc skill này TUYỆT ĐỐI KHÔNG làm (Chuyển giao quyền):
+- Viết component giao diện, HTML/CSS trên Frontend → Chuyển sang `qk-ui-engineer`.
+- Cấu hình hạ tầng Kubernetes cluster hoặc deploy production → Chuyển sang `qk-devops-release`.
+
+---
+
+## 3. Quy Trình Kỹ Nghệ Backend & Dữ Liệu 4 Bước
+
+```
+[Bước 1: Contract & Validation] ── Định nghĩa Schemas, Request/Response DTOs & Auth Guards
+            │
+            ▼
+[Bước 2: Safe Data Modeling]    ── Viết Migration theo chuẩn Expand & Contract kèm Script Rollback
+            │
+            ▼
+[Bước 3: Service & Query Opt]   ── Triển khai Service layer, bọc Transaction & tối ưu hóa Query
+            │
+            ▼
+[Bước 4: Verification & Test]  ── Chạy Migration test, Typecheck. Nếu FAIL ──► Rollback ngay
+```
+
+---
+
+## 4. Xử Lý Sự Cố Khi Migration / Query Thất Bại (Failure Path)
+
+### 🚨 Khi Migration gặp lỗi hoặc làm crash Database:
+1. **Dừng ngay lập tức:** Không cố gắng ép chạy tiếp migration tiếp theo.
+2. **Kích hoạt Script Rollback:**
+   ```bash
+   # Với Prisma:
+   npx prisma migrate resolve --rolled-back <migration_name>
+   # Hoặc chạy file down.sql tương ứng đã chuẩn bị sẵn
+   ```
+3. **Phục hồi schema cũ:** Khôi phục file schema về commit an toàn gần nhất.
+
+---
+
+## 5. Mẫu Code Thực Chiến Đa Ngôn Ngữ (Chống IDOR & N+1)
+
+### TypeScript / Prisma:
+```typescript
+// ❌ Nguy hiểm: Dính IDOR, ai cũng xem được hóa đơn của người khác
+export async function getInvoice(invoiceId: string) {
+  return prisma.invoice.findUnique({ where: { id: invoiceId } });
+}
+
+// ✅ An toàn: Zero-Trust kiểm tra quyền sở hữu tài nguyên + Eager load chống N+1
+export async function getInvoice(invoiceId: string, currentUserId: string) {
+  const invoice = await prisma.invoice.findFirst({
+    where: {
+      id: invoiceId,
+      userId: currentUserId, // Chặn đứng IDOR
+    },
+    include: {
+      items: true, // Eager loading diệt N+1
+    },
+  });
+
+  if (!invoice) throw new NotFoundError("Invoice not found or access denied");
+  return invoice;
+}
+```
+
+### Python / SQLAlchemy:
+```python
+# ✅ An toàn: Eager loading joinedload + Filter theo User ID
+from sqlalchemy.orm import joinedload
+
+def get_user_order(db, order_id: str, user_id: str):
+    order = db.query(Order).options(
+        joinedload(Order.items) # Chống N+1 query
+    ).filter(
+        Order.id == order_id,
+        Order.user_id == user_id # Chống IDOR
+    ).first()
+    
+    if not order:
+        raise HTTPException(status_code=404, detail="Order not found")
+    return order
+```
+
+---
+
+## 6. Thích Ứng Theo Role Kỹ Thuật (Role Adaptation)
+
+| Role | Trọng tâm khi xử lý Backend & Data | Hành vi kỹ thuật đặc thù |
+|---|---|---|
+| `backend` | API architecture, transaction safety, business validation, JWT/OAuth | Viết Service layer, RBAC middleware, transaction manager |
+| `data` | Pipeline reliability, incremental processing, dbt models, SLA | Thiết kế Medallion (Bronze/Silver/Gold), partitioned loads, schema assertion |
+| `data-analyst` | SQL performance, aggregations, window functions, analytics views | Tối ưu complex queries, tạo materialized views, tính cohort metrics |
+| `data-architect` | Enterprise data model, governance, retention, contract compatibility | Thiết kế chuẩn hóa 3NF/Kimball, zero-downtime migration strategy |
+| `fullstack` | API schema contract, ORM updates, FE-BE type synchronization | Cập nhật schema, sinh types cho FE, tạo API handler |
+
+---
+
+## 7. Báo Cáo Nghiệm Thu Chuẩn Xác (Truth-First Report)
+
+```markdown
+🗄️ Backend & Data Summary                             [Role: <role> | Target: <API / DB / Pipeline>]
+─────────────────────────────────────────────────────────────────────
+Trạng thái:          [SUCCESS | BLOCKED | FAILED | PARTIAL]
+Nghiệp vụ thực hiện: [Endpoint mới / Migration / Tối ưu Query]
+Cơ sở dữ liệu / ORM: [PostgreSQL / MySQL / Prisma / SQLAlchemy]
+
+Các thay đổi kỹ thuật (Laser Focus):
+  • [API Endpoint]  [orderController.ts](file:///<workspace-root>/path): [Zod validation + Auth guard]
+  • [Migration]     [20260915_add_column.sql](file:///<workspace-root>/path): [Nullable, có rollback]
+
+Kiểm chứng thực tế (Verify Before Claim):
+  • Zero-Trust:       ✅ Middleware bảo vệ, chặn IDOR
+  • Migration Safety: ✅ Cột mới Nullable, có kịch bản Down/Rollback
+  • Query Plan:       [Đã diệt trừ N+1 bằng Eager loading | Đã kiểm tra Index tĩnh]
+  • Zero Hack:        ✅ Không dùng as any, không tắt ràng buộc DB, không bypass auth
+```
+
+---
+
+## 8. Mô Hình Độ Tin Cậy (Confidence Model)
+
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Direct evidence available | Proceed |
+| MEDIUM | Some assumptions needed | Note assumptions |
+| LOW | Insufficient evidence | EXIT: BLOCKED |
+
+---
+
+## 9. Thoái Ra Mã (Exit Codes)
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Task completed and verified | All acceptance criteria met |
+| PARTIAL | Task done with minor gaps | Some checks skipped |
+| BLOCKED | Missing precondition or info | Ask user |
+| FAILED | Task failed after max retries | Report error |
+
+---
+
+## 10. Bằng Chứng Định Dạng (Evidence Format)
+
+```
+[SEVERITY] path/to/file.ts:LINE
+Reason:     [why this matters]
+Confidence: [HIGH|MEDIUM|LOW]
+Fix:        [suggestion]
+```
+
+---
+
+## Platform-Specific Instructions
+
+### Antigravity (Google Gemini)
+- Uses `.agents/AGENTS.md` as entry point
+- Supports Cockpit integration
+- Rewrite absolute paths for global mode
+- `GEMINI.md` copied for global installs
+
+### Claude Code (Anthropic)
+- Reads `.claude/CLAUDE.md` automatically
+- Large context window (~200K tokens)
+- Can handle full skill files without trimming
+- Uses native tool format (Read, Write, Edit, Bash)
+
+### OpenCode (Open Source)
+- Reads `.opencode/config.yaml`
+- Context window ~128K tokens
+- Keep skill files lean when possible
+- Supports custom tool format
+
+---
+
+## Compliance
+
+| Check | Status |
+|-------|--------|
+| Runtime Standard | 11/11 |
+| Frontmatter Complete | ✅ |
+| Platforms Field | ✅ |
+| References Valid | ✅ |
+| Decision Trees | PASS |
+| Thresholds Defined | PASS |
+| schema_version | 10.2.0 |
+| runtime_version | 1 |
+| platforms | [antigravity, claude, opencode] |