kami_apple_exchage/backend/docs/BATCH_TASKS_GUIDE.md

批量任务功能使用指南

功能概述

批量任务功能允许用户批量上传订单链接和金额，系统会自动轮询处理这些任务。支持以下特性：

• 批量上传订单链接和金额
• 支持Excel文件导入
• 分布式任务处理
• 实时进度跟踪
• 失败任务重试机制
• 详细的处理日志和截图

API 端点

1. 创建批量任务

POST /api/v1/batch-tasks/

{
  "name": "测试批量任务",
  "description": "这是一个测试批量任务",
  "task_items": [
    {
      "order_url": "https://example.com/order/1",
      "amount": 99.99
    },
    {
      "order_url": "https://example.com/order/2", 
      "amount": 149.99
    }
  ]
}

2. 通过Excel文件上传批量任务

POST /api/v1/batch-tasks/upload

• name: 任务名称 (Form字段)
• description: 任务描述 (Form字段，可选)
• file: Excel文件 (文件上传)

Excel文件格式要求：

order_url	amount
https://example.com/order/1	99.99
https://example.com/order/2	149.99
https://example.com/order/3	199.99

3. 获取批量任务列表

GET /api/v1/batch-tasks/

查询参数：

• skip: 跳过记录数 (默认: 0)
• limit: 限制记录数 (默认: 100)
• status: 状态过滤 (可选: pending, processing, completed, failed, cancelled)

4. 获取批量任务详情

GET /api/v1/batch-tasks/{batch_task_id}

5. 获取批量任务统计

GET /api/v1/batch-tasks/stats

6. 控制批量任务

POST /api/v1/batch-tasks/{batch_task_id}/control

{
  "action": "start"  // 可选: start, cancel
}

7. 重试失败任务项

POST /api/v1/batch-tasks/{batch_task_id}/retry

查询参数：

• limit: 重试数量限制 (默认: 10)

8. 更新任务项状态

PUT /api/v1/batch-tasks/items/{item_id}

{
  "status": "success",
  "order_number": "ORDER123456",
  "final_order_url": "https://example.com/final-order/123456",
  "failure_reason": null
}

任务状态说明

批量任务状态

• pending: 待处理
• processing: 处理中
• completed: 已完成
• failed: 失败
• cancelled: 已取消

任务项状态

• pending: 待处理
• processing: 处理中
• success: 成功
• failed: 失败
• skipped: 跳过

使用流程

1. 创建批量任务

   • 通过API或Excel文件上传订单链接和金额
   • 系统创建批量任务和任务项

2. 启动任务处理

   • 调用控制API启动批量任务
   • 系统开始分布式处理任务项

3. 监控进度

   • 通过统计API查看整体进度
   • 通过详情API查看具体任务项状态

4. 处理失败项

   • 查看失败原因和错误截图
   • 使用重试API重新处理失败项

配置说明

环境变量

• MAX_CONCURRENT_BATCH_ITEMS: 最大并发处理数 (默认: 5)
• BATCH_TASK_RETRY_LIMIT: 任务项最大重试次数 (默认: 3)
• BATCH_TASK_TIMEOUT: 单个任务项超时时间 (默认: 300秒)

Arq配置

批量任务使用Arq进行异步处理，确保Redis和Arq Worker正常运行：

# 启动Arq Worker
uv run python -m arq app.core.arq_worker:ArqWorkerSettings

错误处理

常见错误

1. Excel格式错误: 确保包含 order_url 和 amount 列
2. URL格式错误: 确保订单链接格式正确
3. 金额格式错误: 确保金额为有效数字
4. 任务处理超时: 检查网络连接和目标网站可用性

错误截图

系统会自动保存失败任务的错误截图到 /app/screenshots/errors/ 目录，便于问题排查。

性能优化

1. 合理设置并发数: 根据服务器性能调整Arq Worker的并发设置
2. 分批处理: 大量任务建议分批创建，避免单个批次过大
3. 监控资源: 关注CPU、内存和网络使用情况
4. 定期清理: 定期清理旧的截图和日志文件

示例代码

Python客户端示例

import requests
import pandas as pd

# 创建批量任务
def create_batch_task():
    url = "http://localhost:8000/api/v1/batch-tasks/"
    data = {
        "name": "测试批量任务",
        "description": "API创建的批量任务",
        "task_items": [
            {"order_url": "https://example.com/order/1", "amount": 99.99},
            {"order_url": "https://example.com/order/2", "amount": 149.99}
        ]
    }
    response = requests.post(url, json=data)
    return response.json()

# 上传Excel文件
def upload_excel_batch():
    url = "http://localhost:8000/api/v1/batch-tasks/upload"
    files = {"file": open("batch_orders.xlsx", "rb")}
    data = {"name": "Excel批量任务", "description": "通过Excel上传"}
    response = requests.post(url, files=files, data=data)
    return response.json()

# 启动批量任务
def start_batch_task(batch_task_id):
    url = f"http://localhost:8000/api/v1/batch-tasks/{batch_task_id}/control"
    data = {"action": "start"}
    response = requests.post(url, json=data)
    return response.json()

Excel文件创建示例

import pandas as pd

# 创建示例数据
data = {
    'order_url': [
        'https://example.com/order/1',
        'https://example.com/order/2',
        'https://example.com/order/3'
    ],
    'amount': [99.99, 149.99, 199.99]
}

df = pd.DataFrame(data)
df.to_excel('batch_orders.xlsx', index=False)