⚡ Quick Start

Bước 1: Clone & setup backend

git clone <repo-url> vinfast-ai-sales-advisor
cd vinfast-ai-sales-advisor

# Virtual environment
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Cấu hình env
cp .env.example .env
# Mở .env và điền OPENAI_API_KEY (xem mục Environment Variables)

Bước 2: Chạy backend

uvicorn src.main:app --reload --port 8000

• Swagger UI: http://localhost:8000/docs
• Health: http://localhost:8000/health

Bước 3: Chạy frontend

cd frontend
cp .env.example .env.local
# đặt NEXT_PUBLIC_API_URL=http://localhost:8000

npm install
npm run dev

Mở:

http://localhost:3000

Bước 4: (Tùy chọn) Docker

docker compose up --build

🔐 Environment Variables

File .env (backend) — copy từ .env.example. Pydantic Settings đọc không phân biệt hoa/thường, nên OPENAI_API_KEY khớp với field openai_api_key trong src/config.py.

Frontend (.env.local)

Các biến ANTHROPIC_API_KEY, GOOGLE_API_KEY, PINECONE_* trong .env.example là tùy chọn (template), chưa dùng bởi config.py.

🧪 Sample Queries

1. Health check

curl http://localhost:8000/health

Response:

{
  "status": "ok",
  "env": "development"
}

2. Chat tư vấn xe — Endpoint chính

curl -X POST http://localhost:8000/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Tư vấn giúp tôi xe VinFast tầm 700 triệu, 5 chỗ, chủ yếu đi trong phố"}'

Response:

{
  "response": "Với ngân sách ~700 triệu và nhu cầu 5 chỗ đi trong phố, VinFast VF5 là ứng viên phù hợp nhất...",
  "analysis": "Phân tích: ngân sách 700tr, 5 chỗ, city-use"
}

3. Trạng thái agent

curl http://localhost:8000/api/v1/status

Response:

{
  "status": "ready",
  "agent": "LangGraph Agent v1.0"
}

4. Ví dụ luồng tư vấn end-to-end

1. Mở http://localhost:3000/consultation
2. Nhập: "Tôi cần xe 7 chỗ, ngân sách 1.2 tỷ, hay đi xa cuối tuần"
3. Agent trả về đề xuất (VF9 / VF8), so sánh TCO và link đăng ký lái thử.
4. Mở /compare để so sánh 2 xe.
5. Mở /tco để xem chi phí sở hữu.
6. Mở /locations để tìm showroom và trạm sạc.

📁 Cấu trúc dự án

src/
  main.py              # FastAPI entry
  config.py            # Pydantic Settings
  api/routes.py        # /api/v1/chat, /status
  agents/              # LangGraph agent (A1–A10)
    graph.py           # state machine (A4-2)
    legacy_graph.py    # graph ví dụ cũ (sẽ thay ở A4-4)
    nodes/             # extract_slots, layer1/2, score, tco, synthesize, guardrail...
    services/          # retrieval, recommendation, tco_estimation, synthesis...
    adapters/          # catalog_reader, feature_retriever, unit_of_work
    tools/             # tco
    agent_stages/      # tài liệu A1–A10
  models/schemas.py    # ChatRequest / ChatResponse
  services/llm.py      # ChatOpenAI

frontend/
  # Next.js 16 UI
  # Customer / Advisor / Staff / Admin

migrations/
  # Alembic:
  # auth, products, locations, document, agents

eval/
  # Evaluation results

docs/
  # architecture_diagram.md, PRD, UI spec

presentation/
  # Demo Day slides / video

📊 AI Usage Logging

Template tích hợp sẵn auto-logging hooks (Claude/Cursor/Codex/Gemini/Copilot/Antigravity).

Prompt được ghi vào .ai-log/ và submit lên grading server mỗi git push:

bash scripts/setup_hooks.sh

🔀 Git Flow & PR

• Luồng: main ← develop ← feature/*.

• Đã merge ≥ 10 PR — thực tế 12 PR qua gh pr list --state merged.

• Các nhóm tính năng đã merge gồm:

  • Authentication
  • Products / TCO
  • Locations
  • Build Agent
  • Memory Agent
  • Đăng ký lái thử
  • Và các tính năng liên quan khác.

• Source of truth tính năng: nhánh develop.

🔗 Project Resources

Các tài nguyên phục vụ Demo Day, Presentation và giới thiệu dự án:

🖼️ Logo

📁 Google Drive — Logo

📊 Slide

📁 Google Drive — Presentation Slides

🎬 Video Demo

📁 Google Drive — Tổng hợp Video Demo

📄 License

MIT — mục đích giáo dục (AI20K Build Phase).