8.1 KiB
AI 开发入口
给 AI coding agent 的项目入口。这里负责导航和流程，硬性编码规则见
05-coding-rules.md。
一句话定位
cmhub 是「自助用户端 + 计费 API + 运营后台」三合一服务：终端用户在用户端自助注册、扫码充值、管理 API Key，用 API Key 调用把 cmbot 的「生成标题」「生成图片」能力封装成的 HTTP 接口，按点数计费；运营用 django-admin 管理用户、点数与记录。
第一版 MVP 做：用户自助注册登录 → 扫码充值转点数 → 自助生成/删除 API Key → 带 Key 调用按规则算点数 → 点数足够则调上游生成并扣点 / 不足则报错 → 写调用与消费记录 → django-admin 运营后台。注册不送免费点数，必须充值才有点数。
必读顺序
每次开始写代码前，按这个顺序建立上下文：
01-vision.md：为什么做、为谁做、什么不做。02-requirements.md：MVP 要什么、怎么算达成。03-tech-stack.md：既定技术选型（Django + DRF + django-admin）。04-architecture.md：系统结构、计费时序、数据模型和关键难点。05-coding-rules.md：写代码前必须遵守的规则（含资金安全）。api.md：对外接口与支付回调合约。06-tasks.md：领取本轮唯一任务。../progress.md：历史执行记录、验证结果、阻塞点和关键决策。current-state.md：当前代码现实、可运行命令、下一步任务。
仓库根目录 AGENTS.md、CLAUDE.md 必须先读。仓库级规则优先于项目局部建议。
固定开工流程
读完上述文档后，每轮会话按这个机械顺序进入，恢复持久状态再动手：
pwd：确认在cmhub仓库根目录。- 读
../progress.md和current-state.md：恢复已验证状态、下一步和当前 blocker。 git log --oneline -5：看清最近发生了什么（仓库初始化后）。- 运行
./init.sh（Windows 原生 PowerShell 用./init.ps1）：统一安装、验证、打印启动命令；如脚本提示命令未替换，先配置脚本顶部三个命令。 - 跑一条基础 smoke / 端到端路径，确认基线没坏。
- 如果基线已坏，先修基线，不要在坏的起点上叠新功能。
- 基线绿了，再从
06-tasks.md领取唯一任务。
当前阶段
当前项目处于：Phase 4 用户端。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 充值页。
优先路径：
- Phase 0：Django 骨架可运行、自定义 User 模型在首次迁移前定好、django-admin 可登录；T-004 审核修补项已完成。
- Phase 1：最高风险功能原型 —— T-101/T-102/T-103/T-104/T-105 已完成 provider 层、模型配置表、别名解析、配置审计、录制标题/图片 smoke 与审核修补；真实图片同步耗时待配置 Fernet 主密钥、AiModel/ModelAlias 与真实上游后在 T-302/T-403 前补测。
- Phase 2：计费核心 —— T-201/T-202/T-203 已完成 UserWallet/ApiKey/PointsLedger/CallRecord、计费规则、汇率、计费计算、并发安全扣点与失败退点。
- Phase 3：对外 API 与充值 —— T-301 Key 鉴权、T-302 生成接口、T-303 余额查询、T-304 充值回调、T-305 扫码下单与轮询、T-306 安全加固已完成。
- Phase 4：用户端（Django 模板 SSR）—— T-501 注册登录、T-502 API Key 管理与 T-503 个人中心 / 记录页已完成，下一步 T-504 充值页。
- Phase 5：后台与发布 —— 运营后台完善、完整验收、部署 / 运行文档。
领取任务规则
从 06-tasks.md 领取任务时：
- 只领取第一个状态为
TODO且依赖均为DONE的任务。 - 开始前把该任务状态改为
DOING。 - 本轮只完成这一个任务。
- 验收通过后把状态改为
DONE。 - 完成后把执行记录追加到
../progress.md，并覆盖更新current-state.md。 - 结束会话前过一遍
clean-state-checklist.md。 - 做完即停，汇报验证结果，等待下一步指令。
如果代码实际状态和任务看板冲突，先说明冲突，不要擅自跳步或重排。
MVP 边界
MVP 只做：
- 用户端（Django 模板 SSR + Bootstrap）：自助注册/登录、扫码充值、查看充值记录/充值总额/剩余点数/消费记录、自助生成与删除 API Key。
- 对外两个生成接口：
POST /api/v1/generate/title、POST /api/v1/generate/image（同步返回结果）。 - API Key 鉴权，识别所属注册用户（API 只认 Key，不认 Web session）。
- 点数计费：按「操作类型 + 能力别名（+ 可选分辨率）」查计费规则得点数；本地余额原子扣减；不足报错。
- 支付充值回调：支付系统服务端回调 → 验签 + 幂等 → 按汇率把金额转点数入账。
- 调用记录与点数流水落库。
- django-admin 运营后台：管理账号、点数余额、计费规则、充值订单、点数流水、调用记录。
MVP 不做：
- 异步任务队列（图片生成第一版走同步等待返回，不引入 Celery）。
- 自建支付/收银台（充值走外部支付系统，本服务发起扫码下单并接收回调，不碰资金清算）。
- 面向终端消费者的「内容生成产品页」（用户端只做账户自助，生成结果仍只经 API 输出）。
- 注册赠送免费点数（必须充值才有点数）。
- 多币种、分账、自动退款对账。
事实来源
项目事实只信：
- 本
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 字段唯一约束时，先确认业务库无重复数据。 - 如果命令当前不可运行，必须在回复里如实说明原因。