cmhub/docs/02-requirements.md

需求

本文只描述要什么与怎么算达成，用产品 / 用户语言表达，不涉及技术实现。 技术方案、数据结构、字段定义见 架构设计。

一、业务现状

项	状态
用户	其他项目想复用 cmbot 的标题/图片生成，但能力锁在单机桌面端，且无计费
数据	AI 上游调用逻辑与模型配置已存在于 cmbot（ai_text_service.py / ai_image_service.py / config/ai_models.json），可复用
现有系统	cmbot 桌面工具继续运行，不改动；外部已有支付系统，支付协议已明确为微信 V3 native + 支付宝当面付，真实商户配置上线前提供
约束	上游 AI（vectorengine.ai）按次产生真实成本；图片生成单次可能耗时几十秒到 1-2 分钟；涉及资金/点数，必须账目准确、防超扣、防重复入账

二、用户角色

• 注册用户（终端用户）：在用户端自助注册登录、扫码充值、查看自己的充值记录/充值总额/剩余点数/消费记录、自助生成与删除 API Key。点数余额挂在用户账户上。
• 接入方（用户的程序）：持有该用户名下的 API Key，调用生成接口、查询余额；扣的是所属用户的点数。
• 运营人员（后台管理员）：登录 django-admin，管理注册用户、启用/禁用账号、配置计费规则与汇率、查看充值订单/点数流水/调用记录、必要时手工调整点数。
• 游客 / 未登录 / 未携带有效 API Key：可访问公开首页、注册/登录页、公开客户端下载版本检查接口和公开导入模板下载入口；其他用户端自助页面需登录访问；生成/余额接口未带有效 Key 一律拒绝（401）。

三、功能清单

第一版 MVP（最小闭环）

功能	用户能做什么	优先级
用户注册/登录	终端用户在用户端自助注册、登录（免邮箱验证、注册即可用；邮箱仍必填且唯一）；注册成功一次性赠送 100 点试用点数	P0
API Key 自助管理	登录后自助生成/删除 API Key；Key 只在生成时显示一次（库内哈希存储）	P0
扫码充值	用户端发起充值→展示支付二维码→扫码付款→回调到账；金额按汇率转点数	P0
个人中心	查看剩余点数、充值总额、充值记录、点数使用（消费）记录	P0
生成标题 API	带 API Key + prompt（+可选商品图）调用，拿到标题文字	P0
生成图片 API	带 API Key + prompt + 图 + 模型/分辨率调用；旧同步接口可直接返回图片 URL，新版客户端可用异步提交 / 轮询拿结果	P0
点数计费与扣减	按「操作类型+能力别名+分辨率」算点数，余额足够则扣点放行，不足则报错	P0
余额查询 API	查询当前用户点数余额	P0
调用记录	每次调用落库：用户、Key、时间、操作、模型、消耗点数、成功/失败、错误	P0
点数流水	每次点数变动（充值/消费/退款/运营调整）落库，可对账	P0
运营后台	django-admin 管理用户、点数、计费规则、充值订单、流水、调用记录	P0
公开首页 + 客户端下载	匿名访客打开域名看到项目介绍与上手引导（注册→充值→建 Key→下载客户端）、并能下载桌面端安装包（含版本/SHA256 校验）；前期安装包托管在本服务器，后续可切对象存储/CDN	P1
桌面端版本检查 API	桌面端可匿名请求最新版本 JSON，拿到版本号、下载地址、文件大小字节数、SHA256、强制更新标记和发布说明；无当前版本时返回“暂未发布”而不是报错	P1
导入模板下载	匿名访客可在公开首页“下载客户端”旁边下载导入商品数据用的 Excel 模板；运营可在后台更新当前模板文件	P1
用户端品牌展示	终端用户可见的用户端页面统一展示产品名“虾皮圈”；内部工程名、API 路径、环境变量和文档中的服务代号 cmhub 不随本项改名	P1

后续迭代

功能	描述	阶段
旧同步生图接口用量遥测与弃用	观察旧同步生图调用量、错误率和客户端版本，满足条件后再单独任务下线旧同步接口	V2
用量统计报表	按用户/时间/模型聚合消耗与成本	V2
复杂活动赠点 / 邀请奖励	注册 100 点之外的活动额度、邀请返利、历史用户补发等，需单独风控与审批	V2
API Key 轮换 / 授权	Key 到期轮换、按 Key 限授权别名	V2
退款对账自动化	外部退款联动本地点数冲正	V3

四、核心用户故事（MVP）

1. 作为新用户，我在用户端自助注册登录后先获得 100 点试用点数；后续扫码充值一笔钱，看到对应点数按汇率到账。
2. 作为已登录用户，我自助生成一把 API Key（明文只显示一次），也能删除不用的 Key。
3. 作为接入方，我带着 API Key 调用生成标题接口，传入 prompt，能拿到生成的标题。
4. 作为接入方，我可以调用旧同步生成图片接口在同一个响应里拿到图片结果；也可以调用异步图片任务接口先拿到 task_id，再轮询直到成功或失败。
5. 当我的点数不足以支付本次调用时，系统拒绝调用并返回「点数不足，请先充值」，且不调用上游、不扣点。
6. 作为已登录用户，我在个人中心看到剩余点数、充值总额、充值记录和消费（调用）记录。
7. 作为运营，我在后台能管理用户与点数（手工调点带原因），配置某操作的点数单价，查看某用户的调用记录和点数流水。

