docs: refine image async task plan

README.md

@@ -25,7 +25,7 @@ Python 3.12 / Django 5.2 LTS + DRF / django-admin / 用户端 Django 模板 SSR
 
 ## 当前状态
 
-Phase 2 计费核心已完成，Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端已完成 T-501~T-505，Phase 5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档，Phase 6 已完成 T-601 可用别名发现、T-602/T-603 django-admin 中文化、T-604 中文敏感词本地过滤、T-605 免邮箱验证策略落地、T-606 公开首页 + 客户端下载入口、T-607 桌面端最新版本检查接口、T-608 新用户注册赠送 100 点试用点数与 T-609 桌面端版本强制更新标记。用户可通过公开首页进入注册、登录和下载入口；新用户注册后经计费层自动获得 100 点并写注册赠点流水；登录后可扫码充值并轮询到账，生成 / 删除（吊销）API Key，查看余额、充值总额、分页充值记录、分页点数记录与可用模型；桌面端可匿名请求最新客户端版本 JSON，并读取 `release.force_update` 判断是否必须升级；运营可在 django-admin 检索用户、钱包、API Key、计费规则、汇率、充值订单、点数流水、注册赠点记录、调用记录和客户端发布版本，并通过计费层带原因手工调点；生产部署按 `docs/deployment.md` 执行。生产侧仍需补真实支付回调到账闭环、配置并发布客户端下载包和图片真实耗时验证；邮件服务仅用于后续密码找回/通知等邮件能力，不阻塞注册登录。详见 [`docs/current-state.md`](docs/current-state.md)。
+Phase 2 计费核心已完成，Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端已完成 T-501~T-505，Phase 5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档，Phase 6 已完成 T-601 可用别名发现、T-602/T-603 django-admin 中文化、T-604 中文敏感词本地过滤、T-605 免邮箱验证策略落地、T-606 公开首页 + 客户端下载入口、T-607 桌面端最新版本检查接口、T-608 新用户注册赠送 100 点试用点数、T-609 桌面端版本强制更新标记、T-610 首页导入模板下载入口与 T-611 用户端品牌名统一为“虾皮圈”。用户可通过公开首页进入注册、登录、下载客户端和下载导入模板；新用户注册后经计费层自动获得 100 点并写注册赠点流水；登录后可扫码充值并轮询到账，生成 / 删除（吊销）API Key，查看余额、充值总额、分页充值记录、分页点数记录与可用模型；桌面端可匿名请求最新客户端版本 JSON，并读取 `release.force_update` 判断是否必须升级；运营可在 django-admin 检索用户、钱包、API Key、计费规则、汇率、充值订单、点数流水、注册赠点记录、调用记录、客户端发布版本和导入模板，并通过计费层带原因手工调点。下一步已拆为 T-612~T-615，优先处理生图同步接口止血、共享生成 core、异步提交轮询和旧同步接口遥测；生产侧仍需补真实支付回调到账闭环。详见 [`docs/current-state.md`](docs/current-state.md)。
 
 > ⚠️ 涉及资金/点数。改动充值、扣费、退款、对账相关代码前，先读 [`docs/05-coding-rules.md`](docs/05-coding-rules.md) 第 8 节与 [`docs/04-architecture.md`](docs/04-architecture.md) 第四节计费时序。
 

docs/00-ai-start-here.md

@@ -38,7 +38,7 @@
 
 ## 当前阶段
 
