Goal

Nếu message rỗng hoặc null → báo lỗi ngay.

1b. Nếu session_id = null → Tạo session mới

INSERT INTO ai_chat_sessions (user_id, last_active_at, context_json)
VALUES (:user_id, NOW(), :context_json);
-- Lấy session_id = LAST_INSERT_ID()

1c. Nếu session_id có giá trị → Load session

SELECT session_id, user_id, context_json
FROM ai_chat_sessions
WHERE session_id = :session_id;

Nếu không tìm thấy → báo lỗi: "session_id không tồn tại".

Merge context từ session với context từ input (input override session nếu conflict):

merged_context = { ...session.context_json, ...input.context }

1d. Update last_active_at

UPDATE ai_chat_sessions
SET last_active_at = NOW(),
    context_json = :merged_context_json
WHERE session_id = :session_id;

1e. Log user message

INSERT INTO ai_chat_messages (session_id, role, content, created_at)
VALUES (:session_id, 'user', :message, NOW());

1f. Load conversation history (tối đa 10 turns gần nhất)

SELECT role, content, tool_name, tool_payload
FROM ai_chat_messages
WHERE session_id = :session_id
ORDER BY created_at DESC
LIMIT 20;
-- Đảo lại thứ tự để có chronological order

Bước 2: Intent Detection

Phân tích message + conversation_history để xác định intent.

Intent Table (ưu tiên từ trên xuống dưới)

Confidence check trước khi routing

Trước khi route sang skill chuyên biệt, kiểm tra xem đã có đủ thông tin chưa:

Bước 3: Resolve Entities (Tìm variant_id từ tên xe)

Khi user đề cập tên xe (ví dụ "Camry 2024", "Accord 1.5T") → resolve sang variant_id:

SELECT v.variant_id, v.model_year, v.trim_name,
       mo.name AS model_name, mk.name AS make_name
FROM car_variants v
JOIN car_models mo ON mo.model_id = v.model_id
JOIN car_makes  mk ON mk.make_id  = mo.make_id
WHERE (mk.name LIKE :make_keyword OR mo.name LIKE :model_keyword)
  AND (:year IS NULL OR v.model_year = :year)
ORDER BY v.model_year DESC
LIMIT 5;

• Nếu tìm được 1 match duy nhất → dùng luôn.
• Nếu nhiều matches → hỏi user chọn trim/năm cụ thể.
• Liệt kê lựa chọn ngắn gọn: "Em tìm thấy 3 phiên bản Camry 2024: [A], [B], [C]. Anh muốn so sánh phiên bản nào?"

Bước 4: Execute Action theo Intent

4a. Intent = search_catalog

SELECT
  v.variant_id,
  mk.name AS make, mo.name AS model,
  v.model_year, v.trim_name, v.body_type, v.fuel_type, v.seats, v.msrp_base,
  vs.power_hp, vs.torque_nm,
  ROUND(AVG(cr.rating), 1) AS avg_rating,
  COUNT(cr.car_review_id) AS review_count
FROM car_variants v
JOIN car_models mo ON mo.model_id = v.model_id
JOIN car_makes  mk ON mk.make_id  = mo.make_id
LEFT JOIN variant_specs vs ON vs.variant_id = v.variant_id
LEFT JOIN car_reviews cr ON cr.variant_id = v.variant_id
WHERE 1=1
  AND (:body_type IS NULL OR v.body_type = :body_type)
  AND (:fuel_type IS NULL OR v.fuel_type = :fuel_type)
  AND (:seats IS NULL OR v.seats >= :seats)
  AND (:budget IS NULL OR v.msrp_base <= :budget)
GROUP BY v.variant_id
ORDER BY avg_rating DESC, v.msrp_base ASC
LIMIT 5;

Thêm filter giá thị trường nếu có market_id:

-- Subquery lấy latest price per variant
LEFT JOIN (
  SELECT variant_id, price AS market_price
  FROM variant_price_history vph1
  WHERE market_id = :market_id
    AND price_type = 'avg_market'
    AND captured_at = (
      SELECT MAX(captured_at) FROM variant_price_history vph2
      WHERE vph2.variant_id = vph1.variant_id AND vph2.market_id = :market_id
    )
) latest_price ON latest_price.variant_id = v.variant_id

