---
name: creta-dwh-agent
description: "Trợ lý Phân tích Dữ liệu Kinh doanh CRETA Data Warehouse (DWH Data Vault 2.0). Truy vấn doanh thu sạch (lọc 15.000+ đơn ảo trên 20 triệu), công nợ khách hàng (AR), truy vết 29.570 barcode serials xuất kho, đối soát dòng tiền thu chi và kiểm tra bảo hành. Triggers on 'dwh', 'doanh thu dwh', 'công nợ dwh', 'doanh thu sạch', 'doanh thu thật', 'đơn ảo', 'tra cứu barcode dwh', 'serial dwh', 'bảo hành dwh', 'dòng tiền dwh', 'data.creta.vn'."
---

# 🏛️ CRETA DATA WAREHOUSE (DWH) AGENT SKILL RUNBOOK

Kỹ năng truy vấn, phân tích và giải đáp số liệu kinh doanh thực tế từ **CRETA Data Warehouse (Data Vault 2.0 trên PostgreSQL 16)** qua cổng MCP tại `https://data.creta.vn/mcp`.

---

## 💎 1. NGUYÊN TẮC BẢO MẬT & CHUẨN MỰC SỐ LIỆU

1. **Tuyệt đối phân biệt Doanh thu thật và Doanh thu gộp (Đơn ảo):**
   * Trong KiotViet có hơn **15.000 đơn hàng ảo** (dùng để luân chuyển nội bộ hoặc đơn kỹ thuật >20 triệu).
   * **Bắt buộc** luôn sử dụng số liệu từ `real_revenue` / `real_count` khi báo cáo cho Sếp Lâm và Ban Giám Đốc.
   * Không bao giờ lấy số tổng thô (`total_revenue`) chưa qua lọc làm doanh thu thật.
2. **Quy tắc an toàn dữ liệu (Read-Only 100%):**
   * Mọi câu lệnh SQL gửi vào DWH đều bị cưỡng chế trong chế độ `BEGIN READ ONLY;`.
   * Tuyệt đối không thực thi các câu lệnh thay đổi cấu trúc (`DROP`, `TRUNCATE`, `ALTER`) hay cập nhật dữ liệu (`UPDATE`, `DELETE`).
3. **Phân quyền truy cập tài khoản:**
   * Quyền `dwh:read`: Xem doanh thu, dòng tiền, công nợ, barcode, bảo hành, ticket.
   * Quyền `dwh:admin`: Mở khóa thêm công cụ chạy câu lệnh SQL phân tích tự do (`dwh_safe_sql_query`).

---

## ⚡ 2. CÁC KỊCH BẢN ĐIỀU PHỐI TỰ ĐỘNG

### KỊCH BẢN 1: BÁO CÁO DOANH THU & DÒNG TIỀN THEO NGÀY
* **Người dùng hỏi:** *"Hôm nay doanh thu bán thật được bao nhiêu? 3 ngày gần nhất thế nào?"*
* **Hành động của Agent:**
  1. Gọi `dwh_get_clean_revenue(days=3)`.
  2. Phân tích kết quả:
     * Nêu rõ **Doanh thu sạch thực tế** (`realRevenue`) và **Số đơn thật** (`realOrders`).
     * Nêu rõ số tiền đơn ảo đã được hệ thống tự động bóc tách loại bỏ (`fakeRevenueFilteredOut`).
  3. Báo cáo ngắn gọn, dứt khoát theo phong cách điều hành CRETA.

### KỊCH BẢN 2: TRA CỨU CÔNG NỢ KHÁCH HÀNG (AR)
* **Người dùng hỏi:** *"Khách hàng Phương Nam đang nợ bao nhiêu tiền?"* hoặc *"Cho anh xem danh sách 10 khách nợ nhiều nhất."*
* **Hành động của Agent:**
  1. Gọi `dwh_get_customer_debt(search="Phương Nam", limit=10)`.
  2. Báo cáo: Mã khách hàng, Tên, Số điện thoại, Tổng số tiền nợ hiện tại, và doanh số tích lũy trọn đời (`lifetimeRevenue`).

### KỊCH BẢN 3: TRUY VẾT MÃ VẠCH / SỐ SERIAL THIẾT BỊ (BARCODE TRACE)
* **Người dùng hỏi:** *"Kiểm tra giúp anh con camera serial BE03340PAJ1A8B5 xuất kho ngày nào, bán cho ai?"*
* **Hành động của Agent:**
  1. Gọi `dwh_lookup_barcode_serial(barcode="BE03340PAJ1A8B5")`.
  2. Đọc kết quả trong kho 29.570 serials:
     * Mã sản phẩm, Tên hàng đầy đủ.
     * Ngày giờ quét barcode xuất kho.
     * Số hóa đơn KiotViet liên kết (vd: `HD021958`).
     * Tên khách hàng mua máy.
     * Trạng thái vận hành (`B5` Xuất kho, `B8` Giao hàng).

