# Comprehensive Lead Search Agent Documentation

## 📌 Idea
Quy hoạch và tạo ra một tài liệu duy nhất (Single Source of Truth) cho chế độ Lead Search Agent của Canifa AI. Tài liệu sẽ giải thích chi tiết Business Logic (Journey Map), Flowchart 2 Agent (Classifier + Stylist), và Split Query Logic của Tool lấy dữ liệu (Cascading Search 7 tầng).

## 🗂 Codebase Scope
- **Root:** `./backend/agent/lead_stage_agent/` & `./backend/static/lead_flow/`
- **Total files:** ~5-10 files
- **Affected:** `backend/static/lead_flow/lead_docs.html`, `backend/static/lead_flow/lead_search_diagram.svg`
- **Languages:** HTML, SVG, Markdown
- **Size:** S

## 📊 Current State Analysis
Hiện tại tài liệu cho chế độ Lead Search nằm phân tán trong `static/lead_flow/` (html, svg, docx, v.v.). Sơ đồ hiện tại đã cũ và không bám sát kiến trúc 2 Agent (Classifier + Stylist) mới, cũng như chưa có giải thích tường tận về cơ chế tách truy vấn làm 2 (Literal vs Inferred) và luồng rớt mạng 7 tầng (Cascading Search).

## 🎯 Goal / Definition of Done
- Có file `lead_docs.html` với giao diện chia Tabs rõ ràng, giải thích cặn kẽ 4 phần:
  1. Lead Journey Maps (Business Context).
  2. Agent Flowchart.
  3. The Data Extraction Tool & Split Query Logic.
  4. Modification Guide.
- Có sơ đồ `lead_search_diagram.svg` được vẽ lại bằng thiết kế Premium, thể hiện rõ cấu trúc Dual-Agent và sự tách truy vấn của ProductSearchEngine.

## 📋 Execution Plan

### Phase 1: Idea Capture
- [x] Create this idea document.

### Phase 2: Visual Diagram
- [ ] Redraw `lead_search_diagram.svg` using standard SVG highlighting the dual-agent architecture, the dual-lane input (literal/inferred), and the 7-tier cascading search.

### Phase 3: Comprehensive HTML Documentation
- [ ] Rewrite `lead_docs.html` using a tabbed interface and clear sections (Journey, Flow, Logic, Maintenance).

## ⚠️ Risks & Side Effects
- **Risk 1:** Sơ đồ SVG có thể không hiển thị đúng trên một số trình duyệt. -> **Mitigation:** Dùng SVG standard, các viewBox chuẩn và inline CSS an toàn.

## 🔧 Tools / Scripts Needed
- HTML/CSS/SVG design skills (UI/UX Pro Max constraint).

## ⏱ Effort Estimate
**S** — < 2 hours, < 20 files

---
_Captured: 2026-05-04 | Type: Codebase-Aware_
