7.9 KiB
7.9 KiB
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）
第一版做：
- 用户端：自助注册登录、注册成功赠送 100 点试用点数、扫码充值、查看点数/充值/消费记录、自助生成与删除 API Key。
- 生成标题、生成图片两个接口（同步返回结果）。
- 点数计费、扣点、余额查询。
- 充值到账（对接已有支付系统）。
- 调用记录与点数流水。
- 运营后台（账号、点数、计费规则、充值、调用记录）。
第一版先不做（留待后续迭代）：
- 高并发异步处理、用量统计报表、自动退款对账、复杂活动赠点 / 邀请奖励等（自助注册/扫码充值/API Key 管理与注册送 100 点已纳入第一版口径）。
取舍原则：先把「充值 → 调用 → 计费 → 记录」最小闭环做稳，再扩展。
七、设计亮点（用业务语言）
- 换模型不影响客户：对外只暴露「能力档位」（如"高清出图"），底层用哪家 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_urlSSRF 防护、生成/认证限流和充值金额上限已落地。 - 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 公开首页 + 客户端下载入口、T-607 桌面端最新版本检查接口、T-608 新用户注册赠送 100 点试用点数与 T-609 桌面端版本强制更新标记；线上真实标题生成已恢复并验证扣点。
- 下一步可继续补跑真实支付回调到账闭环、配置并发布客户端下载包和真实图片耗时验证。
更多细节：愿景 01-vision.md ｜ 需求与验收 02-requirements.md ｜ 架构 04-architecture.md ｜ 任务计划 06-tasks.md。