Lead Search Agent - Tài Liệu Core

Tài liệu chuẩn (Single Source of Truth) mô tả toàn bộ kiến trúc Dual-Agent và thuật toán Tách truy vấn làm 2 (Split Query Logic).

Tại sao cần Quy trình Lead? (Business Context)

Lead Stage Agent đóng vai trò như một Nhân viên tư vấn (Stylist) thực thụ. Thay vì nhận 1 câu tìm kiếm rồi quăng ra 1 đống sản phẩm (như Search Box truyền thống), hệ thống Lead được thiết kế để:

Thu thập Context (Gom nhu cầu): Tìm hiểu khách mua cho ai? (nam/nữ/trẻ em), mặc dịp gì? (đi tiệc, mặc nhà, đi chơi), mức giá mong muốn?
Tránh tư vấn lan man: Nếu không gom đủ Context, AI sẽ tư vấn sai, dẫn tới rớt khách.
Chốt Sales (Lấy thông tin): Mục tiêu tối thượng của quá trình là chốt được số điện thoại/email để tạo Lead cho hệ thống Telesale/Marketing.

Lead Journey Map (Hành trình khách hàng)

Quá trình tương tác của một User khi vào Lead Flow trải qua 4 bước (Stage):

BROWSE (Khám phá): Khách vừa vào, lướt dạo. AI trò chuyện nhẹ nhàng, khai thác nhu cầu cơ bản.
IDENTIFYING (Xác định nhu cầu): Khách bắt đầu nói về món đồ muốn mua (VD: "Mình muốn tìm váy"). AI sẽ gạn hỏi thêm về màu sắc, size, budget để điền đầy đủ vào bộ nhớ InsightJSON.
CONSIDERING (Cân nhắc): AI gọi Tool tìm kiếm (ProductSearchEngine) để đưa ra tối đa 3 lựa chọn xuất sắc nhất. Khách xem xét, hỏi thêm về chất liệu, cách phối đồ. (Ở bước này, AI sẽ được cung cấp "lý do phối đồ" từ SQLite để thuyết phục khách).
CLOSING (Chốt): Khi khách chốt mã/thích sản phẩm, AI sẽ xin thông tin liên hệ (SĐT, Tên) hoặc hướng dẫn thêm vào giỏ hàng.

            Bí quyết của hệ thống: AI không bị "amnesia" (quên) vì toàn bộ thông tin được cập nhật liên tục vào đối tượng InsightJSON và lưu xuống Redis.
        

Kiến trúc Dual-Agent (2 AI Models)

Đội ngũ đã thiết kế kiến trúc 2 Agent để giải quyết bài toán: Gọi Tool thì phải chuẩn xác (Cần AI thông minh nhưng nhanh), Trả lời thì phải hay và cá nhân hóa (Cần AI văn hay chữ tốt).

Nhiệm vụ của từng Agent

1. Classifier Agent (AI Nhẹ): Chỉ làm nhiệm vụ Đọc tin nhắn -> Định tuyến (Route).
- Nếu khách chỉ chào hỏi (Small talk) -> Kích hoạt Early Exit, không gọi Tool, pass thẳng cho Stylist.
- Nếu khách tìm đồ -> Kích hoạt Split Query Logic (Tách câu nói làm 2 phần: Nguyên văn và Suy luận), truyền vào Tool lấy dữ liệu.
2. Stylist Agent (AI Nặng): Nhận kết quả từ Tool (hoặc không có tool), kết hợp với Lịch sử chat (History) và Bộ nhớ (InsightJSON). Từ đó:
- Sinh ra câu trả lời tự nhiên (Draft AI Reply).
- Cập nhật lại trạng thái khách hàng (Update Insight) vào file JSON và lưu lại.

Data Extraction Tool & Logic Tách Truy Vấn

Công cụ cốt lõi là ProductSearchEngine. Điểm thông minh nhất của nó là cơ chế nhận 2 luồng dữ liệu do Classifier Agent đẩy vào (Dual-Lane Input).

1. Cơ chế Tách truy vấn làm 2 (Split Query Logic)

Ví dụ khách nói: "Mình cần tìm cái áo khoác nam mùa đông, form rộng, khoảng dưới 500k"

            Lane 1: Literal Search (Nguyên văn)

                    raw_text: "áo khoác nam mùa đông form rộng dưới 500k"

                    (Được dùng để search LIKE thuần trong trường hợp khách gõ sai chính tả hoặc cần tìm chính xác).
                
