# 巡店删除 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`
- `aiimage.delete-brand-progress.patrol-delete-initial-timeout-minutes`

## 6. 历史清理

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

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

## 7. Python 端建议

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