![alt text](image.png) ![alt text](image-1.png) --- ## 🚀 HƯỚNG DẪN CHẠY API ### 1️⃣ Cài đặt dependencies ```bash pip install -r requirements.txt ``` ### 2️⃣ Khởi động server ```bash python src/api/main.py ``` Server sẽ chạy tại: **http://localhost:8000** ### 3️⃣ Test API **Endpoint:** `POST http://localhost:8000/api/search` **Request body (JSON):** ```json { "text": "lau", "limit": 20 } ``` **Ví dụ test bằng curl (PowerShell):** ```powershell curl -X POST "http://localhost:8000/api/search" ` -H "Content-Type: application/json" ` -d '{"text":"lau","limit":20}' ``` **Hoặc dùng Postman:** - Method: **POST** - URL: `http://localhost:8000/api/search` - Headers: `Content-Type: application/json` - Body (raw JSON): ```json { "text": "lau san", "limit": 20 } ``` **Response mẫu:** ```json { "query": "lau", "total": 15, "time_ms": 2.3, "results": [ { "id": 0, "text": "Lau sàn nhà", "score": 1.0 }, { "id": 5, "text": "Dọn WC, lau cửa", "score": 0.5 } ] } ``` **API Docs:** http://localhost:8000/docs --- ## 📋 TỔNG QUAN HỆ THỐNG ### ✨ Hệ thống Search gợi ý công việc làm sạch Hệ thống này giúp **người xếp lịch tòa nhà** tìm kiếm nhanh các công việc làm sạch thông qua gợi ý real-time khi gõ từ khóa. ### 🎯 Tính năng chính - ✅ **Tìm kiếm real-time** (< 5ms/query) - ✅ **Không phân biệt dấu** (gõ "lam" tìm được "làm") - ✅ **Tìm từ ở giữa câu** (gõ "san" tìm được "Lau **sàn** nhà") - ✅ **Ưu tiên từ đầu câu** (gõ "lau" → "**Lau** sàn" xuất hiện trước "Dọn WC, **lau** cửa") - ✅ **RESTful API** (POST JSON) --- ## 🏗️ LUỒNG XỬ LÝ ### **Bước 1: Đọc dữ liệu từ JSON** ``` 📂 success/*.json (300+ files) ↓ 📄 unique_work_contents.json (dữ liệu công việc đã lọc) ``` **Dữ liệu mẫu:** ```json [ "Làm sạch nhà vệ sinh", "Lau sàn hành lang", "Vệ sinh kính cửa sổ", "Dọn rác, lau bàn", ... ] ``` **Script:** `extract_work_contents.py` (đã chạy sẵn) --- ### **Bước 2: Build Prefix Tree (Trie)** Khi **server khởi động**, hệ thống: 1. **Load dữ liệu** từ `unique_work_contents.json` 2. **Build Trie** với các tính năng: - **Word-start indexing:** Index mỗi từ trong câu - **Normalize:** Bỏ dấu tiếng Việt - **Scoring:** Từ đầu câu (score=1.0), từ giữa câu (score=0.5) - **Top-K caching:** Cache kết quả để search nhanh **Ví dụ index câu:** `"Làm sạch nhà vệ sinh"` ``` Trie index: ├─ "lam sach nha ve sinh" → score=1.0 (từ đầu) ├─ "sach nha ve sinh" → score=0.5 (từ giữa) ├─ "nha ve sinh" → score=0.5 (từ giữa) ├─ "ve sinh" → score=0.5 (từ giữa) └─ "sinh" → score=0.5 (từ giữa) ``` **Code:** `src/search/trie.py` --- ### **Bước 3: Cung cấp API** Server **FastAPI** cung cấp endpoint: **POST** `/api/search` **Flow:** 1. Nhận request JSON `{"text": "lau", "limit": 20}` 2. Normalize query: `"lau"` → `"lau"` 3. Search trong Trie đã build sẵn (O(m) - m là độ dài query) 4. Trả về kết quả đã sắp xếp theo score **Code:** `src/api/main.py` + `src/api/search_service.py` --- ## 🔧 CẤU TRÚC PROJECT ``` HM_search/ ├── data/ │ └── unique_work_contents.json # Dữ liệu công việc ├── src/ │ ├── search/ │ │ └── trie.py # Prefix Tree implementation │ └── api/ │ ├── main.py # FastAPI server │ └── search_service.py # Search service (singleton) ├── tests/ │ ├── test_trie_production.py # Unit tests │ └── test_with_real_data.py # Integration tests ├── success/ # Raw JSON files (300+ files) ├── requirements.txt # Dependencies ├── RUN_API.md # Chi tiết hướng dẫn chạy └── README.md # File này ``` --- ## 🎯 HOÀN THIỆN HỆ THỐNG ### ⚠️ **Lưu ý quan trọng:** Hiện tại đây **CHỈ LÀ API BACKEND**. Để hoàn thiện hệ thống, bạn cần: ### 1️⃣ **Tích hợp vào Backend chính** API này cần được **gọi từ backend chính** của hệ thống xếp lịch: ``` ┌─────────────────┐ │ Frontend │ (Giao diện người dùng) └────────┬────────┘ │ ↓ (HTTP request) ┌─────────────────┐ │ Backend chính │ (NodeJS/Django/PHP/...) │ (Quản lý lịch) │ └────────┬────────┘ │ ↓ (Gọi API search) ┌─────────────────┐ │ Search API │ ← HỆ THỐNG NÀY │ (FastAPI) │ │ Port 8000 │ └─────────────────┘ ``` **Backend chính cần:** - Gọi API search khi user nhập công việc - Hiển thị gợi ý cho user chọn - Lưu công việc đã chọn vào database --- ### 2️⃣ **Ví dụ tích hợp (NodeJS/Express)** ```javascript // Backend chính gọi Search API const axios = require('axios'); app.post('/api/work-suggestions', async (req, res) => { const { query } = req.body; // Gọi Search API const response = await axios.post('http://localhost:8000/api/search', { text: query, limit: 20 }); // Trả về cho frontend res.json(response.data); }); ``` --- ### 3️⃣ **Frontend tích hợp** Frontend cần: - **Input search** với debounce (150-300ms) - Gọi API mỗi khi user gõ - Hiển thị danh sách gợi ý - Cho phép user chọn và submit **Ví dụ (React):** ```javascript const [query, setQuery] = useState(''); const [suggestions, setSuggestions] = useState([]); // Debounce search useEffect(() => { const timer = setTimeout(async () => { if (query.length > 0) { const res = await fetch('/api/work-suggestions', { method: 'POST', body: JSON.stringify({ query }), headers: { 'Content-Type': 'application/json' } }); const data = await res.json(); setSuggestions(data.results); } }, 200); return () => clearTimeout(timer); }, [query]); ``` --- ## 📊 PERFORMANCE - **Build time:** ~2-3 giây (1 lần khi startup) - **Search time:** < 5ms/query - **Documents:** 300+ công việc - **Trie nodes:** ~50,000 nodes --- ## 🛠️ TECHNOLOGY STACK - **Python 3.8+** - **FastAPI** - REST API framework - **Uvicorn** - ASGI server - **Custom Trie** - Prefix tree implementation - **Unicodedata** - Vietnamese normalization --- ## 📚 TÀI LIỆU THAM KHẢO - **RUN_API.md** - Hướng dẫn chi tiết chạy API - **API Docs** - http://localhost:8000/docs (Swagger UI) - **Tests** - `tests/` folder --- ## 👨‍💻 DEVELOPMENT ### Chạy tests ```bash python tests/test_trie_production.py python tests/test_with_real_data.py ``` ### Debug mode ```bash uvicorn src.api.main:app --reload --log-level debug ``` --- ## ✅ NEXT STEPS 1. ✅ **API đã hoàn thiện** - Có thể test ngay 2. ⏳ **Tích hợp vào backend chính** - Gọi API từ hệ thống xếp lịch 3. ⏳ **Frontend UI** - Xây dựng giao diện autocomplete 4. ⏳ **Deploy production** - Deploy API lên server --- Made with ❤️ for HM Building Management System