-当前项目处于：**Phase 6 增强任务推进期**。Phase 2 计费核心已完成到 T-204；Phase 3 已完成 T-301 API Key 鉴权、T-302 生成标题 / 图片接口、T-303 余额查询接口、T-304 充值回调、T-305 扫码充值下单 + 轮询与 T-306 对外 API 安全加固；Phase 4 已完成 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化；Phase 5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档；Phase 6 已完成 T-601「可用别名发现」、T-602「django-admin 中文化第 1-3 层」、T-603「django-admin 字段级中文化」、T-604「中文敏感词本地过滤」、T-605「免邮箱验证策略落地」、T-606「公开首页 + 客户端下载入口」、T-607「桌面端最新版本检查接口」、T-608「新用户注册赠送 100 点试用点数」、T-609「桌面端版本检查接口增加强制更新标记」、T-610「首页导入模板下载入口」与 T-611「用户端品牌名统一为虾皮圈」。生产侧仍需补真实支付回调到账闭环、配置并发布客户端下载包和图片生成真实耗时验证；邮件服务仅用于后续密码找回/通知等邮件能力，不阻塞注册登录。
+当前项目处于：**Phase 6 增强任务推进期**。Phase 2 计费核心已完成到 T-204；Phase 3 已完成 T-301 API Key 鉴权、T-302 生成标题 / 图片接口、T-303 余额查询接口、T-304 充值回调、T-305 扫码充值下单 + 轮询与 T-306 对外 API 安全加固；Phase 4 已完成 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化；Phase 5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档；Phase 6 已完成 T-601「可用别名发现」、T-602「django-admin 中文化第 1-3 层」、T-603「django-admin 字段级中文化」、T-604「中文敏感词本地过滤」、T-605「免邮箱验证策略落地」、T-606「公开首页 + 客户端下载入口」、T-607「桌面端最新版本检查接口」、T-608「新用户注册赠送 100 点试用点数」、T-609「桌面端版本检查接口增加强制更新标记」、T-610「首页导入模板下载入口」与 T-611「用户端品牌名统一为虾皮圈」。生图慢 / 504 / 客户端超时已拆为 T-612~T-615：先做同步接口止血和上游硬截止，再抽共享生成 core，随后新增异步提交轮询接口并观察旧同步接口用量。生产侧仍需补真实支付回调到账闭环；邮件服务仅用于后续密码找回/通知等邮件能力，不阻塞注册登录。
 
 优先路径：
 
@@ -48,7 +48,7 @@
 4. Phase 3：对外 API 与充值 —— T-301 Key 鉴权、T-302 生成接口、T-303 余额查询、T-304 充值回调、T-305 扫码下单与轮询、T-306 安全加固已完成。
 5. Phase 4：用户端（Django 模板 SSR）—— T-501 注册登录、T-502 API Key 管理、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化已完成。
 6. Phase 5：后台与发布 —— T-401 运营后台完善、T-402 完整验收 MVP、T-403 部署 / 运行文档已完成；计划内 MVP 任务已收尾。
-7. Phase 6：增强（MVP 后）—— T-601 可用别名发现已完成，实现 `/api/v1/models` 与 portal 只读「可用模型」页；T-602 已完成 django-admin 分组/表名中文化；T-603 已完成字段级中文标签代码与 no-op 迁移并人工确认 admin 字段中文化；T-604 已完成中文敏感词本地过滤；T-605 已完成免邮箱验证策略落地；T-606 已完成公开首页 + 客户端下载入口；T-607 已完成桌面端最新版本检查接口；T-608 已完成新用户注册赠送 100 点试用点数；T-609 已完成桌面端版本检查接口增加强制更新标记；T-610 已完成首页导入模板下载入口；T-611 已完成用户端品牌名统一为虾皮圈。
+7. Phase 6：增强（MVP 后）—— T-601 可用别名发现已完成，实现 `/api/v1/models` 与 portal 只读「可用模型」页；T-602 已完成 django-admin 分组/表名中文化；T-603 已完成字段级中文标签代码与 no-op 迁移并人工确认 admin 字段中文化；T-604 已完成中文敏感词本地过滤；T-605 已完成免邮箱验证策略落地；T-606 已完成公开首页 + 客户端下载入口；T-607 已完成桌面端最新版本检查接口；T-608 已完成新用户注册赠送 100 点试用点数；T-609 已完成桌面端版本检查接口增加强制更新标记；T-610 已完成首页导入模板下载入口；T-611 已完成用户端品牌名统一为虾皮圈；T-612~T-615 已立项为生图链路治理任务，当前下一个可领取任务为 T-612。
 
 ## 领取任务规则
 

docs/current-state.md