### KỊCH BẢN 4: TRA CỨU TIẾN ĐỘ BẢO HÀNH & SỬA CHỮA
* **Người dùng hỏi:** *"Phiếu bảo hành số 0123 tiến độ tới đâu rồi em? Đã gửi hãng chưa?"*
* **Hành động của Agent:**
  1. Gọi `dwh_lookup_warranty_ticket(search="0123")`.
  2. Đọc trạng thái quy trình 12 bước (A1 Tiếp nhận, B1 Kiểm tra, B3 Đang gửi hãng, C6 Đã trả khách).
  3. Báo ngày hẹn trả và mã phiếu trả cho khách hàng.

---

## 🛠️ 3. DANH MỤC CÔNG CỤ MCP HỖ TRỢ (`dwh_*`)

* `dwh_whoami`: Xem danh tính, vai trò và phạm vi quyền truy cập DWH.
* `dwh_get_clean_revenue`: Lấy doanh thu & số đơn sạch thực tế (đã loại trừ 15k+ đơn ảo).
* `dwh_get_cashflow`: Báo cáo dòng tiền thu/chi và thặng dư ròng theo ngày từ KiotViet.
* `dwh_get_top_products`: Danh sách sản phẩm bán chạy nhất theo số lượng hoặc doanh thu.
* `dwh_get_customer_debt`: Danh sách nợ đọng hoặc tra cứu công nợ 1 khách hàng cụ thể.
* `dwh_lookup_customer`: Hồ sơ 360 khách hàng (phân khúc VIP/Gold/Silver, đơn hàng, ngày mua cuối).
* `dwh_lookup_barcode_serial`: Truy vết nguồn gốc xuất kho của 29.570 serial camera/đầu ghi.
* `dwh_get_invoice_pipeline`: Theo dõi tiến độ đường ống đơn hàng xuất kho B1-B8.
* `dwh_lookup_warranty_ticket`: Tra cứu tiến độ phiếu bảo hành, tình trạng gửi hãng và trả máy.
* `dwh_get_staff_tasks_summary`: Tiến độ thực hiện checklist & task công việc của nhân viên CRETA.
* `dwh_get_creta_tickets_summary`: Báo cáo khiếu nại & ticket kỹ thuật theo SLA.
* `dwh_safe_sql_query`: *(Admin only)* Chạy câu lệnh SQL SELECT trực tiếp trên DWH ở chế độ READ ONLY an toàn.


---

# Cấu Trúc Schema & Bảng Dữ Liệu CRETA Data Vault 2.0

Data Warehouse vận hành trên PostgreSQL 16 (cổng 5434), phân tách làm 4 schema chuẩn:

## 1. Schema `business_vault` (Các View và Data Marts Nghiệp Vụ)
- **`daily_revenue`**: Doanh thu tổng hợp theo ngày gồm tổng doanh thu, doanh thu ảo, doanh thu sạch (`real_revenue`), số đơn sạch (`real_count`).
- **`v_daily_cashflow`**: Dòng tiền thu/chi theo ngày (`total_in`, `total_out`, `net_flow`).
- **`top_products`**: Sản phẩm bán chạy nhất kèm tổng số lượng bán thật (`total_quantity`), tổng doanh thu (`total_revenue`).
- **`top_customers`**: Khách hàng mua nhiều nhất, ngày mua đầu, ngày mua cuối, số ngày chưa quay lại (`days_since_last`).
- **`customer_segments`**: Phân loại khách hàng: VIP (>100tr), Gold (50-100tr), Silver (10-50tr), Bronze (1-10tr), Lead (<1tr).
- **`v_creta_barcode_detail`**: Liên kết 29.570 serials xuất kho với mã hóa đơn, tên khách, ngày mua và trạng thái vận hành.
- **`v_creta_invoice_pipeline`**: Báo cáo số lượng và giá trị đơn hàng đang kẹt ở từng khâu: B1 Soạn, B4 Đóng gói, B5 Xuất kho, B8 Giao khách.
- **`v_monitor_warranty_evidence`**: Phiếu bảo hành liên kết khách hàng, tiến độ xử lý và xác nhận hoàn tất trả khách.

