# 📋 TÀI LIỆU KỸ THUẬT HỆ THỐNG CANIFA AI STYLIST CHATBOT

> **Phiên bản**: 2.0 — Cập nhật: 09/03/2026  
> **Tác giả**: Team AI Canifa  
> **Mục đích**: Tài liệu chi tiết kiến trúc, chức năng, và vận hành hệ thống Chatbot AI Tư vấn Thời trang CANIFA

---

## 📑 MỤC LỤC

1. [Tổng quan hệ thống](#1-tổng-quan-hệ-thống)
2. [Kiến trúc kỹ thuật](#2-kiến-trúc-kỹ-thuật)
3. [Tech Stack & Infrastructure](#3-tech-stack--infrastructure)
4. [Chatbot V1 — Agent + Vector Search](#4-chatbot-v1--agent--vector-search)
5. [Chatbot V2 — Embedding + Vector Search](#5-chatbot-v2--embedding--vector-search)
6. [Database & Data Pipeline](#6-database--data-pipeline)
7. [API Endpoints](#7-api-endpoints)
8. [Prompt Engineering](#8-prompt-engineering)
9. [Agent Tools](#9-agent-tools)
10. [Hệ thống Feedback & Đánh giá](#10-hệ-thống-feedback--đánh-giá)
11. [Observability & Monitoring (Langfuse)](#11-observability--monitoring-langfuse)
12. [Automated Testing (n8n)](#12-automated-testing-n8n)
13. [Caching & Performance](#13-caching--performance)
14. [Security & Middleware](#14-security--middleware)
15. [So sánh V1 vs V2](#15-so-sánh-v1-vs-v2)
16. [Hướng phát triển](#16-hướng-phát-triển)

---

## 1. TỔNG QUAN HỆ THỐNG

### 1.1 Mô tả
Canifa AI Stylist là chatbot tư vấn thời trang thông minh, giúp khách hàng CANIFA:
- **Tìm kiếm sản phẩm** theo nhu cầu (áo, quần, phụ kiện...)
- **Tư vấn phối đồ** theo dịp, giới tính, lứa tuổi
- **Kiểm tra tồn kho** real-time theo size, màu
- **Gợi ý sản phẩm** dựa trên sở thích và ngân sách
- **Cung cấp thông tin khuyến mãi** và chính sách bán hàng

### 1.2 Hai phiên bản Chatbot

|                  | V1 (Agent)                    | V2 (Direct Search)              |
| ---------------- | ----------------------------- | ------------------------------- |
| **Kiến trúc**    | LangGraph Agent + Tools       | Embedding → Vector Search → LLM |
| **Số bước**      | Agent tự quyết định gọi tools | 3 bước cố định                  |
| **LLM calls**    | 2-5 lần (agent loop)          | 1 lần                           |
| **Embedding**    | 1 lần (search)                | 1 lần (search)                  |
| **Thời gian TB** | 3-6 giây                      | 2-3 giây                        |
| **Độ linh hoạt** | Cao (multi-tool)              | Trung bình (chỉ search)         |
| **Use case**     | Câu hỏi phức tạp, multi-step  | Tìm kiếm sản phẩm nhanh         |

---

## 2. KIẾN TRÚC KỸ THUẬT

### 2.1 System Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    FRONTEND (HTML/JS)                    │
│  index.html │ test_sql.html │ test_db.html │ history.html│
└──────────────────────┬──────────────────────────────────┘
                       │ HTTP/REST API
┌──────────────────────▼──────────────────────────────────┐
│                  FastAPI Server (:5000)                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
│  │ Chat V1  │ │ Chat V2  │ │ Feedback │ │ Stock API  │ │
│  │ /api/    │ │ /api/v2/ │ │ /api/    │ │ /api/stock │ │
│  │ agent/   │ │ chat     │ │ feedback │ │ /check     │ │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └─────┬──────┘ │
│       │            │            │              │         │
│  ┌────▼─────┐ ┌────▼─────┐ ┌───▼──────┐       │         │
│  │LangGraph │ │Embedding │ │GPT-4.1   │       │         │
│  │ Agent    │ │+ Vector  │ │Classifier│       │         │
│  │(Gemini)  │ │ Search   │ │          │       │         │
│  └────┬─────┘ └────┬─────┘ └──────────┘       │         │
└───────┼────────────┼───────────────────────────┼─────────┘
        │            │                           │
┌───────▼────────────▼───────────────────────────▼─────────┐
│                    DATA LAYER                             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐  │
│  │StarRocks │ │  Redis   │ │PostgreSQL│ │  Langfuse   │  │
│  │(Products │ │ (Cache)  │ │(History) │ │(Observ.)    │  │
│  │+Vectors) │ │          │ │          │ │             │  │
│  └──────────┘ └──────────┘ └──────────┘ └────────────┘  │
└──────────────────────────────────────────────────────────┘
```

### 2.2 Cấu trúc thư mục

```
backend/
├── server.py                    # FastAPI main app
├── config.py                    # Environment config
├── api/                         # API Routes (10 files)
│   ├── chatbot_route.py         # V1 Chat endpoints
│   ├── text_to_sql_route.py     # V2 Chat endpoint
│   ├── feedback_route.py        # Feedback endpoints
│   ├── stock_route.py           # Stock check API
│   ├── prompt_route.py          # Prompt management
│   ├── n8n_api_route.py         # n8n testing APIs
│   ├── check_history_route.py   # Chat history
│   ├── conservation_route.py    # Conversation mgmt
│   ├── mock_api_route.py        # Mock endpoints
│   └── tool_prompt_route.py     # Tool prompt config
├── agent/
│   ├── graph.py                 # LangGraph agent (V1)
│   ├── controller.py            # Chat controller logic
│   ├── text_to_sql.py           # V2: Embed→Search→LLM
│   ├── streaming_callback.py    # SSE streaming
│   ├── prompt_module/           # 10 prompt modules
│   └── tools/                   # 10+ agent tools
├── common/
│   ├── llm_factory.py           # LLM instance factory
│   ├── embedding_service.py     # OpenAI embedding
│   ├── starrocks_connection.py  # StarRocks DB
│   ├── cache.py                 # Redis cache (2 layers)
│   ├── conversation_manager.py  # Chat history (PostgreSQL)
│   ├── middleware.py            # Auth, CORS, Rate limit
│   └── feedback_tracker.py      # Feedback storage
└── static/                      # Frontend test pages
```

---

## 3. TECH STACK & INFRASTRUCTURE

### 3.1 AI/LLM

| Component           | Technology                        | Mục đích                       |
| ------------------- | --------------------------------- | ------------------------------ |
| LLM chính           | **Google Gemini 3.1 Flash-Lite**  | Sinh response, agent reasoning |
| Embedding           | **OpenAI text-embedding-3-small** | Vector hóa câu hỏi (1536 dims) |
| Feedback Classifier | **GPT-4.1-mini**                  | Phân loại complaint            |
| AI Judge (n8n)      | **GPT-5-mini**                    | Auto-test chấm điểm            |
| Framework           | **LangChain + LangGraph**         | Agent framework                |

### 3.2 Database & Storage

| Component     | Technology         | Server             | Mục đích                         |
| ------------- | ------------------ | ------------------ | -------------------------------- |
| Product Data  | **StarRocks**      | 172.16.2.100:9030  | Product catalog + Vector search  |
| Cache         | **Redis**          | 172.16.2.192:6379  | Response cache + Embedding cache |
| Chat History  | **PostgreSQL**     | 172.16.2.190:15433 | Conversation persistence         |
| Observability | **Langfuse Cloud** | cloud.langfuse.com | Tracing, scoring, prompts        |

### 3.3 Backend

| Component     | Technology                |
| ------------- | ------------------------- |
| Web Framework | **FastAPI** (Python 3.12) |
| ASGI Server   | **Uvicorn** (hot reload)  |
| Auth          | **JWT + Clerk**           |
| Rate Limiting | Custom middleware         |

---

## 4. CHATBOT V1 — AGENT + VECTOR SEARCH

### 4.1 Luồng xử lý

```
User gửi câu hỏi
    ↓
[1] Load prompt từ Langfuse (10 modules)
    ↓
[2] Load conversation history (PostgreSQL)
    ↓
[3] LangGraph Agent nhận câu hỏi + history + prompt
    ↓
[4] Agent quyết định gọi tool nào:
    ├── data_retrieval_tool → Vector Search sản phẩm
    ├── check_is_stock → Kiểm tra tồn kho
    ├── brand_knowledge_tool → Kiến thức thương hiệu
    ├── promotion_canifa_tool → Khuyến mãi
    ├── store_search_tool → Tìm cửa hàng
    └── customer_info_tool → Thông tin khách
    ↓
[5] Agent nhận kết quả → sinh response
    ↓
[6] Streaming response (SSE) → Frontend
    ↓
[7] Log vào Langfuse + Lưu history PostgreSQL
```

### 4.2 Endpoint
```
POST /api/agent/chat-dev
Body: { "message": "...", "user_id": "...", "device_id": "..." }
Response: SSE stream
```

---

## 5. CHATBOT V2 — EMBEDDING + VECTOR SEARCH

### 5.1 Luồng xử lý

```
User gửi câu hỏi
    ↓
[1] OpenAI Embedding (~200ms) → 1536 dims
    ↓
[2] Vector Search StarRocks (~200ms) → Top 30 SP
    ↓
[3] Gemini viết response (~2s) → Top 10 SP cho LLM
    ↓
[4] JSON response (products + timing)
```

### 5.2 Endpoint
```
POST /api/v2/chat
Body: { "user_query": "tìm áo lót nữ" }
Response: { ai_response, products[30], timing, product_count }
```

---

## 6. DATABASE — STARROCKS SCHEMA

**Bảng**: `shared_source.magento_product_dimension_with_text_embedding`

| Column            | Type         | Mô tả                     |
| ----------------- | ------------ | ------------------------- |
| magento_ref_code  | VARCHAR      | Mã SKU                    |
| product_name      | VARCHAR      | Tên SP                    |
| master_color      | VARCHAR      | Màu chính                 |
| sale_price        | DECIMAL      | Giá bán (VND)             |
| original_price    | DECIMAL      | Giá gốc                   |
| gender_by_product | VARCHAR      | women/men/boy/girl/unisex |
| age_by_product    | VARCHAR      | adult/kid/others          |
| product_line_vn   | VARCHAR      | Dòng SP                   |
| vector            | ARRAY<FLOAT> | Embedding 1536 dims       |
| size_scale        | VARCHAR      | S,M,L,XL                  |
| quantity_sold     | INT          | Đã bán                    |

---

## 7. API ENDPOINTS (Tóm tắt)

| Method | Endpoint                  | Mô tả               |
| ------ | ------------------------- | ------------------- |
| POST   | `/api/agent/chat-dev`     | V1 Chat (streaming) |
| POST   | `/api/v2/chat`            | V2 Chat (JSON)      |
| POST   | `/api/feedback/score`     | Like/Dislike        |
| POST   | `/api/feedback/complaint` | Khiếu nại           |
| GET    | `/api/prompt/current`     | Xem prompt          |
| POST   | `/api/prompt/refresh`     | Refresh prompt      |
| GET    | `/api/history/{user_id}`  | Lịch sử chat        |
| POST   | `/api/stock/check`        | Tồn kho             |
| POST   | `/api/n8n/chat`           | n8n test            |

---

## 8. PROMPT ENGINEERING (10 Modules)

| #     | File                | Mục đích                   |
| ----- | ------------------- | -------------------------- |
| 01    | `core.txt`          | Persona AI Stylist         |
| 02    | `rules.txt`         | Quy tắc ứng xử             |
| 03    | `context.txt`       | Context sản phẩm           |
| 04a-d | `sales_*.txt`       | Kỹ năng bán hàng (4 files) |
| 05    | `tool_routing.txt`  | Logic chọn tool            |
| 06    | `user_insight.txt`  | Phân tích sở thích         |
| 07    | `output_format.txt` | Format response            |

Prompt quản lý qua **Langfuse** → version-controlled, không cần deploy lại.

---

## 9. FEEDBACK & AUTO-TEST

### User Feedback
- 👍/👎 Like/Dislike → Langfuse score
- 📢 Complaint → GPT-4.1-mini phân loại → Langfuse

### n8n Auto-test (hàng ngày 8:00 AM)
- Sinh 20 câu hỏi test → Gọi chatbot → AI Judge chấm điểm → Log Google Sheets

---

## 10. CACHING (Redis 2 Layers)

| Layer             | TTL    | Mục đích               |
| ----------------- | ------ | ---------------------- |
| **L1: Response**  | 5 phút | Cache full response    |
| **L2: Embedding** | 24 giờ | Cache OpenAI embedding |

---

## 11. SO SÁNH V1 VS V2

| Tiêu chí     | V1 (Agent)    | V2 (Direct)     |
| ------------ | ------------- | --------------- |
| Tốc độ       | 3-6s          | ~2.5s ✅         |
| LLM calls    | 2-5           | 1 ✅             |
| Cost/request | ~$0.003-0.008 | ~$0.001-0.002 ✅ |
| Tồn kho      | ✅             | ❌               |
| Cửa hàng     | ✅             | ❌               |
| History      | ✅             | ❌               |
| Streaming    | ✅             | ❌               |

---

## 12. HƯỚNG PHÁT TRIỂN

- [ ] Streaming cho V2
- [ ] Cache Redis cho V2
- [ ] A/B test V1 vs V2
- [ ] Dashboard quản lý (khi BA yêu cầu)
- [ ] Multi-modal (gửi ảnh tìm SP)

---

> Cập nhật: 09/03/2026
