cmhub/docs/06-tasks.md

# 任务看板（Tasks）

> 把 MVP 拆成小步、可独立交付的任务，让 AI 一步一步开发，避免一次生成整个项目。

## 使用规则

1. **一次只做一个任务**：每轮只领取一个状态为 `TODO`、且依赖均已 `DONE` 的任务，取最靠前的那个。
2. **做完即停**：完成该任务、自测通过、把状态改成 `DONE` 后，停下来汇报。
3. **不跳步**：依赖未完成的任务不能开工。
4. **完成定义**：以 [编码规则](05-coding-rules.md) 的验证清单为准。
5. **passing 需证据**：标记 `DONE` 前，必须在 [`../progress.md`](../progress.md) 记录跑过的验证命令和结果。
6. **动手前**先读 `00-ai-start-here.md`、`05-coding-rules.md` 和 `current-state.md`。
7. **完成后**同步任务状态到本文，执行记录追加到 `../progress.md`，覆盖更新 `current-state.md`，过一遍 `clean-state-checklist.md`。

## 状态图例

`TODO` 待开始 · `DOING` 进行中（同一时间最多 1 个）· `DONE` 已完成并验收 · `BLOCKED` 受阻（注明原因）

---

## Phase 0 · 地基

| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| T-001 | 初始化 Django + DRF 项目骨架 | - | `manage.py` 可运行；`runserver` 起得来；用真实命令替换 `init.sh`/`init.ps1` 与 `00-ai-start-here.md`/`03-tech-stack.md`/`current-state.md` 的占位命令 | DONE |
| T-002 | 建立 apps 目录、自定义 User 与配置 | T-001 | 按 `04-architecture.md` 建 `apps/users|portal|billing|ai|api`；**首次迁移前定义自定义 `User` 模型（设 `AUTH_USER_MODEL`）**；settings 用环境变量读密钥、配 MySQL(utf8mb4)，无明文密钥 | DONE |
| T-003 | 接通 django-admin 与最小测试 | T-001 | `createsuperuser` 后能登录 `/admin/`；`manage.py test` 可运行（至少 1 条占位测试通过） | DONE |
| T-004 | Phase 0 骨架审核修补 | T-003 | 按 [`phase-0-review.md`](phase-0-review.md) 修 **P1**（`User.email` 加 `unique`、`requires-python` 落地 + init 校验解释器版本）与 **P2**（`INSTALLED_APPS` 顺序、补 `.env.example`）；同步修正根 `README.md` 当前状态；`check`/`test`/`init` 重新全绿并在 `../progress.md` 留证据。**建议先于 T-101 完成**（P1-1 趁 user 表空成本最低） | DONE |

## Phase 1 · 最高风险验证（AI 调用 + 可插拔供应商）

| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| T-101 | Provider 适配器层 + 移植 cmbot 调用 | T-002 | 定义 `Provider` 接口（`capabilities`/`generate_text`/`generate_image`），按 `api_type` 注册；把 `ai_text_service.py`/`ai_image_service.py` 搬进 `apps/ai/providers/` 并去除桌面依赖；**注意 3 模型机制不同（chat / chat 多模态返图 nano-banana2 / images_edits 改图 gpt-image-2，见 `04` 3.1），两图片模型非标准生成需分别解析、首次对接抓真实响应**；mock 上游单测验证解析与适配器选取 | DONE |
| T-102 | AiModel + ModelAlias 模型 + 别名解析 | T-101 | AiModel 含 `capabilities`、`api_key` **加密存储**（admin 脱敏不回显）；ModelAlias 映射别名→模型；`resolve_alias()` 能解析并按能力校验；配置迁移自 `ai_models.json`；后台改配置运行时热生效 | DONE |
| T-103 | 配置变更审计 | T-102 | AiModel/ModelAlias/密钥的后台变更留痕（谁、何时、改了什么）；可在 admin 查看 | DONE |
| T-104 | 跑通一次真实/录制的标题或图片生成 | T-102 | 用别名 + 最小输入跑通一次生成，结论写入 `progress.md`（含耗时，验证图片同步可行性与超时配置） | DONE（管路已验；**图片同步耗时风险未退，已挂到 T-302/T-403，见 phase-1-review P1-2**） |
| T-105 | Phase 1 AI 层审核修补 | T-104 | 按 [`phase-1-review.md`](phase-1-review.md) 修 **P1**（`parameters`/`extra_body` 透传白名单化，核心/计费字段不可被调用方覆盖，含单测；T-104 结论改写为「图片同步风险未退」并把该未决风险显式登记到 T-302/T-403）与 **P2**（`.env.example` 的 `AI_DEFAULT_*` 超时键接上或删除、`resolution_to_size` 大小写归一、默认别名口径对齐）；`check`/`test`/`init` 全绿并在 `../progress.md` 留证据。**P1-1 建议先于 T-302 完成**（否则易顺手 `parameters=request.data` 造成越权计费） | DONE |

## Phase 2 · 计费核心

| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| T-201 | User / UserWallet / ApiKey / PointsLedger / CallRecord 模型 | T-002 | 表结构符合 `04-architecture.md`；`UserWallet.points_balance>=0` 约束；ApiKey **哈希存储**（key_hash+key_prefix，明文只创建时返回）；CallRecord 含 `user`/`api_key`/`alias`/`model_used`；调用结果只存 `result_ref`/摘要，不 dump provider `raw`、base64 图片或敏感上游字段；admin 注册 | DONE |
| T-202 | PricingRule / ExchangeRate 模型 + 计费计算 | T-201, T-102 | **按「操作 + 能力别名（+ 可选分辨率）」定价**；换底层模型不影响计费；缺规则返回 `no_pricing_rule` | DONE |
| T-203 | 并发安全扣点 / 退点（billing 层） | T-201 | 锁 `UserWallet` 行或 F() 原子扣减；并发测试不超扣、不为负；失败退点写流水；含测试 | DONE |
| T-204 | Phase 2 计费核心审核加固 | T-203 | 按 [`phase-2-review.md`](phase-2-review.md) 处理 **P2**（`points_ledger` 加 MySQL 可落地的 `ref_call + change_type` 复合唯一约束，作为「每 `ref_call` 最多一条 REFUND」DB 兜底，**不要使用 MySQL 不支持的 partial unique / 条件唯一约束**；补直写 `IntegrityError` 测试，并确认同一调用的 CONSUME 与 REFUND 可共存；在稳定 MySQL 上跑一次完整 `test` 全绿留证，并在测试文档标注「并发测试须在 MySQL 上跑，SQLite 会假绿」）；P3 已挂到 T-401/T-501 或备忘。**无 P1**，不阻塞 T-301；`check`/`test`/`init` 全绿并在 `../progress.md` 留证据 | DONE |

## Phase 3 · 对外 API 与充值

| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| T-301 | API Key 鉴权（DRF Authentication） | T-201 | 对请求 Key 哈希比对定位 ApiKey→User；**只挂 Key 认证、不挂 Session**；无效/缺失 401；用户或 Key 禁用 403 | DONE |
| T-302 | 生成标题 / 图片接口 | T-104, T-203, T-301 | 按 `api.md` 实现；请求传**能力别名**+ `parameters`，但 `parameters` 只能经 Provider 白名单透传，核心/计费字段不可被覆盖；编排「别名解析+能力校验→预扣→调上游→成功确认/失败退点→写记录」；评估 `Provider.capabilities()` 与模型声明能力的二次校验；`images_edits` 缺原图 / `AiCapabilityError` 翻译为 400，不落 500；调用记录不保存 provider `raw` / base64；点数不足返回 402；含测试；建议随本任务或 T-403 前跑一次真实图片生成并记录真实耗时 | DONE |
| T-303 | 余额查询接口 | T-301 | 返回余额等于流水累加；含测试 | DONE |
| T-304 | 充值回调（微信/支付宝验签 + 幂等入账） | T-202 | 两端点 `@csrf_exempt`；微信 SDK 验签解密、支付宝 SDK verify；验签失败不入账；同一 order_no 重复回调只入账一次；校验回调金额与订单金额一致；使用订单创建时锁定的 `points_granted` 锁 wallet 入账写流水；补主动查单兜底；含幂等测试 | TODO |
| T-305 | 扫码充值下单 + 轮询（create/status） | T-304 | 支持 weixin(native,金额分)/alipay(precreate,金额元)；建 pending 订单绑定 user，并在下单时锁定汇率/预计点数→取 code_url/qr_code→前端渲染 + 轮询 status；缺商户密钥时 mock | TODO |

## Phase 4 · 用户端（Django 模板 SSR）

| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| T-501 | 注册 / 登录（allauth） | T-201 | 自助注册（邮箱验证）、登录、登出；注册后钱包点数为 0（不送点数）；session + CSRF | TODO |
| T-502 | API Key 自助管理页 | T-501, T-301 | 登录用户生成/删除 Key；明文只显示一次、库存哈希；列表只显示 prefix；删除后该 Key 调用 401 | TODO |
| T-503 | 个人中心 / 记录页 | T-501, T-203 | 剩余点数、充值总额、充值记录、消费（调用）记录；数据与流水一致；仅见本人 | TODO |
| T-504 | 充值页（扫码 + 轮询到账） | T-501, T-305 | 发起充值→展示二维码→轮询订单状态→到账后余额刷新；到账以回调为权威 | TODO |

## Phase 5 · 后台与发布

| ID | 任务 | 依赖 | 验收要点 | 状态 |
| --- | --- | --- | --- | --- |
| T-401 | 运营后台完善 | T-302, T-304 | admin 可管理用户/钱包/ApiKey（脱敏）、配规则/汇率、检索充值订单/流水/调用记录；手工调点带原因并经计费层写流水 | TODO |
| T-402 | 完整验收 MVP | T-401, T-504 | `02-requirements.md` 的 P0 验收全部通过（含用户端注册/充值/API Key/记录） | TODO |
| T-403 | 部署 / 运行文档 | T-402 | 新环境可按文档运行；明确图片接口超时配置；上线前必须引用一次真实图片生成耗时来设置 Gunicorn `--timeout`、Nginx `proxy_read_timeout`、客户端 read timeout；若尚无真实耗时，部署文档必须显式标注图片同步风险未退，不得声称已验证 | TODO |

## 里程碑

- M1：Django + admin 骨架可运行、自定义 User 就位（T-003）。
- M2：服务端跑通一次 AI 生成（T-104）。
- M3：计费 + 对外接口 + 充值闭环（T-305）。
- M4：用户端（注册/充值/API Key/记录）可用（T-504）。
- M5：运营后台 + MVP 验收 + 可部署（T-403）。

## 待办池（Backlog）

- 异步生成（任务队列 + 轮询/回调）。
- 按账号授权可用别名（`account_alias_permission`），防止调用未授权/昂贵模型。
- 别名按比例分流到多个模型（灰度 / A/B / 故障转移）；供应商 A 故障自动切 B。
- 注册赠点 / 试用额度（需邮箱/图形验证码 + 限流防薅羊毛）。
- 用量统计报表。
- 退款对账自动化、API Key 轮换、Provider key 轮换（MultiFernet / 双 key 迁移）、限流细化。