tw/部署文档.md

# AI 客服系统 - 天网协作版部署文档

## 📋 系统架构

```
┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│  天网服务器  │ ───→ │  AI 客服 API  │ ───→ │  企业微信   │
│  (公网 IP)   │      │ (127.0.0.1:6060)│      │  (轻简软件)  │
└─────────────┘      └──────────────┘      └─────────────┘
       ↑                     │
       │                     ↓
       └──────────────┐
                   ┌──────────────┐
                   │   SQLite     │
                   │  任务数据库   │
                   └──────────────┘
```

### 核心组件

| 组件 | 地址 | 说明 |
|------|------|------|
| **AI 客服 HTTP API** | http://127.0.0.1:6060 | 接收天网任务 |
| **天网服务器** | 你的公网 IP | 任务调度中心 |
| **轻简软件** | ws://127.0.0.1:9528 | 企业微信连接 |
| **任务数据库** | SQLite | 本地存储 |

---

## 🚀 快速部署

### 步骤 1：环境检查

```bash
# 检查 Python 版本
python3 --version  # 需要 3.8+

# 检查依赖
pip3 list | grep -E "flask|pydantic|sqlite"
```

### 步骤 2：启动 AI 客服 API

```bash
cd /root/ai_customer_service/ai_cs

# 前台运行（测试用）
python3 run_tianwang_simple.py

# 后台运行（生产用）
nohup python3 run_tianwang_simple.py > /tmp/tianwang.log 2>&1 &

# 查看进程
ps aux | grep run_tianwang

# 查看日志
tail -f /tmp/tianwang.log
```

### 步骤 3：测试 API

```bash
# 健康检查
curl http://localhost:6060/api/health

# 预期输出：
# {"code":200,"data":{"service":"ai-cs-tianwang-bridge","timestamp":"..."},"message":"OK"}
```

---

## 📝 API 接口说明

### 1. 接收任务

**接口**: `POST /api/task/receive`

**请求示例**:
```bash
curl -X POST http://localhost:6060/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"
  }'
```

**响应示例**:
```json
{
  "code": 200,
  "message": "任务接收成功",
  "data": {
    "task_id": "TASK_20260227_001",
    "status": "pending"
  }
}
```

---

### 2. 查询任务状态

**接口**: `GET /api/task/status/:task_id`

**请求示例**:
```bash
curl http://localhost:6060/api/task/status/TASK_20260227_001
```

**响应示例**:
```json
{
  "code": 200,
  "data": {
    "task_id": "TASK_20260227_001",
    "type": "send_file_after_reply",
    "status": "pending",
    "priority": "normal",
    "retry_count": 0,
    "created_at": "2026-02-27T18:00:00",
    "created_by": "设计师 lz",
    "triggered_at": null,
    "completed_at": null,
    "error_message": null
  }
}
```

---

### 3. 取消任务

**接口**: `POST /api/task/cancel`

**请求示例**:
```bash
curl -X POST http://localhost:6060/api/task/cancel \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "TASK_20260227_001",
    "reason": "客户取消订单"
  }'
```

**响应示例**:
```json
{
  "code": 200,
  "message": "任务已取消",
  "data": {
    "task_id": "TASK_20260227_001",
    "status": "cancelled"
  }
}
```

---

### 4. 查询任务列表

**接口**: `GET /api/task/list`

**请求参数**:
- `customer_id` (可选): 客户 ID
- `status` (可选): 任务状态
- `page` (可选): 页码，默认 1
- `page_size` (可选): 每页数量，默认 20

**请求示例**:
```bash
curl "http://localhost:6060/api/task/list?status=pending&page=1&page_size=10"
```

---

### 5. 健康检查

**接口**: `GET /api/health`

**请求示例**:
```bash
curl http://localhost:6060/api/health
```

**响应示例**:
```json
{
  "code": 200,
  "message": "OK",
  "data": {
    "timestamp": "2026-02-27T18:00:00",
    "service": "ai-cs-tianwang-bridge"
  }
}
```

---

## 📊 触发条件类型

### 1. specified_customer_reply（推荐）

**指定客户回复指定内容**

```json
{
  "trigger": {
    "type": "specified_customer_reply",
    "customer_id": "customer_123",
    "customer_name": "小明",
    "keyword": "好的",
    "exact_match": false
  }
}
```

**匹配逻辑**:
- ✅ 客户 ID 匹配
- ✅ 客户名称匹配（可选）
- ✅ 消息包含关键词

---

### 2. customer_reply

**任意客户回复指定内容**

```json
{
  "trigger": {
    "type": "customer_reply",
    "keyword": "好的"
  }
}
```

---

### 3. customer_keyword

**任意客户说某关键词**

