Phase 7: Hoàn thiện Modular RAG Backend với FastAPI và Đa LLM Provider

doc/00.AGENT_ARCHITECTURE_MAP.md

@@ -0,0 +1,88 @@
+# 🧭 AGENT ARCHITECTURE MAP (LIVING DOCUMENT)
+*Đây là tài liệu dẫn đường dành riêng cho các AI Agent tương lai và lập trình viên bảo trì. Không quét toàn bộ code, hãy đọc file này trước.*
+
+**Lần cập nhật cuối:** Phase 6 (Hoàn thiện Semantic Chunking & Vector Indexing)
+**Trạng thái Dự án:** Đã hoàn thành Ingestion, Extraction, Chunking & Indexing. Chuẩn bị bước vào Phase 7 (RAG Search & Chat API).
+
+---
+
+## 1. Bản Đồ Kiến Trúc Lõi (Core Architecture Patterns)
+
+### A. Tầng Ingestion (Thu thập dữ liệu) - Mẫu Modular Provider Pattern
+- **Mục tiêu:** Tách biệt lõi hệ thống khỏi nền tảng lưu trữ (SharePoint, Google Drive, v.v.).
+- **Interface gốc:** `ingestion/providers/base_provider.py` (Bắt buộc phải implement `fetch_changes` và `download_file`).
+- **Implement hiện tại:** `ingestion/providers/sharepoint_provider.py`. Nó bọc lại `GraphClient` và tự động xử lý thuật toán phân trang (pagination) để lấy dữ liệu Delta.
+- **Nếu cần thêm nguồn dữ liệu mới (ví dụ: NAS, Google Drive):** Chỉ cần tạo một class mới kế thừa `BaseStorageProvider`. Lõi hệ thống không cần biết về API của nguồn đó.
+
+### B. Tầng Extraction (Xử lý chữ & Ảnh) - Mẫu Distributed VLM Pattern
+- **Lịch sử:** Đã từng dùng PaddleOCR + VietOCR nhưng gặp lỗi "Rụng dấu" và "Ảo giác" do cắt ảnh sai.
+- **Kiến trúc hiện tại:** Hệ thống đóng vai trò như một **VLM Client**.
+- **Cách hoạt động:** `extraction/ocr_service.py` render file PDF thành ảnh (DPI=86), nén Base64 và bắn POST Request sang một Server LLM khác trong mạng LAN (chạy `llama.cpp` với model `Vintern-3B`).
+- **Lợi ích:** Giải phóng hoàn toàn RAM cho máy chủ RAG, loại bỏ các thư viện AI nặng nền (Torch, Paddle). Lấy được Markdown nguyên bản, không gãy vỡ layout bảng biểu.
+
+### C. Tầng Chunking & Vector DB (Semantic Indexing)
+- **Chunking:** `chunking/markdown_chunker.py` chia nhỏ văn bản bằng Markdown Rules (nhận biết Header `#`, duy trì overlap chống đứt gãy ngữ cảnh), tự động theo dõi `page_from`, `page_to` chuẩn xác.
+- **Embedding:** Dùng thư viện `sentence-transformers` với model `keepitreal/vietnamese-sbert` chạy Local/Offline. Tạo ra Vector 768 chiều chuyên biệt cho Tiếng Việt.
+- **Database:** `indexing/vector_store.py` cấu hình OpenSearch với thuật toán `k-NN HNSW`. Index mặc định là `poc_sharepoint_docs` hoặc `sharepoint_docs`.
+
+### D. Tầng Cấu hình (Decoupled Configuration)
+- Toàn bộ thông số hệ thống, đặc biệt là IP máy chủ VLM, Token của SharePoint đều nằm trong `.env`.
+- Mã nguồn load cấu hình thông qua `core/config.py`.
+- **Tuyệt đối KHÔNG hardcode URL, Token hay Password trong code.**
+
+---
+
+## 2. Bản Đồ File & Thư Mục Quan Trọng
+
+```text
+📁 poc_system/
+├── 📁 core/
+│   ├── config.py         # ⚙️ Trái tim cấu hình (Load từ .env)
+│   └── models.py         # 🧩 Định nghĩa Data Classes (OCRPageResult, v.v.)
+├── 📁 ingestion/
+│   ├── sync.py           # 🔄 Bộ điều phối đồng bộ (Đang chuẩn bị ghép với BaseStorageProvider)
+│   ├── graph_client.py   # 🌐 Microsoft Graph API Client (Bọc Auth)
+│   └── 📁 providers/     # 🔌 Nơi chứa các plugin kết nối dữ liệu
+│       ├── base_provider.py
+│       └── sharepoint_provider.py
+├── 📁 extraction/
+│   └── ocr_service.py    # 👁️ VLM Client (Chuyển ảnh -> Text Markdown qua LAN)
+├── .env                  # 🔑 Chìa khoá và địa chỉ mạng (KHÔNG commit file này)
+└── test_modular_architecture.py # 🧪 Script kiểm tra nhanh kết nối các module
+```
+
+---
+
+## 3. Lịch Sử Các Lỗi Khét Tiếng & Cách Xử Lý (Known Gotchas)
+1. **Lỗi 401 Unauthorized khi tải file từ SharePoint:**
+   - *Nguyên nhân:* Microsoft chặn download trực tiếp bằng `@microsoft.graph.downloadUrl` nếu dùng App-Only Token.
+   - *Giải pháp:* Dùng endpoint `.../items/{item_id}/content` kèm Bearer Token (Đã cài đặt trong `graph_client.py`).
+
+2. **Lỗi 500 Internal Server Error từ Llama.cpp VLM:**
+   - *Nguyên nhân:* Bức ảnh ném vào VLM có độ phân giải quá cao (Matrix 2.0) làm tràn Context Window (ví dụ: Token ảnh > 4096).
+   - *Giải pháp:* Hạ `Matrix` xuống `1.2`, hoặc khởi chạy Server Llama.cpp với `-c 8192`. Bắt buộc phải có file `--mmproj`.
+
+3. **Lỗi Rụng dấu / Ảo giác của VietOCR:**
+   - *Nguyên nhân:* PaddleOCR bắt khung quá khít, làm cụt phần đuôi của các chữ tiếng Việt có dấu. Mô hình `vgg_seq2seq` tự nội suy ra từ tiếng Anh linh tinh.
+   - *Giải pháp triệt để:* Đã loại bỏ hoàn toàn VietOCR, chuyển sang dùng VLM (Vintern-3B).
+
+4. **Lỗi UTF-8 Surrogate (\udcc3) trong Terminal WSL:**
+   - *Hiện tượng:* Câu hỏi đầu tiên đúng, nhưng từ câu thứ 2 bị lỗi mã hóa khi dùng `input()`.
+   - *Nguyên nhân:* Do sự không đồng nhất giữa `sys.stdin` và bộ đệm Terminal sau khi in lượng lớn dữ liệu từ LLM.
+   - *Giải pháp:* Sử dụng `sys.stdin.buffer.readline()` để đọc dữ liệu thô (Bytes) và tự decode bằng UTF-8. Đây là giải pháp cho môi trường CLI, khi lên Web API (FastAPI) sẽ không bị ảnh hưởng.
+
+---
+
+## 4. Nhiệm Vụ Tiếp Theo (Dành cho Lập Trình Viên/AI Agent)
+- [ ] **Phase 7:** Bọc thành API Backend bằng FastAPI.
+
+---
+
+## 5. Tiêu chuẩn Lập trình & Môi trường (Coding Standards)
+
+### A. Quản lý Mã hóa (Encoding)
+- **Quy tắc vàng:** Luôn sử dụng `encoding='utf-8'` trong mọi lệnh `open()`. Tuyệt đối không dựa dẫm vào encoding mặc định của hệ điều hành.
+- **Môi trường:** Hệ thống được thiết kế để chạy trong môi trường UTF-8. Trong Docker hoặc WSL, luôn đảm bảo biến môi trường `PYTHONIOENCODING=utf-8` được thiết lập. Điều này giúp hệ thống tương thích 100% với các ký tự Tiếng Việt từ LLM mà không cần hack code.
+
+### B. Mẫu Provider (Provider Pattern)
+- Mọi kết nối tới dịch vụ bên thứ ba (Storage, LLM) phải thông qua Interface/BaseClass để đảm bảo tính "Cắm rút" (Pluggable).