127 lines
4.1 KiB
Markdown
127 lines
4.1 KiB
Markdown
# 巡店删除 Python 提交接口
|
||
|
||
本文档给 Python 端同学说明 `patrol-delete` 的结果回传方式。前端不会再提供“手动归档”按钮，任务收尾、XLSX 组装、OSS 上传与历史清理均由服务端自动完成。
|
||
|
||
## 1. 提交入口
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/api/patrol-delete/tasks/{taskId}/result`
|
||
- Content-Type：`application/json`
|
||
|
||
示例：
|
||
|
||
```http
|
||
POST /api/patrol-delete/tasks/123/result
|
||
Content-Type: application/json
|
||
```
|
||
|
||
```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 个国家中数据行数的最大值
|
||
- 每个店铺处理完成后会额外空一行
|
||
- 然后再写下一个店铺
|
||
|
||
任务整体完成后：
|
||
|
||
1. 服务端汇总所有已完成店铺的数据
|
||
2. 组装成 XLSX
|
||
3. 上传 OSS
|
||
4. 前端历史任务中出现下载按钮，用户可直接下载
|
||
|
||
## 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 端无需再调用额外“归档”接口
|