tw/SPECIFIED_CUSTOMER_REPLY_EXAMPLE.md

# 指定客户回复触发任务 - 使用示例

## 📋 功能说明

支持**指定特定客户**回复**指定内容**时触发任务。

---

## 🎯 使用场景

### 场景 1：只等小明说"好的"就发文件

**任务配置**：
```json
{
  "task_id": "TASK_001",
  "type": "send_file_after_reply",
  "customer": {
    "id": "customer_123",
    "name": "小明"
  },
  "trigger": {
    "type": "specified_customer_reply",
    "customer_id": "customer_123",
    "customer_name": "小明",
    "keyword": "好的",
    "exact_match": false
  },
  "action": {
    "type": "send_message",
    "message": "这是您要的文件"
  },
  "priority": "normal",
  "timeout_hours": 24,
  "created_by": "设计师 lz"
}
```

**触发逻辑**：
1. ✅ 客户 ID = `customer_123`
2. ✅ 客户名称 = `小明`
3. ✅ 消息内容包含"好的"
4. ✅ 触发任务，发送文件

**如果其他客户说"好的"**：
- ❌ 不触发（客户 ID 不匹配）

**如果小明说"可以的"**：
- ❌ 不触发（关键词不匹配）

---

### 场景 2：精确匹配 - 只认"已付款"三个字

**任务配置**：
```json
{
  "task_id": "TASK_002",
  "type": "send_tutorial_after_payment",
  "customer": {
    "id": "customer_456",
    "name": "小红"
  },
  "trigger": {
    "type": "specified_customer_reply",
    "customer_id": "customer_456",
    "customer_name": "小红",
    "keyword": "已付款",
    "exact_match": true
  },
  "action": {
    "type": "send_message",
    "message": "感谢购买！这是教程..."
  }
}
```

**触发逻辑**：
- ✅ 客户说"已付款" → 触发
- ❌ 客户说"我已付款了" → 不触发（不是精确匹配）
- ❌ 客户说"付款了" → 不触发（关键词不匹配）

---

### 场景 3：不指定客户名称，只认客户 ID

**任务配置**：
```json
{
  "task_id": "TASK_003",
  "type": "send_welcome",
  "customer": {
    "id": "customer_789"
  },
  "trigger": {
    "type": "specified_customer_reply",
    "customer_id": "customer_789",
    "keyword": "你好"
  },
  "action": {
    "type": "send_message",
    "message": "欢迎光临！"
  }
}
```

**触发逻辑**：
- ✅ 只要客户 ID 是 `customer_789`，说"你好"就触发
- ✅ 不检查客户名称

---

## 📝 API 调用示例

### 1. 创建指定客户回复任务

```bash
curl -X POST http://localhost:5678/api/task/receive \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "TASK_20260227_001",
    "type": "send_file_after_reply",
    "customer": {
      "id": "customer_123",
      "name": "小明"
    },
    "trigger": {
      "type": "specified_customer_reply",
      "customer_id": "customer_123",
      "customer_name": "小明",
      "keyword": "好的",
      "exact_match": false
    },
    "action": {
      "type": "send_message",
      "message": "这是您要的文件"
    },
    "priority": "normal",
    "timeout_hours": 24,
    "created_by": "设计师 lz"
  }'
```

### 2. 查询任务状态

```bash
curl http://localhost:5678/api/task/status/TASK_20260227_001
```

### 3. 取消任务

```bash
curl -X POST http://localhost:5678/api/task/cancel \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "TASK_20260227_001",
    "reason": "客户不需要了"
  }'
```

---

## 🔧 触发条件配置说明

### 字段说明

| 字段 | 必填 | 说明 | 示例 |
|------|------|------|------|
| `type` | ✅ | 触发类型 | `specified_customer_reply` |
| `customer_id` | ✅ | 指定客户 ID | `customer_123` |
| `customer_name` | ❌ | 指定客户名称 | `小明` |
| `keyword` | ✅ | 回复关键词 | `好的` |
| `exact_match` | ❌ | 是否精确匹配 | `false`（默认） |

### exact_match 参数

- `false`（默认）：模糊匹配，消息**包含**关键词即可
  - 关键词："好的"
  - 匹配："好的"、"好的谢谢"、"好的我知道了"

- `true`：精确匹配，消息**等于**关键词
  - 关键词："好的"
  - 匹配："好的"
  - 不匹配："好的谢谢"

---

## 📊 触发流程图

```
客户发送消息
    ↓
检查任务列表
    ↓
遍历待触发任务
    ↓
┌─────────────────────────────┐
│ 1. 检查客户 ID 是否匹配？     │ ← specified_customer_id
└──────────┬──────────────────┘
           │ NO → 跳过此任务
           │ YES
           ↓
┌─────────────────────────────┐
│ 2. 检查客户名称是否匹配？     │ ← specified_customer_name（可选）
└──────────┬──────────────────┘
           │ NO → 跳过此任务
           │ YES
           ↓
┌─────────────────────────────┐
│ 3. 检查回复内容是否匹配？     │ ← keyword + exact_match
└──────────┬──────────────────┘
           │ NO → 跳过此任务
           │ YES
           ↓
触发任务执行
```

---

## 🐛 常见问题

### Q1: 如何只监听特定客户？
**A**: 使用 `specified_customer_reply` 触发类型，配置 `customer_id` 字段。

### Q2: 如何精确匹配某句话？
**A**: 设置 `exact_match: true`，只有消息完全等于关键词时才触发。

### Q3: 可以监听多个关键词吗？
**A**: 可以，使用 `customer_keyword` 触发类型，配置 `keywords` 数组。

### Q4: 任务超时后会自动取消吗？
**A**: 是的，默认 24 小时超时，可在任务配置中设置 `timeout_hours`。

---

## 📖 完整文档

查看：`/root/ai_customer_service/ai_cs/TIANWANG_INTEGRATION.md`