文档更新

Project/fonrey/TEST_CASES/TEST_CASES_LOGIN_MODULE.md

@@ -1,8 +1,8 @@
 # Fonrey 登录模块测试用例文档（可自动化）
 
-> 文档版本：v1.0  
-> 适用范围：`PRD/登录管理/用户登录管理模块PRD.md` v2.0  
-> 用例编号范围：`TC-FON-000001` ~ `TC-FON-000048`（全局唯一）  
+> 文档版本：v2.0  
+> 适用范围：`PRD/登录管理/用户登录管理模块PRD.md` v3.0、`TECH_STACK/登录管理技术方案.md` v4.1、`DATA_MODEL/DATA_MODEL_LOGIN.md`、`TECH_STACK/API_CONTRACT.md`  
+> 用例编号范围：`TC-FON-000001` ~ `TC-FON-000048`、`TC-FON-000153` ~ `TC-FON-000172`（全局唯一，共 68 条）  
 > 编号规范：`TEST_CASES/TEST_CASE_ID_SPEC.md`
 
 ---
@@ -12,6 +12,7 @@
 | 日期 | 变更人 | 变更内容 |
 |---|---|---|
 | 2026-04-30 | Atlas | 补充“变更历史”章节（文档治理） |
+| 2026-05-02 | Vulcan | 对齐 PRD v3.0 / 登录技术方案 v4.1 / DATA_MODEL_LOGIN：新增 20 条登录模块补充用例（TC-FON-000153~000172），覆盖 API 契约统一 envelope、`/api/auth/password/change-initial/`、管理员手动解锁、短信 OTP 明文不落库、历史密码保留 3 条、验证码登录错误作废文案、微信扫码预留端点不开放、`/api/auth/wechat/*` 路由未注册、登出接口与客户端会话清理联动等关键口径；总用例数 48→68 |
 
 ## 1. 目标与原则
 
@@ -39,9 +40,9 @@
 
 ---
 
-## 3. 全量测试用例清单（48条）
+## 3. 全量测试用例清单（68条）
 
-### 3.0 登录模块 API 端点口径（以 PRD 为准）
+### 3.0 登录模块 API 端点口径（以 `TECH_STACK/登录管理技术方案.md` §五 + `TECH_STACK/API_CONTRACT.md` 为准）
 
 - `POST /api/auth/tenant/verify/`
 - `GET /api/auth/captcha/`
@@ -51,6 +52,7 @@
 - `POST /api/auth/recover/password/request/`
 - `POST /api/auth/recover/password/verify/`
 - `POST /api/auth/recover/password/reset/`
+- `POST /api/auth/password/change-initial/`
 - `POST /api/auth/logout/`
 
 > 注：测试代码生成与接口调用必须使用以上路径。
@@ -373,11 +375,146 @@
 
 ---
 
