巡店删除 Python 提交接口

本文档给 Python 端同学说明 patrol-delete 的结果回传方式。前端不会再提供“手动归档”按钮，任务收尾、XLSX 组装、OSS 上传与历史清理均由服务端自动完成。

1. 提交入口

方法：POST
路径：/api/patrol-delete/tasks/{taskId}/result
Content-Type：application/json

示例：

POST /api/patrol-delete/tasks/123/result
Content-Type: application/json

{
  "shops": [
    {
      "shopName": "示例店铺",
      "submissionId": "patrol-delete:123:示例店铺:1711111111111",
      "chunkIndex": 1,
      "chunkTotal": 3,
      "shopDone": false,
      "countrySections": [
        {
          "country": "德国",
          "rows": [
            {
              "status": "正常",
              "quantity": "12",
              "deleteQuantity": "3",
              "processStatus": "处理中"
            }
          ]
        }
      ],
      "cartRatios": [
        {
          "country": "德国",
          "ratio": "25%"
        }
      ]
    }
  ]
}

2. 字段说明

shops: 本次提交的店铺结果分片列表，至少 1 条。
shopName: 店铺名。服务端会按店铺名归并分片。
submissionId: 建议每个店铺任务周期内保持同一个 submissionId，方便排查日志。
chunkIndex: 当前分片序号，建议从 1 开始。
chunkTotal: 当前店铺总分片数。
shopDone: 当前店铺是否已全部提交完成。最后一片必须传 true。
error: 当前店铺执行失败时传错误信息。传了 error 后该店铺会直接记为失败并结束。
countrySections: 店铺各国家的状态数据。
cartRatios: 店铺各国家的购物车比例数据。

3. 分片合并规则

服务端按 taskId + shopName 聚合缓存。
同一国家的 countrySections[].rows 会按提交顺序追加合并。
cartRatios 按国家覆盖，后到数据覆盖先到数据。
当 shopDone=true 时，该店铺会被标记为完成。
如果中途提交了 error，该店铺会被标记为失败，不再等待后续分片。

4. Excel 组装规则

最终结果文件使用 xlsx/日常删除格式.xlsx 对应的数据结构：

第 1 列：店铺名
接着是 5 个国家块，每个国家 4 列：
- 国家状态
- 数量
- 删除数量
- 删除结果
最后是 5 组购物车比例列：
- 国家
- 购物车比例

每个店铺输出规则：

一个店铺占用的行数 = 5 个国家中数据行数的最大值
每个店铺处理完成后会额外空一行
然后再写下一个店铺

任务整体完成后：

服务端汇总所有已完成店铺的数据
组装成 XLSX
上传 OSS
前端历史任务中出现下载按钮，用户可直接下载

5. 自动收尾与超时补偿

前端不会手动触发归档，服务端自动处理：

Python 正常把所有店铺都提交完成后，服务端立即尝试收尾。
如果最后一次提交后未来得及触发收尾，定时补偿任务会再次尝试 finalize。
如果某店铺已有部分有效数据，但 Python 异常退出，补偿任务会尽量把已有数据收尾成成功店铺。
如果某店铺完全没有完整结果且已超时，服务端会将该店铺标记为失败。

当前超时配置来自后端配置项：

aiimage.delete-brand-progress.patrol-delete-stale-timeout-minutes
Python should call POST /api/tasks/{taskId}/heartbeat every minute; timeout now uses only the normal stale-timeout setting.

6. 历史清理

服务端会定时清理历史数据，但会跳过仍在执行中的任务。

RUNNING 任务不会被历史清理删除
只有已完成或已失败的历史记录会进入清理范围
临时目录缓存与结果目录也会定期清理

7. Python 端建议

一个店铺处理结束的最后一片一定要传 shopDone=true
如果店铺失败，请直接回传 error
大店铺建议按国家或按分页做分片，避免一次提交过大
如果同一店铺会多次回传，shopName 必须保持一致
如果最后一片提交成功，Python 端无需再调用额外“归档”接口

4.1 KiB Raw Blame History Unescape Escape