Lane 2: Inferred Search (Suy luận có cấu trúc)

                    product_line_vn: ["Áo khoác"]

                    gender_by_product: "men"

                    tags: ["wthr:mua_dong", "fit:oversize"]

                    price_max: 500000

                    (AI đã tự động mapping "mùa đông" thành thẻ chuẩn wthr:mua_dong, "form rộng" thành fit:oversize).

2. Cascading Search (Thuật toán tìm kiếm rớt 7 tầng)

Để đảm bảo AI luôn có sản phẩm trả về cho khách (không bao giờ báo "Tôi không tìm thấy"), Tool áp dụng cơ chế nới lỏng bộ lọc dần (Cascading):

Tầng 1: Tìm chính xác Filters (Giá, Giới tính...) + Keywords (NgramBF).
Tầng 2: Tìm chính xác Filters + Tags (Các tag chuẩn hóa như style:nang_dong được quét BITMAP cực nhanh).
Tầng 3: Chỉ dùng Filters cố định (Giá, Dòng SP, Giới tính).
Tầng 4 (Drop Gender): Nới lỏng Giới tính (Biết đâu đồ Unisex hoặc nữ bận đồ nam cũng được).
Tầng 5 (Price Relaxation 1.5x): Kích giá lên 1.5 lần (Khách tìm áo 500k không có, tool tìm áo 750k và báo AI dụ dỗ khách mua vì áo đẹp).
Tầng 6 (Price Relaxation 2.0x): Kích giá lên gấp đôi.
Tầng 7 (Drop Price): Bỏ hoàn toàn giới hạn giá để lấy đồ xịn nhất ra chào hàng.

3. Làm giàu dữ liệu (Data Enrichment)

Canifa Stock API: Mọi SP lấy ra từ StarRocks đều bị đẩy qua _fetch_stock_batch() để check xem kho thực tế còn hàng và size nào. Hết hàng -> Drop ngay lập tức.
SQLite Outfit Context: Load các gợi ý "Phối cùng cái gì" (ai_matches) từ bảng pg__dashboard_canifa__ai_outfit_product_matches để cung cấp thêm lý lẽ chốt sales cho Stylist Agent.

Cẩm nang sửa đổi Quy trình (Modification Guide)

Khi Business có yêu cầu thay đổi logic chốt sale hoặc phân loại khách, lập trình viên cần nắm được sơ đồ phân quyền để sửa đúng file.

Nguyên tắc cốt lõi: Hãy tưởng tượng Classifier là "Lễ tân" và Stylist là "Nhân viên Sales".

1. Thêm/Sửa thuộc tính phân loại khách hàng (Tags/Insights)

Ví dụ: Business muốn thêm tag occ:di_dam_cuoi để gom khách dự tiệc cưới, hoặc muốn lưu thông tin PET_OWNER vào Insight khách.

Sửa file backend/agent/lead_stage_agent/graph.py.
Kéo xuống class InferredSearchArgs: Thêm/Sửa Enum trong field tags.
Kéo xuống class InsightJSON: Thêm field PET_OWNER: str.

2. Thay đổi cách AI xưng hô, văn phong chốt Sales

Ví dụ: Marketing muốn AI bớt xưng "Mình/Bạn" mà phải xưng "Stylist Canifa / Quý khách", hoặc yêu cầu "Không bao giờ được tự ý báo giảm giá nếu không chắc".

Sửa file backend/agent/lead_stage_agent/prompts.py.
Chỉnh sửa hằng số STYLIST_SYSTEM_PROMPT. Đây là bộ não quyết định thái độ và giọng điệu của AI thứ 2.

3. Thay đổi thuật toán lấy dữ liệu (Tool Logic)

Ví dụ: Hệ thống StarRocks có bảng mới, hoặc muốn đổi Tầng 5 từ "Nới giá 1.5x" thành "1.2x" thôi.

Sửa file backend/agent/lead_stage_agent/product_search_engine.py.
Tìm hàm _cascading_search() để đổi cấu trúc tầng tìm kiếm.
Tìm hàm _build_full_query() để can thiệp vào SQL.

4. Thêm Tool mới cho hệ thống

Ví dụ: Muốn thêm Tool book_fitting_room (Đặt lịch thử đồ tại cửa hàng).

Tạo file tool trong thư mục agent/tools/.
Vào graph.py, thêm tên tool vào class ClassifierOutput và dictionary self._tool_registry. Classifier sẽ tự động hiểu và định tuyến.