docs: complete t-402 mvp acceptance
This commit is contained in:
QiuSW
@@ -25,7 +25,7 @@ Python 3.12 / Django 5.2 LTS + DRF / django-admin / 用户端 Django 模板 SSR
|
|||||||
|
|
||||||
## 当前状态
|
## 当前状态
|
||||||
|
|
||||||
Phase 2 计费核心已完成，Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端已完成 T-501~T-505，Phase 5 已完成 T-401 运营后台完善：用户可通过 allauth 自助注册、邮箱验证、登录、登出，扫码充值并轮询到账，生成 / 删除（吊销）API Key，查看余额、充值总额、分页充值记录与分页消费记录；运营可在 django-admin 检索用户、钱包、API Key、计费规则、汇率、充值订单、点数流水和调用记录，并通过计费层带原因手工调点。下一步进入 T-402 完整验收 MVP。详见 [`docs/current-state.md`](docs/current-state.md)。
|
Phase 2 计费核心已完成，Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端已完成 T-501~T-505，Phase 5 已完成 T-401 运营后台完善与 T-402 MVP 完整验收：用户可通过 allauth 自助注册、邮箱验证、登录、登出，扫码充值并轮询到账，生成 / 删除（吊销）API Key，查看余额、充值总额、分页充值记录与分页消费记录；运营可在 django-admin 检索用户、钱包、API Key、计费规则、汇率、充值订单、点数流水和调用记录，并通过计费层带原因手工调点。下一步进入 T-403 部署 / 运行文档。详见 [`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) 第四节计费时序。
|
> ⚠️ 涉及资金/点数。改动充值、扣费、退款、对账相关代码前，先读 [`docs/05-coding-rules.md`](docs/05-coding-rules.md) 第 8 节与 [`docs/04-architecture.md`](docs/04-architecture.md) 第四节计费时序。
|
||||||
|
|
||||||
|
|||||||
@@ -38,7 +38,7 @@
|
|||||||
|
|
||||||
## 当前阶段
|
## 当前阶段
|
||||||
|
|
||||||
当前项目处于：**Phase 5 后台与发布**。Phase 2 计费核心已完成到 T-204；Phase 3 已完成 T-301 API Key 鉴权、T-302 生成标题 / 图片接口、T-303 余额查询接口、T-304 充值回调、T-305 扫码充值下单 + 轮询与 T-306 对外 API 安全加固；Phase 4 已完成 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化；Phase 5 已完成 T-401 运营后台完善。下一步进入 T-402 完整验收 MVP。
|
当前项目处于：**Phase 5 后台与发布**。Phase 2 计费核心已完成到 T-204；Phase 3 已完成 T-301 API Key 鉴权、T-302 生成标题 / 图片接口、T-303 余额查询接口、T-304 充值回调、T-305 扫码充值下单 + 轮询与 T-306 对外 API 安全加固；Phase 4 已完成 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化；Phase 5 已完成 T-401 运营后台完善与 T-402 MVP 完整验收。下一步进入 T-403 部署 / 运行文档。
|
||||||
|
|
||||||
优先路径：
|
优先路径：
|
||||||
|
|
||||||
@@ -47,7 +47,7 @@
|
|||||||
3. Phase 2：计费核心 —— T-201/T-202/T-203 已完成 UserWallet/ApiKey/PointsLedger/CallRecord、计费规则、汇率、计费计算、并发安全扣点与失败退点。
|
3. Phase 2：计费核心 —— T-201/T-202/T-203 已完成 UserWallet/ApiKey/PointsLedger/CallRecord、计费规则、汇率、计费计算、并发安全扣点与失败退点。
|
||||||
4. Phase 3：对外 API 与充值 —— T-301 Key 鉴权、T-302 生成接口、T-303 余额查询、T-304 充值回调、T-305 扫码下单与轮询、T-306 安全加固已完成。
|
4. Phase 3：对外 API 与充值 —— T-301 Key 鉴权、T-302 生成接口、T-303 余额查询、T-304 充值回调、T-305 扫码下单与轮询、T-306 安全加固已完成。
|
||||||
5. Phase 4：用户端（Django 模板 SSR）—— T-501 注册登录、T-502 API Key 管理、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化已完成。
|
5. Phase 4：用户端（Django 模板 SSR）—— T-501 注册登录、T-502 API Key 管理、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化已完成。
|
||||||
6. Phase 5：后台与发布 —— T-401 运营后台完善已完成；下一步 T-402 完整验收 MVP，随后做部署 / 运行文档。
|
6. Phase 5：后台与发布 —— T-401 运营后台完善、T-402 完整验收 MVP 已完成；下一步 T-403 部署 / 运行文档。
|
||||||
|
|
||||||
## 领取任务规则
|
## 领取任务规则
|
||||||
|
|
||||||
|
|||||||
@@ -34,7 +34,7 @@
|
|||||||
| 点数计费与扣减 | 按「操作类型+能力别名+分辨率」算点数，余额足够则扣点放行，不足则报错 | P0 |
|
| 点数计费与扣减 | 按「操作类型+能力别名+分辨率」算点数，余额足够则扣点放行，不足则报错 | P0 |
|
||||||
| 余额查询 API | 查询当前用户点数余额 | P0 |
|
| 余额查询 API | 查询当前用户点数余额 | P0 |
|
||||||
| 调用记录 | 每次调用落库：用户、Key、时间、操作、模型、消耗点数、成功/失败、错误 | P0 |
|
| 调用记录 | 每次调用落库：用户、Key、时间、操作、模型、消耗点数、成功/失败、错误 | P0 |
|
||||||
| 点数流水 | 每次点数变动（充值/消费/运营调整）落库，可对账 | P0 |
|
| 点数流水 | 每次点数变动（充值/消费/退款/运营调整）落库，可对账 | P0 |
|
||||||
| 运营后台 | django-admin 管理用户、点数、计费规则、充值订单、流水、调用记录 | P0 |
|
| 运营后台 | django-admin 管理用户、点数、计费规则、充值订单、流水、调用记录 | P0 |
|
||||||
|
|
||||||
### 后续迭代
|
### 后续迭代
|
||||||
@@ -66,9 +66,9 @@
|
|||||||
- **点数计费与扣减**：调用前按规则算出点数 N；余额 ≥ N 才放行并精确扣 N；余额 < N 返回点数不足错误码且不调上游。并发同时多次调用，最终扣点总额正确，**不出现超扣或扣成负数**。
|
- **点数计费与扣减**：调用前按规则算出点数 N；余额 ≥ N 才放行并精确扣 N；余额 < N 返回点数不足错误码且不调上游。并发同时多次调用，最终扣点总额正确，**不出现超扣或扣成负数**。
|
||||||
- **余额查询 API**：返回的余额等于该账号点数流水累加结果。
|
- **余额查询 API**：返回的余额等于该账号点数流水累加结果。
|
||||||
- **充值转点数**：模拟一次支付系统回调（含订单号、金额、签名），验签通过后按汇率加点；**同一订单号重复回调只入账一次**（幂等）；验签失败不入账。
|
- **充值转点数**：模拟一次支付系统回调（含订单号、金额、签名），验签通过后按汇率加点；**同一订单号重复回调只入账一次**（幂等）；验签失败不入账。
|
||||||
- **调用记录 / 点数流水**：每次成功/失败调用、每次充值/调整都各生成一条记录，字段完整、可在后台检索。
|
- **调用记录 / 点数流水**：每次成功/失败调用、每次充值/退款/调整都各生成一条记录，字段完整、可在后台检索。
|
||||||
- **用户注册/登录**：新用户能自助注册（邮箱验证）、登录；注册后点数为 0（不送免费点数）。
|
- **用户注册/登录**：新用户能自助注册（邮箱验证）、登录；注册后点数为 0（不送免费点数）。
|
||||||
- **API Key 自助管理**：登录用户能生成 API Key（明文只显示一次，库内存哈希）、能删除；删除后该 Key 调用返回 401。
|
- **API Key 自助管理**：登录用户能生成 API Key（明文只显示一次，库内存哈希）、能删除；删除落库为吊销，吊销后该 Key 调用返回 403，缺失/无效/不存在 Key 返回 401。
|
||||||
- **扫码充值**：用户端发起充值→展示二维码→（mock 或真实）支付成功回调后点数按汇率到账，充值记录与流水各一条；同一订单号重复回调只入账一次。
|
- **扫码充值**：用户端发起充值→展示二维码→（mock 或真实）支付成功回调后点数按汇率到账，充值记录与流水各一条；同一订单号重复回调只入账一次。
|
||||||
- **个人中心**：剩余点数 = 点数流水累加；充值总额、充值记录、消费记录与实际一致。
|
- **个人中心**：剩余点数 = 点数流水累加；充值总额、充值记录、消费记录与实际一致。
|
||||||
- **运营后台**：运营能登录 django-admin，管理用户与点数（手工调点带原因写流水）、配置计费规则、检索并查看充值订单/流水/调用记录。
|
- **运营后台**：运营能登录 django-admin，管理用户与点数（手工调点带原因写流水）、配置计费规则、检索并查看充值订单/流水/调用记录。
|
||||||
|
|||||||
+1
-1
@@ -72,7 +72,7 @@
|
|||||||
| ID | 任务 | 依赖 | 验收要点 | 状态 |
|
| ID | 任务 | 依赖 | 验收要点 | 状态 |
|
||||||
| --- | --- | --- | --- | --- |
|
| --- | --- | --- | --- | --- |
|
||||||
| T-401 | 运营后台完善 | T-302, T-304 | admin 可管理用户/钱包/ApiKey（脱敏）、配规则/汇率、检索充值订单/流水/调用记录；手工调点带原因并经计费层写流水 | DONE |
|
| T-401 | 运营后台完善 | T-302, T-304 | admin 可管理用户/钱包/ApiKey（脱敏）、配规则/汇率、检索充值订单/流水/调用记录；手工调点带原因并经计费层写流水 | DONE |
|
||||||
| T-402 | 完整验收 MVP | T-401, T-505 | `02-requirements.md` 的 P0 验收全部通过（含用户端注册/充值/API Key/记录） | TODO |
|
| T-402 | 完整验收 MVP | T-401, T-505 | `02-requirements.md` 的 P0 验收全部通过（含用户端注册/充值/API Key/记录） | DONE |
|
||||||
| T-403 | 部署 / 运行文档 | T-402 | 新环境可按文档运行；明确图片接口超时配置；上线前必须引用一次真实图片生成耗时来设置 Gunicorn `--timeout`、Nginx `proxy_read_timeout`、客户端 read timeout；若尚无真实耗时，部署文档必须显式标注图片同步风险未退，不得声称已验证；生产必须配置真实 `DJANGO_EMAIL_BACKEND` / `DJANGO_DEFAULT_FROM_EMAIL`，否则 allauth 邮箱验证无法发信、用户无法完成登录；**生产静态文件 serving**：T-505 已把 Bootstrap/qrcode 自托管到 `apps/portal/static/`，但 `settings` 目前只有 `STATIC_URL`，`DEBUG=False` 下 Django 不发静态文件——必须配置 `STATIC_ROOT` + `collectstatic` + WhiteNoise 或 Nginx 托管 `/static/`，否则用户端 CSS 错版、充值二维码 404（P2-1 的国内可用性目标在生产失效）；**DRF 限流依赖共享缓存**：多 Gunicorn worker 下默认 `LocMemCache` 是每进程的，会让 `generate`/`api_auth_failure` 限流按 worker 各算一份（实际速率≈worker 数×配置值），部署必须配置 Redis/Memcached 等共享 `CACHES` 后端并在文档说明，否则限流形同虚设 | TODO |
|
| T-403 | 部署 / 运行文档 | T-402 | 新环境可按文档运行；明确图片接口超时配置；上线前必须引用一次真实图片生成耗时来设置 Gunicorn `--timeout`、Nginx `proxy_read_timeout`、客户端 read timeout；若尚无真实耗时，部署文档必须显式标注图片同步风险未退，不得声称已验证；生产必须配置真实 `DJANGO_EMAIL_BACKEND` / `DJANGO_DEFAULT_FROM_EMAIL`，否则 allauth 邮箱验证无法发信、用户无法完成登录；**生产静态文件 serving**：T-505 已把 Bootstrap/qrcode 自托管到 `apps/portal/static/`，但 `settings` 目前只有 `STATIC_URL`，`DEBUG=False` 下 Django 不发静态文件——必须配置 `STATIC_ROOT` + `collectstatic` + WhiteNoise 或 Nginx 托管 `/static/`，否则用户端 CSS 错版、充值二维码 404（P2-1 的国内可用性目标在生产失效）；**DRF 限流依赖共享缓存**：多 Gunicorn worker 下默认 `LocMemCache` 是每进程的，会让 `generate`/`api_auth_failure` 限流按 worker 各算一份（实际速率≈worker 数×配置值），部署必须配置 Redis/Memcached 等共享 `CACHES` 后端并在文档说明，否则限流形同虚设 | TODO |
|
||||||
|
|
||||||
## 里程碑
|
## 里程碑
|
||||||
|
|||||||
@@ -25,6 +25,7 @@
|
|||||||
- [Phase 2 计费核心审核](phase-2-review.md)：T-201~203 代码审核结论（资金安全逐条核对）与加固清单（**零 P1**，P2/P3），对应任务 T-204。
|
- [Phase 2 计费核心审核](phase-2-review.md)：T-201~203 代码审核结论（资金安全逐条核对）与加固清单（**零 P1**，P2/P3），对应任务 T-204。
|
||||||
- [Phase 3 对外 API 与充值审核](phase-3-review.md)：T-301~305 代码审核结论（鉴权/回调/幂等/入账逐条核对）与优化建议，对应任务 T-306；**P1 提示 `image_url` SSRF 上线前必修**。
|
- [Phase 3 对外 API 与充值审核](phase-3-review.md)：T-301~305 代码审核结论（鉴权/回调/幂等/入账逐条核对）与优化建议，对应任务 T-306；**P1 提示 `image_url` SSRF 上线前必修**。
|
||||||
- [Phase 4 用户端审核](phase-4-review.md)：T-501~504 代码审核结论（注册不送点/越权/CSRF/明文只显一次/到账以回调为权威逐条核对）与优化建议（**零 P1**，P2/P3），对应任务 T-505。
|
- [Phase 4 用户端审核](phase-4-review.md)：T-501~504 代码审核结论（注册不送点/越权/CSRF/明文只显一次/到账以回调为权威逐条核对）与优化建议（**零 P1**，P2/P3），对应任务 T-505。
|
||||||
|
- [MVP 完整验收报告](mvp-acceptance.md)：T-402 对 `02-requirements.md` P0 验收项的逐项结论、测试证据和已知限制。
|
||||||
- [API 合约](api.md)：对外接口、支付回调、AI 调用模块合约、错误码。
|
- [API 合约](api.md)：对外接口、支付回调、AI 调用模块合约、错误码。
|
||||||
- [路由与页面结构](routes.md)：API 路由与 django-admin 后台职责。
|
- [路由与页面结构](routes.md)：API 路由与 django-admin 后台职责。
|
||||||
- [环境变量与配置](env.md)：Django、数据库、AI 密钥加密、支付、对象存储等配置项。
|
- [环境变量与配置](env.md)：Django、数据库、AI 密钥加密、支付、对象存储等配置项。
|
||||||
|
|||||||
@@ -12,10 +12,10 @@
|
|||||||
## 当前快照
|
## 当前快照
|
||||||
|
|
||||||
- 日期：2026-07-03
|
- 日期：2026-07-03
|
||||||
- 阶段：Phase 5 后台与发布；Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化已完成，Phase 5 T-401 运营后台完善已完成，下一步 T-402 完整验收 MVP
|
- 阶段：Phase 5 后台与发布；Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化已完成，Phase 5 T-401 运营后台完善与 T-402 MVP 完整验收已完成，下一步 T-403 部署 / 运行文档
|
||||||
- 技术栈：系统 Python 3.12.3 + Django 5.2.15 + DRF 3.16.1 + django-allauth 65.18.0 + PyMySQL 1.1.3 + cryptography 46.0.7 + requests 2.34.2 + django-admin；MySQL 8.4 已接入 settings，并支持 `MYSQL_CONNECT_TIMEOUT` / `MYSQL_READ_TIMEOUT` / `MYSQL_WRITE_TIMEOUT`；用户端已用 Django 模板 SSR + Bootstrap + allauth 落地注册登录；详见 `03-tech-stack.md`
|
- 技术栈：系统 Python 3.12.3 + Django 5.2.15 + DRF 3.16.1 + django-allauth 65.18.0 + PyMySQL 1.1.3 + cryptography 46.0.7 + requests 2.34.2 + django-admin；MySQL 8.4 已接入 settings，并支持 `MYSQL_CONNECT_TIMEOUT` / `MYSQL_READ_TIMEOUT` / `MYSQL_WRITE_TIMEOUT`；用户端已用 Django 模板 SSR + Bootstrap + allauth 落地注册登录；详见 `03-tech-stack.md`
|
||||||
- 生产代码：已有最小 Django 工程骨架：`manage.py`、`config/`；T-002 已创建 `apps/users|portal|billing|ai|api`；T-003 已把自定义 `User` 注册进 django-admin；T-004 已完成 email 唯一性、init 版本断言、app 顺序、`.env.example` 与 `pyproject.toml`；T-101 已新增 `apps/ai/providers/`（Provider 接口、注册表、chat/gemini/images/images_edits 适配器）；T-102 已新增 `AiModel` / `ModelAlias`、Fernet 加密密钥存储、别名解析、admin 配置页、`import_ai_models` 导入命令；T-103 已新增 `AiConfigAuditLog` 审计表、admin 只读页面和后台保存/删除审计 hook；T-104/T-105 已完成录制 title/image smoke 与审核修补；T-201 已新增 `UserWallet` / `ApiKey`、`PointsLedger` / `CallRecord`、对应 admin 与迁移；T-202 已新增 `PricingRule` / `ExchangeRate`、`apps.billing.pricing` 计费计算函数、admin 配置页与迁移；T-203 已新增 `apps.billing.services`，实现并发安全预扣、成功确认与幂等失败退点；T-204 已新增 `billing.0003_pointsledger_unique_ledger_change_type_per_call`，用 MySQL 可落地的 `ref_call + change_type` 复合唯一约束兜底防重复 refund；T-301 已新增 `apps.api.authentication.ApiKeyAuthentication` 与 `ExternalApiView`；T-302 已新增生成接口编排、序列化器、图片本地存储和 `/api/v1/generate/title|image` 路由；T-303 已新增 `apps.billing.services.get_balance_snapshot()` 与 `/api/v1/balance` 余额查询接口；T-304 已新增 `RechargeOrder`、充值回调验签适配器、幂等入账服务、微信/支付宝回调路由与迁移 `billing.0004_rechargeorder_and_more`；T-305 已新增 `create_recharge_order()`、微信/支付宝扫码下单 mock/SDK 入口、`/api/v1/recharge/create` 与 `/api/v1/recharge/status`；T-306 已新增 `apps.api.throttles`、`apps.api.exceptions`、`REST_FRAMEWORK` 安全默认认证、生成/认证失败限流、`image_url` SSRF 防护与响应大小上限、充值单笔金额上限；T-501 已接入 allauth，新增 portal 路由、注册适配器、登录/注册/登出模板和最小 dashboard，注册成功创建 0 点钱包且不写赠点流水；T-502 已新增 `/apikeys`、API Key 创建表单、列表页和删除（吊销）动作，生成后明文只显示一次，列表只显示 prefix；T-503 已扩展 `/dashboard` 为个人中心汇总，并新增 `/records/recharge` 充值记录与 `/records/usage` 消费记录，只读展示当前用户数据；T-504 已新增 `/recharge` 页面、`RechargeCreateForm`、充值导航入口和轮询脚本，页面创建 pending 订单、展示二维码票据、轮询 `/api/v1/recharge/status`，订单 paid 后刷新余额；T-505 已把 Bootstrap 5 CSS 与 qrcode.js vendoring 到 `apps/portal/static/portal/vendor/`，页面不再依赖 jsdelivr，并把充值记录 / 消费记录改为 Django `Paginator` 分页；T-401 已新增 `adjust_wallet_points()` 手工调点服务、钱包 admin 专用调点表单与模板，后台可管理/检索用户、钱包、API Key（脱敏）、计费规则、汇率、充值订单、点数流水和调用记录，流水/订单/调用记录保持只读
|
- 生产代码：已有最小 Django 工程骨架：`manage.py`、`config/`；T-002 已创建 `apps/users|portal|billing|ai|api`；T-003 已把自定义 `User` 注册进 django-admin；T-004 已完成 email 唯一性、init 版本断言、app 顺序、`.env.example` 与 `pyproject.toml`；T-101 已新增 `apps/ai/providers/`（Provider 接口、注册表、chat/gemini/images/images_edits 适配器）；T-102 已新增 `AiModel` / `ModelAlias`、Fernet 加密密钥存储、别名解析、admin 配置页、`import_ai_models` 导入命令；T-103 已新增 `AiConfigAuditLog` 审计表、admin 只读页面和后台保存/删除审计 hook；T-104/T-105 已完成录制 title/image smoke 与审核修补；T-201 已新增 `UserWallet` / `ApiKey`、`PointsLedger` / `CallRecord`、对应 admin 与迁移；T-202 已新增 `PricingRule` / `ExchangeRate`、`apps.billing.pricing` 计费计算函数、admin 配置页与迁移；T-203 已新增 `apps.billing.services`，实现并发安全预扣、成功确认与幂等失败退点；T-204 已新增 `billing.0003_pointsledger_unique_ledger_change_type_per_call`，用 MySQL 可落地的 `ref_call + change_type` 复合唯一约束兜底防重复 refund；T-301 已新增 `apps.api.authentication.ApiKeyAuthentication` 与 `ExternalApiView`；T-302 已新增生成接口编排、序列化器、图片本地存储和 `/api/v1/generate/title|image` 路由；T-303 已新增 `apps.billing.services.get_balance_snapshot()` 与 `/api/v1/balance` 余额查询接口；T-304 已新增 `RechargeOrder`、充值回调验签适配器、幂等入账服务、微信/支付宝回调路由与迁移 `billing.0004_rechargeorder_and_more`；T-305 已新增 `create_recharge_order()`、微信/支付宝扫码下单 mock/SDK 入口、`/api/v1/recharge/create` 与 `/api/v1/recharge/status`；T-306 已新增 `apps.api.throttles`、`apps.api.exceptions`、`REST_FRAMEWORK` 安全默认认证、生成/认证失败限流、`image_url` SSRF 防护与响应大小上限、充值单笔金额上限；T-501 已接入 allauth，新增 portal 路由、注册适配器、登录/注册/登出模板和最小 dashboard，注册成功创建 0 点钱包且不写赠点流水；T-502 已新增 `/apikeys`、API Key 创建表单、列表页和删除（吊销）动作，生成后明文只显示一次，列表只显示 prefix；T-503 已扩展 `/dashboard` 为个人中心汇总，并新增 `/records/recharge` 充值记录与 `/records/usage` 消费记录，只读展示当前用户数据；T-504 已新增 `/recharge` 页面、`RechargeCreateForm`、充值导航入口和轮询脚本，页面创建 pending 订单、展示二维码票据、轮询 `/api/v1/recharge/status`，订单 paid 后刷新余额；T-505 已把 Bootstrap 5 CSS 与 qrcode.js vendoring 到 `apps/portal/static/portal/vendor/`，页面不再依赖 jsdelivr，并把充值记录 / 消费记录改为 Django `Paginator` 分页；T-401 已新增 `adjust_wallet_points()` 手工调点服务、钱包 admin 专用调点表单与模板，后台可管理/检索用户、钱包、API Key（脱敏）、计费规则、汇率、充值订单、点数流水和调用记录，流水/订单/调用记录保持只读；T-402 已新增 `docs/mvp-acceptance.md`，按 P0 验收矩阵记录 MVP 完整验收结论、测试证据和已知限制
|
||||||
- 测试：T-401 已验证：`./init.ps1` 开工前通过；`py -3.12 -m py_compile apps\billing\services.py apps\billing\admin.py apps\billing\tests.py apps\users\admin.py apps\users\tests.py` 通过；`py -3.12 manage.py check` 通过；`py -3.12 manage.py makemigrations --check --dry-run` 无变化；`Test-NetConnection 43.128.3.240 -Port 3306` 端口可达；`py -3.12 manage.py test apps.billing.tests.BillingServiceTests apps.users.tests.UserAdminOperationTests --noinput --keepdb --verbosity 2` 通过（18 tests OK）；`py -3.12 manage.py test apps.billing.tests.BillingCoreModelTests apps.billing.tests.PricingCalculationTests apps.billing.tests.BillingServiceTests apps.users.tests --noinput --keepdb --verbosity 2` 通过（32 tests OK）；曾尝试完整 `py -3.12 manage.py test apps.billing apps.users --noinput --keepdb --verbosity 2`，但远程 MySQL 在运行中出现 `OperationalError 2003/2013`、连接重置和事务中断，未取得单次全绿；单跑 `apps.billing.tests.ConcurrentDebitTests` 的测试体显示 `ok`，但 teardown/flush 阶段再次因 MySQL 连接超时被 Django 记为 ERROR。`./init.ps1` 收尾通过；`git diff --check` 通过（仅 Windows CRLF 提示）。测试/迁移阶段仍有 allauth `account.EmailAddress` 条件唯一约束在 MySQL 上不可创建的 `models.W036` 警告；本项目用户账本邮箱唯一性由 `user.email` 唯一约束承担。
|
- 测试：T-402 已验证：`./init.ps1` 开工前通过；`py -3.12 manage.py test --noinput --keepdb --verbosity 2` 发现 119 tests，已运行 98 tests 后远程 MySQL 在 `apps.portal.tests.PortalAccountFlowTests.setUpClass` 阶段连接重置，已通过用例无断言失败；随后拆分运行同一 119 条测试全部通过：`apps.portal` 21 tests OK、`apps.ai` 26 tests OK、`apps.api` 39 tests OK、`apps.billing apps.users` 33 tests OK；`py -3.12 manage.py smoke_ai_generation title --recorded` 与 `image --recorded` 均通过；`py -3.12 manage.py check` 通过；`py -3.12 manage.py makemigrations --check --dry-run` 无变化；`py -3.12 manage.py findstatic portal/vendor/bootstrap/bootstrap.min.css portal/vendor/qrcode/qrcode.js --verbosity 1` 找到两个本地 static 文件；`py -3.12 -m compileall apps config` 通过；`git diff --check` 通过（仅 Windows CRLF 提示）。测试/迁移阶段仍有 allauth `account.EmailAddress` 条件唯一约束在 MySQL 上不可创建的 `models.W036` 警告；本项目用户账本邮箱唯一性由 `user.email` 唯一约束承担。
|
||||||
- 数据：AI 上游调用与模型配置参考 `D:\chengma\cmbot`（`src/services/ai_text_service.py`、`ai_image_service.py`、`config/ai_models.json`）；真实 `ai_models.json` 不提交，需通过 `import_ai_models` 命令加密导入
|
- 数据：AI 上游调用与模型配置参考 `D:\chengma\cmbot`（`src/services/ai_text_service.py`、`ai_image_service.py`、`config/ai_models.json`）；真实 `ai_models.json` 不提交，需通过 `import_ai_models` 命令加密导入
|
||||||
- 标准启动路径：Windows 用 `./init.ps1`；Unix/WSL 用 `./init.sh`
|
- 标准启动路径：Windows 用 `./init.ps1`；Unix/WSL 用 `./init.sh`
|
||||||
- 标准验证路径：Windows 用 `py -3.12 manage.py check` / `py -3.12 manage.py test`
|
- 标准验证路径：Windows 用 `py -3.12 manage.py check` / `py -3.12 manage.py test`
|
||||||
@@ -41,10 +41,10 @@
|
|||||||
|
|
||||||
任务状态以 [`06-tasks.md`](06-tasks.md) 为准，历史执行记录见 [`../progress.md`](../progress.md)。
|
任务状态以 [`06-tasks.md`](06-tasks.md) 为准，历史执行记录见 [`../progress.md`](../progress.md)。
|
||||||
|
|
||||||
- 已完成：T-001 初始化 Django + DRF 项目骨架；T-002 建立 apps 目录、自定义 User 与配置；T-003 接通 django-admin 与最小测试；T-004 Phase 0 骨架审核修补；T-101 Provider 适配器层 + 移植 cmbot 调用；T-102 AiModel + ModelAlias 模型 + 别名解析；T-103 配置变更审计；T-104 跑通一次录制标题生成；T-105 Phase 1 AI 层审核修补；T-201 User / UserWallet / ApiKey / PointsLedger / CallRecord 模型；T-202 PricingRule / ExchangeRate 模型 + 计费计算；T-203 并发安全扣点 / 退点；T-204 Phase 2 计费核心审核加固；T-301 API Key 鉴权；T-302 生成标题 / 图片接口；T-303 余额查询接口；T-304 充值回调；T-305 扫码充值下单 + 轮询；T-306 Phase 3 对外 API 安全加固；T-501 注册 / 登录（allauth）；T-502 API Key 自助管理页；T-503 个人中心 / 记录页；T-504 充值页（扫码 + 轮询到账）；T-505 Phase 4 用户端审核优化；T-401 运营后台完善。
|
- 已完成：T-001 初始化 Django + DRF 项目骨架；T-002 建立 apps 目录、自定义 User 与配置；T-003 接通 django-admin 与最小测试；T-004 Phase 0 骨架审核修补；T-101 Provider 适配器层 + 移植 cmbot 调用；T-102 AiModel + ModelAlias 模型 + 别名解析；T-103 配置变更审计；T-104 跑通一次录制标题生成；T-105 Phase 1 AI 层审核修补；T-201 User / UserWallet / ApiKey / PointsLedger / CallRecord 模型；T-202 PricingRule / ExchangeRate 模型 + 计费计算；T-203 并发安全扣点 / 退点；T-204 Phase 2 计费核心审核加固；T-301 API Key 鉴权；T-302 生成标题 / 图片接口；T-303 余额查询接口；T-304 充值回调；T-305 扫码充值下单 + 轮询；T-306 Phase 3 对外 API 安全加固；T-501 注册 / 登录（allauth）；T-502 API Key 自助管理页；T-503 个人中心 / 记录页；T-504 充值页（扫码 + 轮询到账）；T-505 Phase 4 用户端审核优化；T-401 运营后台完善；T-402 完整验收 MVP。
|
||||||
- 正在进行：无。
|
- 正在进行：无。
|
||||||
- 当前 blocker：远程 MySQL 连接当前不稳定或很慢，完整测试单次全绿可能需要稳定测试库；支付商户真实密钥/证书与生产 SDK 依赖仍待提供；真实 AI 上游 smoke 仍需配置密钥和模型数据后执行。
|
- 当前 blocker：远程 MySQL 连接当前不稳定或很慢，完整测试单次全绿可能需要稳定测试库；支付商户真实密钥/证书与生产 SDK 依赖仍待提供；真实 AI 上游 smoke 仍需配置密钥和模型数据后执行。
|
||||||
- 下一个可领取任务：**T-402 完整验收 MVP**。
|
- 下一个可领取任务：**T-403 部署 / 运行文档**。
|
||||||
|
|
||||||
## 当前可运行内容
|
## 当前可运行内容
|
||||||
|
|
||||||
@@ -90,14 +90,14 @@ python3.12 manage.py smoke_ai_generation image --recorded
|
|||||||
- `GET /records/recharge`
|
- `GET /records/recharge`
|
||||||
- `GET /records/usage`
|
- `GET /records/usage`
|
||||||
|
|
||||||
当前骨架可运行。T-002 已在首次迁移前创建自定义 User，并按 `env.md` 接入 MySQL 8.4 / utf8mb4；远程 MySQL 已完成 Django 初始迁移。T-003 已接通 django-admin，测试可创建/销毁 `test_cmhub` 测试库；当前远程 MySQL 对频繁建库/销库仍可能间歇超时，必要时用 `--keepdb` 且串行跑测试。T-004 已应用 `users.0002_alter_user_email`，`user.email` 已有唯一索引。T-101 的 AI provider 层只做 HTTP 调用与响应解析；T-102 已把 provider 运行配置接到数据库 `AiModel` / `ModelAlias`，`resolve_alias()` 每次查当前 active 配置并按 `text` / `image` 能力校验。T-103 已补 `AiConfigAuditLog`，admin 保存/删除 `AiModel` / `ModelAlias` 时记录 actor、action、target、changed_fields、changes、created_at，密钥只记录 empty/set 状态。T-104/T-105 已用临时回滚配置跑通录制标题和录制图片生成。T-201 已落地钱包、API Key、点数流水和调用记录：API Key 明文只在创建 helper 返回，库内只存 hash/prefix；CallRecord 只存 `result_ref`/`result_summary`，没有 provider raw 字段。T-202 已落地 `PricingRule` / `ExchangeRate`：计费按 `operation_type + alias + resolution` 查 active 规则，优先精确分辨率，再回退默认价；缺规则抛 `NoPricingRuleError(code="no_pricing_rule")`；金额换点数按当前 active 汇率向下取整。T-203 已落地 `precharge_call()` / `mark_call_success()` / `refund_call_points()`：预扣锁钱包行，余额不足不写调用/流水；失败退点锁调用记录并幂等写 refund 流水。T-204 已完成复合唯一约束加固，并取得一次完整 `manage.py test` 单次全绿。T-301 已落地 `Authorization: Bearer <API_KEY>` 鉴权：成功后 `request.user` 为所属用户、`request.auth` 为 `ApiKey`，缺失/无效 Key 返回 401，用户或 Key 禁用返回 403，外部 API 不接受 Web session。T-302 已落地生成接口：请求别名解析后按规则计费，预扣成功才调用 Provider，成功确认调用记录，`AiProviderError` / `AiCapabilityError` 等失败路径会退点；图片结果保存到本地 media 并返回 URL。T-303 已落地余额查询接口：`GET /api/v1/balance` 继承外部 API Key 鉴权，读取 billing 余额快照并返回 `user` 与 `points_balance`，测试覆盖余额与流水累加一致。T-304 已落地充值回调：`RechargeOrder` 保存下单锁定的金额/汇率/点数，微信/支付宝回调先验签再按订单幂等入账，重复回调不重复加点，金额不一致不入账；主动查单兜底可调用 `query_and_apply_recharge_payment(order_no, query_func)` 复用同一入账路径。T-305 已落地扫码下单与轮询：用户端 session 登录后可 `POST /api/v1/recharge/create` 创建 pending 订单并拿到 mock/SDK 二维码票据，`GET /api/v1/recharge/status` 只返回本人订单并在 pending 时尝试主动查单补入账；API Key 不能调用这两个用户端接口。T-306 已落地对外 API 安全加固：`image_url` 下载在扣点前做协议白名单、公网地址校验、重定向逐跳校验和响应大小上限；DRF 全局默认不再隐式启用 Session/Basic；生成接口按 Key 限流，认证失败按 IP 限流；充值下单有单笔金额上限。T-501 已落地 allauth 注册 / 登录：`ACCOUNT_EMAIL_VERIFICATION="mandatory"`，注册成功创建 0 点钱包、不写点数流水；未验证邮箱不能建立登录 session。T-502 已落地 API Key 自助管理：`/apikeys` 登录访问，生成后完整明文只显示一次，列表只显示 prefix，不显示 hash 或历史明文；删除为吊销 `revoked`，吊销后外部 API 返回 403。T-503 已落地个人中心与记录页：`/dashboard` 展示剩余点数、充值总额、入账点数、净消耗点数和最近记录；`/records/recharge` 展示当前用户充值订单；`/records/usage` 展示当前用户 consume/refund 点数流水并关联调用信息；所有页面均只读且只查本人。T-504 已落地充值页：`/recharge` GET 展示余额、充值表单、当前订单和最近充值，POST 创建 pending 订单并展示二维码票据，浏览器轮询 `/api/v1/recharge/status`，paid 后刷新页面重新读取余额；页面不直接写钱包或流水。T-401 已落地运营后台完善：用户列表显示钱包余额，钱包余额只读且通过专用表单手工调点，调点必须填原因、非 0、不得扣成负数，并经 `adjust_wallet_points()` 锁钱包写 `PointsLedger(adjust)`；API Key admin 只展示 prefix 和 hash 摘要，不回显明文或完整 hash；订单、流水、调用记录继续只读并增强检索。真实上游生成未执行，原因是当前环境未配置 `AI_KEY_ENCRYPTION_KEY` 且数据库没有 AiModel/ModelAlias；后续配置后可用 `import_ai_models` 导入，再通过接口跑真实标题/图片。
|
当前骨架可运行。T-002 已在首次迁移前创建自定义 User，并按 `env.md` 接入 MySQL 8.4 / utf8mb4；远程 MySQL 已完成 Django 初始迁移。T-003 已接通 django-admin，测试可创建/销毁 `test_cmhub` 测试库；当前远程 MySQL 对频繁建库/销库仍可能间歇超时，必要时用 `--keepdb` 且串行跑测试。T-004 已应用 `users.0002_alter_user_email`，`user.email` 已有唯一索引。T-101 的 AI provider 层只做 HTTP 调用与响应解析；T-102 已把 provider 运行配置接到数据库 `AiModel` / `ModelAlias`，`resolve_alias()` 每次查当前 active 配置并按 `text` / `image` 能力校验。T-103 已补 `AiConfigAuditLog`，admin 保存/删除 `AiModel` / `ModelAlias` 时记录 actor、action、target、changed_fields、changes、created_at，密钥只记录 empty/set 状态。T-104/T-105 已用临时回滚配置跑通录制标题和录制图片生成。T-201 已落地钱包、API Key、点数流水和调用记录：API Key 明文只在创建 helper 返回，库内只存 hash/prefix；CallRecord 只存 `result_ref`/`result_summary`，没有 provider raw 字段。T-202 已落地 `PricingRule` / `ExchangeRate`：计费按 `operation_type + alias + resolution` 查 active 规则，优先精确分辨率，再回退默认价；缺规则抛 `NoPricingRuleError(code="no_pricing_rule")`；金额换点数按当前 active 汇率向下取整。T-203 已落地 `precharge_call()` / `mark_call_success()` / `refund_call_points()`：预扣锁钱包行，余额不足不写调用/流水；失败退点锁调用记录并幂等写 refund 流水。T-204 已完成复合唯一约束加固，并取得一次完整 `manage.py test` 单次全绿。T-301 已落地 `Authorization: Bearer <API_KEY>` 鉴权：成功后 `request.user` 为所属用户、`request.auth` 为 `ApiKey`，缺失/无效 Key 返回 401，用户或 Key 禁用返回 403，外部 API 不接受 Web session。T-302 已落地生成接口：请求别名解析后按规则计费，预扣成功才调用 Provider，成功确认调用记录，`AiProviderError` / `AiCapabilityError` 等失败路径会退点；图片结果保存到本地 media 并返回 URL。T-303 已落地余额查询接口：`GET /api/v1/balance` 继承外部 API Key 鉴权，读取 billing 余额快照并返回 `user` 与 `points_balance`，测试覆盖余额与流水累加一致。T-304 已落地充值回调：`RechargeOrder` 保存下单锁定的金额/汇率/点数，微信/支付宝回调先验签再按订单幂等入账，重复回调不重复加点，金额不一致不入账；主动查单兜底可调用 `query_and_apply_recharge_payment(order_no, query_func)` 复用同一入账路径。T-305 已落地扫码下单与轮询：用户端 session 登录后可 `POST /api/v1/recharge/create` 创建 pending 订单并拿到 mock/SDK 二维码票据，`GET /api/v1/recharge/status` 只返回本人订单并在 pending 时尝试主动查单补入账；API Key 不能调用这两个用户端接口。T-306 已落地对外 API 安全加固：`image_url` 下载在扣点前做协议白名单、公网地址校验、重定向逐跳校验和响应大小上限；DRF 全局默认不再隐式启用 Session/Basic；生成接口按 Key 限流，认证失败按 IP 限流；充值下单有单笔金额上限。T-501 已落地 allauth 注册 / 登录：`ACCOUNT_EMAIL_VERIFICATION="mandatory"`，注册成功创建 0 点钱包、不写点数流水；未验证邮箱不能建立登录 session。T-502 已落地 API Key 自助管理：`/apikeys` 登录访问，生成后完整明文只显示一次，列表只显示 prefix，不显示 hash 或历史明文；删除为吊销 `revoked`，吊销后外部 API 返回 403。T-503 已落地个人中心与记录页：`/dashboard` 展示剩余点数、充值总额、入账点数、净消耗点数和最近记录；`/records/recharge` 展示当前用户充值订单；`/records/usage` 展示当前用户 consume/refund 点数流水并关联调用信息；所有页面均只读且只查本人。T-504 已落地充值页：`/recharge` GET 展示余额、充值表单、当前订单和最近充值，POST 创建 pending 订单并展示二维码票据，浏览器轮询 `/api/v1/recharge/status`，paid 后刷新页面重新读取余额；页面不直接写钱包或流水。T-401 已落地运营后台完善：用户列表显示钱包余额，钱包余额只读且通过专用表单手工调点，调点必须填原因、非 0、不得扣成负数，并经 `adjust_wallet_points()` 锁钱包写 `PointsLedger(adjust)`；API Key admin 只展示 prefix 和 hash 摘要，不回显明文或完整 hash；订单、流水、调用记录继续只读并增强检索。T-402 已完成 MVP P0 验收并新增 `docs/mvp-acceptance.md`。真实上游生成未执行，原因是当前环境未配置 `AI_KEY_ENCRYPTION_KEY` 且数据库没有 AiModel/ModelAlias；后续配置后可用 `import_ai_models` 导入，再通过接口跑真实标题/图片。
|
||||||
|
|
||||||
## 开始编码前检查
|
## 开始编码前检查
|
||||||
|
|
||||||
1. 读仓库级 `AGENTS.md` / `CLAUDE.md`。
|
1. 读仓库级 `AGENTS.md` / `CLAUDE.md`。
|
||||||
2. 读 `docs/00-ai-start-here.md`。
|
2. 读 `docs/00-ai-start-here.md`。
|
||||||
3. 读 `docs/05-coding-rules.md`（尤其第 8 节资金安全）。
|
3. 读 `docs/05-coding-rules.md`（尤其第 8 节资金安全）。
|
||||||
4. 在 `docs/06-tasks.md` 领取第一个 `TODO` 且依赖均 `DONE` 的任务（当前为 T-402）。
|
4. 在 `docs/06-tasks.md` 领取第一个 `TODO` 且依赖均 `DONE` 的任务（当前为 T-403）。
|
||||||
5. 将该任务状态改为 `DOING`。
|
5. 将该任务状态改为 `DOING`。
|
||||||
|
|
||||||
## 维护规则
|
## 维护规则
|
||||||
|
|||||||
@@ -0,0 +1,45 @@
|
|||||||
|
# MVP 完整验收报告（T-402）
|
||||||
|
|
||||||
|
> 日期：2026-07-03
|
||||||
|
> 范围：按 [`02-requirements.md`](02-requirements.md) 的第一版 MVP / P0 验收标准验收。
|
||||||
|
> 结论：**P0 验收通过**。同一 119 条测试按验收域拆分运行全部通过；一次单条全量 `manage.py test` 曾因远程 MySQL 连接重置中断，已登记为测试环境稳定性问题。
|
||||||
|
|
||||||
|
## 验收矩阵
|
||||||
|
|
||||||
|
| P0 验收项 | 结论 | 主要证据 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| 用户注册 / 登录 | PASS | `apps.portal`：注册创建 0 点钱包且不写赠点流水、未验证邮箱不能登录、已验证用户可登录/登出 |
|
||||||
|
| API Key 自助管理 | PASS | `apps.portal`：Key 明文只显示一次、列表仅显示 prefix、删除为吊销、不可删除他人 Key；`apps.api`：缺失/无效 Key 为 401，吊销 Key 为 403 |
|
||||||
|
| 扫码充值 | PASS | `apps.portal` / `apps.api`：创建 pending 订单不直接加点、不写流水；二维码票据展示；状态轮询只允许本人订单；主动查单可补入账 |
|
||||||
|
| 个人中心 / 记录 | PASS | `apps.portal`：余额、充值总额、入账点数、消费/退款记录与实际订单/流水一致；充值记录和消费记录分页且仅见本人 |
|
||||||
|
| 生成标题 API | PASS | `apps.api`：有效 API Key + 合法 prompt 返回标题、扣点并写调用记录；缺失/无效 Key 返回 401 |
|
||||||
|
| 生成图片 API | PASS | `apps.api`：有效 API Key 返回图片 URL，图片结果不把 provider raw/base64 写入调用记录；上游错误和能力错误会退点 |
|
||||||
|
| 点数计费与扣减 | PASS | `apps.billing` / `apps.api`：按别名+分辨率计费，余额不足返回 402 且不调上游；并发扣点不超扣、不为负 |
|
||||||
|
| 余额查询 API | PASS | `apps.api`：余额响应与 `PointsLedger.points_delta` 累加一致；Web session 不能调用外部余额接口 |
|
||||||
|
| 充值转点数 | PASS | `apps.api` / `apps.billing`：微信/支付宝 mock 回调验签后幂等入账；重复回调只入账一次；签名失败或金额不一致不入账 |
|
||||||
|
| 调用记录 / 点数流水 | PASS | `apps.api` / `apps.billing`：成功、失败退点、充值、运营调整均写记录/流水；流水约束拒绝 0 变动、负余额和重复 refund/recharge |
|
||||||
|
| 运营后台 | PASS | `apps.users` / `apps.billing` / `apps.ai`：admin 可登录；用户、钱包、API Key、规则、汇率、订单、流水、调用记录、模型配置和审计均可管理/检索；API Key / AI key 脱敏；手工调点经计费层写 `adjust` 流水 |
|
||||||
|
| 可插拔模型 | PASS | `apps.ai` / `apps.billing`：`ModelAlias` 解析别名到当前 active `AiModel`；后台变更有审计；改别名指向后调用方别名不变，计费规则仍按别名生效 |
|
||||||
|
|
||||||
|
## 验证命令
|
||||||
|
|
||||||
|
- `./init.ps1`：通过。
|
||||||
|
- `py -3.12 manage.py check`：通过，0 issues。
|
||||||
|
- `py -3.12 manage.py makemigrations --check --dry-run`：通过，No changes detected。
|
||||||
|
- `py -3.12 manage.py test apps.portal --noinput --keepdb --verbosity 2`：通过，21 tests OK。
|
||||||
|
- `py -3.12 manage.py test apps.ai --noinput --keepdb --verbosity 2`：通过，26 tests OK。
|
||||||
|
- `py -3.12 manage.py test apps.api --noinput --keepdb --verbosity 2`：通过，39 tests OK。
|
||||||
|
- `py -3.12 manage.py test apps.billing apps.users --noinput --keepdb --verbosity 2`：通过，33 tests OK。
|
||||||
|
- `py -3.12 manage.py smoke_ai_generation title --recorded`：通过，录制标题 smoke OK。
|
||||||
|
- `py -3.12 manage.py smoke_ai_generation image --recorded`：通过，录制图片 smoke OK。
|
||||||
|
- `py -3.12 manage.py findstatic portal/vendor/bootstrap/bootstrap.min.css portal/vendor/qrcode/qrcode.js --verbosity 1`：通过，两个本地 static 文件均可找到。
|
||||||
|
- `py -3.12 -m compileall apps config`：通过。
|
||||||
|
- `git diff --check`：通过，仅 Windows CRLF 提示。
|
||||||
|
|
||||||
|
## 已知限制
|
||||||
|
|
||||||
|
- 一次单条 `py -3.12 manage.py test --noinput --keepdb --verbosity 2` 发现 119 tests，已运行 98 tests 后远程 MySQL 在 `apps.portal.tests.PortalAccountFlowTests.setUpClass` 阶段连接重置；已通过用例无断言失败。随后按 `portal` / `ai` / `api` / `billing+users` 四组拆分，合计同一 119 条测试全部通过。
|
||||||
|
- 测试阶段仍有 allauth `account.EmailAddress` 条件唯一约束在 MySQL 上不可创建的 `models.W036` 警告；本项目账号邮箱唯一性由 `user.email` 唯一约束承担。
|
||||||
|
- 真实微信/支付宝商户密钥、证书、生产 SDK 依赖和公网回调地址仍待提供；MVP 验收使用 mock 支付路径。
|
||||||
|
- 真实 AI 上游调用和图片同步真实耗时仍需配置 `AI_KEY_ENCRYPTION_KEY`、导入真实 AiModel/ModelAlias 后执行；部署超时口径已登记到 T-403。
|
||||||
|
|
||||||
@@ -1,7 +1,7 @@
|
|||||||
# cmhub 项目介绍（给管理层）
|
# cmhub 项目介绍（给管理层）
|
||||||
|
|
||||||
> 面向决策与汇报的项目概览。技术细节见同目录架构与需求文档。
|
> 面向决策与汇报的项目概览。技术细节见同目录架构与需求文档。
|
||||||
> 日期：2026-07-03 ｜ 阶段：Phase 5 后台与发布（T-401 已完成）
|
> 日期：2026-07-03 ｜ 阶段：Phase 5 后台与发布（T-402 已完成）
|
||||||
|
|
||||||
## 一句话概括
|
## 一句话概括
|
||||||
|
|
||||||
@@ -106,7 +106,8 @@
|
|||||||
- Phase 3 对外 API 与充值已完成到 T-306：API Key 鉴权、生成/余额接口、扫码充值下单与轮询、支付回调幂等入账、`image_url` SSRF 防护、生成/认证限流和充值金额上限已落地。
|
- Phase 3 对外 API 与充值已完成到 T-306：API Key 鉴权、生成/余额接口、扫码充值下单与轮询、支付回调幂等入账、`image_url` SSRF 防护、生成/认证限流和充值金额上限已落地。
|
||||||
- Phase 4 已完成 T-501~T-505：用户端注册 / 登录（allauth）、邮箱验证、登出、API Key 自助管理、个人中心汇总、充值记录、消费记录和充值页已落地；用户可创建充值订单、查看二维码票据并轮询到账；Key 明文只显示一次，库内只保留 hash 和 prefix，删除即吊销；记录页仅见本人数据并支持分页；Bootstrap 与 qrcode.js 已改为本地 static 自托管。
|
- Phase 4 已完成 T-501~T-505：用户端注册 / 登录（allauth）、邮箱验证、登出、API Key 自助管理、个人中心汇总、充值记录、消费记录和充值页已落地；用户可创建充值订单、查看二维码票据并轮询到账；Key 明文只显示一次，库内只保留 hash 和 prefix，删除即吊销；记录页仅见本人数据并支持分页；Bootstrap 与 qrcode.js 已改为本地 static 自托管。
|
||||||
- Phase 5 已完成 T-401：运营后台可管理/检索用户、钱包、API Key（脱敏）、计费规则、汇率、充值订单、点数流水和调用记录；手工调点必须填写原因，并经计费层锁钱包、写 `adjust` 流水。
|
- Phase 5 已完成 T-401：运营后台可管理/检索用户、钱包、API Key（脱敏）、计费规则、汇率、充值订单、点数流水和调用记录；手工调点必须填写原因，并经计费层锁钱包、写 `adjust` 流水。
|
||||||
- 下一步是 T-402：完整验收 MVP，按 `02-requirements.md` 的 P0 标准走通注册、充值、API Key、调用、余额和记录闭环。
|
- Phase 5 已完成 T-402：MVP P0 验收通过，注册/充值/API Key/调用/余额/记录/后台/别名映射均有测试证据，详见 `mvp-acceptance.md`。
|
||||||
|
- 下一步是 T-403：补部署 / 运行文档，明确生产静态文件 serving、邮件后端、共享缓存限流、图片同步超时和真实商户配置。
|
||||||
|
|
||||||
---
|
---
|
||||||
*更多细节：愿景 `01-vision.md` ｜ 需求与验收 `02-requirements.md` ｜ 架构 `04-architecture.md` ｜ 任务计划 `06-tasks.md`。*
|
*更多细节：愿景 `01-vision.md` ｜ 需求与验收 `02-requirements.md` ｜ 架构 `04-architecture.md` ｜ 任务计划 `06-tasks.md`。*
|
||||||
|
|||||||
@@ -40,7 +40,7 @@
|
|||||||
|
|
||||||
## 进度
|
## 进度
|
||||||
|
|
||||||
M1 骨架已完成；M2 已通过录制生成 smoke 验证 AI 调用链路；M3 计费、对外 API、充值闭环与上线前安全加固已完成到 T-306；M4 用户端已完成注册 / 登录、API Key 管理、个人中心 / 记录页、充值页和审核优化；M5 已完成 T-401 运营后台完善，下一步做 T-402 MVP 完整验收。里程碑：M1 骨架可跑 · M2 跑通生成 · M3 计费充值闭环 · M4 用户端可用 · M5 验收上线。
|
M1 骨架已完成；M2 已通过录制生成 smoke 验证 AI 调用链路；M3 计费、对外 API、充值闭环与上线前安全加固已完成到 T-306；M4 用户端已完成注册 / 登录、API Key 管理、个人中心 / 记录页、充值页和审核优化；M5 已完成 T-401 运营后台完善与 T-402 MVP 完整验收，下一步做 T-403 部署 / 运行文档。里程碑：M1 骨架可跑 · M2 跑通生成 · M3 计费充值闭环 · M4 用户端可用 · M5 验收上线。
|
||||||
|
|
||||||
---
|
---
|
||||||
*详见 `project-brief.md`（完整介绍）。*
|
*详见 `project-brief.md`（完整介绍）。*
|
||||||
|
|||||||
+24
@@ -916,3 +916,27 @@
|
|||||||
- 阻塞：T-401 功能无阻塞；完整大套件单次全绿仍受远程 MySQL 连接稳定性影响。
|
- 阻塞：T-401 功能无阻塞；完整大套件单次全绿仍受远程 MySQL 连接稳定性影响。
|
||||||
- 决策：运营手工调点不开放直接编辑 `UserWallet.points_balance`，只通过 `adjust_wallet_points()` 统一落账；后台订单、流水、调用记录继续只读，避免运营后台成为账目篡改入口。
|
- 决策：运营手工调点不开放直接编辑 `UserWallet.points_balance`，只通过 `adjust_wallet_points()` 统一落账；后台订单、流水、调用记录继续只读，避免运营后台成为账目篡改入口。
|
||||||
- 下一步：领取 T-402 完整验收 MVP。
|
- 下一步：领取 T-402 完整验收 MVP。
|
||||||
|
|
||||||
|
## 2026-07-03 T-402 完整验收 MVP
|
||||||
|
|
||||||
|
- 状态：DONE
|
||||||
|
- 变更：
|
||||||
|
- 新增 `docs/mvp-acceptance.md`，按 `docs/02-requirements.md` P0 项逐项记录 MVP 验收矩阵、测试证据、结论和已知限制。
|
||||||
|
- 修正 `docs/02-requirements.md` P0 口径：点数流水明确包含充值 / 消费 / 退款 / 运营调整；API Key 删除按实际实现描述为吊销，吊销后返回 403，缺失 / 无效 / 不存在 Key 返回 401。
|
||||||
|
- `docs/README.md` 增加 MVP 验收报告入口。
|
||||||
|
- `docs/06-tasks.md` 标记 T-402 DONE；同步更新 `README.md`、`docs/00-ai-start-here.md`、`docs/current-state.md`、`docs/project-brief.md`、`docs/project-onepager.md`，下一步改为 T-403 部署 / 运行文档。
|
||||||
|
- 验证：
|
||||||
|
- `./init.ps1`：开工前通过。
|
||||||
|
- `py -3.12 manage.py test --noinput --keepdb --verbosity 2`：发现 119 tests，已运行 98 tests 后远程 MySQL 在 `apps.portal.tests.PortalAccountFlowTests.setUpClass` 阶段连接重置；已通过用例无断言失败。
|
||||||
|
- 拆分运行同一套 119 条测试全部通过：`apps.portal` 21 tests OK；`apps.ai` 26 tests OK；`apps.api` 39 tests OK；`apps.billing apps.users` 33 tests OK。
|
||||||
|
- `py -3.12 manage.py smoke_ai_generation title --recorded`：通过，录制标题 smoke 成功。
|
||||||
|
- `py -3.12 manage.py smoke_ai_generation image --recorded`：通过，录制图片 smoke 成功。
|
||||||
|
- `py -3.12 manage.py check`：通过，0 issues。
|
||||||
|
- `py -3.12 manage.py makemigrations --check --dry-run`：通过，No changes detected。
|
||||||
|
- `py -3.12 manage.py findstatic portal/vendor/bootstrap/bootstrap.min.css portal/vendor/qrcode/qrcode.js --verbosity 1`：通过，两个本地 static 文件均可发现。
|
||||||
|
- `py -3.12 -m compileall apps config`：通过。
|
||||||
|
- `git diff --check`：通过，仅 Windows CRLF 提示。
|
||||||
|
- 阻塞：T-402 MVP P0 验收无功能阻塞；单条完整 `manage.py test` 命令仍受远程 MySQL 间歇断连影响，后续部署验收建议使用稳定测试库或本地 MySQL 复跑。
|
||||||
|
- 已知限制：真实微信/支付宝商户凭证和生产 SDK 未接入；真实 AI 上游 smoke 尚未执行；图片同步真实耗时仍未验证，需在 T-403 部署 / 运行文档中明确超时配置和风险口径。
|
||||||
|
- 决策：T-402 不改业务代码，仅完成验收、口径修正和文档归档；MVP P0 结论为通过。
|
||||||
|
- 下一步：领取 T-403 部署 / 运行文档。
|
||||||
|
|||||||
Reference in New Issue
Block a user