cmhub/docs/00-ai-start-here.md

AI 开发入口

给 AI coding agent 的项目入口。这里负责导航和流程，硬性编码规则见 05-coding-rules.md。

一句话定位

cmhub 是「自助用户端 + 计费 API + 运营后台」三合一服务：终端用户在用户端自助注册、扫码充值、管理 API Key，用 API Key 调用把 cmbot 的「生成标题」「生成图片」能力封装成的 HTTP 接口，按点数计费；运营用 django-admin 管理用户、点数与记录。

第一版 MVP 做：用户自助注册登录 → 注册成功赠送 100 点试用点数 → 扫码充值转点数 → 自助生成/删除 API Key → 带 Key 调用按规则算点数 → 点数足够则调上游生成并扣点 / 不足则报错 → 写调用与消费记录 → django-admin 运营后台。注册赠点也是账本资产，必须经计费层入账并写点数流水。

必读顺序

每次开始写代码前，按这个顺序建立上下文：

1. 01-vision.md：为什么做、为谁做、什么不做。
2. 02-requirements.md：MVP 要什么、怎么算达成。
3. 03-tech-stack.md：既定技术选型（Django + DRF + django-admin）。
4. 04-architecture.md：系统结构、计费时序、数据模型和关键难点。
5. 05-coding-rules.md：写代码前必须遵守的规则（含资金安全）。
6. api.md：对外接口与支付回调合约。
7. 06-tasks.md：领取本轮唯一任务。
8. ../progress.md：历史执行记录、验证结果、阻塞点和关键决策。
9. current-state.md：当前代码现实、可运行命令、下一步任务。

仓库根目录 AGENTS.md、CLAUDE.md 必须先读。仓库级规则优先于项目局部建议。

固定开工流程

读完上述文档后，每轮会话按这个机械顺序进入，恢复持久状态再动手：

1. pwd：确认在 cmhub 仓库根目录。
2. 读 ../progress.md 和 current-state.md：恢复已验证状态、下一步和当前 blocker。
3. git log --oneline -5：看清最近发生了什么（仓库初始化后）。
4. 运行 ./init.sh（Windows 原生 PowerShell 用 ./init.ps1）：统一安装、验证、打印启动命令；如脚本提示命令未替换，先配置脚本顶部三个命令。
5. 跑一条基础 smoke / 端到端路径，确认基线没坏。
6. 如果基线已坏，先修基线，不要在坏的起点上叠新功能。
7. 基线绿了，再从 06-tasks.md 领取唯一任务。

当前阶段

当前项目处于：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「用户端品牌名统一为虾皮圈」、T-612「生图同步接口止血」、T-613「抽生成核心 service」、T-614「生图异步任务化接口」与 T-615「旧同步生图接口遥测 / 弃用口径」。生图慢 / 504 / 客户端超时已拆为 T-612~T-615 并完成：T-612 已做同步接口上游硬截止止血，T-613 已抽共享生成 core，T-614 已新增异步提交 / 轮询接口与 DB worker，T-615 已给旧同步 / 新异步提交路径接入结构化日志并形成旧同步接口退出条件。生产侧仍需补真实支付回调到账闭环；邮件服务仅用于后续密码找回/通知等邮件能力，不阻塞注册登录。

优先路径：

1. Phase 0：Django 骨架可运行、自定义 User 模型在首次迁移前定好、django-admin 可登录；T-004 审核修补项已完成。
2. Phase 1：最高风险功能原型 —— T-101/T-102/T-103/T-104/T-105 已完成 provider 层、模型配置表、别名解析、配置审计、录制标题/图片 smoke 与审核修补；真实图片同步耗时待配置 Fernet 主密钥、AiModel/ModelAlias 与真实上游后在 T-302/T-403 前补测。
3. Phase 2：计费核心 —— T-201/T-202/T-203 已完成 UserWallet/ApiKey/PointsLedger/CallRecord、计费规则、汇率、计费计算、并发安全扣点与失败退点。
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~T-618 已完成，覆盖可用别名发现、后台中文化、敏感词过滤、免邮箱验证、公开首页与客户端发布、注册赠点、用户端品牌、生图异步化 / 遥测 / 自动重试和客户端发布校验元数据；T-619「多张图片理解并返回文字」已登记为下一项 TODO，将新增独立 vision 操作、能力别名和同步多图理解接口，当前尚未实现。