```json
{
  "trigger": {
    "type": "customer_keyword",
    "keywords": ["好的", "可以", "行"]
  }
}
```

---

### 4. customer_payment

**客户付款**

```json
{
  "trigger": {
    "type": "customer_payment",
    "keywords": ["已付款", "拍下了", "已下单"]
  }
}
```

---

### 5. time_reach

**到达指定时间**

```json
{
  "trigger": {
    "type": "time_reach",
    "time": "2026-02-27 09:00:00"
  }
}
```

---

## 🔧 配置说明

### 环境变量文件

位置：`/root/ai_customer_service/ai_cs/.env.tianwang`

```bash
# AI 客服配置
AI_CS_HOST=127.0.0.1
AI_CS_PORT=6060

# AI 客服 HTTP API 地址（本地）
AI_CS_API_URL=http://127.0.0.1:6060

# 天网回调地址
TIANWANG_CALLBACK_URL=http://127.0.0.1:6060/api/task/callback

# API 接口
TASK_RECEIVE=/api/task/receive
TASK_STATUS=/api/task/status
TASK_CANCEL=/api/task/cancel
TASK_LIST=/api/task/list
HEALTH=/api/health
```

---

### 数据库配置

位置：`/root/ai_customer_service/ai_cs/db/task_db/tasks.db`

**数据库结构**:
```sql
CREATE TABLE tasks (
    task_id TEXT PRIMARY KEY,
    specified_customer_id TEXT,
    specified_customer_name TEXT,
    type TEXT NOT NULL,
    customer_name TEXT,
    customer_id TEXT,
    trigger_type TEXT,
    trigger_keyword TEXT,
    trigger_keywords TEXT,
    action_type TEXT,
    action_file_url TEXT,
    action_message TEXT,
    priority TEXT DEFAULT 'normal',
    timeout_hours INTEGER DEFAULT 24,
    status TEXT DEFAULT 'pending',
    retry_count INTEGER DEFAULT 0,
    max_retry INTEGER DEFAULT 3,
    created_at TEXT,
    created_by TEXT,
    triggered_at TEXT,
    completed_at TEXT,
    error_message TEXT,
    result TEXT
);
```

---

## 📖 使用场景

### 场景 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": "好的"
  },
  "action": {
    "type": "send_message",
    "message": "这是您要的文件"
  },
  "priority": "normal",
  "timeout_hours": 24,
  "created_by": "设计师 lz"
}
```

**流程**:
1. 天网下发任务 → AI 客服 API
2. 客户在群里说"好的"
3. AI 客服检测到匹配任务
4. 自动发送消息给客户
5. 任务标记为 completed
6. 回调通知天网

---

### 场景 2：客户付款后发送教程

**天网下发任务**:
```json
{
  "task_id": "TASK_002",
  "type": "send_tutorial_after_payment",
  "customer": {
    "id": "customer_456",
    "name": "小红"
  },
  "trigger": {
    "type": "customer_payment"
  },
  "action": {
    "type": "send_message",
    "message": "感谢购买！这是使用教程：..."
  },
  "created_by": "设计师 lz"
}
```

---

### 场景 3：定时发送问候

**天网下发任务**:
```json
{
  "task_id": "TASK_003",
  "type": "send_greeting",
  "customer": {
    "id": "customer_789"
  },
  "trigger": {
    "type": "time_reach",
    "time": "2026-02-28 09:00:00"
  },
  "action": {
    "type": "send_message",
    "message": "早上好！有什么可以帮您？"
  },
  "created_by": "设计师 lz"
}
```

---

## 🔍 监控与日志

### 查看进程状态

```bash
# 查看进程
ps aux | grep run_tianwang

# 查看端口
netstat -tlnp | grep 6060
```

### 查看日志

```bash
# 实时日志
tail -f /tmp/tianwang.log

# 最近 100 行
tail -100 /tmp/tianwang.log

# 搜索关键词
grep "任务" /tmp/tianwang.log
```

### 查看数据库

```bash
# 进入 SQLite
sqlite3 /root/ai_customer_service/ai_cs/db/task_db/tasks.db

# 查看所有任务
SELECT task_id, type, status, created_at FROM tasks ORDER BY created_at DESC LIMIT 10;

# 查看待触发任务
SELECT * FROM tasks WHERE status='pending';

# 查看失败任务
SELECT task_id, error_message FROM tasks WHERE status='failed';

# 查看统计数据
SELECT status, COUNT(*) as count FROM tasks GROUP BY status;

# 退出
.exit
```

---

## ⚠️ 故障排查

### 问题 1：API 无法访问

**症状**: `curl http://localhost:6060/api/health` 无响应

