# DoTouch.AI 功能清单与验收标准（Acceptance Matrix）

> 版本：v1.0 ｜ 日期：2026-08-08
> 用途：独立测试 Agent 按此清单逐项验收；结果记录于 `test-run-log.md`
> 测试环境：本地 docker（PG16/Redis7）+ mock 上游 :19090 + API :8080
> 测试账号：`test-e2e@dotouch.ai/Test1234`（admin，余额 $108.80）｜ `demo.user@dotouch.ai/User2026!`（user，$50）｜ `admin@dotouch.ai/Admin2026!`（admin）

---

## 一、认证与账号（F-01 ~ F-03）

### F-01 注册 + 邮箱验证码
| # | 步骤 | 验收标准 |
|---|---|---|
| 1.1 | POST /v1/auth/send-code {email, purpose:register} | 201 |
| 1.2 | 日志读验证码 | 8 位 `[A-Z0-9]` |
| 1.3 | 错误验证码注册 | 400 验证码错误 |
| 1.4 | 正确验证码注册 | 201 创建用户 |
| 1.5 | 同邮箱重复注册 | 409 |
| 1.6 | send-code 60 秒内重复 | 429 冷却 |

### F-02 登录与密码策略
| # | 步骤 | 验收标准 |
|---|---|---|
| 2.1 | 正确密码登录 | 200 + JWT（含 role） |
| 2.2 | 错误密码 ×5 | 401 ×5 |
| 2.3 | 第 6 次 | 429（约 15 分钟） |
| 2.4 | 弱密码（<8 位/无数字）注册 | 400 |
| 2.5 | GET /v1/auth/me | 200 email/role |

### F-03 密码重置
| # | 步骤 | 验收标准 |
|---|---|---|
| 3.1 | POST /v1/auth/forgot（不存在邮箱） | 200 不泄露存在性 |
| 3.2 | 日志读重置验证码 | 8 位 |
| 3.3 | 错误码重置 | 400 |
| 3.4 | 正确码重置为新密码 | 201 |
| 3.5 | 旧密码登录 | 401 |
| 3.6 | 新密码登录 | 200 |
| 3.7 | 恢复原密码（重复 3.1-3.4） | 201 + 旧密码可登录 |

## 二、API Key（F-04）

| # | 步骤 | 验收标准 |
|---|---|---|
| 4.1 | POST /v1/keys {name} | 201 完整 `dt_` Key 仅返回一次 |
| 4.2 | GET /v1/keys | 脱敏（仅 prefix） |
| 4.3 | POST /v1/keys/:id/rotate | 201 新 Key；**旧 Key 调网关 401** |
| 4.4 | DELETE /v1/keys/:id | 200；**已撤销 Key 调网关 401** |
| 4.5 | 可选 expiresAt 过期 Key | 过期后调网关 401 |
| 4.6 | 他人 Key 操作（不同用户） | 403 |

## 三、钱包与计费（F-05 / F-09）

| # | 步骤 | 验收标准 |
|---|---|---|
| 5.1 | GET /v1/wallet | 200 余额 + 流水 |
| 5.2 | dev-credit 充值 | 余额增加 + deposit 流水 |
| 9.1 | 非流式调用后余额 | 精确扣减（cost>0） |
| 9.2 | 流式调用后余额 | 预扣-结算-退款净值正确 |
| 9.3 | 余额不足调用 | 402 insufficient_balance |
| 9.4 | 用量记录 costCents | 与扣款一致 |

## 四、模型目录（F-06）

| # | 步骤 | 验收标准 |
|---|---|---|
| 6.1 | GET /v1/models | ≥236 个，OpenAI 格式 |
| 6.2 | 定价元数据 | glm-5.2 等含 input/output 价格 |
| 6.3 | 未认证网关 | 401 invalid_api_key |

## 五、OpenAI 兼容网关（F-07 / F-08）

