# Tool: `canifa_get_promotions` — Tài liệu Kỹ thuật

---

## 1. Tool này nhận vào gì?

Chỉ **một tham số duy nhất**, và tham số đó có thể để trống:

| Tham số | Kiểu | Bắt buộc? | Ý nghĩa |
|---|---|---|---|
| `check_date` | `string` (YYYY-MM-DD) | Không | Ngày muốn kiểm tra khuyến mãi. Để `null` → tự lấy ngày hôm nay |

**Ví dụ Agent 1 gọi tool:**
```json
{
  "intent": "promotion_check",
  "tools_to_call": ["canifa_get_promotions"],
  "check_date": null
}
```

---

## 2. Luồng Xử lý Logic (Request Flow)

![Promotion Tool Logic Flow](data/31-promoton-search-tool/promotion_tool_flow.svg)

---

## 3. Bên trong tool làm gì?

### Bước 1 — Xử lý ngày
Nếu `check_date = null` → lấy ngày hệ thống (`datetime.now()`). Đây là bước phòng thủ để tool không bao giờ bị lỗi vì thiếu ngày.

### Bước 2 — Query SQL với logic ưu tiên kênh
Tool truy vấn bảng khuyến mãi với điều kiện: ngày truyền vào phải nằm **trong khoảng** `from_date` đến `to_date` của CTKM.

Kết quả được **sắp xếp theo kênh bán hàng** theo thứ tự ưu tiên:
1. `only_online`: Web/App — dễ tiếp cận nhất.
2. `both`: Áp dụng cả 2 kênh.
3. `unknown`: Chưa phân loại.
4. `only_offline`: Chỉ tại cửa hàng.

*Trong cùng nhóm kênh → sắp theo `to_date ASC` (CTKM sắp hết hạn lên trước).*

### Bước 3 — Format output
Mỗi CTKM được đóng gói thành block `[CTKM N]` với đầy đủ: tên, kênh, nội dung, thời gian. Nếu `description_full` dài hơn `description` → dùng cái dài hơn để Agent 2 có đủ thông tin tư vấn.

---

## 4. Agent 2 nhận kết quả và làm gì?

Tool trả về text có cấu trúc rõ ràng → Agent 2 đọc và viết lại thành tư vấn tự nhiên:

> **Tool trả:** `[CTKM 1] Tên: Sale hè... Kênh: Online... Thời gian: đến 15/06`
>
> **Agent 2 viết:** *"Chị ơi, Canifa đang có sale hè giảm 30% toàn áo đến hết 15/06 ạ! Chị mua online trên web hoặc app là được giá khuyến mãi ngay..."*

---

## 5. Điểm cần lưu ý khi vận hành

- **Không có filter theo danh mục:** Tool này trả về **tất cả** CTKM đang chạy. Agent 2 phải tự chọn CTKM phù hợp.
- **Giới hạn 20 CTKM:** `LIMIT 20` để đảm bảo context window không bị tràn.
- **Không có cache:** Query trực tiếp DB thời gian thực.