+## F. 补充用例（PRD v3.0 / 技术方案 v4.1 / DATA_MODEL / API_CONTRACT 对齐）
+
+### TC-FON-000153 首次登录改密提交接口成功
+- 级别：API
+- 前置：账号 `is_initial_password=true`，已完成登录并具备改密会话
+- 步骤：
+  - `TC-FON-000153-S01` 调用 `POST /api/auth/password/change-initial/` 提交合法新密码
+  - `TC-FON-000153-S02` 校验返回成功，`is_initial_password=false`
+  - `TC-FON-000153-S03` 校验 `password_histories` 新增记录
+- 预期：首次改密成功落库，账号脱离初始密码状态
+
+### TC-FON-000154 首次登录改密弱密码拦截
+- 级别：API+E2E
+- 前置：账号处于首次改密页
+- 步骤：`S01` 输入不满足复杂度的新密码；`S02` 提交改密；`S03` 校验错误码/错误提示
+- 预期：返回 `AUTH_PASSWORD_WEAK`，拒绝提交
+
+### TC-FON-000155 首次登录改密禁止复用最近3次历史密码
+- 级别：API
+- 前置：`password_histories` 已有最近 3 条
+- 步骤：`S01` 提交与最近历史重复的新密码；`S02` 校验错误响应；`S03` 校验密码未更新
+- 预期：拒绝历史重复密码，历史记录不新增
+
+### TC-FON-000156 首次改密成功后会话保持并直达首页
+- 级别：E2E
+- 前置：初始密码登录进入强制改密页
+- 步骤：`S01` 完成改密提交；`S02` 校验未二次登录；`S03` 校验直接进入首页
+- 预期：沿用当前会话进入系统（不强制重新登录）
+
+### TC-FON-000157 找回密码成功后不再触发首次改密
+- 级别：API+E2E
+- 前置：账号原为初始密码状态，执行找回密码三步成功
+- 步骤：
+  - `TC-FON-000157-S01` 调用 `POST /api/auth/recover/password/reset/` 成功后校验 `is_initial_password=false`
+  - `TC-FON-000157-S02` 返回登录页使用新密码登录
+  - `TC-FON-000157-S03` 校验直接进入首页而非首次改密页
+- 预期：找回密码后视为已完成身份核验，不再触发强制改密
+
+### TC-FON-000158 主动登出销毁会话与登录凭证
+- 级别：API+E2E
+- 前置：已登录
+- 步骤：
+  - `TC-FON-000158-S01` 调用 `POST /api/auth/logout/`
+  - `TC-FON-000158-S02` 校验服务端会话失效（后续受保护请求无效）
+  - `TC-FON-000158-S03` Electron 客户端侧校验登录凭证清理与跳转登录页
+- 预期：登出后不可复用原凭证继续访问系统
+
+### TC-FON-000159 管理员手动解锁账号
+- 级别：API
+- 前置：账号因连续密码错误达到阈值已处于 `locked`
+- 步骤：`S01` Tenant Admin 在后台执行手动解锁；`S02` 校验 `user_accounts.status=active` 且 `locked_until` 清空；`S03` 立即发起登录请求并成功
+- 预期：管理员可提前解锁，无需等待 30 分钟自动解锁
+
+### TC-FON-000160 找回密码步骤一防枚举且无效账号不落短信记录
+- 级别：API
+- 前置：准备“未注册手机号”“停用账号手机号”
+- 步骤：`S01` 分别调用 `POST /api/auth/recover/password/request/`；`S02` 校验外显响应一致；`S03` 校验 `sms_otp_records` 未新增对应记录
+- 预期：外显统一且不泄露账号状态，不产生无效 OTP 记录
+
+### TC-FON-000161 短信验证码仅哈希存储（禁止明文入库）
+- 级别：API
+- 前置：触发找回密码或验证码登录发码
+- 步骤：`S01` 查询 `sms_otp_records` 最新记录；`S02` 校验存在 `otp_hash`；`S03` 校验无 OTP 明文字段/日志明文
+- 预期：满足 DATA_MODEL 安全要求（OTP 明文不落库）
+
+### TC-FON-000162 找回密码验证码错误5次后作废并持久化状态
+- 级别：API
+- 前置：已生成有效 `scene=password_reset` OTP
+- 步骤：`S01` 连续提交错误验证码 5 次；`S02` 校验第 5 次后提示“验证码已失效，请重新获取”；`S03` 校验记录 `verify_attempts=5` 且 `is_used=true`
+- 预期：OTP 作废口径与数据状态一致
+
+### TC-FON-000163 OTP 两场景有效期差异校验（10 分钟 / 5 分钟）
+- 级别：API
+- 步骤：
+  - `TC-FON-000163-S01` 发起 `scene=password_reset`，校验 `expires_at=created_at+10分钟`
+  - `TC-FON-000163-S02` 发起 `scene=login`，校验 `expires_at=created_at+5分钟`
+  - `TC-FON-000163-S03` 校验两场景限流计数独立
+- 预期：有效期与频控均符合技术方案与数据模型
+
+### TC-FON-000164 验证码登录错误5次后作废并提示重新获取
+- 级别：API+E2E
+- 前置：已发送 `scene=login` 验证码
+- 步骤：`S01` 连续输入错误 OTP 5 次；`S02` 校验第 5 次提示“验证码已失效，请重新获取”；`S03` 再次提交原 OTP 必须失败
+- 预期：验证码登录错误上限与作废文案符合 PRD
+
+### TC-FON-000165 登录审计 `login_attempts.failure_reason` 写入准确
+- 级别：API
+- 步骤：
+  - `TC-FON-000165-S01` 触发一次密码错误，校验记录 `wrong_password`
+  - `TC-FON-000165-S02` 触发一次滑块失败，校验记录 `wrong_captcha`
+  - `TC-FON-000165-S03` 触发一次 OTP 错误，校验记录 `wrong_otp`
+- 预期：失败原因枚举写入正确，便于审计与风控
+
+### TC-FON-000166 锁定账号验证码登录返回标准错误码
+- 级别：API
+- 前置：账号已 `locked`
+- 步骤：`S01` 调用 `POST /api/auth/login/phone/`；`S02` 校验 HTTP 423；`S03` 校验错误码 `AUTH_ACCOUNT_LOCKED`
+- 预期：账号维度锁定策略对验证码登录同样生效
+
+### TC-FON-000167 Tenant 校验限流错误契约
+- 级别：API
+- 前置：同 IP 1 分钟内第 11 次请求
+- 步骤：`S01` 触发 `POST /api/auth/tenant/verify/` 限流；`S02` 校验 HTTP 429；`S03` 校验 `code=AUTH_TENANT_RATE_LIMITED` 且错误体字段完整
+- 预期：限流错误符合 API_CONTRACT 与技术方案
+
+### TC-FON-000168 API 失败响应统一 envelope 契约
+- 级别：API
+- 前置：构造任一登录失败场景（如密码错误）
+- 步骤：`S01` 调用失败接口；`S02` 校验响应包含 `ok=false`、`error`、`code`、`meta.request_id`、`meta.timestamp`；`S03` 校验字段类型正确
+- 预期：失败响应结构符合 `TECH_STACK/API_CONTRACT.md`
+
+### TC-FON-000169 密码登录失败错误码与状态码契约
+- 级别：API
+- 前置：账号存在，密码错误
+- 步骤：`S01` 调用 `POST /api/auth/login/`；`S02` 校验 HTTP 401；`S03` 校验 `code=AUTH_INVALID_CREDENTIAL` 与统一错误结构
+- 预期：失败状态码与错误码稳定、可机器判定
+
+### TC-FON-000170 找回密码重置凭证无效错误契约
+- 级别：API
+- 前置：`sms_reset_token` 无效或过期
+- 步骤：`S01` 调用 `POST /api/auth/recover/password/reset/`；`S02` 校验 HTTP 400；`S03` 校验 `code=AUTH_SMS_RESET_TOKEN_INVALID`
+- 预期：错误码与文案符合技术方案
+
+### TC-FON-000171 登录页微信扫码入口禁用态验证
+- 级别：E2E
+- 步骤：`S01` 打开登录页；`S02` 校验“微信扫码登录 - 即将开放”为灰态不可点击；`S03` 校验无跳转行为
+- 预期：MVP 仅展示禁用入口，不提供可用登录能力
+
+### TC-FON-000172 微信预留端点未开放（qrcode/callback）
+- 级别：API
+- 步骤：`S01` 调用 `GET /api/auth/wechat/qrcode/`，校验 HTTP 404 或路由未注册；`S02` 调用 `POST /api/auth/wechat/callback/`，校验 HTTP 404 或路由未注册；`S03` 校验未返回可用二维码数据且未签发任何登录态
+- 预期：MVP 阶段微信相关预留端点均不开放
+
+---
+
 ## 4. 工程实现指引（给测试开发工程师）
 
 1. **目录建议**
