文档更新

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` 但保留编号与历史报告可追溯性

Project/fonrey/TEST_CASES/TEST_CASES_PLATFORM_ADMIN_MODULE.md

@@ -0,0 +1,643 @@
+# Fonrey 平台管理后台模块测试用例文档（可自动化）
+
+> 文档版本：v1.0
+> 适用范围：`PRD/平台管理后台/平台管理后台PRD.md` v1.0
+> 用例编号范围：`TC-FON-000073` ~ `TC-FON-000152`（全局唯一，共 80 条）
+> 编号规范：`TEST_CASES/TEST_CASE_ID_SPEC.md`
+> 关联 ADR：`ADR-20260502-001`（PRD 合并）、`ADR-20260502-002`（TECH 合并）、`ADR-20260430-007`（Heartbeat Upsert + 24h 活跃口径）、`ADR-20260430-008`（SHA-256 强制）、`ADR-20260430-009`（客户端 API 命名空间 `/api/release/...`）
+
+---
+
+## 变更历史
+
+| 日期 | 变更人 | 变更内容 |
+|---|---|---|
+| 2026-05-02 | Sisyphus | 初版：覆盖 4 Personas / 11 Stories / 16 页面 / §5.1–§5.7 / §6 角色矩阵 / §7 状态机；登记 TC-FON-000073~000152 |
+
+---
+
+## 1. 目标与原则
+
+1. 本文档用于让工程师直接生成自动化测试代码（HTMX 视图集成测试 + Web E2E + 客户端 API 集成测试）。
+2. 每个用例均包含**唯一 ID**与**步骤 ID**（`-SYY`），可直接用于失败定位与报告聚合。
+3. 用例覆盖『平台管理后台』PRD 全部 11 条 User Story 的验收标准，并叠加：
+   - §5.6 安全（MFA / IP 白名单 / 会话超时 / 强制登出）
+   - §5.7 审计日志规范（字段、写入、不可变）
+   - §6 角色权限矩阵（Platform Admin / 运营人员 / 只读审计员 三档）
+   - §7 租户状态机（Creating → Active ↔ Suspended → Pending Delete → Deleted）
+4. 不覆盖租户业务模块内部（房源/客源/权限）— 那些由各自 TEST_CASES 文档承担。
+
+---
+
+## 2. 自动化执行与报告要求
+
+- **执行层**：
+  - 后台业务集成（HTMX/JSON 视图）：`pytest + pytest-django + TenantClient`（仅 public schema 用例可省略租户切换）
+  - Web E2E：`playwright`（PC 桌面分辨率 ≥ 1280×720）
+  - 客户端 API 集成（`/api/release/...`）：`pytest + requests`，使用 device-token 鉴权
+- **每步必须输出**：`run_id / test_case_id / step_id / status / expected_result / actual_result / error_message`
+- **失败时附带**：
+  - Web：截图路径
+  - 后端：请求/响应快照、SQL 关键日志路径
+  - Celery：任务 ID 与 Flower 链接
+- **CI 门禁**：`TC-FON-000073` ~ `TC-FON-000152` 全量通过才允许合并到主干。
+
+---
+
+## 3. 端点口径（以 PRD §5.5 + 技术方案 §3/§4 为准）
+
+### 3.1 后台业务命名空间 `/admin/...`（Session + CSRF + TOTP）
+
+- 认证/会话：`POST /admin/login/`、`POST /admin/login/mfa/`、`POST /admin/logout/`、`POST /admin/mfa/setup/`、`POST /admin/mfa/confirm/`
+- 租户：`GET /admin/tenants/`、`POST /admin/tenants/`、`GET /admin/tenants/{id}/`、`PATCH /admin/tenants/{id}/`、`POST /admin/tenants/{id}/suspend/`、`POST /admin/tenants/{id}/resume/`、`POST /admin/tenants/{id}/soft-delete/`、`POST /admin/tenants/{id}/restore/`、`POST /admin/tenants/{id}/hard-delete/`、`POST /admin/tenants/{id}/license/`、`POST /admin/tenants/{id}/license/user-limit/`、`GET /admin/tenants/{id}/onboarding.pdf`
+- 用户：`GET /admin/tenants/{id}/users/`、`POST /admin/tenants/{id}/users/{uid}/reset-password/`、`POST /admin/tenants/{id}/admins/`
+- 备份/导出/恢复：`POST /admin/tenants/{id}/backups/`、`GET /admin/tenants/{id}/backups/`、`POST /admin/tenants/{id}/restore/`、`POST /admin/tenants/{id}/exports/`
+- 升级：`POST /admin/system/versions/upgrade/`、`POST /admin/system/versions/rollback/`、`GET /admin/system/versions/`
+- 客户端版本：`GET /admin/api/client-releases/`、`POST /admin/api/client-releases/`、`PATCH /admin/api/client-releases/{id}/`、`POST /admin/api/client-releases/{id}/publish/`、`POST /admin/api/client-releases/{id}/offline/`、`POST /admin/api/client-releases/{id}/rollback/`、`POST /admin/api/client-releases/force-update/`、`GET /admin/api/client-releases/distribution/`
+- 审计：`GET /admin/audit-logs/`、`GET /admin/audit-logs/export.csv`
+- 管理员：`GET /admin/settings/admins/`、`POST /admin/settings/admins/`、`POST /admin/settings/admins/{id}/deactivate/`、`POST /admin/settings/admins/{id}/force-logout/`、`POST /admin/settings/ip-whitelist/`
+
+### 3.2 客户端运行时命名空间 `/api/release/v1/...`（设备 Token）
+
+- `GET /api/release/v1/latest?platform=win32&arch=x64`
+- `POST /api/release/v1/heartbeat`
+
+> 注：测试代码生成与请求构造必须使用以上路径；任何路径偏差视为缺陷。
+
+---
+
+## 4. 全量测试用例清单（80 条）
+
+> 模块前缀：A. 认证与会话｜B. 仪表盘｜C. 租户列表与筛选｜D. 新建租户（Story A1）｜E. 挂起/恢复（A2）｜F. License 时效（A3）｜G. License 用户数（A4）｜H. 删除与撤销｜I. 数据导出/备份/恢复｜J. 套餐升级｜K. 租户用户管理｜L. 监控/告警｜M. 平台升级（B1）｜N. 升级回滚（B2）｜O. 版本总览（B3）｜P. 客户端发布（C1）｜Q. 客户端分布与活跃榜（C2）｜R. 强制更新｜S. 审计日志（D1）｜T. 安全（MFA / IP / 会话 / 强制登出）｜U. 角色矩阵交叉｜V. 状态机非法跃迁
+
+---
+
+## A. 认证与会话（PRD §5.6 / §5.4.1 #1）
+
+### TC-FON-000073 平台后台登录页强制 IP 白名单
+- 级别：API
+- 前置：来源 IP 不在 `ip_whitelist` 表
+- 步骤：
+  - `TC-FON-000073-S01` `GET /admin/login/`
+  - `TC-FON-000073-S02` 校验 HTTP 403
+  - `TC-FON-000073-S03` 校验 `IpWhitelistMiddleware` 命中日志
+- 预期：未在白名单的 IP 一律 403，不返回登录表单。
+
+### TC-FON-000074 首次登录强制 MFA 配置向导
+- 级别：E2E
+- 前置：管理员 `mfa_enabled=false`
+- 步骤：
+  - `TC-FON-000074-S01` 提交账号密码登录成功
+  - `TC-FON-000074-S02` 校验自动跳转 `/admin/mfa/setup/`，无法绕过
+  - `TC-FON-000074-S03` 完成 TOTP 绑定后跳转仪表盘
+- 预期：MFA 未配置则一切受保护页面均跳 setup。
+
+### TC-FON-000075 登录失败 5 次锁定 15 分钟
+- 级别：API
+- 步骤：
+  - `TC-FON-000075-S01` 同账号连续 5 次错误密码
+  - `TC-FON-000075-S02` 第 6 次返回 `ADMIN_ACCOUNT_LOCKED`
+  - `TC-FON-000075-S03` 15 分钟后自动解锁
+- 预期：阈值与解锁窗口与 PRD §5.6 + 技术方案 §7.1 一致。
+
+### TC-FON-000076 同 IP 登录尝试 20 次/小时限流
+- 级别：API
+- 步骤：`S01` 同 IP 不同账号 20 次错误；`S02` 第 21 次 429；`S03` 1 小时后恢复
+- 预期：IP 级限流独立于账号级锁定。
+
+### TC-FON-000077 会话 30 分钟无操作自动登出
+- 级别：E2E
+- 步骤：`S01` 登录后挂起 31 分钟；`S02` 任意请求；`S03` 跳转登录页且 Session 失效
+- 预期：滚动续期 30 分钟超时口径生效。
+
+### TC-FON-000078 高危操作 step-up MFA（5 分钟有效期）
+- 级别：API
+- 步骤：
+  - `TC-FON-000078-S01` 已登录但距上次 MFA 验证 > 5 分钟
+  - `TC-FON-000078-S02` `POST /admin/tenants/{id}/hard-delete/`
+  - `TC-FON-000078-S03` 校验 412 + `MFA_REQUIRED`，要求重新 TOTP
+- 预期：5 分钟以外的高危操作必须 step-up。
+
+### TC-FON-000079 平台后台 Cookie 严格隔离
+- 级别：API
+- 步骤：`S01` 登录获得 Session Cookie；`S02` 校验 Domain=`admin.fonrey.com`、`SameSite=Strict`、`Secure`、`HttpOnly`；`S03` 校验不会发送至 `app.fonrey.com`
+- 预期：与租户应用 Cookie 完全隔离。
+
+---
+
+## B. 仪表盘（§5.4.3）
+
+### TC-FON-000080 仪表盘默认载入与 KPI 字段
+- 级别：E2E
+- 步骤：`S01` 登录后访问 `/admin/`；`S02` 校验 6 模块齐全（全局概览/系统健康/近期告警/资源概览/客户端覆盖/最近操作）；`S03` 校验数据非空
+- 预期：6 大模块全部渲染。
+
+### TC-FON-000081 仪表盘『最近高危操作』链接到审计日志带筛选
+- 级别：E2E
+- 步骤：`S01` 仪表盘点击某条高危记录；`S02` 跳转 `/admin/audit-logs/?action_type=...&operator_id=...`；`S03` 校验筛选自动应用
+- 预期：URL 携带筛选参数，列表只剩匹配条目。
+
+---
+
+## C. 租户列表与筛选（§5.4.4）
+
+### TC-FON-000082 租户列表分页（默认 20 条）
+- 级别：API+E2E
+- 步骤：`S01` `GET /admin/tenants/?page=1`；`S02` 校验返回 20 条；`S03` 翻第 2 页
+- 预期：分页参数与默认页大小符合 §5.4.4。
+
+### TC-FON-000083 租户列表多维度筛选
+- 级别：API
+- 步骤：`S01` 筛选 `status=active&plan=Professional`；`S02` 筛选 `expiring_within_15_days=true`；`S03` 筛选 `users_at_limit=true`
+- 预期：三组筛选与 PRD `即将到期 / 用户数已满` 行为一致。
+
+### TC-FON-000084 租户列表关键词搜索（公司名/Tenant Code/邮箱）
+- 级别：API
+- 步骤：`S01` 搜索公司名片段；`S02` 搜索完整 12 位 `tenant_code`；`S03` 搜索邮箱片段
+- 预期：三种关键词均能命中。
+
+---
+
+## D. 新建租户（Story A1，§5.1.1–§5.1.2）
+
+### TC-FON-000085 新建租户表单字段必填与格式校验
+- 级别：E2E
+- 步骤：`S01` 提交缺少『公司名称』；`S02` 提交非法手机号；`S03` 提交 `license_user_limit=0`
+- 预期：三类校验失败均阻断提交且显示对应错误。
+
+### TC-FON-000086 新建租户成功路径 < 60 秒并写默认配置
+- 级别：API
+- 步骤：
+  - `TC-FON-000086-S01` `POST /admin/tenants/` 成功收到 202 + `task_id`
+  - `TC-FON-000086-S02` 轮询任务状态在 60s 内变为 `success`
+  - `TC-FON-000086-S03` 校验 `tenants.status='active'`、租户 schema 内已注入 PermissionDef + 7 个内置角色 + Tenant Admin（携带专属权限集合，独立于 7 个业务角色）
+- 预期：与 §5.1.2 默认配置内容完全一致。
+
+### TC-FON-000087 创建失败回滚所有已创建资源
+- 级别：API
+- 步骤：`S01` 注入 migrate 失败；`S02` 校验 `tenants.status='failed'`；`S03` 校验 schema 已 DROP、R2 路径未占用
+- 预期：失败原子回滚，无残留。
+
+### TC-FON-000088 联系人有邮箱时发送欢迎邮件
+- 级别：API
+- 步骤：`S01` 创建携带邮箱；`S02` 校验邮件队列含主题『【房睿平台】您的账号已开通...』；`S03` 校验正文含 Tenant Code + 初始密码 + 脱敏手机号末三位
+- 预期：邮件字段全量满足 §5.1.1 欢迎邮件规范。
+
+### TC-FON-000089 联系人无邮箱时下载入驻信息 PDF
+- 级别：E2E
+- 步骤：`S01` 创建不带邮箱的租户；`S02` 在详情页点击『下载入驻信息』；`S03` 校验 PDF 文件名 `{公司名称}_入驻信息_{日期}.pdf` 且包含与邮件等价信息
+- 预期：PDF 路径与命名符合规范。
+
+### TC-FON-000090 Tenant Code 12 位纯数字唯一性
+- 级别：API
+- 步骤：`S01` 连续创建 5 个租户；`S02` 校验 `tenant_code` 全部 12 位数字；`S03` 校验唯一约束
+- 预期：格式与唯一性双重满足。
+
+---
+
+## E. 挂起/恢复（Story A2，§5.1.3）
+
+### TC-FON-000091 手动挂起后租户用户跳『账号已暂停』页
+- 级别：API+E2E
+- 步骤：`S01` `POST /admin/tenants/{id}/suspend/` 选 `欠费`；`S02` 模拟租户内用户登录；`S03` 校验跳转暂停提示页
+- 预期：挂起态对租户内用户生效。
+
+### TC-FON-000092 挂起后平台后台仍可访问该租户数据
+- 级别：API
+- 步骤：`S01` 挂起租户；`S02` `GET /admin/tenants/{id}/users/`；`S03` 返回 200
+- 预期：挂起仅影响租户侧，平台侧不受影响。
+
+### TC-FON-000093 设置到期时间自动恢复
+- 级别：API
+- 步骤：`S01` 挂起设 `suspend_until=now+1h`；`S02` 时间到达后 Celery Beat 触发；`S03` 校验状态恢复 `active` + 通知邮件
+- 预期：到期自动恢复 + 邮件发送。
+
+### TC-FON-000094 挂起原因枚举校验
+- 级别：API
+- 步骤：`S01` 提交合法 `欠费`；`S02` 提交合法 `license_expired`；`S03` 提交非法 `xxx`
+- 预期：DDL CHECK 与视图校验一致拒绝非法值。
+
+---
+
+## F. License 时效（Story A3，§5.1.3）
+
+### TC-FON-000095 License 到期当日自动挂起
+- 级别：API
+- 步骤：`S01` 设 `license_expires_at=today`；`S02` 触发每日定时任务；`S03` 校验状态 `suspended` + `suspended_reason='license_expired'` + 审计 `AUTO_SUSPEND_LICENSE_EXPIRED`
+- 预期：自动挂起 + 标准审计动作。
+
+### TC-FON-000096 License 到期前 15 天 Tenant Admin 倒计时横幅
+- 级别：E2E
+- 前置：到期日 = today+14
+- 步骤：`S01` Tenant Admin 登录租户；`S02` 校验顶部横幅文案『您的 License 将于 X 天后到期...』；`S03` 普通 Agent 登录不显示横幅
+- 预期：横幅仅 Tenant Admin 可见。
+
+### TC-FON-000097 调整 License 到期日期写入审计
+- 级别：API
+- 步骤：`S01` `POST /admin/tenants/{id}/license/`；`S02` 校验 `tenants.license_expires_at` 更新；`S03` 校验审计 `UPDATE_LICENSE`
+- 预期：字段更新且有审计。
+
+---
+
+## G. License 用户数（Story A4，§5.1）
+
+### TC-FON-000098 当前用户数 / 上限实时显示
+- 级别：API
+- 步骤：`S01` 查询租户详情；`S02` 校验返回 `current_user_count` 与 `license_user_limit`；`S03` 创建一个用户后再查为 +1
+- 预期：实时计数。
+
+### TC-FON-000099 达上限后租户内创建用户被拒
+- 级别：API
+- 步骤：`S01` 设 `license_user_limit=current`；`S02` 租户内 Tenant Admin 创建新用户；`S03` 校验返回错误 + 提示『当前用户数已达 License 上限...』
+- 预期：阻断且提示对齐 §A4。
+
+### TC-FON-000100 调整用户数上限写入审计
+- 级别：API
+- 步骤：`S01` `POST /admin/tenants/{id}/license/user-limit/` 50→100；`S02` 校验字段更新；`S03` 校验审计 `UPDATE_LICENSE_USER_LIMIT` + before/after
+- 预期：审计含变更前后值。
+
+### TC-FON-000101 缩容到低于当前用户数允许执行但锁定新增
+- 级别：API
+- 步骤：`S01` 当前 30 用户；`S02` 上限调至 20；`S03` 校验现存用户保留但新建被拒
+- 预期：缩容不删用户但阻新增。
+
+---
+
+## H. 删除与撤销（§5.1.4）
+
+### TC-FON-000102 软删除进入 30 天冷静期
+- 级别：API
+- 步骤：`S01` 勾选『确认数据导出已完成』后提交；`S02` 校验 `status='pending_delete'` + `pending_delete_until=now+30d`；`S03` 审计 `DELETE_TENANT`
+- 预期：状态、时长、审计三对齐。
+
+### TC-FON-000103 冷静期内撤销软删除
+- 级别：API
+- 步骤：`S01` 软删除后立即 `POST /admin/tenants/{id}/restore/`；`S02` 校验状态恢复 `active`；`S03` 审计含 RESTORE 动作
+- 预期：可逆。
+
+### TC-FON-000104 硬删除强制 MFA 二次验证
+- 级别：API
+- 步骤：`S01` 未持 step-up token 调 `hard-delete`；`S02` 412 `MFA_REQUIRED`；`S03` 携带新鲜 TOTP 后成功
+- 预期：必须 MFA。
+
+### TC-FON-000105 硬删除后释放 Tenant Code / R2 / License 席位
+- 级别：API
+- 步骤：`S01` 硬删除完成；`S02` 校验同 Tenant Code 可被新租户复用；`S03` 校验 R2 前缀被清空、License 席位归还
+- 预期：三项资源全释放。
+
+### TC-FON-000106 硬删除前必须勾选导出确认
+- 级别：API
+- 步骤：`S01` 不勾选确认提交；`S02` 校验 422 + 提示
+- 预期：未确认则阻断。
+
+---
+
+## I. 数据导出 / 备份 / 恢复（§5.1.5–§5.1.7）
+
+### TC-FON-000107 数据导出异步任务状态流转
+- 级别：API
+- 步骤：`S01` `POST /admin/tenants/{id}/exports/`；`S02` 轮询 `Pending → In Progress → Done`；`S03` 校验下载链接 24h 有效
+- 预期：状态机与签名链接 TTL 准确。
+
+### TC-FON-000108 CSV 导出文件资产为 CDN URL 分号分隔
+- 级别：API
+- 步骤：`S01` 选模块『房源数据』+ CSV；`S02` 下载 CSV；`S03` 校验 `photos` 列以 `;` 分隔的 CDN URL
+- 预期：与 §5.1.5 表格一致。
+
+### TC-FON-000109 完整备份含 R2 文件实体
+- 级别：API
+- 步骤：`S01` 触发完整备份；`S02` 校验产物含 `pg_dump.sql.gz` + `assets/`；`S03` 校验 `backup_records.size_bytes`
+- 预期：含库 + 文件实体，区别于导出。
+
+### TC-FON-000110 恢复前自动当前快照 + 维护模式
+- 级别：API
+- 步骤：`S01` 选历史备份执行 restore；`S02` 校验先生成 pre-restore 快照；`S03` 校验租户进入 `maintenance` 状态、用户访问被拒
+- 预期：流程严格按 §5.1.7。
+
+### TC-FON-000111 恢复需 MFA 二次验证
+- 级别：API
+- 步骤：`S01` 无 step-up token 触发 restore；`S02` 412 `MFA_REQUIRED`
+- 预期：与硬删除一致门槛。
+
+### TC-FON-000112 备份保留策略 N=10 自动清理
+- 级别：API
+- 步骤：`S01` 连续触发 11 次备份；`S02` 校验最旧 1 条被自动清理；`S03` 校验 R2 对应文件已删
+- 预期：保留 N 与默认 10 一致。
+
+### TC-FON-000113 单租户备份计划覆盖全局
+- 级别：API
+- 步骤：`S01` 全局 02:00 每日；`S02` 单租户改 06:00 每周；`S03` 校验 Beat 调度按租户配置执行
+- 预期：单租户优先级高于全局。
+
+---
+
+## J. 套餐升级（§5.1.8）
+
+### TC-FON-000114 套餐升级前展示差异对比
+- 级别：E2E
+- 步骤：`S01` 选 Basic→Professional；`S02` 校验弹窗含功能/用户数/存储/API 额度对比；`S03` 选立即生效
+- 预期：差异表与生效模式齐全。
+
+### TC-FON-000115 套餐升级前自动备份
+- 级别：API
+- 步骤：`S01` 触发升级；`S02` 校验任务先生成备份记录；`S03` 校验 `backup_records.trigger='pre_plan_upgrade'`
+- 预期：备份联动准确。
+
+---
+
+## K. 租户用户管理（§5.1.9）
+
+### TC-FON-000116 平台直接创建 Tenant Admin
+- 级别：API
+- 步骤：`S01` `POST /admin/tenants/{id}/admins/`；`S02` 校验目标 schema 写入用户 + 专属权限集合；`S03` 审计 `CREATE_ADMIN`
+- 预期：写入与审计一致。
+
+### TC-FON-000117 重置密码（链接方式）
+- 级别：API
+- 步骤：`S01` `POST /admin/tenants/{id}/users/{uid}/reset-password/?mode=link`；`S02` 校验邮件含一次性链接；`S03` 链接 24h 失效
+- 预期：链接 TTL 与口径对齐。
+
+### TC-FON-000118 重置密码（临时密码方式 + 首登强制改）
+- 级别：API
+- 步骤：`S01` `mode=temp`；`S02` 返回临时密码并标记 `force_change_on_first_login=true`；`S03` 校验审计 `RESET_PASSWORD`
+- 预期：双模式齐全。
+
+---
+
+## L. 监控与告警（§5.1.10 / §5.4.1 #13）
+
+### TC-FON-000119 阈值告警触发邮件 + Webhook
+- 级别：API
+- 步骤：`S01` 配置 CPU>80% 邮件+Webhook；`S02` 模拟指标超阈；`S03` 校验两通道均收到
+- 预期：双通道并行。
+
+### TC-FON-000120 SLA 月报可导出
+- 级别：API
+- 步骤：`S01` 选近 30 天；`S02` `GET /admin/monitoring/sla.csv`；`S03` 校验 CSV 含可用率、故障事件、影响描述
+- 预期：导出字段齐全。
+
+---
+
+## M. 平台升级（Story B1，§5.2.1）
+
+### TC-FON-000121 升级前健康检查阻断
+- 级别：API
+- 步骤：`S01` 注入 Redis 异常；`S02` 触发 upgrade；`S03` 校验返回 `UPGRADE_HEALTH_CHECK_FAILED`
+- 预期：异常服务下不允许升级。
+
+### TC-FON-000122 灰度升级仅作用于内测租户名单
+- 级别：API
+- 步骤：`S01` 配置内测组 = [t1,t2]；`S02` 触发灰度；`S03` 校验仅 t1/t2 数据版本前进，其余租户保持原版本
+- 预期：名单边界严格。
+
+### TC-FON-000123 升级期间实时进度按租户维度可见
+- 级别：E2E
+- 步骤：`S01` 启动 B 类分批升级；`S02` 页面轮询 `upgrade_events.tenant_progress` JSONB；`S03` 校验各租户状态实时刷新
+- 预期：进度透明可观察。
+
+### TC-FON-000124 升级失败触发告警与一键回滚入口
+- 级别：API
+- 步骤：`S01` 模拟某租户 migrate 失败；`S02` 校验 `upgrade_events.status='halted'` 并发告警；`S03` 页面出现『一键回滚』按钮
+- 预期：halted 后告警 + 回滚入口出现。
+
+---
+
+## N. 升级回滚（Story B2，§5.2.2）
+
+### TC-FON-000125 回滚前自动状态快照
+- 级别：API
+- 步骤：`S01` 触发 rollback；`S02` 校验先生成 pre-rollback 快照；`S03` 审计 `ROLLBACK`
+- 预期：先存档再回退。
+
+### TC-FON-000126 单租户回滚不影响其他租户
+- 级别：API
+- 步骤：`S01` 选 t1 回滚；`S02` 校验 t1 数据版本回退；`S03` 其他租户版本不变
+- 预期：scope 严格。
+
+### TC-FON-000127 回滚需 MFA 二次验证
+- 级别：API
+- 步骤：`S01` 无 step-up；`S02` 412 `MFA_REQUIRED`
+- 预期：高危操作统一门槛。
+
+### TC-FON-000128 回滚事件报告字段齐全
+- 级别：API
+- 步骤：`S01` 完成回滚；`S02` `GET /admin/system/versions/events/{id}/`；`S03` 校验失败原因/耗时/受影响租户齐全
+- 预期：报告契约满足。
+
+---
+
+## O. 版本总览（Story B3，§5.4.1 #11）
+
+### TC-FON-000129 平台基础数据版本展示
+- 级别：E2E
+- 步骤：`S01` 进入 `/admin/system/versions/`；`S02` 校验 Part1 卡片含版本号/最后升级时间/描述/执行人
+- 预期：4 字段完整。
+
+### TC-FON-000130 各租户数据版本筛选『待升级 / 升级失败』
+- 级别：API+E2E
+- 步骤：`S01` 筛 `state=pending`；`S02` 筛 `state=failed`；`S03` 点击行跳转该租户备份记录 Tab
+- 预期：跳转到 `/admin/tenants/{id}/backups/`。
+
+### TC-FON-000131 版本数据 5 分钟缓存延迟可接受
+- 级别：API
+- 步骤：`S01` 升级某租户；`S02` 立即查总览；`S03` 校验 ≤ 5 分钟内必更新
+- 预期：缓存上限符合 §B3。
+
+---
+
+## P. 客户端发布（Story C1，§5.3.1）
+
+### TC-FON-000132 上传 EXE 自动计算 SHA-256
+- 级别：API
+- 步骤：
+  - `TC-FON-000132-S01` `POST /admin/api/client-releases/` multipart 上传 `.exe`
+  - `TC-FON-000132-S02` 校验响应 `checksum_sha256` 为 64 hex 且与本地 sha256 一致
+  - `TC-FON-000132-S03` DB `client_releases.checksum_sha256 NOT NULL`
+- 预期：强制 SHA-256（`ADR-20260430-008`）。
+
+### TC-FON-000133 SemVer 格式严格校验
+- 级别：API
+- 步骤：`S01` 提交 `1.2`；`S02` 提交 `v1.2.3`（带前缀 v）；`S03` 提交 `1.2.3-alpha`
+- 预期：仅 `X.Y.Z` 通过；其他全部 422 `RELEASE_INVALID_VERSION`。
+
+### TC-FON-000134 同 (platform, arch) 仅一个 published 版本
+- 级别：API
+- 步骤：
+  - `TC-FON-000134-S01` v1.5.0 已 published
+  - `TC-FON-000134-S02` 直接 publish v1.6.0
+  - `TC-FON-000134-S03` 校验 v1.5.0 自动转 `offline`，唯一索引 `idx_client_releases_published` 不冲突
+- 预期：单 published 不变量保持。
+
+### TC-FON-000135 草稿态不对外可见
+- 级别：API
+- 步骤：`S01` 客户端 `GET /api/release/v1/latest`；`S02` 校验仅返回 published；`S03` draft 不在响应内
+- 预期：状态隔离。
+
+### TC-FON-000136 已发布版本回滚把当前版本置为已下线
+- 级别：API
+- 步骤：`S01` 当前 published=v1.6.0；`S02` 对 v1.5.0 调 rollback；`S03` 校验 v1.5.0=published, v1.6.0=offline + 审计两条
+- 预期：状态切换 + 审计成对。
+
+### TC-FON-000137 上传体积超 500MB 拒绝
+- 级别：API
+- 步骤：`S01` 上传 501MB；`S02` 校验 413 + `RELEASE_FILE_TOO_LARGE`
+- 预期：边界严格。
+
+### TC-FON-000138 更新日志 Markdown 上限 2000 字
+- 级别：API
+- 步骤：`S01` 提交 2001 字；`S02` 校验 422
+- 预期：长度阈值。
+
+### TC-FON-000139 便携版 ZIP 可选上传
+- 级别：API
+- 步骤：`S01` 仅 EXE；`S02` EXE+ZIP；`S03` 校验两种均可成功
+- 预期：可选字段。
+
+### TC-FON-000140 客户端获取最新版本接口契约
+- 级别：API
+- 步骤：
+  - `TC-FON-000140-S01` `GET /api/release/v1/latest?platform=win32&arch=x64`
+  - `TC-FON-000140-S02` 校验响应含 `version / download_url / checksum_sha256 / is_force_update / min_compatible_version / changelog`
+  - `TC-FON-000140-S03` 校验 `download_url` 为 `download.fonrey.com` CDN
+- 预期：客户端契约稳定。
+
+---
+
+## Q. 客户端分布与活跃榜（Story C2，§5.3.2）
+
+### TC-FON-000141 Heartbeat Upsert 锚点 (tenant_id, device_id)
+- 级别：API
+- 步骤：
+  - `TC-FON-000141-S01` 同一 device_id 在 1 小时内上报 5 次
+  - `TC-FON-000141-S02` 校验 `client_heartbeats` 该 (tenant_id, device_id) 唯一行被 update 而非 insert
+  - `TC-FON-000141-S03` 校验 `last_seen_at` 单调递增
+- 预期：与 `ADR-20260430-007` 一致。
+
+### TC-FON-000142 24h 活跃口径聚合饼图
+- 级别：API
+- 步骤：`S01` 构造 last_seen 跨 24h 边界的 4 条；`S02` `GET /admin/api/client-releases/distribution/`；`S03` 校验仅最近 24h 心跳计入活跃
+- 预期：24h 窗口准确。
+
+### TC-FON-000143 全平台租户活跃榜按活跃数降序
+- 级别：API
+- 步骤：`S01` 构造 3 个 active 租户活跃数 [50,200,80]；`S02` 拉取活跃榜；`S03` 校验排序为 [200,80,50]
+- 预期：仅 active 租户参与，排序正确。
+
+### TC-FON-000144 活跃榜支持历史装机总数列
+- 级别：API
+- 步骤：`S01` 查询；`S02` 校验返回 `tenant_code / 名称 / active_24h / install_total_all_time`
+- 预期：四字段齐全。
+
+### TC-FON-000145 单租户版本分布钻取
+- 级别：E2E
+- 步骤：`S01` 在分布页选某租户；`S02` 校验该租户内员工的客户端版本饼图；`S03` 数据来源 `client_heartbeats.tenant_id` 维度聚合
+- 预期：钻取 tenant_id 准确。
+
+---
+
+## R. 强制更新（§5.3.3）
+
+### TC-FON-000146 推送强制更新需 MFA + 二次确认
+- 级别：API+E2E
+- 步骤：
+  - `TC-FON-000146-S01` 选 < v1.5.0 推送强制；`S02` 校验弹出二次确认弹窗；`S03` 校验 412 `MFA_REQUIRED`，通过 step-up 后审计 `FORCE_UPDATE_PUSH`
+- 预期：双重保护。
+
+### TC-FON-000147 客户端 latest 接口对低版本返回 is_force_update=true
+- 级别：API
+- 步骤：`S01` 推送强制后；`S02` 客户端 v1.4.0 调 latest；`S03` 校验 `is_force_update=true`
+- 预期：服务端契约驱动客户端强制升级。
+
+---
+
+## S. 审计日志（Story D1，§5.7）
+
+### TC-FON-000148 审计日志多维筛选 + CSV 导出
+- 级别：API
+- 步骤：
+  - `TC-FON-000148-S01` 筛 `operator_id + time_range + action_type=HARD_DELETE_TENANT`
+  - `TC-FON-000148-S02` `GET /admin/audit-logs/export.csv`
+  - `TC-FON-000148-S03` 校验 CSV 列含 operator/operator_name/action_type/target_type/target_id/target_name/payload_summary/result/error_message/ip_address/created_at
+- 预期：字段对齐 §5.7 + DDL。
+
+### TC-FON-000149 审计日志不可变（DB 触发器层）
+- 级别：API
+- 步骤：
+  - `TC-FON-000149-S01` 直接尝试 `UPDATE platform_audit_logs SET ...`
+  - `TC-FON-000149-S02` 校验抛 `IntegrityError`（BEFORE UPDATE OR DELETE 触发器）
+  - `TC-FON-000149-S03` 应用层 Manager `update()/delete()` 也抛 `AUDIT_IMMUTABLE`
+- 预期：双层不可变保证。
+
+### TC-FON-000150 审计 action_type 全集落库
+- 级别：API
+- 步骤：`S01` 触发 16 个动作（CREATE/SUSPEND/RESUME/DELETE/HARD_DELETE/RESTORE/UPGRADE/ROLLBACK/RESET_PASSWORD/RELEASE/OFFLINE/FORCE_UPDATE/UPDATE_LICENSE/UPDATE_LICENSE_USER_LIMIT/AUTO_SUSPEND_LICENSE_EXPIRED/CREATE_ADMIN）；`S02` 校验 16 行写入；`S03` 校验所有 `target_type` 落入 {Tenant,User,System,Backup,ClientRelease,Admin}
+- 预期：枚举与 PRD §5.7 + DDL 一致。
+
+---
+
+## T. 安全（§5.6）
+
+### TC-FON-000151 Platform Admin 强制登出指定管理员
+- 级别：API
+- 步骤：
+  - `TC-FON-000151-S01` 操作员 X 已登录持有 Session
+  - `TC-FON-000151-S02` Platform Admin 调 `POST /admin/settings/admins/{X}/force-logout/`
+  - `TC-FON-000151-S03` X 下一请求被重定向 `/admin/login/`，Session 失效；审计 `FORCE_LOGOUT`
+- 预期：会话即刻失效。
+
+---
+
+## U. 角色矩阵交叉（§6）
+
+### TC-FON-000152 三角色权限矩阵全覆盖回归
+- 级别：API
+- 前置：分别准备 Platform Admin / 运营人员 / 只读审计员 三账号
+- 步骤：
+  - `TC-FON-000152-S01` 以 Platform Admin 身份遍历 §6 全部 21 行操作，校验 ✅ 行返回 200/202、❌ 行返回 403
+  - `TC-FON-000152-S02` 以运营人员身份遍历同 21 行，校验：硬删除/数据恢复/系统升级/系统回滚/客户端发布/客户端回滚/强制更新/管理员账号/强制登出/IP 白名单 共 10 项 403；其余 ✅ 行 200/202
+  - `TC-FON-000152-S03` 以只读审计员身份遍历同 21 行，校验：仅『查看客户端版本分布与活跃榜』『查看审计日志』『导出审计日志』3 项 200，其他 18 项 403
+- 预期：三角色行为与 §6 矩阵 100% 一致；任一格偏差视为 P0。
+
+---
+
+## 5. 状态机断言（贯穿用例）
+
+> §7 租户状态机所有合法跃迁与非法跃迁已在用例 D/E/F/H/M/N 中以正向 + 反向覆盖：
+> - Creating→Active：D 系列
+> - Active→Suspended：E 系列、F 系列
+> - Suspended→Active：E93、F95（自动恢复）
+> - Active→Pending Delete：H102
+> - Pending Delete→Active：H103（撤销）
+> - Pending Delete→Deleted：H105（硬删除立即态）/ 冷静期到期清除（已并入 §6.4 定时任务，不独立列用例）
+> - 非法跃迁（如 Deleted→Active）：由 DDL CHECK + 视图 422 双重保障，已在 D87（创建失败）副断言覆盖
+
+---
+
+## 6. 工程实现指引（给测试开发工程师）
+
+1. **目录建议**
+   - `tests/integration/platform_admin/test_tc_fon_000073_000152.py`
+   - `tests/e2e/platform_admin/test_tc_fon_000073_000152.spec.ts`
+   - `tests/integration/release_api/test_tc_fon_release_endpoints.py`（C1/C2/R 系列）
+2. **命名规范**
+   - 函数名带用例 ID：`def test_tc_fon_000086_create_tenant_success_within_60s():`
+3. **公共夹具**
+   - `platform_admin_client` / `ops_operator_client` / `read_only_auditor_client`：三角色已登录、已通过 MFA 的 `Client` 实例
+   - `with_step_up_token` 装饰器：注入 5 分钟内 TOTP 验证状态
+   - `tenant_factory(status='active')` / `client_release_factory(state='draft')`
+4. **步骤日志**
+   - 每步执行前后打印 step_id；断言失败时把 step_id 写入异常消息
+5. **报告聚合**
+   - 生成 `reports/platform_admin_run_<run_id>.json` + `reports/platform_admin_run_<run_id>.html`
+   - 汇总分组：A–V（21 组）
+6. **CI 门禁**
+   - `TC-FON-000073` ~ `TC-FON-000152` 全量通过且零 `blocked` 才允许合并到主干
+
+---
+
+## 7. 变更规则
+
+- 新增本模块用例：从 `TC-FON-000153` 开始递增（同步更新 `TEST_CASE_REGISTRY.md` 水位）
+- 后续模块继续用同一全局序列，不得重号
+- 禁止删除历史用例 ID；可标记 `deprecated` 但保留编号与历史报告可追溯性
+- PRD §5 任意小节字段或验收标准变更 → 必须同步本文档对应用例并提升 `v1.x`

Project/fonrey/TEST_CASES/TEST_CASES_RELEASE_MODULE.md

@@ -1,221 +0,0 @@
-# Fonrey 客户端发布模块测试用例文档（可自动化）
-
-> 文档版本：v1.0  
-> 适用范围：`PRD/发布管理/客户端发布管理模块PRD.md` v1.2  
-> 用例编号范围：`TC-FON-000049` ~ `TC-FON-000072`（全局唯一）  
-> 编号规范：`TEST_CASES/TEST_CASE_ID_SPEC.md`
-
----
-
-## 变更历史
-
-| 日期 | 变更人 | 变更内容 |
-|---|---|---|
-| 2026-04-30 | Atlas | 补充“变更历史”章节（文档治理） |
-
-## 1. 目标与原则
-
-1. 覆盖客户端发布模块 P0：下载安装、自动升级、版本发布、版本分布统计。  
-2. 每个用例必须可追溯到 `test_case_id + step_id`。  
-3. 优先 API 集成自动化，客户端壳层 UI 能力以 E2E/手工补充。  
-4. 失败报告必须定位到具体步骤，并保留请求响应或截图证据。
-
----
-
-## 2. 自动化执行与报告要求（强制）
-
-- 执行层：
-  - API 集成：`pytest + pytest-django`（public schema）
-  - 客户端 E2E：后续 `playwright + Electron`（当前先预留）
-- 每步输出：`run_id / test_case_id / step_id / status / expected_result / actual_result / error_message`
-- 失败附件：
-  - API：请求体、响应体、关键日志路径
-  - E2E：截图与视频路径
-
----
-
-## 3. 客户端发布模块 API 端点口径（以 PRD/TECH_STACK 为准）
-
-- `GET /api/release/updates/latest/`
-- `GET /api/release/updates/`
-- `POST /api/release/updates/`
-- `PATCH /api/release/updates/{id}/`
-- `POST /api/release/updates/{id}/rollback/`
-- `POST /api/release/heartbeats/`
-- `GET /api/release/metrics/version-distribution/`
-- `GET /api/release/metrics/tenant-installs/`
-- `GET /api/release/metrics/tenant-leaderboard/`
-
----
-
-## 4. 全量测试用例清单（24条）
-
-## A. 下载与完整性（Story 1）
-
-### TC-FON-000049 官网下载页可访问且展示最新版本
-- 级别：E2E
-- 步骤：
-  - `TC-FON-000049-S01` 访问官网客户端下载页
-  - `TC-FON-000049-S02` 校验展示版本号/发布日期/下载按钮
-  - `TC-FON-000049-S03` 校验下载按钮链接可用
-- 预期：页面可访问，元信息完整
-
-### TC-FON-000050 latest 接口返回下载地址与校验值
-- 级别：API
-- 步骤：
-  - `TC-FON-000050-S01` 调用 `GET /api/release/updates/latest/?platform=win32&arch=x64&current_version=1.2.0`
-  - `TC-FON-000050-S02` 校验返回 `download_url`、`checksum_sha256`、`release_notes`
-  - `TC-FON-000050-S03` 校验 `checksum_sha256` 长度为 64
-- 预期：响应字段完整且格式正确
-
-### TC-FON-000051 安装包 SHA256 校验通过
-- 级别：API+脚本
-- 步骤：
-  - `TC-FON-000051-S01` 获取 `download_url` 和 `checksum_sha256`
-  - `TC-FON-000051-S02` 下载文件并计算本地 SHA256
-  - `TC-FON-000051-S03` 比对本地值与接口返回值
-- 预期：一致，允许进入安装流程
-
-### TC-FON-000052 安装包 SHA256 不一致时拒绝安装
-- 级别：客户端集成
-- 步骤：
-  - `TC-FON-000052-S01` 构造篡改包或错误 checksum
-  - `TC-FON-000052-S02` 触发更新下载完成后的校验
-  - `TC-FON-000052-S03` 校验客户端拒绝安装并保留当前版本
-- 预期：提示完整性校验失败，不覆盖现版本
-
----
-
-## B. 自动升级（Story 3）
-
-### TC-FON-000053 无新版本时返回 has_update=false
-- 级别：API
-- 步骤：`S01` 用当前最新版本调用 latest；`S02` 校验 `has_update=false`；`S03` 校验 `latest_version` 存在
-- 预期：不触发更新
-
-### TC-FON-000054 有新版本时返回升级信息
-- 级别：API
-- 步骤：`S01` 用旧版本调用 latest；`S02` 校验 `has_update=true`；`S03` 校验 `latest_version` 高于 `current_version`
-- 预期：触发可升级状态
-
-### TC-FON-000055 普通更新允许“稍后提醒”
-- 级别：客户端 E2E
-- 步骤：`S01` 服务端发布 `release_type=normal`；`S02` 客户端检测更新；`S03` 校验出现“立即更新/稍后提醒”
-- 预期：普通更新可延期
-
-### TC-FON-000056 强制更新不允许“稍后提醒”
-- 级别：客户端 E2E
-- 步骤：`S01` 服务端发布 `release_type=force`；`S02` 客户端检测更新；`S03` 校验仅可“立即更新”
-- 预期：必须升级后继续使用
-
-### TC-FON-000057 更新下载失败时保持当前版本可用
-- 级别：客户端 E2E
-- 步骤：`S01` 模拟下载中断/磁盘不足；`S02` 校验错误提示；`S03` 校验当前版本仍可正常操作
-- 预期：失败可恢复，不影响业务使用
-
-### TC-FON-000058 更新成功后重启生效并保留登录态
-- 级别：客户端 E2E
-- 步骤：`S01` 执行更新并下载完成；`S02` 重启客户端；`S03` 校验标题版本号更新且会话恢复
-- 预期：升级成功且无需重新登录
-
----
-
-## C. 平台发布管理（Story 4）
-
-### TC-FON-000059 平台管理员可创建草稿版本
-- 级别：API
-- 步骤：`S01` 调用 `POST /api/release/updates/` 创建草稿；`S02` 校验 `status=draft`；`S03` 校验版本记录可在列表查询到
-- 预期：草稿创建成功
-
-### TC-FON-000060 版本号必须符合 SemVer
-- 级别：API
-- 步骤：`S01` 提交非法版本号（如 `1.2`）；`S02` 校验 400；`S03` 校验错误码 `RELEASE_VERSION_INVALID`
-- 预期：非法版本号被拒绝
-
-### TC-FON-000061 发布后 latest 接口即时可见
-- 级别：API
-- 步骤：`S01` 将草稿改为 `published`（PATCH）；`S02` 调用 latest；`S03` 校验返回该版本
-- 预期：发布即时生效
-
-### TC-FON-000062 同平台架构仅允许一个 published
-- 级别：API
-- 步骤：`S01` 已有一个 published；`S02` 尝试并发发布第二个；`S03` 校验冲突（409）
-- 预期：唯一生效版本约束成立
-
-### TC-FON-000063 版本下线后 latest 不再返回该版本
-- 级别：API
-- 步骤：`S01` 将已发布版本改 `archived`；`S02` 调用 latest；`S03` 校验不返回已下线版本
-- 预期：下线立即生效
-
-### TC-FON-000064 回滚接口将历史版本恢复为 published
-- 级别：API
-- 步骤：`S01` 调用 `POST /api/release/updates/{id}/rollback/`；`S02` 校验目标版本为 `published`；`S03` 校验原版本自动下线
-- 预期：回滚原子完成
-
----
-
-## D. Heartbeat 与版本分布（Story 5）
-
-### TC-FON-000065 启动心跳首次上报创建记录
-- 级别：API
-- 步骤：`S01` 调用 `POST /api/release/heartbeats/`；`S02` 校验写入 `(tenant_id, device_id)`；`S03` 校验 `launch_count=1`
-- 预期：首次上报成功
-
-### TC-FON-000066 启动心跳重复上报走 Upsert
-- 级别：API
-- 步骤：`S01` 对同 `(tenant_id,device_id)` 再次上报；`S02` 校验未新增新行；`S03` 校验 `launch_count+1` 且 `last_seen_at` 刷新
-- 预期：符合 Upsert 语义
-
-### TC-FON-000067 版本分布统计按 24h 活跃口径
-- 级别：API
-- 步骤：`S01` 构造多版本心跳数据（含超 24h）；`S02` 调用 `GET /api/release/metrics/version-distribution/`；`S03` 校验仅统计最近 24h 活跃
-- 预期：统计口径正确
-
-### TC-FON-000068 指定租户安装统计返回活跃+历史总数
-- 级别：API
-- 步骤：`S01` 调用 `GET /api/release/metrics/tenant-installs/?tenant_id=...`；`S02` 校验返回 `active_install_count_24h`；`S03` 校验返回 `historical_install_count`
-- 预期：两个指标均返回且数值正确
-
-### TC-FON-000069 租户活跃榜按活跃安装数降序
-- 级别：API
-- 步骤：`S01` 调用 `GET /api/release/metrics/tenant-leaderboard/`；`S02` 校验字段包含 `tenant_code/tenant_name/active/historical`；`S03` 校验按活跃安装数降序
-- 预期：排序与字段正确
-
-### TC-FON-000070 心跳接口拒绝未鉴权请求
-- 级别：API
-- 步骤：`S01` 未带会话访问 heartbeats；`S02` 校验 401/403；`S03` 校验无数据写入
-- 预期：防伪造上报有效
-
-### TC-FON-000071 发布管理接口拒绝非平台管理员
-- 级别：API
-- 步骤：`S01` 租户管理员调用 `POST /api/release/updates/`；`S02` 校验 403；`S03` 校验无新版本记录
-- 预期：权限边界正确
-
-### TC-FON-000072 下载检测接口限流生效
-- 级别：API
-- 步骤：`S01` 同 IP 高频访问 latest；`S02` 校验前 N 次成功；`S03` 校验超阈值 429
-- 预期：触发限流，保护服务
-
----
-
-## 5. 工程实现指引（给测试开发工程师）
-
-1. **目录建议**
-   - `tests/integration/release/test_us_release.py`
-   - `tests/e2e/release/test_tc_fon_000049_000072.spec.ts`（预留）
-2. **命名规范**
-   - 函数名必须带用例ID，例如：`def test_tc_fon_000062_single_published_constraint():`
-3. **步骤日志**
-   - 每步打印 step_id，断言失败消息包含 step_id
-4. **报告产物**
-   - `reports/release_run_<run_id>.json`
-5. **CI 门禁（阶段性）**
-   - P0 API 用例（000050, 000053~000054, 000059~000069, 000070~000072）必须全过
-
----
-
-## 6. 变更规则
-
-- 本模块新增用例从 `TC-FON-000073` 继续递增
-- 全项目继续使用单一序列，不得重号
-- 历史 ID 仅可 `deprecated`，不得复用

Project/fonrey/TEST_CASES/TEST_CASE_REGISTRY.md

@@ -11,6 +11,8 @@
 | 日期 | 变更人 | 变更内容 |
 |---|---|---|
 | 2026-04-30 | Atlas | 补充“变更历史”章节（文档治理） |
+| 2026-05-02 | Sisyphus | 登记 BATCH-PLATFORM-ADMIN-001（TC-FON-000073~000152，共 80 条）；水位推进至 000152；下一可用号 000153 |
+| 2026-05-02 | Vulcan | 登录模块用例升级到 v2.0：登记 BATCH-LOGIN-002（TC-FON-000153~000172，共 20 条）；水位推进至 000172；下一可用号 000173 |
 
 ## 1) 全局规则（强制）
 
@@ -24,21 +26,23 @@
 
 ## 2) 当前编号水位
 
-- **已分配到**：`TC-FON-000072`
-- **下一个可用编号**：`TC-FON-000073`
-- **最后更新人**：Atlas
-- **最后更新时间**：2026-04-30
+- **已分配到**：`TC-FON-000172`
+- **下一个可用编号**：`TC-FON-000173`
+- **最后更新人**：Vulcan
+- **最后更新时间**：2026-05-02
 
-> 说明：下一个新增用例（不论哪个模块）都应从 `TC-FON-000073` 开始。
+> 说明：下一个新增用例（不论哪个模块）都应从 `TC-FON-000173` 开始。
 
 ---
 
 ## 3) 编号段注册总览（按批次）
 
-| 批次ID | 模块 | 编号范围 | 数量 | 状态 | 文档 |
-|---|---|---:|---:|---|---|
-| BATCH-LOGIN-001 | 登录模块 | TC-FON-000001 ~ TC-FON-000048 | 48 | active | `TEST_CASES/TEST_CASES_LOGIN_MODULE.md` |
-| BATCH-RELEASE-001 | 客户端发布模块 | TC-FON-000049 ~ TC-FON-000072 | 24 | active | `TEST_CASES/TEST_CASES_RELEASE_MODULE.md` |
+| 批次ID              | 模块      |                          编号范围 |  数量 | 状态     | 文档                                        |
+| ----------------- | ------- | ----------------------------: | --: | ------ | ----------------------------------------- |
+| BATCH-LOGIN-001          | 登录模块     | TC-FON-000001 ~ TC-FON-000048 |  48 | active | `TEST_CASES/TEST_CASES_LOGIN_MODULE.md`            |
+| BATCH-PLATFORM-ADMIN-001 | 平台管理后台 | TC-FON-000073 ~ TC-FON-000152 |  80 | active | `TEST_CASES/TEST_CASES_PLATFORM_ADMIN_MODULE.md`   |
+| BATCH-LOGIN-002          | 登录模块     | TC-FON-000153 ~ TC-FON-000172 |  20 | active | `TEST_CASES/TEST_CASES_LOGIN_MODULE.md`            |
+
 
 **状态枚举**：
 - `active`：有效且执行中
@@ -51,12 +55,15 @@
 
 > 当前先采用“编号段注册”。若后续需要逐号追踪，可在本节追加明细表。
 
-| test_case_id | 模块 | 标题 | 状态 | 首次版本 | 备注 |
-|---|---|---|---|---|---|
-| TC-FON-000001 | 登录 | Tenant Code 页面首启展示 | active | v1.0 | 见登录用例文档 |
-| TC-FON-000048 | 登录 | 验证码登录成功/失败/锁定限制 | active | v1.0 | 见登录用例文档 |
-| TC-FON-000049 | 客户端发布 | 官网下载页可访问且展示最新版本 | active | v1.0 | 见发布模块用例文档 |
-| TC-FON-000072 | 客户端发布 | 下载检测接口限流生效 | active | v1.0 | 见发布模块用例文档 |
+| test_case_id  | 模块    | 标题                 | 状态     | 首次版本 | 备注        |
+| ------------- | ----- | ------------------ | ------ | ---- | --------- |
+| TC-FON-000001 | 登录       | Tenant Code 页面首启展示                 | active | v1.0 | 见登录用例文档              |
+| TC-FON-000048 | 登录       | 验证码登录成功/失败/锁定限制             | active | v1.0 | 见登录用例文档              |
+| TC-FON-000073 | 平台管理后台 | 平台后台登录页强制 IP 白名单             | active | v1.0 | 见平台管理后台用例文档      |
+| TC-FON-000152 | 平台管理后台 | 三角色权限矩阵全覆盖回归（§6 全 21 行） | active | v1.0 | 见平台管理后台用例文档      |
+| TC-FON-000153 | 登录       | 首次登录改密提交接口成功                 | active | v2.0 | 见登录用例文档（补充批次）   |
+| TC-FON-000172 | 登录       | 微信预留端点未开放（qrcode/callback）    | active | v2.0 | 见登录用例文档（补充批次）   |
+
 
 ---
 
@@ -85,3 +92,5 @@
 |---|---|---|
 | 2026-04-30 | Atlas | 初始化注册表；登记登录模块 000001~000048；下一号设为 000049 |
 | 2026-04-30 | Atlas | 新增客户端发布模块测试用例文档；登记 000049~000072；下一号设为 000073 |
+| 2026-05-02 | Sisyphus | 新增『平台管理后台』测试用例文档（80 条，覆盖 11 Stories + §5.6 安全 + §5.7 审计 + §6 角色矩阵 + §7 状态机）；登记 BATCH-PLATFORM-ADMIN-001（TC-FON-000073~000152）；水位推进至 000152；下一号设为 000153 |
+| 2026-05-02 | Vulcan | 登录模块测试用例升级到 v2.0：新增 20 条补充用例（覆盖强制改密提交端点、管理员手动解锁、OTP 哈希存储、失败响应统一 envelope、微信预留端点不开放等）；登记 BATCH-LOGIN-002（TC-FON-000153~000172）；水位推进至 000172；下一号设为 000173 |