@@ -56,9 +56,9 @@
 
 - 已完成：T-001 初始化 Django + DRF 项目骨架；T-002 建立 apps 目录、自定义 User 与配置；T-003 接通 django-admin 与最小测试；T-004 Phase 0 骨架审核修补；T-101 Provider 适配器层 + 移植 cmbot 调用；T-102 AiModel + ModelAlias 模型 + 别名解析；T-103 配置变更审计；T-104 跑通一次录制标题生成；T-105 Phase 1 AI 层审核修补；T-201 User / UserWallet / ApiKey / PointsLedger / CallRecord 模型；T-202 PricingRule / ExchangeRate 模型 + 计费计算；T-203 并发安全扣点 / 退点；T-204 Phase 2 计费核心审核加固；T-301 API Key 鉴权；T-302 生成标题 / 图片接口；T-303 余额查询接口；T-304 充值回调；T-305 扫码充值下单 + 轮询；T-306 Phase 3 对外 API 安全加固；T-501 注册 / 登录（allauth）；T-502 API Key 自助管理页；T-503 个人中心 / 记录页；T-504 充值页（扫码 + 轮询到账）；T-505 Phase 4 用户端审核优化；T-401 运营后台完善；T-402 完整验收 MVP；T-403 部署 / 运行文档；T-601 可用别名发现；T-602 django-admin 中文化（第 1-3 层）；T-603 django-admin 中文化（第 4 层·字段级）；T-604 中文敏感词本地过滤；T-605 免邮箱验证策略落地；T-606 公开首页 + 客户端下载入口；T-607 桌面端最新版本检查接口；T-608 新用户注册赠送 100 点试用点数；T-609 桌面端版本检查接口增加强制更新标记；T-610 首页导入模板下载入口；T-611 用户端品牌名统一为虾皮圈。
 - 正在进行：无。
-- 待开始：当前无编号 TODO；之后可继续处理真实支付回调到账闭环、配置并发布客户端下载包、真实图片耗时验证，或从 Backlog 拆新任务。
+- 待开始：T-612 生图同步接口止血（上游硬截止 + 长请求池校准）、T-613 抽生成核心 service、T-614 生图异步任务化接口、T-615 旧同步生图接口用量遥测 + 弃用口径。
-- 当前 blocker：支付商户真实密钥/证书与生产 SDK 依赖仍待提供；微信回调到账闭环仍需真实支付验收；真实 AI 标题生成已在线上跑通，图片生成真实耗时仍需补测。
+- 当前 blocker：支付商户真实密钥/证书与生产 SDK 依赖仍待提供；微信回调到账闭环仍需真实支付验收；真实 AI 标题生成已在线上跑通，图片生成慢 / 504 / 客户端超时风险已拆为 T-612~T-615 分阶段处理。
-- 下一个可领取任务：当前无编号 TODO；需先从 Backlog 或业务优先级拆出下一项任务。
+- 下一个可领取任务：T-612 生图同步接口止血（上游硬截止 + 长请求池校准）。
 
 ## 当前可运行内容
 
@@ -123,8 +123,8 @@ gunicorn config.wsgi:application --bind 127.0.0.1:8002 --workers 1 --worker-clas
 1. 读仓库级 `AGENTS.md` / `CLAUDE.md`。
 2. 读 `docs/00-ai-start-here.md`。
 3. 读 `docs/05-coding-rules.md`（尤其第 8 节资金安全）。
-4. 在 `docs/06-tasks.md` 领取第一个 `TODO` 且依赖均 `DONE` 的任务；当前无编号 TODO。
+4. 在 `docs/06-tasks.md` 领取第一个 `TODO` 且依赖均 `DONE` 的任务；当前为 T-612。
-5. 下一步按业务优先级拆真实支付回调到账闭环、客户端下载包发布、真实图片耗时验证，或从 Backlog 创建新任务。
+5. 下一步优先处理 T-612，给旧同步生图接口加上游硬截止并校准长请求池；真实支付回调到账闭环和客户端下载包发布继续作为后续业务事项排期。
 
 ## 维护规则
 

progress.md

@@ -1619,3 +1619,32 @@
   - `git diff --check`：通过，仅 Windows CRLF 提示。
   - `py -3.12 manage.py test apps.portal.tests.PortalAccountFlowTests.test_homepage_is_public_and_shows_anonymous_onboarding_without_release apps.portal.tests.PortalAccountFlowTests.test_homepage_shows_current_download_release apps.portal.tests.PortalAccountFlowTests.test_portal_pages_use_shopee_circle_branding --keepdb --noinput --verbosity 2`：通过，3 tests OK。
 - 下一步：如需线上生效，部署最新代码到 185.216.248.75 并重启服务；无数据库迁移需要执行。