| # | 步骤 | 验收标准 |
|---|---|---|
| 7.1 | chat/completions 非流式 | 200 OpenAI 格式 + usage |
| 7.2 | stream:true | SSE `data:` 块 + `[DONE]` |
| 7.3 | 未知模型 | 404 model_not_found |
| 7.4 | 无效 Key | 401 |
| 7.5 | 错误响应体 | `{error:{message,type,code,param}}` |
| 8.1 | 61 次/分钟（同 Key） | 第 61 次 429 rate_limit_exceeded |

## 六、用量（F-10）

| # | 步骤 | 验收标准 |
|---|---|---|
| 10.1 | GET /v1/usage | 明细含 model/tokens/cost |
| 10.2 | GET /v1/usage/summary | 按日聚合 totalTokens>0 |

## 七、Quota 用量限额（F-11）

| # | 步骤 | 验收标准 |
|---|---|---|
| 11.1 | PUT /v1/keys/:id/limits {dailyRequestLimit:2} | 200 |
| 11.2 | 第 1/2 次调用 | 200 |
| 11.3 | 第 3 次调用 | 429 code=quota_exceeded |
| 11.4 | 清空限额（null） | 调用恢复 200 |
| 11.5 | 预警阈值（alertPct=50，达 50%） | quota-events 出现 alert |
| 11.6 | PUT /v1/account/limits 账号级 | 生效（账号维度拦截） |
| 11.7 | GET /v1/usage/quota | 限额配置 + 当前用量 + pct |
| 11.8 | GET /v1/admin/quotas | 全局视图（用户/Key/状态） |
| 11.9 | GET /v1/admin/quota-events | block/alert 事件 |
| 11.10 | 重复超限 | block 事件 5 分钟节流 |

## 八、管理后台（F-12）

| # | 步骤 | 验收标准 |
|---|---|---|
| 12.1 | admin 访问 /v1/admin/stats | 200 |
| 12.2 | 普通用户访问 admin | 403 |
| 12.3 | PUT /v1/admin/models/glm-5.2 定价 | 200 且 /v1/models 生效 |
| 12.4 | GET /v1/admin/users 搜索 | 200 分页 |
| 12.5 | PATCH 用户封禁 | 封禁后登录 401/网关 401 |
| 12.6 | POST /v1/admin/models/sync | 501 占位 |

## 九、支付 P4（F-13）— 验收标准

| # | 步骤 | 验收标准 |
|---|---|---|
| 13.1 | POST /v1/wallet/deposit {amountCents:2500}（mock） | 201 订单 pending + paymentUrl |
| 13.2 | GET /v1/payments/mock-pay/:orderId 模拟支付 | 成功 |
| 13.3 | GET /v1/wallet | 余额 +2500¢，deposit 流水 refId=orderId |
| 13.4 | GET /v1/wallet/orders | 订单 status=paid |
| 13.5 | 重复回调同一订单 | 幂等，余额不重复增加 |
| 13.6 | provider=stripe/momo 无凭据 | 501/400 提示配置 |
| 13.7 | amountCents < 100 | 400 |
| 13.8 | 未认证 deposit | 401 |

## 十、官网首页 P5（F-14）

| # | 步骤 | 验收标准 |
|---|---|---|
| 14.1 | pnpm build | 零错误 |
| 14.2 | /vi /en /zh-CN /zh-TW 渲染 | 4 语言文本正确 |
| 14.3 | 导航 5 项 | 首页/模型/定价/操作文档/控制台 |
| 14.4 | B1 Logo | SVG 渲染正确 |
| 14.5 | 客服 widget | FAB 可开合面板 |
| 14.6 | 认证弹窗 | 登录/注册/重置视图切换 + 8 格验证码输入 |

---

## 评分规则
- 每项 PASS/FAIL + 证据（状态码/响应摘要）
- 回归要求：修复后必须复测并通过才可关闭
- 每轮测试结果追加至 `docs/testing/test-run-log.md`