116 lines
7.6 KiB
Markdown
116 lines
7.6 KiB
Markdown
# cmhub 项目介绍（给管理层）
|
||
|
||
> 面向决策与汇报的项目概览。技术细节见同目录架构与需求文档。
|
||
> 日期：2026-07-03 ｜ 阶段：Phase 5 后台与发布（计划内 MVP 任务已完成）
|
||
|
||
## 一句话概括
|
||
|
||
把现有桌面工具 `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 防护、生成/认证限流和充值金额上限已落地。
|
||
- Phase 4 已完成 T-501~T-505：用户端注册 / 登录（allauth，免邮箱验证、注册即可用，邮箱仍唯一）、登出、API Key 自助管理、个人中心汇总、充值记录、消费记录和充值页已落地；用户可创建充值订单、查看二维码票据并轮询到账；Key 明文只显示一次，库内只保留 hash 和 prefix，删除即吊销；记录页仅见本人数据并支持分页；Bootstrap 与 qrcode.js 已改为本地 static 自托管。
|
||
- Phase 5 已完成 T-401：运营后台可管理/检索用户、钱包、API Key（脱敏）、计费规则、汇率、充值订单、点数流水和调用记录；手工调点必须填写原因，并经计费层锁钱包、写 `adjust` 流水。
|
||
- Phase 5 已完成 T-402：MVP P0 验收通过，注册/充值/API Key/调用/余额/记录/后台/别名映射均有测试证据，详见 `mvp-acceptance.md`。
|
||
- Phase 5 已完成 T-403：已补部署 / 运行文档，明确宝塔/Nginx/Gunicorn、生产静态与媒体文件、共享缓存限流、图片同步超时、真实商户配置和上线检查；当前免邮箱验证，邮件服务仅作为后续密码找回/通知等邮件能力配置项，详见 `deployment.md`。
|
||
- Phase 6 已完成 T-601 可用别名发现、T-602 后台表名/分组中文化、T-603 字段级中文化、T-604 中文敏感词本地过滤与 T-605 免邮箱验证策略落地；线上真实标题生成已恢复并验证扣点。
|
||
- 下一步是 T-606 公开首页 + 客户端下载入口，并继续补跑真实支付回调到账闭环和真实图片耗时验证。
|
||
|
||
---
|
||
*更多细节：愿景 `01-vision.md` ｜ 需求与验收 `02-requirements.md` ｜ 架构 `04-architecture.md` ｜ 任务计划 `06-tasks.md`。*
|