132 lines
10 KiB
Markdown
132 lines
10 KiB
Markdown
# AI 开发入口
|
||
|
||
> 给 AI coding agent 的项目入口。这里负责导航和流程，硬性编码规则见 [`05-coding-rules.md`](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`](01-vision.md)：为什么做、为谁做、什么不做。
|
||
2. [`02-requirements.md`](02-requirements.md)：MVP 要什么、怎么算达成。
|
||
3. [`03-tech-stack.md`](03-tech-stack.md)：既定技术选型（Django + DRF + django-admin）。
|
||
4. [`04-architecture.md`](04-architecture.md)：系统结构、计费时序、数据模型和关键难点。
|
||
5. [`05-coding-rules.md`](05-coding-rules.md)：写代码前必须遵守的规则（含资金安全）。
|
||
6. [`api.md`](api.md)：对外接口与支付回调合约。
|
||
7. [`06-tasks.md`](06-tasks.md)：领取本轮唯一任务。
|
||
8. [`../progress.md`](../progress.md)：历史执行记录、验证结果、阻塞点和关键决策。
|
||
9. [`current-state.md`](current-state.md)：当前代码现实、可运行命令、下一步任务。
|
||
|
||
仓库根目录 `AGENTS.md`、`CLAUDE.md` 必须先读。仓库级规则优先于项目局部建议。
|
||
|
||
## 固定开工流程
|
||
|
||
读完上述文档后，每轮会话按这个机械顺序进入，恢复持久状态再动手：
|
||
|
||
1. `pwd`：确认在 `cmhub` 仓库根目录。
|
||
2. 读 [`../progress.md`](../progress.md) 和 [`current-state.md`](current-state.md)：恢复已验证状态、下一步和当前 blocker。
|
||
3. `git log --oneline -5`：看清最近发生了什么（仓库初始化后）。
|
||
4. 运行 `./init.sh`（Windows 原生 PowerShell 用 `./init.ps1`）：统一安装、验证、打印启动命令；如脚本提示命令未替换，先配置脚本顶部三个命令。
|
||
5. 跑一条基础 smoke / 端到端路径，确认基线没坏。
|
||
6. **如果基线已坏，先修基线**，不要在坏的起点上叠新功能。
|
||
7. 基线绿了，再从 [`06-tasks.md`](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」。生图慢 / 504 / 客户端超时已拆为 T-612~T-615：T-612 已先做同步接口上游硬截止止血，T-613 已抽共享生成 core；下一步 T-614 新增异步提交轮询接口，随后 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 可用别名发现已完成，实现 `/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-613 已完成抽生成核心 service；当前下一个可领取任务为 T-614。
|
||
|
||
## 领取任务规则
|
||
|
||
从 [`06-tasks.md`](06-tasks.md) 领取任务时：
|
||
|
||
- 只领取第一个状态为 `TODO` 且依赖均为 `DONE` 的任务。
|
||
- 开始前把该任务状态改为 `DOING`。
|
||
- 本轮只完成这一个任务。
|
||
- 验收通过后把状态改为 `DONE`。
|
||
- 完成后把执行记录追加到 [`../progress.md`](../progress.md)，并覆盖更新 [`current-state.md`](current-state.md)。
|
||
- 结束会话前过一遍 [`clean-state-checklist.md`](clean-state-checklist.md)。
|
||
- 做完即停，汇报验证结果，等待下一步指令。
|
||
|
||
如果代码实际状态和任务看板冲突，先说明冲突，不要擅自跳步或重排。
|
||
|
||
## MVP 边界
|
||
|
||
MVP 只做：
|
||
|
||
- **用户端（Django 模板 SSR + Bootstrap）**：自助注册/登录、注册成功一次性赠送 100 点试用点数、扫码充值、查看充值记录/充值总额/剩余点数/消费记录、自助生成与删除 API Key。
|
||
- 对外两个生成接口：`POST /api/v1/generate/title`、`POST /api/v1/generate/image`（同步返回结果）。
|
||
- API Key 鉴权，识别所属注册用户（API 只认 Key，不认 Web session）。
|
||
- 点数计费：按「操作类型 + 能力别名（+ 可选分辨率）」查计费规则得点数；本地余额原子扣减；不足报错。
|
||
- 支付充值回调：支付系统服务端回调 → 验签 + 幂等 → 按汇率把金额转点数入账。
|
||
- 调用记录与点数流水落库。
|
||
- django-admin 运营后台：管理账号、点数余额、计费规则、充值订单、点数流水、调用记录。
|
||
|
||
MVP 不做：
|
||
|
||
- 异步任务队列（图片生成第一版走**同步等待**返回，不引入 Celery）。
|
||
- 自建支付/收银台（充值走外部支付系统，本服务发起扫码下单并接收回调，不碰资金清算）。
|
||
- 面向终端消费者的「内容生成产品页」（用户端只做账户自助，生成结果仍只经 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`）。骨架落地后，真实命令大致为：
|
||
|
||
```bash
|
||
# 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 字段唯一约束时，先确认业务库无重复数据。
|
||
- 如果命令当前不可运行，必须在回复里如实说明原因。
|