40 lines
3.4 KiB
Markdown
40 lines
3.4 KiB
Markdown
# cmhub
|
||
|
||
`cmhub` 是一个**自助用户端 + 计费型 AI 能力网关 + 运营后台**三合一服务：终端用户自助注册、扫码充值、管理 API Key；用 API Key 调用把桌面工具 `cmbot` 的「生成标题」「生成图片」能力封装成的 HTTP API，按**点数计费**；运营用 django-admin 管理用户、点数和记录。
|
||
|
||
## 它做什么
|
||
|
||
- 用户端（自助）：公开首页、注册/登录、扫码充值、查看充值记录/剩余点数/消费记录、查看可用模型、生成与删除 API Key、下载桌面端（注册不送免费点数）。
|
||
- 对外提供 HTTP API：生成标题、生成图片（同步返回）、查询点数余额、查询可用能力别名。
|
||
- 按「操作类型 + 能力别名（+ 可选分辨率）」计费，调用消耗不同点数；余额不足返回「点数不足，请先充值」。
|
||
- **预付费点数模型**：用户在外部支付系统充值，付款成功由支付系统回调本服务，按汇率把金额转成点数存在本地；之后调用直接扣本地点数，扣费与上游解耦、低延迟。
|
||
- django-admin 运营后台：管理注册用户、点数余额、计费规则、充值订单、点数流水、调用记录。
|
||
|
||
## 技术栈
|
||
|
||
Python 3.12 / Django 5.2 LTS + DRF / django-admin / 用户端 Django 模板 SSR + Bootstrap 5 + allauth / MySQL 8.4 LTS（cmhub 专用独立实例，不复用 VPS 已有的 MySQL 5.7）。AI 上游调用复用 `cmbot/src/services/` 的实现。详见 [`docs/03-tech-stack.md`](docs/03-tech-stack.md)。
|
||
|
||
## 文档入口
|
||
|
||
本仓库采用 harness coding 文档约定。AI coding agent 与开发者请从这里进入：
|
||
|
||
- 人类总览：本文件。
|
||
- agent 工作入口：[`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)。
|
||
- 文档导航：[`docs/README.md`](docs/README.md)。
|
||
- 仓库级规则：[`AGENTS.md`](AGENTS.md) / [`CLAUDE.md`](CLAUDE.md)。
|
||
|
||
## 当前状态
|
||
|
||
Phase 2 计费核心已完成，Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端已完成 T-501~T-505，Phase 5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档，Phase 6 已完成 T-601 可用别名发现、T-602/T-603 django-admin 中文化、T-604 中文敏感词本地过滤、T-605 免邮箱验证策略落地与 T-606 公开首页 + 客户端下载入口。用户可通过公开首页进入注册、登录和下载入口；登录后可扫码充值并轮询到账，生成 / 删除（吊销）API Key，查看余额、充值总额、分页充值记录、分页消费记录与可用模型；运营可在 django-admin 检索用户、钱包、API Key、计费规则、汇率、充值订单、点数流水、调用记录和客户端发布版本，并通过计费层带原因手工调点；生产部署按 `docs/deployment.md` 执行。生产侧仍需补真实支付回调到账闭环、配置并发布客户端下载包和图片真实耗时验证；邮件服务仅用于后续密码找回/通知等邮件能力，不阻塞注册登录。详见 [`docs/current-state.md`](docs/current-state.md)。
|
||
|
||
> ⚠️ 涉及资金/点数。改动充值、扣费、退款、对账相关代码前，先读 [`docs/05-coding-rules.md`](docs/05-coding-rules.md) 第 8 节与 [`docs/04-architecture.md`](docs/04-architecture.md) 第四节计费时序。
|
||
|
||
## 启动
|
||
|
||
```bash
|
||
./init.sh # WSL / Git Bash / macOS / Linux
|
||
./init.ps1 # Windows 原生 PowerShell
|
||
```
|
||
|
||
脚本完成依赖安装 + 验证 + 打印启动命令。当前 Windows 标准入口为 `./init.ps1`。
|