**解决**:
```bash
# 1. 检查进程
ps aux | grep run_tianwang

# 2. 检查端口
netstat -tlnp | grep 6060

# 3. 重启服务
pkill -f run_tianwang
cd /root/ai_customer_service/ai_cs
nohup python3 run_tianwang_simple.py > /tmp/tianwang.log 2>&1 &

# 4. 查看日志
tail -f /tmp/tianwang.log
```

---

### 问题 2：任务接收失败

**症状**: POST /api/task/receive 返回 500 错误

**解决**:
```bash
# 1. 查看日志
tail -f /tmp/tianwang.log | grep "ERROR"

# 2. 检查数据库
sqlite3 /root/ai_customer_service/ai_cs/db/task_db/tasks.db ".schema tasks"

# 3. 测试数据库
sqlite3 /root/ai_customer_service/ai_cs/db/task_db/tasks.db "SELECT 1;"

# 4. 如果数据库损坏，删除重建
rm /root/ai_customer_service/ai_cs/db/task_db/tasks.db
# 重启服务后会自动创建
```

---

### 问题 3：任务未触发

**症状**: 任务一直是 pending 状态

**解决**:
```bash
# 1. 检查任务状态
curl http://localhost:6060/api/task/status/TASK_ID

# 2. 查看触发日志
grep "任务触发" /tmp/tianwang.log

# 3. 检查触发条件
# 确认客户消息包含触发关键词

# 4. 手动触发测试
sqlite3 /root/ai_customer_service/ai_cs/db/task_db/tasks.db \
  "UPDATE tasks SET status='pending' WHERE task_id='TASK_ID';"
```

---

### 问题 4：内存占用过高

**症状**: 进程内存持续增长

**解决**:
```bash
# 1. 查看内存使用
ps aux | grep run_tianwang | awk '{print $6/1024 " MB"}'

# 2. 定期重启（建议每天）
crontab -e
# 添加：0 3 * * * pkill -f run_tianwang && sleep 2 && nohup python3 /root/ai_customer_service/ai_cs/run_tianwang_simple.py > /tmp/tianwang.log 2>&1 &
```

---

## 📞 技术支持

### 文件位置

| 文件 | 路径 |
|------|------|
| **启动脚本** | `/root/ai_customer_service/ai_cs/run_tianwang_simple.py` |
| **HTTP API** | `/root/ai_customer_service/ai_cs/api/http_server.py` |
| **任务调度** | `/root/ai_customer_service/ai_cs/core/task_scheduler.py` |
| **数据模型** | `/root/ai_customer_service/ai_cs/db/task_db/task_model.py` |
| **配置文件** | `/root/ai_customer_service/ai_cs/.env.tianwang` |
| **日志文件** | `/tmp/tianwang.log` |
| **数据库** | `/root/ai_customer_service/ai_cs/db/task_db/tasks.db` |

### 文档位置

| 文档 | 路径 |
|------|------|
| **部署文档** | `/root/ai_customer_service/ai_cs/部署文档.md` |
| **功能文档** | `/root/ai_customer_service/ai_cs/TIANWANG_INTEGRATION.md` |
| **使用示例** | `/root/ai_customer_service/ai_cs/SPECIFIED_CUSTOMER_REPLY_EXAMPLE.md` |

---

## 📧 发送文档

如需发送此文档，可以：

### 方式 1：复制内容
```bash
# 复制文档内容
cat /root/ai_customer_service/ai_cs/部署文档.md
```

### 方式 2：生成 PDF
```bash
# 安装 pandoc
apt-get install pandoc

# 转换为 PDF
pandoc /root/ai_customer_service/ai_cs/部署文档.md -o 部署文档.pdf
```

### 方式 3：发送邮件
```bash
# 使用 mail 命令
mail -s "AI 客服系统部署文档" recipient@example.com < /root/ai_customer_service/ai_cs/部署文档.md
```

---

## 🎯 快速参考卡片

```
┌─────────────────────────────────────────────┐
│  AI 客服 API - 快速参考                      │
├─────────────────────────────────────────────┤
│ 地址：http://localhost:6060                  │
│                                             │
│ POST /api/task/receive    - 接收任务        │
│ GET  /api/task/status/:id - 查询状态        │
│ POST /api/task/cancel     - 取消任务        │
│ GET  /api/task/list       - 任务列表        │
│ GET  /api/health          - 健康检查        │
│                                             │
│ 启动：python3 run_tianwang_simple.py        │
│ 日志：tail -f /tmp/tianwang.log             │
│ 数据库：sqlite3 db/task_db/tasks.db         │
└─────────────────────────────────────────────┘
```

---

**文档版本**: v1.0  
**更新日期**: 2026-02-27  
**维护者**: AI 客服系统团队