-   - `tests/integration/login/test_tc_fon_000001_000048.py`
-   - `tests/e2e/login/test_tc_fon_000001_000048.spec.ts`
+   - `tests/integration/login/test_tc_fon_000001_000048_and_000153_000172.py`
+   - `tests/e2e/login/test_tc_fon_000001_000048_and_000153_000172.spec.ts`
 2. **命名规范**
    - 函数名必须带用例ID，例如：`def test_tc_fon_000024_account_lock_after_5_failures():`
 3. **步骤日志**
@@ -385,12 +522,12 @@
 4. **报告聚合**
    - 生成 `reports/login_run_<run_id>.json` + `reports/login_run_<run_id>.html`
 5. **CI 门禁**
-   - `TC-FON-000001` ~ `TC-FON-000048` 全量通过才允许合并
+   - `TC-FON-000001` ~ `TC-FON-000048` 与 `TC-FON-000153` ~ `TC-FON-000172` 全量通过才允许合并
 
 ---
 
 ## 5. 变更规则
 
-- 新增登录用例：从 `TC-FON-000049` 开始递增
+- 新增登录用例：从 `TC-FON-000173` 开始递增
 - 后续房源/客源模块：继续用同一全局序列，不得重号
 - 禁止删除历史用例ID；可标记 `deprecated` 但保留编号与历史报告可追溯性