+
+## 2026-07-08 生图异步任务化任务口径修正（非任务）
+
+- 状态：DONE。
+- 背景：Claude Code 新增了 T-612~T-615 草案，用于处理生图慢、504 gateway timeout、客户端请求超时和旧同步接口迁移问题。复核线上实际运行后确认当前 `cmhub-generate` 已是 `gthread --workers 2 --threads 16 --timeout 900`，并非 sync worker，因此原草案中“sync worker 池饥饿 → 默认切 gevent”的口径需要修正。
+- 文档变更：
+  - `docs/06-tasks.md`：T-612 改为“上游硬截止 + 长请求池校准”，明确先保留已验证的 `gthread` 长请求池，gevent 仅作为兼容性验证后的替代方案；T-613 明确重构现有 `apps/api/generation.py`，不得复制第二套扣点 / 退点逻辑；T-614 补充 `ImageGenerationTask`、UUID `task_id`、`Idempotency-Key` 去重与 payload 冲突、DB worker + systemd、公开 URL 配置、IDOR 防护和本期不暴露 cancel；T-615 补充旧同步 / 新异步路径结构化遥测与弃用条件。
+  - `docs/current-state.md`：把“当前无编号 TODO”更新为 T-612~T-615 待开始，下一步为 T-612。
+  - `README.md`、`docs/00-ai-start-here.md`：同步 Phase 6 当前状态和下一步任务。
+- 验证：
+  - `git diff --check -- README.md docs/00-ai-start-here.md docs/06-tasks.md docs/current-state.md`：通过，仅 Windows CRLF 提示。
+  - `Select-String` 确认 `docs/06-tasks.md` 中 T-612~T-615、M11 和 Backlog 已更新，`docs/current-state.md` 的下一个可领取任务为 T-612。
+  - `rg -n "sync worker|先 gevent|当前无编号 TODO|图片真实耗时验证" README.md docs/00-ai-start-here.md docs/06-tasks.md docs/current-state.md`：仅保留 T-612 中“当前是 `gthread` 而非 sync worker”的事实说明，未再出现“当前无编号 TODO”等旧口径。
+- 阻塞：无。
+- 决策：T-612 先做硬截止和现有 gthread 长请求池校准，不把 gevent 作为默认第一步；T-614 第一版用 DB 任务表 + management command worker + systemd，不引入 Celery / Redis；异步 worker 必须复用共享 core 和已预扣 `CallRecord`，不得复制资金逻辑。
+- 下一步：领取 T-612，先更新 `deployment.md` / `04-architecture.md` / `env.md`，再落代码实现上游硬截止与退点测试。
+
+## 2026-07-08 T-614 验收条件加固（非任务）
+
+- 状态：DONE。
+- 背景：复核 Claude Code 对 T-614 的新增验收条件后，确认“结果保留窗口”“僵任务回收 reaper”“worker 重复执行幂等”方向合理，但需要把重排队、租约和迟到 worker 的口径写得更严格。
+- 变更：更新 `docs/06-tasks.md` 中 T-614：
+  - `ImageGenerationTask` 字段补充 `locked_at`、`lease_expires_at`、`heartbeat_at`、`worker_id`、`attempt_count`。
+  - reaper 改为按 `lease_expires_at` / `heartbeat_at` 识别僵任务，默认 `running -> failed + 退点`，不默认重排队；只有能证明尚未调上游时才允许后续任务设计重排队。
+  - worker 语义改为“允许至少一次执行，但账务和结果终态必须 exactly-once”，不得重复扣 / 退，不得覆盖已成功结果，也不得把已被 reaper 判失败并退点的任务改回成功。
+  - 环境变量口径补充 `IMAGE_TASK_RETENTION_HOURS`、`GENERATED_IMAGE_RETENTION_HOURS`、`IMAGE_TASK_REAPER_INTERVAL_SECONDS`、`IMAGE_TASK_LEASE_SECONDS`。
+  - 验收补充迟到 worker 场景：reaper 已判失败并退点后，迟到 worker 返回成功也不能改回 `succeeded`、不能覆盖结果、不能再次改账。
+- 验证：仅文档更新；提交前用 `git diff --check`、`Select-String` 复核。
+- 下一步：提交本轮文档；后续领取 T-612。