# Database Schema — Bản đồ toàn bộ bảng phục vụ AI Chatbot

> **Tóm tắt:** 21 bảng trong `canifa_ai_dump.sqlite`, phân thành 6 nhóm chức năng. Tài liệu này mô tả chi tiết từng bảng, mối quan hệ JOIN, và vai trò trong pipeline AI Chatbot.

---

## Sơ đồ quan hệ (ER Diagram)

![ER — Entity Relationship](er_diagram.svg)

---

## 14 Database Diagrams — Bộ sưu tập đầy đủ

### 1. ER — Quan hệ bảng
![ER Diagram](er_diagram.svg)

### 2. Architecture — 6 nhóm kết nối
![Architecture](arch_db.svg)

### 3. Flowchart — Query routing qua bảng
![Flowchart](flow_db.svg)

### 4. Sequence — Timeline truy vấn
![Sequence](seq_db.svg)

### 5. State Machine — Vòng đời dữ liệu
![State Machine](state_db.svg)

### 6. Swimlane — Agent ↔ Table
![Swimlane](swim_db.svg)

### 7. Timeline — Pipeline xử lý data
![Timeline](timeline_db.svg)

### 8. Quadrant — Rows vs Importance
![Quadrant](quad_db.svg)

### 9. Nested — Nhóm bảng lồng nhau
![Nested](nested_db.svg)

### 10. Tree — Cây phụ thuộc bảng
![Tree](tree_db.svg)

### 11. Layer Stack — Tầng dữ liệu
![Layers](layers_db.svg)

### 12. Venn — 3-table enrichment
![Venn](venn_db.svg)

### 13. Pyramid — Khối lượng dữ liệu
![Pyramid](pyramid_db.svg)

### 14. Consultant 2×2 — Impact vs Volume
![Consultant](consult_db.svg)

---

## Tổng quan 6 nhóm bảng

```
┌─────────────────────────────────────────────────────────────────┐
│                   canifa_ai_dump.sqlite                          │
│                                                                  │
│  🔵 Nhóm 1: PRODUCT CORE          (1 bảng,  2,540 rows)        │
│  🟢 Nhóm 2: OUTFIT & FASHION      (4 bảng, 124,749 rows)      │
│  🟡 Nhóm 3: PRODUCT ENRICHMENT    (2 bảng,  2,919 rows)        │
│  🔴 Nhóm 4: CHAT & LEAD           (3 bảng,  1,520 rows)        │
│  🟣 Nhóm 5: AI CONFIG & PROMPT    (4 bảng,    107 rows)        │
│  ⚪ Nhóm 6: DASHBOARD & ADMIN     (5 bảng,     41 rows)        │
└─────────────────────────────────────────────────────────────────┘
```

---

## Nhóm 1: 🔵 PRODUCT CORE — Bảng SP chính

### `sr__test_db__magento_product_dimension_with_text_embedding`

| Thuộc tính | Giá trị |
|------------|---------|
| **Rows** | 2,540 |
| **Columns** | 44 |
| **Vai trò** | Bảng trung tâm — mọi tool search đều chọc vào đây |

**Columns quan trọng (44 cols):**

| Column | Type | Ý nghĩa | Tool sử dụng |
|--------|------|---------|--------------|
| `internal_ref_code` | TEXT | **PK** — Mã SP nội bộ (VD: `1AX24A002`) | Tất cả |
| `product_name` | TEXT | Tên sản phẩm | Search, Stylist |
| `product_line_vn` | TEXT | Dòng SP tiếng Việt (Áo phông, Quần jean...) | Classifier, Search |
| `gender_by_product` | TEXT | `men/women/boy/girl/unisex` | Search filter |
| `age_by_product` | TEXT | `adult/kid` | Search filter |
| `sale_price` | REAL | Giá bán | Search, Stylist |
| `original_price` | REAL | Giá gốc | Tính discount |
| `discount_amount` | REAL | % giảm giá | Search filter |
| `style` | TEXT | `Feminine/Dynamic/Essential/Classic` | BITMAP search |
| `fitting` | TEXT | `Slim/Regular/Relax` | BITMAP search |
| `season_sale` | TEXT | `Year/Winter/Summer` | BITMAP search |
| `master_color` | TEXT | Màu chính (VN/EN) | Color filter |
| `tags` | TEXT | JSON tags `["occ:di_choi","style:basic"]` | Tag search |
| `similar_items` | TEXT | JSON mã SP tương tự | Similar enrichment |
| `suggest_items` | TEXT | JSON gợi ý (⚠️ không chuẩn, dùng outfit thay thế) | — |
| `description_text` | TEXT | Mô tả ngắn | Stylist context |
| `description_text_full` | TEXT | Mô tả đầy đủ | Ultra desc fallback |
| `quantity_sold` | REAL | Số lượng đã bán | Sort by popularity |
| `is_new_product` | INTEGER | Sản phẩm mới | Discovery mode |
| `size_scale` | TEXT | Size có sẵn | Size message |
| `product_image_url_thumbnail` | TEXT | Ảnh thumbnail | Response UI |
| `product_web_url` | TEXT | Link web SP | Response UI |
| `vector` | REAL | Embedding vector | Vector search (future) |