Nếu market_id có → ưu tiên dùng market_price thay vì msrp_base để filter budget.

Hiển thị kết quả dạng list ngắn gọn (tên, giá, rating, điểm nổi bật).

4b. Intent = compare → Route sang skill compare_variants

Chuẩn bị payload:

{
  "variant_ids": [<resolved ids>],
  "market_id": <từ merged_context.market_id hoặc null>,
  "price_type": "avg_market"
}

Gọi skill compare_variants với payload trên. Lấy response và embed vào câu trả lời theo dạng conversational.

4c. Intent = predict_price → Route sang skill predict_price

{
  "variant_id": <resolved id>,
  "market_id": <market_id>,
  "price_type": "avg_market",
  "horizon_months": <từ message nếu có, default 6>
}

Giải thích kết quả cho user: "Theo lịch sử X điểm giá, dự đoán sau 6 tháng giá xe sẽ là..."

4d. Intent = tco → Route sang skill calculate_tco

{
  "profile_id": <resolve từ market_id: thị trường VN → profile_id phù hợp>,
  "base_price": <từ message hoặc msrp_base>,
  "ownership_years": <từ message, default 5>,
  "km_per_year": <từ context.usage_km_per_year hoặc null>
}

Lưu ý: profile_id mapping từ market_id:

SELECT profile_id FROM tco_profiles
WHERE market_id = :market_id
LIMIT 1;

Nếu không tìm được profile_id → hỏi user: "Anh muốn tính TCO theo thị trường nào?"

4e. Intent = buy_sell_guidance

Provide guidance chung dựa trên DB facts. Không bịa thông tin ngoài DB.

4f. Intent = clarification_needed

Tạo tối đa 3 câu hỏi ngắn gọn để làm rõ:

• Budget: "Ngân sách của anh khoảng bao nhiêu?"
• Market: "Anh đang ở thị trường nào (VN, US...)?"
• Use case: "Anh dùng xe chủ yếu cho mục đích gì (gia đình, đi làm, off-road...)?"

Bước 5: Generate Answer

Viết câu trả lời theo phong cách chuyên gia tư vấn:

• Bắt đầu bằng tóm tắt ý chính (1-2 câu).
• Nêu facts cụ thể từ DB (giá, specs, rating). Không nói chung chung.
• Nếu routing sang skill → tóm tắt kết quả key, không dump raw JSON.
• Kết thúc bằng follow-up suggestion hoặc câu hỏi làm rõ (nếu cần).

Tone: Thân thiện, chuyên nghiệp. Dùng tiếng Việt nếu user hỏi tiếng Việt.

KHÔNG ĐƯỢC:

• Bịa specs/giá/rating không có trong DB.
• Đưa recommendation mà không có dữ liệu backing.
• Nói "theo tôi biết" hay "thông thường" nếu không có fact từ DB.

Bước 6: Log Response

6a. Nếu có tool call → Log tool message trước

INSERT INTO ai_chat_messages
  (session_id, role, tool_name, tool_payload, content, created_at)
VALUES
  (:session_id, 'tool', :tool_name, :tool_payload_json, NULL, NOW());

tool_name = tên skill được gọi: 'compare_variants', 'predict_price', 'calculate_tco'. tool_payload = JSON payload đã gửi cho skill.

6b. Log assistant response

INSERT INTO ai_chat_messages (session_id, role, content, created_at)
VALUES (:session_id, 'assistant', :answer, NOW());

Bước 7: Build Output JSON

{
  "session_id": <bigint>,
  "answer": "...",
  "intent": "search_catalog|compare|predict_price|tco|buy_sell_guidance|clarification_needed",
  "suggested_actions": [
    {
      "type": "compare_variants",
      "label": "So sánh chi tiết Toyota Camry vs Honda Accord",
      "payload": { "variant_ids": [101, 102], "market_id": 1 }
    },
    {
      "type": "calculate_tco",
      "label": "Tính tổng chi phí sở hữu 5 năm",
      "payload": { "profile_id": 1, "base_price": 1200000000, "ownership_years": 5 }
    }
  ],
  "follow_up_questions": [
    "Anh có muốn tính tổng chi phí sở hữu 5 năm không?",
    "Anh muốn xem giá dự đoán 6 tháng tới không?"
  ],
  "facts_used": [
    { "source": "car_variants", "id": 101 },
    { "source": "variant_specs", "id": 101 },
    { "source": "variant_price_history", "variant_id": 101, "market_id": 1 }
  ]
}