五、验收标准（MVP）

每条 P0 功能对应可验证的判据：

• 生成标题 API：携带有效 API Key + 合法 prompt 调用，返回 200 且响应含标题文本；无效/缺失 Key 返回 401。
• 生成图片 API：旧同步接口携带有效 Key 调用，在超时上限内返回 200 且含图片 URL；异步接口提交后返回 task_id，轮询成功后返回稳定图片 URL。上游失败、超时或异步任务僵死时返回明确错误码，且不最终扣点（已扣则冲正）。
• 点数计费与扣减：调用前按规则算出点数 N；余额 ≥ N 才放行并精确扣 N；余额 < N 返回点数不足错误码且不调上游。并发同时多次调用，最终扣点总额正确，不出现超扣或扣成负数。
• 余额查询 API：返回的余额等于该账号点数流水累加结果。
• 充值转点数：模拟一次支付系统回调（含订单号、金额、签名），验签通过后按汇率加点；同一订单号重复回调只入账一次（幂等）；验签失败不入账。
• 调用记录 / 点数流水：每次成功/失败调用、每次充值/退款/调整/注册赠点都各生成一条记录，字段完整、可在后台检索。
• 用户注册/登录：新用户能自助注册（免邮箱验证、注册即可用；邮箱仍必填且唯一）、登录；注册成功后点数为 100，且有一条对应的注册赠点流水。重复提交或服务重试不得重复赠送。
• API Key 自助管理：登录用户能生成 API Key（明文只显示一次，库内存哈希）、能删除；删除落库为吊销，吊销后该 Key 调用返回 403，缺失/无效/不存在 Key 返回 401。
• 扫码充值：用户端发起充值→展示二维码→（mock 或真实）支付成功回调后点数按汇率到账，充值记录与流水各一条；同一订单号重复回调只入账一次。
• 个人中心：剩余点数 = 点数流水累加；充值总额、充值记录、消费记录与实际一致。
• 运营后台：运营能登录 django-admin，管理用户与点数（手工调点带原因写流水）、配置计费规则、检索并查看充值订单/流水/调用记录。
• 可插拔模型：运营在后台维护具体上游模型并配置「能力别名 → 模型」映射；调用方只用别名调用。改某别名的指向后，调用方无需改动即用上新模型；切换前后该别名的计费规则不变。

六、范围边界与决策

问题	决策
第一版形态	自助用户端（Django 模板 SSR + Bootstrap）+ 对外 HTTP API（DRF）+ Web 运营后台（django-admin），单体部署
是否需要账号	是。终端用户自助注册（Django auth / allauth）→ 自助生成 API Key；运营用 Django 后台账号
计费模型	预付费点数：充值时按汇率把金额转点数存本地，调用直接扣本地点数
余额是否实时查支付系统	否。本地点数余额为唯一权威账本，调用链路不查支付系统
生成返回方式	标题仍同步返回；图片旧同步接口保留兼容，新版客户端优先使用异步提交 / 轮询
模型选择方式	对外用能力别名（如 image-hd），不暴露具体模型名；后台配置别名→模型映射
充值入口	用户端自助发起扫码充值（本服务向支付系统下单取二维码），付款成功由支付系统服务端回调入账
注册是否送点数	是。新用户注册成功一次性赠送 100 点试用点数；只对功能上线后的新注册用户自动发放，历史用户是否补发需另行审批和单独任务
暂不支持	复杂活动赠点 / 邀请奖励、多币种、分账、自动退款对账；异步生图本期只做提交 / 轮询，不做 cancel、回调通知或 Celery/RQ

七、待确认 / 风险点

• 支付商户配置：协议字段、签名/验签方式、成功应答已明确；上线前仍需提供微信/支付宝真实商户密钥、证书、公网 notify_url。配置到位前，先以 mock 支付客户端开发和测试。
• 汇率与点数单价：1 元 = 多少点？标题/图片/各模型各分辨率分别多少点？由运营/产品确认，配置在后台。
• 资金风险：充值入账必须幂等防重复加点；扣点必须并发安全防超扣；上游失败必须不扣点或冲正。规则由产品确认，实现按 05-coding-rules.md 第 8 节。
• 注册赠点风险：注册送点虽然不来自支付回调，但仍是可消费点数，必须防重复发放、防并发重试重复入账，并配套注册限流 / 图形验证码等防刷手段。
• 凭证风险：上游 AI 的 api_key、支付系统密钥属敏感信息，只能放环境变量/后台配置，不入代码与文档样例。
• 第三方平台风险：上游 vectorengine 可能限流、超时、变更；需处理超时、错误透传与失败不扣点。
• 耗时风险：图片旧同步生成耗时长，需确认网关/反向代理/客户端超时上限；新版客户端应优先使用异步任务接口，避免连接中断导致结果丢失。异步任务必须通过租约 / reaper 处理 worker 崩溃，避免点数已扣但任务永远 running。
• 退款 / 纠纷：外部退款后本地点数如何冲正？MVP 不自动化，但数据结构需保留可冲正能力。
• 待确认决策：上述由谁、何时决策需明确，尤其商户配置交付时间与计费规则。