tw/图片任务数据库功能说明.md

# 图片任务数据库功能说明

## 📋 功能说明

图片任务现在会保存到 SQLite 数据库，支持：
1. ✅ 任务持久化（重启不丢失）
2. ✅ 客户后续增加需求细节
3. ✅ 需求变更历史记录
4. ✅ 任务状态追踪

---

## 🗄️ 数据库表结构

### 1. image_tasks（图片任务表）

| 字段 | 类型 | 说明 |
|------|------|------|
| task_id | TEXT | 任务 ID（主键） |
| customer_id | TEXT | 客户 ID |
| customer_name | TEXT | 客户名称 |
| original_image | TEXT | 原图 URL |
| operation | TEXT | 操作类型（enhance/remove_bg/vectorize） |
| requirements | TEXT | 需求 JSON（复杂度、比例、透视等） |
| customer_notes | TEXT | 客户备注/需求细节 |
| status | TEXT | 状态（pending/paid/processing/completed/failed） |
| created_at | TEXT | 创建时间 |
| paid_at | TEXT | 付款时间 |
| started_at | TEXT | 开始处理时间 |
| completed_at | TEXT | 完成时间 |
| result_image | TEXT | 结果图 URL |
| error_message | TEXT | 错误信息 |
| retry_count | INTEGER | 重试次数 |
| acc_id | TEXT | 店铺 ID |
| acc_type | TEXT | 平台类型 |

---

### 2. task_requirement_changes（需求变更表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 自增 ID（主键） |
| task_id | TEXT | 任务 ID（外键） |
| change_type | TEXT | 变更类型（add_note/modify_operation/add_requirement） |
| old_value | TEXT | 旧值 |
| new_value | TEXT | 新值 |
| changed_at | TEXT | 变更时间 |
| changed_by | TEXT | 变更者（customer/staff） |

---

## 🎯 使用场景

### 场景 1：客户发送图片，创建任务

```python
# AI 识别图片后自动创建
workflow.image_analysis_result(
    customer_id="customer_123",
    image_url="https://xxx.com/image.jpg",
    complexity="normal",
    aspect_ratio="1:1",
    perspective="no"
)

# 自动保存到数据库
# 任务状态：pending（待付款）
```

---

### 场景 2：客户付款，开始处理

```python
# 客户付款后
workflow.trigger_processing_on_payment(
    customer_id="customer_123"
)

# 任务状态更新：pending → paid → processing
```

---

### 场景 3：客户增加需求细节

```python
# 客户说："对了，需要去掉背景"
await workflow.add_customer_requirement(
    task_id="TASK_20260227_001",
    customer_id="customer_123",
    requirement="需要去掉背景"
)

# 数据库记录：
# customer_notes: "[02-27 18:00] 需要去掉背景"
# 任务变更表新增记录
```

---

### 场景 4：客户修改操作类型

```python
# 客户说："改成要分层文件"
await workflow.modify_operation(
    task_id="TASK_20260227_001",
    customer_id="customer_123",
    new_operation="remove_bg_and_layer"
)

# 数据库更新：
# operation: "enhance" → "remove_bg_and_layer"
# 任务变更表新增记录
```

---

### 场景 5：查看需求变更历史

```python
# 查看客户修改了哪些需求
history = workflow.get_task_requirement_history("TASK_20260227_001")

# 返回：
# [
#   {"change_type": "modify_operation", "old_value": "enhance", "new_value": "remove_bg_and_layer", ...},
#   {"change_type": "add_note", "old_value": "无", "new_value": "需要去掉背景", ...}
# ]
```

---

## 🔄 任务状态流转

```
pending（待付款）
    ↓
paid（已付款）
    ↓
processing（处理中）
    ↓
awaiting_confirm（待确认）
    ↓
completed（已完成）
    ↓
[failed（失败）]  ← 可能失败
```

---

## 📝 API 接口

### 创建任务
```python
workflow.create_image_task(
    customer_id="customer_123",
    original_image="https://xxx.com/image.jpg",
    operation="enhance"
)
```

### 添加需求
```python
await workflow.add_customer_requirement(
    task_id="TASK_001",
    customer_id="customer_123",
    requirement="需要高分辨率"
)
```

### 修改操作
```python
await workflow.modify_operation(
    task_id="TASK_001",
    customer_id="customer_123",
    new_operation="vectorize"
)
```

### 查询任务
```python
task = workflow.get_task("TASK_001")
tasks = workflow.get_customer_tasks("customer_123")
```

### 查询历史
```python
history = workflow.get_task_requirement_history("TASK_001")
```

---

## 🔍 数据库操作

### 查看数据库文件
```bash
sqlite3 /root/ai_customer_service/ai_cs/db/image_tasks.db
```

### 查询所有任务
```sql
SELECT task_id, customer_id, status, created_at FROM image_tasks ORDER BY created_at DESC LIMIT 10;
```

### 查询待处理任务
```sql
SELECT * FROM image_tasks WHERE status='pending';
```

### 查询客户需求变更
```sql
SELECT task_id, change_type, old_value, new_value, changed_at, changed_by 
FROM task_requirement_changes 
WHERE task_id='TASK_001' 
ORDER BY changed_at DESC;
```

---

## ⚠️ 注意事项

1. **任务持久化**：所有任务自动保存到数据库，重启不丢失
2. **需求变更**：客户可以随时增加需求细节（付款前）
3. **操作修改**：付款前可以修改操作类型，付款后不允许
4. **历史记录**：所有变更都有记录，可追溯
5. **状态管理**：任务状态自动流转，无需手动更新

---

## 📊 数据库位置

```
/root/ai_customer_service/ai_cs/db/image_tasks.db
```

数据库管理器：
```
/root/ai_customer_service/ai_cs/db/image_tasks_db.py
```

---

**文档版本**: v1.0  
**更新日期**: 2026-02-27