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。

文档入口

本仓库采用 harness coding 文档约定。AI coding agent 与开发者请从这里进入：

• 人类总览：本文件。
• agent 工作入口：docs/00-ai-start-here.md。
• 文档导航：docs/README.md。
• 仓库级规则：AGENTS.md / CLAUDE.md。

当前状态

Phase 2 计费核心已完成，Phase 3 对外 API 与充值已完成到 T-306：对外 API 可用 Authorization: Bearer <API_KEY> 调用生成能力或查询点数余额；用户端 session 流程可创建充值订单、获取二维码票据并轮询订单状态，充值回调按订单幂等入账；image_url 已做 SSRF 防护，生成/认证失败有限流，充值下单有单笔金额上限。下一步进入 Phase 4 用户端，先做 T-501 注册 / 登录（allauth）。详见 docs/current-state.md。

⚠️ 涉及资金/点数。改动充值、扣费、退款、对账相关代码前，先读 docs/05-coding-rules.md 第 8 节与 docs/04-architecture.md 第四节计费时序。

启动

./init.sh        # WSL / Git Bash / macOS / Linux
./init.ps1       # Windows 原生 PowerShell

脚本完成依赖安装 + 验证 + 打印启动命令。当前 Windows 标准入口为 ./init.ps1。