Backend 测试需求¶

需求 ID 前缀 BE-REQ。验收采用 Given-When-Then。用例矩阵见 test-matrix.md。

角色¶

ID	描述	验收
BE-REQ-001	Admin 短信登录	Given 有效 admin_users；When send-sms+正确码 login；Then 返回 token 且可访问 `/api/admin/users`
BE-REQ-002	Admin 非管理员拒绝	Given 仅 users 无 admin_users；When admin login；Then 失败且无 token
BE-REQ-003	用户短信登录	Given 手机号；When send-code+login；Then 返回 User JWT，`/api/auth/me` 成功
BE-REQ-004	as_agent 开通	Given 无 agents 行；When login `as_agent=true`；Then 创建 agents 且可访问 `/api/agents/me`
BE-REQ-005	禁用用户拦截	Given `users.status=0`；When 调需 CurrentUser 接口；Then 401/业务错误

ID	描述	验收
BE-REQ-010	大类子类 CRUD	Admin 创建→查询→更新→删除；DB 一致；C 端 catalog 可见启用项
BE-REQ-011	子类面料关联	批量关联后 `GET .../fabric-materials` 返回正确集合（虚拟影棚等仍用）
BE-REQ-012	主图/详情模板 match（品类×风格）	Given 模板 `product_category_ids`∋category 且 `style_ids`∋style；When `match`/`list` 传 `product_category_id`+`style_id`；Then 命中对应主图/详情模板（同风格可多套；match 返回首条，list 返回全量摘要）
BE-REQ-012b	模板风格 CRUD	Admin 在品类下创建/更新/停用 `product_styles`；C 端 `GET /user/catalog/styles?category_id=` 仅见启用项
BE-REQ-013	Word 上传（主图/详情风格链路）	上传合法 docx 并指定 `product_category_id`+`style_id`（可选 `image_template_id`）；Then word_sessions/items 有记录且图片可入对应模板套

ID	描述	验收
BE-REQ-020	模型池成员调度配置	Admin 加成员设 weight/priority；health 接口可查
BE-REQ-021	用户生图扣费	Given 配额充足；When generate 成功；Then used 增加且有 consumption_records
BE-REQ-022	配额不足拒绝	Given used≥total；When generate；Then 明确错误且不写成功任务扣费
BE-REQ-023	并发上限	Given concurrent_tasks=1 且有处理中任务；When 再 generate；Then 拒绝或排队策略符合实现

ID	描述	验收
BE-REQ-030	项目乐观锁	Given revision=0；When PUT expectedRevision=0；Then revision=1；再 PUT expected=0 → 409
BE-REQ-031	项目隔离	UserA 不可读写 UserB 的 project_id
BE-REQ-032	删文件夹	删除 folder；项目 folder_id 变 NULL，项目未删

ID	描述	验收
BE-REQ-040	下单支付 mock	创建订单 → mock-pay → status paid；配额/订阅按方案更新
BE-REQ-041	落地绑客	未绑定用户 bind 成功；再次 bind 其他代理失败；customer_agent_bindings 唯一
BE-REQ-042	优惠比例	Agent 设置 customer_discount_rate=10；客户下单金额按规则打折（对照实现）
BE-REQ-043	分账生成	绑定客户支付成功后产生 commission_records（pending）
BE-REQ-044	提现审批	Agent 提现 pending → Admin approve → balance 与 withdrawn 正确；reject 回滚预占
BE-REQ-045	退款	Admin refund 后订单 refunded，配额/佣金按实现回滚或 clawback

ID	描述	验收要点
BE-REQ-050	结算扫码	创建 scan token → mock-confirm → settlement_account 写入
BE-REQ-051	导出 Excel	Agent JWT 导出 customers 等返回可解析 xlsx
BE-REQ-052	操作日志	Admin PUT 写资源后 operation_logs 有记录
BE-REQ-053	Prompt 测试记录	test-generate 后 prompt_test_runs 可查
BE-REQ-054	resolve-urls	过期 object_key 可重新签发可访问 URL
BE-REQ-055	批量生图	batch-generate 创建 job；可查状态；单项 retry
BE-REQ-055b	主图/详情批量生图（品类×风格）	Given 配额充足且已选品类/风格/模板套；When `batch-generate` `task_type=main_image\\|detail_image`，params 含 `product_category_id`+`style_id`+`image_template_id`+`mode(auto\\|copy)`+`custom_product`/`custom_material`（复刻另需 reference）；Then 创建 job、扣积分、入队；缺必填槽 → 400 中文错误
BE-REQ-058	爆款模板目录	Given 子类下有启用 HotStyle；When `GET /api/user/catalog/hot-styles?product_sub_type_id=`；Then 返回款式列表含 category_id；When 详情；Then 含模板图摘要
BE-REQ-059	爆款模板批量生图	Given 款式有模板图；When `batch-generate` `task_type=hot_template` 且无 fabric；Then 创建 task+job、按图数扣积分、入队 Redis；Worker 落图占容；可查进度与 retry

ID	描述	验收（Given-When-Then）
BE-REQ-046	储存限容-上传占容	Given 会员 storage_gb=5；When 上传使 used+size>total；Then 返回 400「存储空间不足」；When 删除资产；Then used 减回
BE-REQ-047	储存限容-生成图占容	Given Worker 生图成功；When 落 OSS；Then `usage_quotas(storage).used += size` 且 `generation_result.image_object_keys` 写入；When 软删任务；Then used 按 image_sizes 释放
BE-REQ-048	L1/L2 分账	Given 一级设 `sub_agent_share_rate=30` 且已提拔二级；When 二级客户成交；Then 二级得规则佣金 + 一级佣金池×30%；一级得池×70%
BE-REQ-049	月结关账幂等	Given 某月已关账；When 重复 close 同月；Then `balance_commission` 不变（幂等键拦截）
BE-REQ-050b	日终对账	When `recon/run`；Then 生成 recon_batches；When `replay/user` 传手机号；Then 该户账本重算并修复余额
BE-REQ-051b	登录积分	Given 今日未领取；When claim；Then 积分入账 + 标记已领；When 再次 claim；Then 拒绝
BE-REQ-056	储存用量查询	When `GET /api/billing/storage`；Then 返回 `{storage_gb, total_bytes, used_bytes, remaining_bytes}`
BE-REQ-057	订阅激活同步上限	When mark_paid 激活订阅；Then `usage_quotas(storage).total` = 方案 storage_gb×1024³（used 不重置）

ID	描述	验收
BE-REQ-060	响应包络	成功 code=200；业务错误非 200 且 data 为空或约定结构
BE-REQ-061	CORS	允许配置的 Vite 源与 `*.localhost`
BE-REQ-062	密钥隔离	backend 进程环境无 OSS AK；仅 STORAGE_SERVICE_URL
BE-REQ-063	幂等支付回调	同一 transaction_id 重复 notify 不重复加配额
BE-REQ-064	健康检查	`/health/live` `/health/ready`（若挂载）可用