处理后台管理系统、修复BUG、处理权限

backend-java/docs/patrol-delete-python-api.md

@@ -0,0 +1,126 @@
+# 巡店删除 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 端无需再调用额外“归档”接口