---
id: T-570
title: cmhub 异步生图 submit 读取等待调整为 36 秒
phase: 7
deps: [T-564]
status: DONE
created: 2026-07-09
---

## 问题 / 背景

T-564 后，②批量生图已改为异步任务接口：先 `POST /api/v1/generate/image/tasks` 提交任务，再轮询 `GET /api/v1/generate/image/tasks/{task_id}` 获取图片地址。当前 submit 阶段单次 read timeout 是 30 秒。

真实使用中，cmhub submit 可能因为上游排队、网关抖动或服务端首次调度稍慢，30 秒边界略紧，容易在服务端可能已受理任务但客户端未拿到 `task_id` 的窗口报超时。为降低边界抖动，本任务把 submit 阶段单次 read timeout 从 30 秒调到 36 秒。

## 方案

- `app/ai.py`
  - 将 `CMHUB_IMAGE_SUBMIT_READ_TIMEOUT_SECONDS` 从 `30` 改为 `36`。
  - 只影响 `POST /api/v1/generate/image/tasks` 的读取等待。
  - 不改 poll 单次 15 秒、本地总预算 900 秒、图片下载 900 秒。
- `tests/test_ai.py`
  - 补充/更新 cmhub 异步生图测试，断言 submit 请求实际使用 `timeout=(connect_timeout, 36)`。
- 文档
  - 同步 `docs/api.md` 和 `docs/cmhub-integration-design.md` 中关于 submit 读取等待的精确说明。

## 验收要点

- `POST /api/v1/generate/image/tasks` 的 read timeout 为 36 秒。
- poll 单次读取等待仍为 15 秒，本地总预算仍为 900 秒。
- 下载读取等待仍为 900 秒。
- 不改 cmhub submit/poll 状态机、DB schema、幂等键和重启续查逻辑。
- 验证命令：
  - `py -3.10 -m unittest tests.test_ai`
  - `python -m ruff check app tests main.py`
  - `py -3.10 -m compileall app main.py`
  - `py -3.10 -m unittest discover -s tests`
  - `git diff --check`

## 边界（不改什么）

- 不改 `ai.cmhub.connect_timeout` 默认值 66 秒。
- 不改生图 poll 总等待 900 秒、poll 单次 15 秒和轮询间隔。
- 不改图片下载逻辑、curl/requests 选择、图片 URL 安全校验。
- 不改 CDP/Shopee、Excel、GUI 布局或 DB schema。

## 执行记录

- 2026-07-09：完成 T-570。
  - `app/ai.py`：将 `CMHUB_IMAGE_SUBMIT_READ_TIMEOUT_SECONDS` 从 30 调整为 36，只影响 `POST /api/v1/generate/image/tasks` 的 submit 读取等待；poll 单次 15 秒、本地总预算 900 秒和下载 900 秒不变。
  - `tests/test_ai.py`：在 cmhub 异步 submit 落库测试中断言实际请求 timeout 为 `(connect_timeout, 36)`，防止后续回退。
  - 文档：同步 `docs/api.md` 与 `docs/cmhub-integration-design.md` 的 submit 读取等待口径。
  - 验证通过：`py -3.10 -m unittest tests.test_ai`、`python -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`py -3.10 -m unittest discover -s tests`、`git diff --check`。