feat: add async image task API

docs/02-requirements.md

@@ -30,7 +30,7 @@
 | 扫码充值 | 用户端发起充值→展示支付二维码→扫码付款→回调到账；金额按汇率转点数 | P0 |
 | 个人中心 | 查看剩余点数、充值总额、充值记录、点数使用（消费）记录 | P0 |
 | 生成标题 API | 带 API Key + prompt（+可选商品图）调用，拿到标题文字 | P0 |
-| 生成图片 API | 带 API Key + prompt + 图 + 模型/分辨率调用，**同步**拿到生成图片 | P0 |
+| 生成图片 API | 带 API Key + prompt + 图 + 模型/分辨率调用；旧同步接口可直接返回图片 URL，新版客户端可用异步提交 / 轮询拿结果 | P0 |
 | 点数计费与扣减 | 按「操作类型+能力别名+分辨率」算点数，余额足够则扣点放行，不足则报错 | P0 |
 | 余额查询 API | 查询当前用户点数余额 | P0 |
 | 调用记录 | 每次调用落库：用户、Key、时间、操作、模型、消耗点数、成功/失败、错误 | P0 |
@@ -45,7 +45,7 @@
 
 | 功能 | 描述 | 阶段 |
 | --- | --- | --- |
-| 异步生成 | 图片生成改任务队列 + 轮询/回调，提升并发 | V2 |
+| 旧同步生图接口用量遥测与弃用 | 观察旧同步生图调用量、错误率和客户端版本，满足条件后再单独任务下线旧同步接口 | V2 |
 | 用量统计报表 | 按用户/时间/模型聚合消耗与成本 | V2 |
 | 复杂活动赠点 / 邀请奖励 | 注册 100 点之外的活动额度、邀请返利、历史用户补发等，需单独风控与审批 | V2 |
 | API Key 轮换 / 授权 | Key 到期轮换、按 Key 限授权别名 | V2 |
@@ -56,7 +56,7 @@
 1. 作为新用户，我在用户端自助注册登录后先获得 100 点试用点数；后续扫码充值一笔钱，看到对应点数按汇率到账。
 2. 作为已登录用户，我自助生成一把 API Key（明文只显示一次），也能删除不用的 Key。
 3. 作为接入方，我带着 API Key 调用生成标题接口，传入 prompt，能拿到生成的标题。
-4. 作为接入方，我调用生成图片接口，等待若干秒后在同一个响应里拿到图片结果。
+4. 作为接入方，我可以调用旧同步生成图片接口在同一个响应里拿到图片结果；也可以调用异步图片任务接口先拿到 `task_id`，再轮询直到成功或失败。
 5. 当我的点数不足以支付本次调用时，系统拒绝调用并返回「点数不足，请先充值」，且不调用上游、不扣点。
 6. 作为已登录用户，我在个人中心看到剩余点数、充值总额、充值记录和消费（调用）记录。
 7. 作为运营，我在后台能管理用户与点数（手工调点带原因），配置某操作的点数单价，查看某用户的调用记录和点数流水。
@@ -66,7 +66,7 @@
 每条 P0 功能对应可验证的判据：
 
 - **生成标题 API**：携带有效 API Key + 合法 prompt 调用，返回 200 且响应含标题文本；无效/缺失 Key 返回 401。
-- **生成图片 API**：携带有效 Key 调用，在超时上限内返回 200 且含图片（URL 或 base64）；上游失败时返回明确错误码，且**不扣点**（已扣则冲正）。
+- **生成图片 API**：旧同步接口携带有效 Key 调用，在超时上限内返回 200 且含图片 URL；异步接口提交后返回 `task_id`，轮询成功后返回稳定图片 URL。上游失败、超时或异步任务僵死时返回明确错误码，且**不最终扣点**（已扣则冲正）。
 - **点数计费与扣减**：调用前按规则算出点数 N；余额 ≥ N 才放行并精确扣 N；余额 < N 返回点数不足错误码且不调上游。并发同时多次调用，最终扣点总额正确，**不出现超扣或扣成负数**。
 - **余额查询 API**：返回的余额等于该账号点数流水累加结果。
 - **充值转点数**：模拟一次支付系统回调（含订单号、金额、签名），验签通过后按汇率加点；**同一订单号重复回调只入账一次**（幂等）；验签失败不入账。
@@ -86,11 +86,11 @@
 | 是否需要账号 | 是。终端用户**自助注册**（Django auth / allauth）→ 自助生成 API Key；运营用 Django 后台账号 |
 | 计费模型 | **预付费点数**：充值时按汇率把金额转点数存本地，调用直接扣本地点数 |
 | 余额是否实时查支付系统 | 否。本地点数余额为唯一权威账本，调用链路不查支付系统 |
-| 生成返回方式 | **同步**等待返回结果（图片接口需把网关/服务超时调到 ≥ 300s） |
+| 生成返回方式 | 标题仍同步返回；图片旧同步接口保留兼容，新版客户端优先使用异步提交 / 轮询 |
 | 模型选择方式 | 对外用**能力别名**（如 `image-hd`），不暴露具体模型名；后台配置别名→模型映射 |
 | 充值入口 | 用户端自助发起扫码充值（本服务向支付系统下单取二维码），付款成功由支付系统**服务端回调**入账 |
 | 注册是否送点数 | 是。新用户注册成功一次性赠送 100 点试用点数；只对功能上线后的新注册用户自动发放，历史用户是否补发需另行审批和单独任务 |
-| 暂不支持 | 异步队列、复杂活动赠点 / 邀请奖励、多币种、分账、自动退款对账 |
+| 暂不支持 | 复杂活动赠点 / 邀请奖励、多币种、分账、自动退款对账；异步生图本期只做提交 / 轮询，不做 cancel、回调通知或 Celery/RQ |
 
 ## 七、待确认 / 风险点
 
@@ -100,6 +100,6 @@
 - **注册赠点风险**：注册送点虽然不来自支付回调，但仍是可消费点数，必须防重复发放、防并发重试重复入账，并配套注册限流 / 图形验证码等防刷手段。
 - **凭证风险**：上游 AI 的 api_key、支付系统密钥属敏感信息，只能放环境变量/后台配置，不入代码与文档样例。
 - **第三方平台风险**：上游 vectorengine 可能限流、超时、变更；需处理超时、错误透传与失败不扣点。
-- **耗时风险**：图片同步生成耗时长，需确认网关/反向代理/客户端超时上限，避免连接中断导致已扣点但结果丢失。
+- **耗时风险**：图片旧同步生成耗时长，需确认网关/反向代理/客户端超时上限；新版客户端应优先使用异步任务接口，避免连接中断导致结果丢失。异步任务必须通过租约 / reaper 处理 worker 崩溃，避免点数已扣但任务永远 running。
 - **退款 / 纠纷**：外部退款后本地点数如何冲正？MVP 不自动化，但数据结构需保留可冲正能力。
 - **待确认决策**：上述由谁、何时决策需明确，尤其商户配置交付时间与计费规则。