领取任务规则

从 06-tasks.md 领取任务时：

• 只领取第一个状态为 TODO 且依赖均为 DONE 的任务。
• 开始前把该任务状态改为 DOING。
• 本轮只完成这一个任务。
• 验收通过后把状态改为 DONE。
• 完成后把执行记录追加到 ../progress.md，并覆盖更新 current-state.md。
• 结束会话前过一遍 clean-state-checklist.md。
• 做完即停，汇报验证结果，等待下一步指令。

如果代码实际状态和任务看板冲突，先说明冲突，不要擅自跳步或重排。

MVP 边界

MVP 只做：

• 用户端（Django 模板 SSR + Bootstrap）：自助注册/登录、注册成功一次性赠送 100 点试用点数、扫码充值、查看充值记录/充值总额/剩余点数/消费记录、自助生成与删除 API Key。
• 对外生成接口：POST /api/v1/generate/title（同步返回标题）、POST /api/v1/generate/image（旧同步生图，保留兼容）、POST /api/v1/generate/image/tasks + GET /api/v1/generate/image/tasks/{task_id}（异步生图提交 / 轮询）。
• API Key 鉴权，识别所属注册用户（API 只认 Key，不认 Web session）。
• 点数计费：按「操作类型 + 能力别名（+ 可选分辨率）」查计费规则得点数；本地余额原子扣减；不足报错。
• 支付充值回调：支付系统服务端回调 → 验签 + 幂等 → 按汇率把金额转点数入账。
• 调用记录与点数流水落库。
• django-admin 运营后台：管理账号、点数余额、计费规则、充值订单、点数流水、调用记录。

MVP 不做：

• Celery/RQ 等外部任务队列（T-614 已用 DB 任务表 + management command worker 实现生图异步提交 / 轮询；本期不做 cancel、回调通知或专业队列）。
• 自建支付/收银台（充值走外部支付系统，本服务发起扫码下单并接收回调，不碰资金清算）。
• 面向终端消费者的「内容生成产品页」（用户端只做账户自助，生成结果仍只经 API 输出）。
• 复杂活动赠点、邀请奖励或历史用户自动补发；除 T-608 明确定义的新用户一次性 100 点注册试用额度外，不做其他免费点数活动。
• 多币种、分账、自动退款对账。

事实来源

项目事实只信：

• 本 docs/ 目录的需求、架构、API 合约。
• cmbot/src/services/ai_text_service.py、ai_image_service.py、cmbot/config/ai_models.json：AI 上游调用的权威实现与模型配置形状。
• 支付协议以 api.md 与 04-architecture.md 为准：微信 V3 native + 支付宝当面付的下单、回调、验签、应答已按同系统实现明确；仅真实商户密钥/证书/notify_url 待提供。

不要把以下内容当事实来源：历史备份、旧导出文档、临时实验目录、未被任务或需求引用的草稿。

常见任务该看哪里

做对外 API / 支付回调：先看 api.md 合约，再看 04-architecture.md 的鉴权与计费时序。

做计费 / 扣点 / 充值：先看 04-architecture.md 第四节计费时序与并发安全，再看 05-coding-rules.md 第 8 节。

做数据模型：先看 04-architecture.md 第三节；schema 变化必须同步 api.md、current-state.md 和相关任务验收。

做运营后台：先看 routes.md（admin 入口与页面职责），再看 04-architecture.md 数据模型。

做部署 / 运行：先看 03-tech-stack.md 的运行命令、env.md 的环境变量，再看 current-state.md 的当前真实命令。

验证命令

统一启动与验证入口收敛到根目录 ./init.sh（Windows 原生 PowerShell 用 ./init.ps1）。骨架落地后，真实命令大致为：

# Windows PowerShell
py -3.12 -m pip install -r requirements.txt
py -3.12 manage.py check
py -3.12 manage.py test
py -3.12 manage.py runserver

# Unix / WSL
python3.12 -m pip install -r requirements.txt
python3.12 manage.py check
python3.12 manage.py test
python3.12 manage.py runserver

说明：

• 改后端逻辑后跑：py -3.12 manage.py test（Windows）或 python3.12 manage.py test（Unix/WSL）。
• 改数据模型后跑：makemigrations && migrate && test；涉及 User 字段唯一约束时，先确认业务库无重复数据。
• 如果命令当前不可运行，必须在回复里如实说明原因。