106 lines
10 KiB
Markdown
106 lines
10 KiB
Markdown
# 需求
|
||
|
||
> 本文只描述**要什么**与**怎么算达成**，用产品 / 用户语言表达，**不涉及技术实现**。
|
||
> 技术方案、数据结构、字段定义见 [架构设计](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（最小闭环）
|
||
|
||
| 功能 | 用户能做什么 | 优先级 |
|
||
| --- | --- | --- |
|
||
| 用户注册/登录 | 终端用户在用户端自助注册、登录（**免邮箱验证、注册即可用；邮箱仍必填且唯一**）；注册成功一次性赠送 **100 点**试用点数 | P0 |
|
||
| API Key 自助管理 | 登录后自助生成/删除 API Key；Key 只在生成时显示一次（库内哈希存储） | P0 |
|
||
| 扫码充值 | 用户端发起充值→展示支付二维码→扫码付款→回调到账；金额按汇率转点数 | P0 |
|
||
| 个人中心 | 查看剩余点数、充值总额、充值记录、点数使用（消费）记录 | P0 |
|
||
| 生成标题 API | 带 API Key + prompt（+可选商品图）调用，拿到标题文字 | P0 |
|
||
| 生成图片 API | 带 API Key + prompt + 图 + 模型/分辨率调用，**同步**拿到生成图片 | 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. 作为接入方，我调用生成图片接口，等待若干秒后在同一个响应里拿到图片结果。
|
||
5. 当我的点数不足以支付本次调用时，系统拒绝调用并返回「点数不足，请先充值」，且不调用上游、不扣点。
|
||
6. 作为已登录用户，我在个人中心看到剩余点数、充值总额、充值记录和消费（调用）记录。
|
||
7. 作为运营，我在后台能管理用户与点数（手工调点带原因），配置某操作的点数单价，查看某用户的调用记录和点数流水。
|
||
|
||
## 五、验收标准（MVP）
|
||
|
||
每条 P0 功能对应可验证的判据：
|
||
|
||
- **生成标题 API**：携带有效 API Key + 合法 prompt 调用，返回 200 且响应含标题文本；无效/缺失 Key 返回 401。
|
||
- **生成图片 API**：携带有效 Key 调用，在超时上限内返回 200 且含图片（URL 或 base64）；上游失败时返回明确错误码，且**不扣点**（已扣则冲正）。
|
||
- **点数计费与扣减**：调用前按规则算出点数 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 后台账号 |
|
||
| 计费模型 | **预付费点数**：充值时按汇率把金额转点数存本地，调用直接扣本地点数 |
|
||
| 余额是否实时查支付系统 | 否。本地点数余额为唯一权威账本，调用链路不查支付系统 |
|
||
| 生成返回方式 | **同步**等待返回结果（图片接口需把网关/服务超时调到 ≥ 300s） |
|
||
| 模型选择方式 | 对外用**能力别名**（如 `image-hd`），不暴露具体模型名；后台配置别名→模型映射 |
|
||
| 充值入口 | 用户端自助发起扫码充值（本服务向支付系统下单取二维码），付款成功由支付系统**服务端回调**入账 |
|
||
| 注册是否送点数 | 是。新用户注册成功一次性赠送 100 点试用点数；只对功能上线后的新注册用户自动发放，历史用户是否补发需另行审批和单独任务 |
|
||
| 暂不支持 | 异步队列、复杂活动赠点 / 邀请奖励、多币种、分账、自动退款对账 |
|
||
|
||
## 七、待确认 / 风险点
|
||
|
||
- **支付商户配置**：协议字段、签名/验签方式、成功应答已明确；上线前仍需提供微信/支付宝真实商户密钥、证书、公网 `notify_url`。配置到位前，先以 mock 支付客户端开发和测试。
|
||
- **汇率与点数单价**：1 元 = 多少点？标题/图片/各模型各分辨率分别多少点？由运营/产品确认，配置在后台。
|
||
- **资金风险**：充值入账必须幂等防重复加点；扣点必须并发安全防超扣；上游失败必须不扣点或冲正。规则由产品确认，实现按 `05-coding-rules.md` 第 8 节。
|
||
- **注册赠点风险**：注册送点虽然不来自支付回调，但仍是可消费点数，必须防重复发放、防并发重试重复入账，并配套注册限流 / 图形验证码等防刷手段。
|
||
- **凭证风险**：上游 AI 的 api_key、支付系统密钥属敏感信息，只能放环境变量/后台配置，不入代码与文档样例。
|
||
- **第三方平台风险**：上游 vectorengine 可能限流、超时、变更；需处理超时、错误透传与失败不扣点。
|
||
- **耗时风险**：图片同步生成耗时长，需确认网关/反向代理/客户端超时上限，避免连接中断导致已扣点但结果丢失。
|
||
- **退款 / 纠纷**：外部退款后本地点数如何冲正？MVP 不自动化，但数据结构需保留可冲正能力。
|
||
- **待确认决策**：上述由谁、何时决策需明确，尤其商户配置交付时间与计费规则。
|