---

## Nhóm 2: 🟢 OUTFIT & FASHION — Phối đồ

### `pg__dashboard_canifa__ai_outfit_product_matches` ⭐

| Thuộc tính | Giá trị |
|------------|---------|
| **Rows** | 124,000 |
| **Columns** | 12 |
| **JOIN key** | `anchor_product_code` → Product.`internal_ref_code` |
| **Vai trò** | Bảng phối đồ CHUẨN — mỗi SP anchor có 5-50 SP match |

| Column | Ý nghĩa |
|--------|---------|
| `anchor_product_code` | SP gốc (khách đang xem) |
| `match_product_code` | SP phối đồ đề xuất |
| `match_product_name` | Tên SP phối |
| `match_role` | `top/bottom/accessory/footwear` |
| `match_gender` | Giới tính SP phối |
| `match_age` | Độ tuổi SP phối |
| `score` | Điểm phối (0-100) |
| `ai_reason` | LLM giải thích tại sao phối kiểu này |
| `occasion` | Dịp mặc (đi chơi, đi làm...) |

### `pg__dashboard_canifa__chatbot_fashion_rules`

| Thuộc tính | Giá trị |
|------------|---------|
| **Rows** | 698 |
| **Vai trò** | Rules phối đồ theo gender + occasion + category |

| Column | Ý nghĩa |
|--------|---------|
| `gender_target` | Giới tính target |
| `anchor_category` | Loại SP gốc (VD: Áo phông) |
| `occasion` | Dịp (đi làm, đi chơi, đi biển...) |
| `match_role` | Vị trí phối (top/bottom/accessory) |
| `target_category` | Loại SP nên phối (VD: Quần jean) |
| `ai_reason` | Lý do phối |

### `chatbot_fashion_rules` (Legacy)

| **Rows** | 51 | Rules phối đồ cũ — đang được thay thế bởi bảng trên |

### `pg__dashboard_canifa__ai_outfit_set/items` (Trống)

| Bảng | Rows | Ghi chú |
|------|------|---------|
| `ai_outfit_set` | 0 | Outfit sets — chưa dùng |
| `ai_outfit_items` | 0 | Outfit items — chưa dùng |

---

## Nhóm 3: 🟡 PRODUCT ENRICHMENT — Làm giàu SP

### `pg__dashboard_canifa__ultra_descriptions` ⭐

| Thuộc tính | Giá trị |
|------------|---------|
| **Rows** | 1,930 |
| **Columns** | 18 |
| **JOIN key** | `internal_ref_code` → Product.`internal_ref_code` |
| **Vai trò** | Mô tả AI sâu — tagline, chất liệu, lý do mua, cross-sell |

| Column | Ý nghĩa |
|--------|---------|
| `description_data` | JSON đầy đủ (20+ fields) |
| `description_data_cut` | JSON rút gọn cho AI context |
| `clean_description` | Mô tả dạng text sạch |
| `tags` | Tags occasion/style JSON |
| `size_scale` | Size có sẵn JSON |
| `size` | Bảng size markdown |
| `embedding` | Vector embedding |

**`description_data_cut` JSON chứa:**
```json
{
  "ten_san_pham": "Quần Lót Brief Bé Gái",
  "mo_ta_chinh": "Form dáng brief ôm nhẹ...",
  "chat_lieu": "95% cotton, 5% spandex",
  "tagline": "Bảo vệ làn da bé yêu...",
  "phong_cach": "Trung tính, thoải mái",
  "ly_do_mua": "Oeko-Tex chứng nhận an toàn...",
  "cross_sell": "Áo lót cùng BST..."
}
```

### `pg__dashboard_canifa__product_size_guide`

| **Rows** | 989 | Bảng size HTML theo SP |
| **JOIN key** | `internal_ref_code` |
| **Data** | `sizeguide_content` = HTML bảng size đầy đủ |