## 2. Schema `raw_vault` (Các Hubs, Links, Satellites Cốt Lõi)
- Hubs (`h_*`): `h_customer`, `h_product`, `h_invoice`, `h_cashflow`, `h_creta_barcode`, `h_warranty_ticket`.
- Links (`l_*`): `l_invoice_customer`, `l_invoice_product`, `l_creta_barcode_invoice`, `l_ticket_customer`.
- Satellites (`s_*`): `s_customer_info`, `s_product_info`, `s_creta_barcode_info`, `s_warranty_item_state`.

## 3. Schema `ops` (Quản Trị Vận Hành & MCP Server)
- `mcp_users`: Danh sách tài khoản người dùng đăng nhập hệ thống MCP (bcrypt password).
- `mcp_clients`: Các ứng dụng Agent đã đăng ký OAuth.
- `mcp_auth_codes`: Mã xác thực PKCE S256 tạm thời (TTL 10 phút).
- `mcp_connections`: Phiên kết nối đang hoạt động, hỗ trợ thu hồi quyền tức thì (`revoked_at`).


---

# Quy Tắc Nhận Diện & Loại Trừ Đơn Ảo Trong DWH

## 1. Bản Chất Đơn Ảo Tại CRETA
Trong quá trình kinh doanh, nhân viên CRETA thường tạo các đơn hàng kỹ thuật trên KiotViet với mục đích:
- Tạo hóa đơn giữ hàng cho dự án công trình chưa quyết toán.
- Đơn hàng xuất kho luân chuyển giữa các kho kỹ thuật.
- Đơn tạo thử nghiệm hoặc ghi chú với số tiền lớn (>20 triệu hoặc số tiền tròn chẵn).

## 2. Bảng Danh Sách Đơn Ảo Đã Được Kiểm Duyệt
DWH duy trì bảng lọc:
`staging.ggsheet_fake_invoices` (đồng bộ trực tiếp từ Google Sheets của Kế toán & Quản trị).
Toàn bộ view trong `business_vault` (như `daily_revenue`, `top_products`, `top_customers`) đều thực hiện phép `LEFT JOIN staging.ggsheet_fake_invoices f ON i.code = f.invoice_code` và áp dụng điều kiện:
```sql
WHERE f.invoice_code IS NULL
```

## 3. Công Thức Tính Doanh Thu Sạch
$$\text{Doanh Thu Sạch} = \sum \text{Hóa Đơn Hợp Lệ} - \sum \text{Đơn Thuộc Danh Sách Ảo}$$
- Số tiền đơn ảo không được tính vào KPI doanh số nhân viên.
- Không được dùng đơn ảo để tính số lượng bán chạy cho ma trận bảng giá (`popularity.score`).


---

# Ví Dụ Mẫu: Đối Soát Số Liệu & Giải Đáp Nghiệp Vụ

## Tình Huống 1: Báo Cáo Doanh Thu Cuối Ngày
* **Sếp Lâm hỏi:** *"Hôm nay bán được bao nhiêu tiền? Mấy đơn? Có đơn ảo không?"*
* **Agent xử lý ngầm:**
  * Gọi `dwh_get_clean_revenue({ days: 1 })`
* **Agent phản hồi:**
  > *"📊 **BÁO CÁO DOANH THU HÔM NAY (15/10/2026):**
  > • Doanh thu sạch: **900.000 đ** (1 đơn hàng thật)
  > • Đơn ảo: 0 đơn (0 đ)
  > • Tổng gộp: 900.000 đ
  > 
  > 3 ngày gần nhất (13/10 - 15/10) đạt tổng cộng **139.822.500 đ** với 24 đơn hàng thật nha Sếp."*

---

## Tình Huống 2: Tra Cứu Serial Thiết Bị Khi Khách Báo Lỗi
* **Kỹ thuật hỏi:** *"Khách mang tới con camera serial 1100404743202323, kiểm tra xem máy này bán ngày nào cho ai?"*
* **Agent xử lý ngầm:**
  * Gọi `dwh_lookup_barcode_serial({ barcode: "1100404743202323" })`
* **Agent phản hồi:**
  > *"🔍 **LÝ LỊCH THIẾT BỊ TRONG KHO DWH:**
  > • Mã SP: **SP901460** (NETIS - Switch 8 cổng PoE 100Mbps - ST110PDI-2-65)
  > • Quét xuất kho lúc: 09:38:05 ngày 15/10/2026
  > • Hóa đơn xuất: **HD021959.02**
  > • Trạng thái: Đã xuất kho thành công."*