Rules cho suggested_actions:

• Chỉ suggest actions có đủ data để thực thi (có variant_id, có market_id nếu cần).
• Tối đa 3 suggested actions.
• payload phải ready-to-use cho skill tương ứng.

Rules cho follow_up_questions:

• Tối đa 3 câu.
• Nếu intent đã rõ và đã trả lời đầy đủ → 0-1 câu gợi ý sâu hơn.
• Nếu clarification_needed → 1-3 câu hỏi để gather missing info.

Examples

📚 Xem chi tiết: examples/example_search.md, examples/example_compare_routing.md, examples/example_tco_routing.md

Quick Reference — Tìm xe theo ngân sách

Input:

{
  "session_id": null,
  "user_id": 42,
  "message": "SUV 7 chỗ dưới 1 tỷ ở VN",
  "context": { "market_id": 1 }
}

Intent: search_catalog Action: Query car_variants với body_type='SUV', seats>=7, budget<=1000000000, market_id=1. Answer: List top 5 xe thỏa điều kiện, kèm giá và rating thực từ DB.

Quick Reference — Routing sang compare_variants

Input:

{
  "session_id": 100,
  "message": "So sánh Camry 2022 và Accord 2022"
}

Intent: compare Action: Resolve "Camry 2022" → variant_id=X, "Accord 2022" → variant_id=Y. Gọi compare_variants({ variant_ids: [X, Y], market_id: 1 }). Answer: Tóm tắt bảng so sánh conversational, highlight điểm khác biệt chính.

Quick Reference — Routing sang calculate_tco

Input:

{
  "session_id": 100,
  "message": "Tính TCO xe giá 700 triệu ở VN trong 5 năm"
}

Intent: tco Action: Lấy profile_id cho VN (market_id=1). Gọi calculate_tco({ profile_id: 1, base_price: 700000000, ownership_years: 5 }). Answer: Giải thích chi phí từng hạng mục, tổng 5 năm, chi phí trung bình/năm.

Constraints

Session & Data

• ❌ KHÔNG ĐƯỢC bịa specs/giá/rating nếu DB không có
• ❌ KHÔNG ĐƯỢC dùng kiến thức LLM về thị trường thay cho dữ liệu DB
• ❌ KHÔNG ĐƯỢC tạo session mới nếu session_id đã tồn tại
• ✅ Nếu session_id không tồn tại → tạo mới, không báo lỗi
• ✅ Mọi message (user, assistant, tool) đều phải được log vào ai_chat_messages
• ✅ context_json trong session phải được update mỗi lượt (merge context mới vào)

Intent & Routing

• ❌ KHÔNG ĐƯỢC route sang skill khi thiếu thông tin bắt buộc → hỏi lại trước
• ❌ KHÔNG ĐƯỢC hỏi lại quá 3 câu trong 1 lượt
• ✅ Resolved entity (variant_id) PHẢI từ DB query — không tự đặt số
• ✅ Nếu resolve ra nhiều matches → hỏi user chọn, không tự chọn
• ✅ suggested_actions[].payload phải ready-to-use (đủ fields cho skill tương ứng)

Answer Quality

• ❌ KHÔNG ĐƯỢC dump raw JSON ra answer (tóm tắt dạng conversational)
• ❌ KHÔNG ĐƯỢC trả lời chung chung kiểu "thường thì...", "theo kinh nghiệm..."
• ✅ Mọi fact trong answer phải có nguồn trong facts_used
• ✅ Nếu thiếu info quan trọng → intent = 'clarification_needed'
• ✅ Tone: thân thiện, chuyên nghiệp, dùng ngôn ngữ của user (Việt/Anh)