cmhub/docs/project-brief.md

# cmhub 项目介绍（给管理层）

> 面向决策与汇报的项目概览。技术细节见同目录架构与需求文档。
> 日期：2026-07-03 ｜ 阶段：Phase 4 起步（T-501 注册 / 登录）

## 一句话概括

把现有桌面工具 `cmbot` 里的「AI 生成标题、生成图片」能力，做成一个**自助用户端 + 对外计费 API 服务 + 运营后台**，让用户可自助注册充值和管理 API Key，让公司其他项目可按点数计费调用，做到用量可控、账目可查。

## 一、为什么做

- 现在 AI 生成能力**锁在单机桌面工具里**，别的项目想用就得各自重复对接上游 AI，成本高、不统一。
- 上游 AI 调用**按次产生真实成本**，目前没有计费和用量管控，谁用了多少、花了多少不清楚。
- 缺一个统一入口去**管账号、管用量、管成本、留记录**。

## 二、做成什么

一个**自助用户端 + 计费型 AI 能力网关 + 运营后台**：

- 用户可自助注册、扫码充值、查看点数和记录、管理 API Key。
- 对外只提供两个稳定接口：**生成标题**、**生成图片**。
- 谁能调、调多少，用**点数**计费：不同操作、不同能力别名/分辨率消耗不同点数。
- 点数不够时直接提示「点数不足，请先充值」。
- 配一个**运营后台**，运营人员可视化管理用户、点数、计费规则和所有调用记录。

> 它不是面向消费者的「内容生成网站」；终端用户有一个**自助用户端**（注册 / 扫码充值 / 管理 API Key / 查记录），生成能力则通过 **API** 提供给用户的程序调用。

## 三、给业务带来什么价值

| 价值 | 说明 |
| --- | --- |
| 能力复用 | 一处建设，多个项目共享，无需各自重复对接 AI |
| 成本可控 | 按点数计费，用量与成本透明、可量化 |
| 收入闭环 | 用户充值 → 转点数 → 调用扣点，形成可计量的变现链路 |
| 可运营 | 后台一处管理账号、点数、计费规则、充值与调用记录 |
| 可演进 | 后台可随时切换/新增底层 AI 模型，调用方无感知 |

## 四、它怎么运转（业务流程）

**充值**：用户到公司**已有支付系统**付款 → 付款成功后系统按汇率自动把金额**转成点数**记到账户。

**调用**：其他项目带密钥调用接口 → 系统检查点数是否足够 → 足够就生成内容并扣点、记一条账 → 不足就提示充值。

```
用户付款 ──> 支付系统 ──回调──> 点数到账
其他项目 ──调用接口──> 够点? ──是──> 生成 + 扣点 + 记录
                              └──否──> 提示充值
```

关键原则：**账目必须对得上**——每一笔点数变动都有流水，可追溯到充值订单或具体调用。

## 五、商业 / 计费模式

- **预付费点数**：先充值、后消费，类似话费/云服务的预付费。
- 充值金额按**可配置汇率**换算成点数（如 1 元 = N 点，由运营在后台设定）。
- 不同接口、不同能力别名、不同清晰度可设**不同点数单价**，灵活定价。
- 付款在公司**已有支付系统**完成，本项目不碰收银，只接收付款结果——合规、风险低。

## 六、第一版范围（MVP）

**第一版做**：

- 用户端：自助注册登录、扫码充值、查看点数/充值/消费记录、自助生成与删除 API Key（注册不送免费点数）。
- 生成标题、生成图片两个接口（同步返回结果）。
- 点数计费、扣点、余额查询。
- 充值到账（对接已有支付系统）。
- 调用记录与点数流水。
- 运营后台（账号、点数、计费规则、充值、调用记录）。

**第一版先不做**（留待后续迭代）：

- 高并发异步处理、用量统计报表、自动退款对账、注册赠点等（自助注册/扫码充值/API Key 管理已纳入第一版）。

> 取舍原则：先把「充值 → 调用 → 计费 → 记录」最小闭环做稳，再扩展。

## 七、设计亮点（用业务语言）

- **换模型不影响客户**：对外只暴露「能力档位」（如"高清出图"），底层用哪家 AI 模型由后台配置，**随时可换、可比价、可降本**，调用方完全无感。
- **资金安全内建**：防止并发超扣、防止重复充值入账、生成失败自动退点、全程留痕——保证不会算错账、不会乱扣费。

## 八、关键依赖与风险（需要拍板的事）

| 事项 | 说明 | 需谁确认 |
| --- | --- | --- |
| 支付商户配置 | 协议已明确；上线前需提供微信/支付宝商户密钥、证书、公网回调域名 | 支付系统负责人 |
| 计费定价 | 1 元换多少点、各接口/模型多少点 | 产品 / 运营 |
| 上游 AI 成本 | 上游按次收费，需关注成本与定价的利润空间 | 财务 / 产品 |

> 这些不阻塞开发起步；前期可用模拟方式推进，定价与真实商户配置到位后接入真实环境。

## 九、计划与里程碑

| 里程碑 | 内容 |
| --- | --- |
| M1 | Django + admin 骨架可运行，自定义 User 就位 |
| M2 | 服务端跑通一次 AI 生成（验证可行性） |
| M3 | 计费 + 对外接口 + 充值闭环打通 |
| M4 | 用户端（注册 / 充值 / API Key / 记录）可用 |
| M5 | 运营后台完善 + MVP 验收 + 可部署上线 |

## 十、当前状态

- M1 骨架已完成：Django + admin + 自定义 User + MySQL 8.4 已跑通。
- Phase 1 已完成 T-101~T-104：AI Provider 适配器、AiModel/ModelAlias、Fernet 加密密钥存储、别名解析、配置审计与录制标题生成 smoke 已落地。
- Phase 2 计费核心已完成：PricingRule / ExchangeRate、计费计算、并发安全扣点与失败退点已落地，并覆盖并发测试。
- Phase 3 对外 API 与充值已完成到 T-306：API Key 鉴权、生成/余额接口、扫码充值下单与轮询、支付回调幂等入账、`image_url` SSRF 防护、生成/认证限流和充值金额上限已落地。
- 下一步是 T-501：实现用户端注册 / 登录（allauth），注册后钱包点数为 0，不送免费点数。

---
*更多细节：愿景 `01-vision.md` ｜ 需求与验收 `02-requirements.md` ｜ 架构 `04-architecture.md` ｜ 任务计划 `06-tasks.md`。*