---

## Nhóm 4: 🔴 CHAT & LEAD — Lịch sử chat

### `pg__canifa_chat__lead_flow_history`

| **Rows** | 1,488 | Lịch sử chat lead-flow |
| **Columns** | message, ai_response, products (JSON), lead_stage |

### `pg__dashboard_canifa__chat_history`

| **Rows** | 16 | Chat history dashboard module |

### `faqs`

| **Rows** | 63 | FAQ + variants cho BM25 search |

---

## Nhóm 5: 🟣 AI CONFIG & PROMPT

| Bảng | Rows | Vai trò |
|------|------|---------|
| `pg__public__prompt_rules` | 16 | Dynamic prompt rules (từ feedback loop) |
| `pg__dashboard_canifa__desc_field_config` | 28 | Config fields cho Ultra Description |
| `pg__dashboard_canifa__system_settings` | 0 | System settings (chưa dùng) |
| `dashboard_links` | 16 | Dashboard navigation links |

---

## Nhóm 6: ⚪ DASHBOARD & ADMIN

| Bảng | Rows | Vai trò |
|------|------|---------|
| `pg__dashboard_canifa__admin_users` | 2 | Admin users |
| `pg__dashboard_canifa__activity_logs` | 0 | Activity logs |
| `pg__dashboard_canifa__saved_reports` | 6 | Saved AI reports |
| `pg__dashboard_canifa__sql_trace_sessions` | 17 | SQL trace sessions |

---

## Bảng JOIN chính cho AI Agent Pipeline

```
┌──────────────────────────────────────────────────────────────────┐
│                     AI AGENT PIPELINE                             │
│                                                                   │
│  User Query                                                       │
│      │                                                            │
│      ▼                                                            │
│  ┌─ Classifier ─┐                                                │
│  │  FAQ (63)     │   ← faqs table (BM25)                        │
│  │  Prompt (16)  │   ← prompt_rules table                       │
│  └──────┬────────┘                                                │
│         ▼                                                         │
│  ┌─ Product Search (7-Tier) ──────────────────────────────────┐  │
│  │  Product (2,540)      ← sr__test_db__magento_...           │  │
│  │    │                                                        │  │
│  │    ├─→ Outfit (124K)  ← ai_outfit_product_matches          │  │
│  │    │   JOIN by anchor_product_code                          │  │
│  │    │                                                        │  │
│  │    ├─→ Ultra Desc (1.9K) ← ultra_descriptions              │  │
│  │    │   JOIN by internal_ref_code                            │  │
│  │    │                                                        │  │
│  │    ├─→ Similar Items  ← Product.similar_items (self-join)   │  │
│  │    │                                                        │  │
│  │    └─→ Fashion Rules (698) ← chatbot_fashion_rules         │  │
│  │        Logic: anchor_category → target_category by occasion │  │
│  └─────────────────────────────────────────────────────────────┘  │
│         ▼                                                         │
│  ┌─ Stylist ─────┐                                                │
│  │  Compose       │   Uses: product data + outfit + ultra desc    │
│  │  Response      │                                               │
│  └───────────────┘                                                │
└──────────────────────────────────────────────────────────────────┘
```

---

## Quick Reference: JOIN Queries

### 1. Search → Outfit (phối đồ)
```sql
SELECT b.match_product_code, b.match_role, b.score, b.ai_reason
FROM [pg__dashboard_canifa__ai_outfit_product_matches] b
WHERE b.anchor_product_code = 'SKU_FROM_SEARCH'
ORDER BY b.score DESC
LIMIT 5
```

### 2. Search → Ultra Description
```sql
SELECT c.description_data_cut
FROM [pg__dashboard_canifa__ultra_descriptions] c
WHERE c.internal_ref_code = 'SKU_FROM_SEARCH'
```

### 3. Search → Similar (self-join)
```sql
-- Step 1: Get similar_items JSON from product
-- Step 2: Parse JSON → list of SKUs
-- Step 3: Query product table again
SELECT product_name, sale_price, product_image_url_thumbnail
FROM [sr__test_db__magento_product_dimension_with_text_embedding]
WHERE internal_ref_code IN ('SKU1', 'SKU2', 'SKU3')
```

### 4. Fashion Rules (phối đồ theo occasion)
```sql
SELECT target_category, match_role, ai_reason
FROM [pg__dashboard_canifa__chatbot_fashion_rules]
WHERE anchor_category = 'Ao phong'
  AND gender_target = 'women'
  AND occasion LIKE '%di choi%'
```
