131 lines
7.9 KiB
Markdown
131 lines
7.9 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 做：**用户自助注册登录 → 扫码充值转点数 → 自助生成/删除 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 4 用户端起步**。Phase 2 计费核心已完成到 T-204；Phase 3 已完成 T-301 API Key 鉴权、T-302 生成标题 / 图片接口、T-303 余额查询接口、T-304 充值回调与 T-305 扫码充值下单 + 轮询。下一步进入 T-501 注册 / 登录（allauth）。
|
||
|
||
优先路径：
|
||
|
||
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 扫码下单与轮询已完成。
|
||
5. Phase 4：用户端（Django 模板 SSR）—— 下一步 T-501 注册登录，然后 API Key 管理、个人中心/记录页、充值页。
|
||
6. Phase 5：后台与发布 —— 运营后台完善、完整验收、部署 / 运行文档。
|
||
|
||
## 领取任务规则
|
||
|
||
从 [`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）**：自助注册/登录、扫码充值、查看充值记录/充值总额/剩余点数/消费记录、自助生成与删除 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`）。骨架落地后，真实命令大致为：
|
||
|
||
```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 字段唯一约束时，先确认业务库无重复数据。
|
||
- 如果命令当前不可运行，必须在回复里如实说明原因。
|