cmhub/docs/02-requirements.md

# 需求

> 本文只描述**要什么**与**怎么算达成**，用产品 / 用户语言表达，**不涉及技术实现**。
> 技术方案、数据结构、字段定义见 [架构设计](04-architecture.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（最小闭环）

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

### 后续迭代

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

## 四、核心用户故事（MVP）

1. 作为新用户，我在用户端自助注册登录后先获得 10 点试用点数；后续扫码充值一笔钱，看到对应点数按汇率到账。
2. 作为已登录用户，我自助生成一把 API Key（明文只显示一次），也能删除不用的 Key。
3. 作为接入方，我带着 API Key 调用生成标题接口，传入 prompt，能拿到生成的标题。
4. 作为接入方，我可以提交一张或多张图片生成商品图：第一张作为主商品图，后续图片仅作风格、构图、场景或排版参考；可调用旧同步接口在同一个响应里拿到图片结果，也可先提交异步图片任务拿到 `task_id` 再轮询直到成功或失败。
5. 作为接入方，我可以提交一张或多张商品图，让支持视觉理解的模型按输入顺序分析并返回文字；一次请求只按对应能力别名扣一次点数。
6. 当我的点数不足以支付本次调用时，系统拒绝调用并返回「点数不足，请先充值」，且不调用上游、不扣点。
7. 作为已登录用户，我在个人中心看到剩余点数、充值总额、充值记录和消费（调用）记录。
8. 作为运营，我在后台能管理用户与点数（手工调点带原因），配置某操作的点数单价，查看某用户的调用记录和点数流水。

## 五、验收标准（MVP）

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

- **生成标题 API**：携带有效 API Key + 合法 prompt 调用，返回 200 且响应含标题文本；无效/缺失 Key 返回 401。
- **生成图片 API**：同步与异步接口均可兼容旧单图字段，或使用 1–8 张有序图片；第一张为主商品图，后续图仅作参考。接口在超时上限内返回图片 URL / `task_id`；输入无效、超限、命中敏感词或 URL 不安全时不扣点。上游失败、超时或异步任务僵死时返回明确错误码，且**不最终扣点**（已扣则冲正）。
- **多图理解 API**：携带有效 Key、合法 prompt 和 1–8 张图片调用，返回 200 且响应含完整文字；图片顺序保持不变；输入无效、超限、命中敏感词或 URL 不安全时不扣点，上游失败时已扣点数只退一次。
- **点数计费与扣减**：调用前按规则算出点数 N；余额 ≥ N 才放行并精确扣 N；余额 < N 返回点数不足错误码且不调上游。并发同时多次调用，最终扣点总额正确，**不出现超扣或扣成负数**。
- **余额查询 API**：返回的余额等于该账号点数流水累加结果。
- **充值转点数**：模拟一次支付系统回调（含订单号、金额、签名），验签通过后按汇率加点；**同一订单号重复回调只入账一次**（幂等）；验签失败不入账。
- **调用记录 / 点数流水**：每次成功/失败调用、每次充值/退款/调整/注册赠点都各生成一条记录，字段完整、可在后台检索。
- **用户注册/登录**：新用户能自助注册（**免邮箱验证、注册即可用；邮箱仍必填且唯一**）、登录；注册成功后点数为 10，且有一条对应的注册赠点流水。重复提交或服务重试不得重复赠送。
- **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`），不暴露具体模型名；后台配置别名→模型映射 |
| 充值入口 | 用户端自助发起扫码充值（本服务向支付系统下单取二维码），付款成功由支付系统**服务端回调**入账 |
| 注册是否送点数 | 是。新用户注册成功一次性赠送 10 点试用点数；只对本次额度调整上线后的新注册用户自动发放，历史用户是否补发需另行审批和单独任务 |
| 暂不支持 | 复杂活动赠点 / 邀请奖励、多币种、分账、自动退款对账；异步生图本期只做提交 / 轮询，不做 cancel、回调通知或 Celery/RQ |

## 七、待确认 / 风险点

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