jiapuapp/docs/今晚全量联调与明早测试执行计划.md

# 今晚全量联调与明早测试执行计划

> 修订日期：2026-07-24（北京时间）  
> 时间口径：“今晚”固定指 2026-07-23 晚间，“明早”固定指 2026-07-24 上午。  
> 当前状态：用户已明确说“开始执行”，实施、测试与 MuMu 基座联调已启动；用户将本轮硬截止提前为 `T_due=2026-07-24 08:00`。55 个候选 PA 本轮仍不纳入（`approvedCandidateActions=0`）。

> 本次续执行状态：逐页 Apifox 账本已覆盖 53 个页面文件；当前页面目录不再导入 `data/mock`。已接线但未实测的创建/维护动作仍统一记为 `DECLARED_UNVERIFIED`；缺 DTO、ID、权限或上传 owner 的页面已改为明确关闭态，不以 fixture、本地数组、timer 或本地成功提示冒充服务端结果。本次续执行只做静态 API 语法和源代码归属核验，未构建、未操作 MuMu、未发起任何真实写入。

## 0. 已执行记录与人工回归保留

- 已通过 HBuilderX 标准基座连接 `emulator-5554` 并完成差量编译、同步、启动；本轮不构建或安装独立测试包。
- A01 密码登录页已在 MuMu 实机完成账号密码提交、协议勾选和真实供应商 TAC challenge 展示验证；TAC 已改为供应商原生呈现，不再叠加项目标题、主题、按钮或覆盖供应商刷新/关闭控件。
- 已自动通过 A01/A04/A05 的认证合同、认证接口映射、短信冷却、TAC renderjs 安全传输、注册后导航和编译审计；原始截图仅保存在本机临时受限目录，仓库不保留账号、手机号、令牌、短信或 TAC 相关截图。
- 2026-07-23 20:56 全量夜跑逻辑调度 `208` 项：`PASS=162`、`EXPECTED_BLOCKED=19`、`FAIL=0`、`INFRA_ERROR=27`、`timedOut=0`。27 项均依赖“`localhost:5173` 的 H5 页面 + `127.0.0.1:9222` 的 Chrome 调试页”；临时 H5 服务可启动，但当前执行环境拒绝启动 Chrome 调试端口，故夜跑器已将这组前置条件显式标为 `H5_CHROME_RUNTIME_UNAVAILABLE`，不将其写成产品失败或通过。临时 H5 服务已停止。
- 2026-07-23 23:01 HBuilderX 5.07 已通过标准基座向 `emulator-5554` 完成最新差量编译；控制台末次记录为“项目 jiapuapp 编译成功”。未生成或安装独立测试包。
- 同轮 Apifox 合同收紧后的最小验证已通过：`compile-audit`、`navigation-flow-contract`、`t04-relative-remote-close-contract`、`t05-member-remote-close-contract`、`lineage-write-apifox-contract`、`t03-t08-member-flow-contract`、`tree-member-fixture-runtime-smoke`。新增 Apifox 写入合同脚本尚未纳入 20:56 的历史全量夜跑，后续全量统计须重新计算，不得沿用 `208` 作为最新 inventory。
- 2026-07-23 23:29 已移除 T01 旧固定底部抽屉；点击头像人物卡现在直接打开唯一人物操作面板，面板中央头像可进入 T03，十个入口仍由同一 `selected` 人物上下文承载。相关 T01 面板、视觉、导航、文档流与编译审计已通过；23:28 的 HBuilderX 标准基座差量编译同样成功，未生成或安装独立测试包。
- 2026-07-23 23:37 已按 Apifox 的已登录改密 owner 接通 M04：`PUT /genealogy/app/auth/password`、`oldPassword/newPassword` 32 位 MD5 摘要、鉴权与 APP `clientId` 由统一请求层持有。页面移除“仅本地校验、不提交”伪流程，成功/明确失败/离页取消均有对应状态；本轮不实际修改测试账号密码，真实调用与密码恢复保留人工窗口。
- 2026-07-23 23:42 已按 Apifox 的已登录退出 owner 接通 M10：REMOTE 模式使用 `DELETE /genealogy/app/auth/logout`，无请求体，鉴权与 APP `clientId` 继续由统一请求层持有；严格成功才可确认远端已响应。无论请求失败、取消或结果未知，本机会话均安全清理并回到 A01，不自动重试、不把失败写成服务端已退出。本轮未对测试账号发送该敏感请求。M10、M04 的静态契约、页面归属、导航和编译审计均已通过；23:42 HBuilderX 标准基座差量编译成功，未生成或安装独立测试包。
- 2026-07-23 23:50 当前源码的全量夜跑已完整执行 `209/209`：`PASS=163`、`EXPECTED_BLOCKED=19`、`FAIL=0`、`INFRA_ERROR=27`、`timedOut=0`、`NOT_RUN=0`。库存为 `baselineInventoryTests=204` 加本轮 `newExecutableTests=5`。27 项均是需 `localhost:5173` 页面及 `127.0.0.1:9222` Chrome 调试页的 H5 运行时检查，统一记 `H5_CHROME_RUNTIME_UNAVAILABLE`，不写成产品失败或通过；因此本轮尚无可冻结候选。T01 唯一操作面板替换造成的五项旧断言/孤儿资产偏差已外科式收口并重跑通过。23:50 HBuilderX 5.07 标准基座差量编译成功，未生成或安装独立测试包。
- 2026-07-24 00:00 已从 `emulator-5554` 的 HBuilderX 标准基座读取 A01 实机画面：国风登录页、密码/验证码切换、协议入口、注册/忘记密码与微信登录入口均正常呈现，无白块、截断或覆盖。此检查未输入账号密码、未触发 TAC、短信、注册、找回或任何远端写操作；截图只保留在本机临时受限目录，不入库，也不替代登录后的完整实机验收。
- 2026-07-24 00:13 已用 HBuilderX 临时 Web 运行复核 H5 页面服务，`http://localhost:5173` 返回 `200`；但 `127.0.0.1:9222/json/list` 仍超时，当前执行环境不允许启动隔离 Chrome 调试端口。故 27 项 H5 Chrome 运行时检查继续统一记 `H5_CHROME_RUNTIME_UNAVAILABLE`，不改变其测试口径，也不将 H5 服务可达写成浏览器运行时通过。
- 2026-07-24 00:30 已在本机临时验收目录建立唯一 `role-seed-matrix.json`：仅登记脱敏测试角色别名、允许动作、人工 TAC/短信阻塞与清理责任，当前对象 ID 为零；不含账号、手机号、密码、令牌、验证码、TAC proof 或原始响应。
- 2026-07-24 00:31 已对当前源码重新执行 T0 夜跑：`inventory=209`、`scheduled=25`、`executed=25`、`PASS=6`、`EXPECTED_BLOCKED=19`、`FAIL=0`、`INFRA_ERROR=0`、`timedOut=0`、`notRunScheduled=0`；其余 184 项为本次 T0 未调度项，不得写成已通过。输出仅保存在本机临时验收目录。
- 2026-07-24 00:33 已重跑 T01/T03—T08 的 12 项人物流门禁：唯一人物操作面板、树状态/视觉/文档流、成员详情映射、亲属与资料写入合同、排行关闭态、Apifox 写入合同及树 fixture runtime 均通过。此为静态/运行时映射证据，不替代未取得的真实服务端写入响应。
- 2026-07-24 00:36 已对受保护的“我的家谱”读取执行无鉴权只读探测：远端可达，HTTP 成功信封内业务码为 `401` 且数据为空。未携带账号、令牌或其他凭据，未发送写请求；后续受保护读取/写入的唯一下一步仍是人工完成 TAC 并建立会话。
- 2026-07-24 00:40 已对当前源码完整执行 `ALL` 夜跑 `209/209`：`PASS=163`、`EXPECTED_BLOCKED=19`、`FAIL=0`、`INFRA_ERROR=27`、`timedOut=0`、`NOT_RUN=0`。27 项均在连接 `localhost:5173` 的 Chrome 调试页前被统一标记 `H5_CHROME_RUNTIME_UNAVAILABLE`，没有进入产品断言；不得将它们记为产品失败或通过。输出仅保存在本机临时验收目录。
- 2026-07-24 00:45 已再次读取 `emulator-5554` 的 HBuilderX 标准基座 A01 画面：国风背景、密码/验证码切换、手机号与密码输入区、协议入口、注册和找回入口完整可见，无白屏、截断或遮挡。未输入账号、未触发 TAC/短信或远端写操作；截图只保存在本机临时受限目录。
- 2026-07-24 00:51 已在 Apifox 的 APP 目录核对“搜索行政区划” operation 为 `GET /genealogy/region/search`，随后以只读请求取得当前部署实证：HTTP `200`、业务码 `200`、服务器 `Date=Thu, 23 Jul 2026 16:51:08 GMT`，单条结果稳定含字符串 `regionCode`、`label`、`parentCode`、`ancestors`、`regionName`、`regionLevel`、`regionType` 与 `leaf`。当前部署的旧 `/genealogy/app/region/search` 同样返回该投影，但 Apifox 的 APP 目录 owner 仍以前者为准；不将双路径同响应静默写成兼容 owner。
- 2026-07-24 00:52 已重订 G03 客户端历史门禁：它只校验明确本地预览且不存在虚构的原子 bootstrap、结果查询、错误区域路径或远端请求，已转为可通过并从预期阻塞清单移除。保护 OpenAPI 门禁同时改为只报告实际快照与 Apifox 的合同冲突，不再要求项目实现未声明的 bootstrap。
- 2026-07-24 00:55 已对更新后的当前源码再次完整执行 `ALL` 夜跑 `209/209`：`PASS=164`、`EXPECTED_BLOCKED=18`、`FAIL=0`、`INFRA_ERROR=27`、`timedOut=0`、`NOT_RUN=0`。库存仍为 `baselineInventoryTests=204` 加本轮 `newExecutableTests=5`。27 项均因当前执行环境拒绝提供 `127.0.0.1:9222` 的 Chrome 调试运行时而在产品断言前标记为 `H5_CHROME_RUNTIME_UNAVAILABLE`；不记为产品失败或通过。输出仅保存在本机临时验收目录。
- 2026-07-24 00:56 已重订 M06 帮助中心的旧 OpenAPI 门禁：不再要求受保护快照提供 `RListHelpArticleVo`、文章分类/标题/纯文本正文等当前 Apifox 未声明的 DTO，也不引入独立详情 owner。门禁现已通过并从预期阻塞清单移除；M06 页面补充“本地使用说明、非服务端文章”的可见来源提示，仍只提供本地说明与 M07 反馈入口，远端列表保持 `DECLARED_UNVERIFIED`。
- 2026-07-24 00:57 已对 M06 变更后的当前源码再次完整执行 `ALL` 夜跑 `209/209`：`PASS=165`、`EXPECTED_BLOCKED=17`、`FAIL=0`、`INFRA_ERROR=27`、`timedOut=0`、`NOT_RUN=0`。27 项仍全部为 `H5_CHROME_RUNTIME_UNAVAILABLE`，未进入产品断言；输出仅保存在本机临时验收目录。
- 2026-07-24 00:58 HBuilderX 5.07 控制台记录“开始编译…”后输出“项目 jiapuapp 编译成功”，已通过标准基座同步 `emulator-5554`；未生成或安装独立测试包。前台 CLI 未自行退出但对应基座仍正常前台，故只将 IDE 的成功回执计为编译证据，不将 CLI 常驻误记为失败或额外构建。
- 2026-07-24 01:04 已读取同步后的 `emulator-5554` 标准基座 A01 画面：登录页完整可见，密码/验证码登录切换、手机号/密码输入、找回、微信、注册与协议入口均无白屏、截断或错位。未输入账号、未勾选协议、未触发 TAC/短信或任何远端写请求；截图只保存在本机临时受限目录。
- 2026-07-24 01:08 已重订认证旧 OpenAPI 门禁：密码登录的唯一请求 wire 为 `phone`、MD5 `password` 与 `grantType=password`，原生 TAC 保持客户端前置，不上传 `validToken`；短信发送仍为唯一消费 `validToken` 的认证动作。门禁与认证 API runtime 均通过，并从预期阻塞清单移除。
- 2026-07-24 01:10 已对当前源码完整执行 `ALL` 夜跑 `209/209`：`PASS=167`、`EXPECTED_BLOCKED=15`、`FAIL=0`、`INFRA_ERROR=27`、`timedOut=0`、`NOT_RUN=0`。剩余 15 项均为仍缺真实合同、稳定 DTO/权限投影或人工前置的精确阻塞；27 项仍为未取得 `127.0.0.1:9222` Chrome 调试运行时的 `H5_CHROME_RUNTIME_UNAVAILABLE`，未进入产品断言。输出仅保存在本机临时验收目录。
- 2026-07-24 01:12 已修复 G03 OpenAPI 门禁以中文计划文件名读取时在 Windows PowerShell 无 BOM 解析下产生的伪阻塞；该门禁现只依据快照/客户端合同判断并通过，也已从预期阻塞清单移除。若同版本快照以后出现错误 owner，仍会以精确 `BLOCKED` 报告。
- 2026-07-24 01:20 已再跑最新 T0：`25/25`，`PASS=10`、`EXPECTED_BLOCKED=15`、`FAIL=0`、`INFRA_ERROR=0`、`NOT_RUN=184`。本轮 allowlist 与计划中的 15 条精确阻塞逐项一致；其余 H5 运行时前置只在 `ALL` 中作为基础设施阻塞统计。
- 2026-07-24 03:59 已将 M04/M10 的旧快照门禁改为当前 Apifox 已核对客户端接线门禁：M04 校验 `PUT /genealogy/app/auth/password` 的 MD5 body 与取消归属；M10 校验 `DELETE /genealogy/app/auth/logout` 的无 body、取消归属与本机会话兜底。两项均通过并从预期阻塞清单移除；真实改密、服务端退出继续分别保留人工恢复/登录会话验证，未发起任何远端 mutation。随后完整执行 `ALL` 夜跑 `209/209`：`PASS=169`、`EXPECTED_BLOCKED=13`、`FAIL=0`、`INFRA_ERROR=27`、`timedOut=0`、`NOT_RUN=0`。27 项仍均为缺失 `127.0.0.1:9222` Chrome 调试运行时的 `H5_CHROME_RUNTIME_UNAVAILABLE`，未进入产品断言；输出仅保存在本机临时验收目录。
- 2026-07-24 04:00 已按更新后的 manifest 再跑 T0：`23/23`，`PASS=10`、`EXPECTED_BLOCKED=13`、`FAIL=0`、`INFRA_ERROR=0`、`NOT_RUN=186`；allowlist 与第 0.2 节的 13 条精确自动阻塞逐项一致。该结果只说明安全/合同候选门禁没有新增失败，不替代人工 TAC、短信、敏感 mutation 或登录后实机闭环。
- 早晨人工回归保留：密码登录真实拖动 TAC；短信登录、注册、忘记密码的真实短信与 TAC。不得绕过、猜解或重复请求这些人机/短信步骤。

### 0.1 明早人工回归最短清单

1. 使用已启动的 HBuilderX 标准基座进入 A01；不构建或安装独立测试包。
2. 人工勾选协议后，在密码登录页使用已单独提供的测试账号发起一次登录；在供应商原生 TAC 中由人工完成拖动，不添加任何项目自定义样式或覆盖层。成功后检查是否进入 G01，并冷启动一次确认会话恢复；不记录或截图凭据、令牌、验证码和 TAC proof。
3. 短信登录、注册和忘记密码各自需要真实收码人和原生 TAC：每个场景只在本人在场时发起一次，遵守页面冷却；未能完成即记录“人工 TAC/短信阻塞”，不重试、不猜解、不绕过。
4. 换绑手机号、修改密码、注销、支付、提现、删除和退出家谱均不在无人值守阶段执行。若人工验证修改密码，结束后按约定恢复，并只在本机临时脱敏台账登记结果。
5. 人工结果只记录页面、动作、时间、四字段结论和非敏感对象 ID；远端返回、手机号、账号、密码、令牌、验证码、TAC proof、邀请码和个人资料一律不进入仓库、文档或截图文件名。

### 0.2 当前 12 条精确自动阻塞与解除条件

| 门禁 | 当前阻塞 | 解除条件 |
| --- | --- | --- |
| Android 认证无障碍 | 原生 TAC 的 TalkBack、键盘与大字号无法由当前自动化可靠判定 | 早晨在 MuMu/真机人工完成原生 TAC 无障碍回归 |
| G11 家谱设置 | 依赖的 mine/overview 工作区读取未取得唯一稳定 owner | 先收敛工作区读取合同与真实权限投影 |
| G12 字辈诗 | 正常列表、维护列表、批量预览与保存已接线，但尚未获得真实登录会话下的读取/预览/保存响应 | 在人工可观察会话中按“读列表→读维护→预览→保存→维护回读”验证；浏览器 CORS 仅是 H5 环境前置，不替代 APP 业务合同 |
| 家谱工作区 | 单家谱 overview owner 在受保护快照中缺失或不唯一 | 以 Apifox 与同版本快照收敛唯一读取路径、DTO 与权限 |
| 邀请票据 | 无“我的票据/签发/撤销/接受”当前 operation | 后端提供独立邀请票据闭环，不以普通申请替代 |
| 加入申请 | public 搜索/申请 operation 标识与快照不一致 | 后端同版本合同明确查询、提交、撤回、审核及结果语义 |
| 世系 locator | 缺少精确定位人物的读取 operation | 后端声明并实测人物定位/恢复读取 owner；不得从列表猜 ID |
| 通知读取 | 缺未读数 operation 且列表无稳定通知 DTO | 后端提供未读数与列表 item 的 ID、正文、类型/跳转投影 |
| 通知已读状态 | notification ID wire 与 `RVoid` 信封约束不完整 | 同一 owner 收紧 ID、响应和错误语义，再用可控通知种子实测 |
| 换绑手机号 | 缺专用受保护发码 operation 与资料前置投影 | 后端补齐 operation/DTO 后，在人工 TAC/短信窗口实测 |
| 个人资料读取 | `RObject` 未声明可消费资料字段 | 后端提供稳定资料 DTO、权限与脱敏语义 |
| 个人资料更新 | 缺 profileVersion/If-Match 与合并 body 合同 | 后端提供版本并发与字段白名单，再对测试账号做可恢复验证 |

M04 和 M10 的客户端接线门禁现只以 Apifox 已核对的 owner、方法、body/空 body、取消归属与本机会话收口为准，已不再把旧受保护导出中虚构的会话安全语义当作阻塞。两项真实远端 mutation 仍均为 `DECLARED_UNVERIFIED`：改密必须在可恢复的人工窗口完成后恢复约定密码；服务端退出必须由人工登录会话确认撤销结果。两者均不得在无人值守期间发起。

F01/F02/F03 必须拆开处理：F01 已删除本地动态列表，因列表条目 DTO 缺失而明确关闭正文/详情入口；F02 已按唯一可映射的 `feedContent` 接通发布，不发送媒体、排序或状态猜测字段；F03 动态正文继续不接线、不猜字段，一级评论已有 `FamilyFeedCommentView[]` 和明确提交 body，客户端已按该合同接通真实读取/提交并在提交后回读。没有真实登录会话、实际响应和人工可观察写入前，三页均仍是 `DECLARED_UNVERIFIED`，绝不能把接线写成已完成。

## 一、计划地位

本文是今晚到明早的唯一执行顺序与验收入口；[产品参考页面功能映射表](./产品参考页面功能映射表.md) 是本文直接引用的权威附件，二者必须一起评审、一起确认。既有治理文档继续提供历史背景和长期发布约束，但与今晚的批次顺序、时间分配或“可测试”口径冲突时，以本文及该附件为准。`APP.openapi.yaml` 和 `APP.openapi.json` 只读且受保护，不得修改、格式化、覆盖或删除。

当前处于“执行与验证”阶段。用户已完成三人交叉评审后的规划确认并明确说“开始执行”，因此允许按本文对业务代码、页面样式、接口接线、测试、HBuilderX 与 MuMu 标准基座做最小必要变更与验证；仍不得以已存在的半成品、旧报告、参考项目能运行或局部截图代替当前项目验收。

## 二、明早交付目标与项目范围

本规划对象是当前 `jiapuapp` UniApp 整个项目，不只覆盖认证或世系树。A、G、T、F、R、N、M 七个路由域、共享导航与会话、文件上传、权限、异常恢复、视觉、参考资产、无障碍、构建和 MuMu 验收都在范围内。参考思维导图中的后台管理、公司官网和独立 PC 管理端不是本仓库的实现范围，只能为 APP 角色、权限和后端依赖提供参考，不能据此在当前仓库静默扩张成三个新项目。

当前 `pages.json` 的 52 条活动路由是今晚的最低活动基线，不是产品功能的永久上限，也不能单独代表整个项目完成。两个参考源中发现的候选功能必须先逐页面、逐动作、逐接口完成书面甄别；只有结论为“直接采用”或“改造后采用”，且明确当前路由归属或新增路由必要性后，才进入最终活动清单。最终遍历分母为“52 条基线路由＋本轮明确采纳并已注册的新增路由”，报告必须同时给出基线分母和最终分母，禁止用 52/52 掩盖已确认但未纳入的产品功能。

明早目标是在用户授权开始执行后，交付一套连接 `https://backend-api.ddxcjp.cn/`、能够在 MuMu 中从认证入口开始遍历的 UniApp 测试版本。最终活动清单中的页面必须可进入、可返回、无白屏和死路；后端已有且合同可用的动作必须调用真实接口，后端确实没有可靠 operation 的动作必须显示“服务暂未开放”或同义的明确状态，不得用 mock、fixture、timer、本地数组写入或假成功伪装闭环。

测试版本不等同于正式发布版本。发布签名、正式域名 CORS、后端未实现合同和真实支付等外部条件可以保留为发布阻塞，但必须提供失败门禁、复现证据、解除条件和继续步骤。

“全量”按五个互不替代的层级报告，禁止把较低层通过写成整个产品完成：

1. **产品库存覆盖**：52 条当前基线路由、已批准新增路由、60 个设计文件、78 条参考活动路由、1 条注释路由声明、7 个未注册参考页面文件和 531 个参考媒体资产均有稳定 ID、候选池或书面去向；资产候选池覆盖不等于逐文件批准复用。
2. **路由结构遍历**：某候选包中的已注册活动路由可进入、可返回、无白屏和死路；这只证明结构可遍历。
3. **实时接口迁移**：单个动作的合同、权限、请求、响应、刷新和重进闭环均完成，并通过引导式真实设备实时验收；当前没有可证明自动操控设备与断言业务结果的完整 E2E harness，因此不使用“自动 live E2E”表述。
4. **明早最低候选**：存在可追溯的冻结候选，当前 7 个直接 `appApi` consumer 的主链结果、其余页面的数据模式、参考甄别结论和精确剩余项齐全；完整九小时窗口的目标还包括 52 条基线路由结构结果。若有效窗口不足或结构遍历未完成，未跑路由必须记 `NOT_RUN`，本层不得冒充达成。
5. **整个产品完成**：所有已批准产品动作均达到产品完成条件；任一必需动作仍为关闭、半成品、未运行或合同阻塞时，整个产品不得标记完成。

完整九小时窗口的可靠目标是第 1、2、4 层和可在时间窗内诚实完成的第 3 层；窗口缩短时第 1 层与精确剩余项仍必须交付，第 2、3、4 层按实际结果报告，不承诺在一个夜间窗口内把全部 52 页与所有参考候选都迁成 LIVE。不得为了追求数字把路径拼接、宽 DTO 直传、页面内 fixture、timer 提示、诚实关闭页或单一成功样例提前标记为产品完成。

## 三、已确认口径

- 当前源码基线由用户在 2026-07-23 手动拉取最新 `main` 后提供。本轮及后续执行均不进行任何 Git 操作，也不读取或写入 HEAD、分支、dirty、提交哈希作为实施前置；计划中的旧提交哈希全部视为历史记录，不再代表当前基线。
- 第一参考源为 `C:\Users\Rain\Desktop\job\app设计`，当前只读清单为 59 张 PNG 和 1 份 PDF。项目内 `docs/design/references/产品参考原稿` 与其中 59 个同名文件 SHA-256 一致；源目录新增 `思维导图.png`，本轮只把它作为规划证据，不在用户确认前复制或归档。
- 第二参考源为 `C:\Users\Rain\Desktop\job\Jiapu-App`。第一轮只读盘点确认其 `pages.json` 有 79 个 `path` 文本，其中 `pages/index/vertical-swiper/vertical-swiper` 整段已注释，故活动路由为 78 条；另有 79 个 Vue 文件、6 个 NVue 文件、7 个未注册页面文件和 113 个旧 API wrapper。未安装依赖、未运行、未构建、未修改。它使用旧技术与旧接口封装，只能证明候选页面、动作和状态存在，不能证明当前后端合同可用。
- 用户已明确允许把第二参考源中的图标、插画、背景等资产作为复用候选。该授权只改变“可以逐文件甄别”的边界，不代表整目录批准，也不证明第三方/商标素材的来源或平台规范；任何资产仍须绑定已批准 PA、页面和状态，并逐文件通过来源、隐私、旧品牌、格式、视觉、无障碍和性能门禁。
- 产品目标以用户对当前项目的明确需求为第一优先；接口路径、方法、字段、权限、状态码和失败语义以当前真实后端合同与可复现响应为准；当前项目架构、安全和国风视觉决定落地方式；截图和已完成参考项目排在最后，只作候选证据。
- 唯一后端为 `https://backend-api.ddxcjp.cn/`，今晚联调使用 remote 模式。
- 已提供有效测试账号；账号凭据只用于本机联调，不写入源码、测试、文档、日志或 Git。
- 规划前在 2026-07-23 曾以标准 JSON 观察到密码登录和 `/captcha/challenge` 返回 HTTP 200，challenge 摘要为 `TIANAI/SLIDER`；后端可识别版本未留存，敏感响应不进入规划。该记录只解释此前因命令行 JSON 引号破坏得到的空体 500，不属于本轮 `LIVE_VERIFIED` 或 `PASS`。收到“开始执行”后仍须对冻结的线上合同和部署重新取证。
- 密码登录、短信登录、注册、忘记密码都必须显示并完成 TAC。密码登录接口不接收 `validToken`，滑动成功只作为客户端强制前置；短信发送接口必须消费对应场景的 `validToken`。
- 只有用户明确说“开始执行”后才允许操作 MuMu，并把实机画面、返回路径和交互状态纳入验收；规划确认本身不构成 MuMu 授权。
- 当前 `static` 国风视觉资产、token 和现有页面结构仍是唯一视觉基线；参考项目资产可在逐文件通过门禁后直接复用、裁切重导出或重绘，不能反向改变已批准产品动作，也不能把旧整页红色主题、旧组件或旧样式一并迁入。
- 允许测试账号创建带“联调测试”标识的家谱、成员、申请、动态、文章、相册、礼仪、备忘、功德和反馈等测试数据。
- 不删除已有真实数据；无人值守期间不执行支付、换绑手机号、注销账号或不可逆操作。修改密码若经人工窗口测试，结束后恢复约定密码。
- 本轮不执行任何 Git 命令或 Git 写操作；源码同步由用户自行负责。

## 四、单页完成定义

一个页面只有同时满足以下五项才标记为完成：

1. 从真实业务入口可进入，系统返回键、页面返回按钮和根页面切换行为正确。
2. 后端已有操作使用真实接口，路径、方法、请求字段、响应字段和身份上下文与 Apifox、线上文档及真实响应一致。
3. 正常、加载、空数据、失败、无权限和提交中状态完整；写操作另有校验、重复点击保护、成功、明确失败和结果未知处理。
4. MuMu 实际画面没有白块、文字截断、控件错位、默认原生底色或不可点击区域；普通内容、长内容和状态页均可阅读。
5. 页面对应的 mapper/runtime 测试、静态合同、编译检查和实机检查均通过。

页面内存在按钮不等于功能完成。每个主动作还必须验证“入口人物或对象正确 → 参数身份正确 → 权限来自可靠合同 → 请求结果可判定 → 返回后源页面刷新为服务端事实 → 重进页面仍一致”的跨页闭环；其中任一环仍依赖 fixture、旧参考接口、timer 或本地数组写入时，该动作不得标记完成。一个页面有多个主动作时逐动作记状态，不能用一个成功动作覆盖其他未完成动作。

自动脚本通过不能替代实机视觉合格，单张静态截图也不能替代接口与交互合格。

每个动作必须同时记录四个正交字段，禁止用一个“通过”覆盖不同含义：

| 字段 | 允许值 | 判定用途 |
| --- | --- | --- |
| `contractState` | `LIVE_VERIFIED`、`DECLARED_UNVERIFIED`、`CONTRACT_CONFLICT`、`MISSING_OPERATION`、`NOT_APPLICABLE` | 当前后端合同及真实部署证据；纯本地权威内容用 `NOT_APPLICABLE` |
| `dataMode` | `LIVE`、`LOCAL_PREVIEW`、`CLOSED` | 页面当前从哪里取得或是否允许提交数据；唯一 owner 的正式本地静态内容可为 `LIVE` |
| `checkResult` | `PASS`、`FAIL`、`EXPECTED_BLOCKED`、`NOT_RUN`、`INFRA_ERROR` | 某一次合同、测试、构建或实机检查的结果 |
| `productCompletion` | `COMPLETE`、`PARTIAL`、`BLOCKED`、`NOT_APPLICABLE` | 用户所需产品动作是否真正闭环 |

`CLOSED` 页面的关闭文案、返回路径和无假成功检查可以得到 `checkResult=PASS`，但必需动作仍须记 `productCompletion=BLOCKED`；不能由此把页面或产品写成完成。已知合同门禁脚本只有在“非零退出＋精确 `... BLOCKED` 标记”同时成立时才记 `checkResult=EXPECTED_BLOCKED`，它与关闭页行为检查的 `PASS` 不是同一结果。`LOCAL_PREVIEW` 最多为 `PARTIAL`。只有已批准动作在 LIVE 模式完成权限、请求、结果确认、刷新和重进闭环时，动作才可为 `COMPLETE`。

汇总规则固定为：

1. 动作逐项保留四字段，不取平均值。
2. 页面另报 `structuralCheck` 和 `productCompletion`；任一必需动作 `productCompletion=BLOCKED`，页面产品完成度即 `BLOCKED`；没有 BLOCKED 但存在 `productCompletion=PARTIAL`，或必需检查 `checkResult=NOT_RUN`，页面最多为 `PARTIAL`。
3. 域与整个项目只按已批准必需动作向上汇总；出现 `BLOCKED` 即不得宣称完成，全部为 `COMPLETE/NOT_APPLICABLE` 才能标记域或产品 `COMPLETE`。
4. 每个 `checkResult` 同时记录首次结果；允许重试时另记重试结果，不覆盖首次失败。

## 五、接口判定和实现规则

### 5.1 Apifox 桌面端优先的合同发现门禁（本轮新增硬约束）

导出的 `APP.openapi.yaml`、`APP.openapi.json` 和线上 `/v3/api-docs` 均可能缺少 Apifox 工作区中已经维护、但未导出的接口；它们只能作索引和交叉核验，绝不能作为“接口不存在”或“接口完整”的结论。每个受影响动作在写代码、关闭入口、补测试或判定 `MISSING_OPERATION` 前，必须先在用户已打开的 **Apifox 桌面端**逐项只读核对：

1. 所属目录、接口名称、HTTP 方法和完整路径；
2. 鉴权方式、必填请求头、路径/查询/请求体字段及类型；
3. 成功与失败响应示例、业务码、分页/ID wire 和权限语义；
4. 是否存在同一业务动作的补充接口、前置接口或结果查询接口；
5. 与导出文档、当前 `utils/api.js`、参考项目或真实请求不一致之处。

核对结果须以“动作 → Apifox 证据 → 当前部署实测 → 结论”写入临时脱敏账本；不得记录 Token、手机号、验证码、TAC proof、邀请口令或原始敏感响应。Apifox 与导出文档不一致时，以 Apifox 的业务定义为先导，并用真实部署响应复核 wire/权限/失败语义；两者仍不能证实时标为 `CONTRACT_CONFLICT` 或 `DECLARED_UNVERIFIED`，不得凭导出缺项关闭功能。只有 Apifox 也不存在、且经目录/关键词/相邻业务链检索留证后，才可标记 `MISSING_OPERATION`。

#### 5.1.1 本轮 Apifox 只读核对记录（2026-07-23 晚）

下表只记录已在用户打开的 Apifox 桌面端逐页读取到的声明；尚未通过测试账号取得同一部署的脱敏真实响应，故均不得写成 `LIVE_VERIFIED`。

| 动作/对象 | Apifox 桌面端声明 | 当前结论 |
| --- | --- | --- |
| 世系树读取 | `GET /genealogy/app/genealogies/{genealogyId}/lineage/tree`，`genealogyId` 为必填 `int64` 路径参数，APP `clientId` header 必填 | 路径与当前读取 owner 一致；ID wire 和权限投影仍待实测，`DECLARED_UNVERIFIED` |
| 人物详情 | `GET /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}`，两个路径 ID 均为必填 `int64`，响应为 `LineagePersonResult` | 路径与当前读取 owner 一致；`DECLARED_UNVERIFIED` |
| 人物新增/编辑 | `POST /genealogy/app/genealogies/{genealogyId}/lineage/persons` 与 `PUT /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}` 均使用统一人物 body；`name` 必填，`sex` 仅说明“建议使用系统字典值”，`avatarOssId` 只能来自统一上传，`sortOrder` 仅说明“数值越小越靠前”。已以“字典”“性别”检索 APP/PC 目录，均未发现可供 APP 消费的枚举 operation | 首人/编辑可继续按 body 收紧；性别字典、上传闭环和单人排序的并发语义未证实，不能虚构枚举或把 `sortOrder` 当原子排行 |
| 新增父母/子女/兄弟姐妹/配偶 | 已分别声明 `POST .../parents`、`POST .../children`、`POST .../siblings`、`POST .../spouses`，均返回 `LineagePersonResult` | 原来按导出文档作出的“无 operation”结论无效；关系方向、性别字典、冲突、权限、结果未知恢复尚待实测，先列为 `DECLARED_UNVERIFIED`，不得以本地成功替代 |
| 统一文件上传与人物头像 | `POST /genealogy/app/files/upload`，APP `clientId` header 必填，`multipart/form-data` 仅有必填 `file`；返回 `ossId`、`url`、`thumbUrl`、`fileName`、`originalName`。树与人物详情只声明 `avatarOssId`，未声明可重进读取的头像 URL/file projection | 上传本身为 `DECLARED_UNVERIFIED`；不得把 `avatarOssId` 拼接为 URL，也不把一次上传响应 URL 持久化成资料事实。T01 使用确定性国风默认头像；真实头像显示仍等待文件读取投影与真实重进验证 |
| 已登录密码修改 | `PUT /genealogy/app/auth/password`，要求鉴权与 APP `clientId`，body 为 `oldPassword`、`newPassword` 两个 32 位 MD5 字段 | 与 A05 的无登录态 `PUT /genealogy/app/auth/password/reset` 不是同一 owner；M04 已按独立 owner 接线，未发生本轮真实 mutation，仍为 `DECLARED_UNVERIFIED`，人工恢复窗口验证前不得标记完成 |
| 已登录手机号换绑 | `PUT /genealogy/app/auth/phone`，要求鉴权与 APP `clientId`，body 为 `clientId`、新 `phone`、四位 `smsCode`；通用短信发送接口声明允许 `APP_PHONE_CHANGE`，但前置 `validToken` 需先完成验证码中心 | 当前 profile 响应未声明可安全消费的手机号 DTO，且真实 TAC/短信需要人工窗口；M05 不猜字段、不静默发码或换绑，保持人工 `DECLARED_UNVERIFIED` |
| 已登录退出 | `DELETE /genealogy/app/auth/logout`，要求鉴权与 APP `clientId`，无 body，响应 `RVoid`/`data:null` | M10 已接严格 REMOTE owner；当前未发真实退出 mutation，仍为 `DECLARED_UNVERIFIED`。本机退出与服务端撤销确认分开记录，不能把前者写成后者 |
| 家族圈列表、正文详情与发布 | 列表：`GET /genealogy/app/genealogies/{genealogyId}/feeds`（`ListResult`）；详情：`GET /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}`（`ObjectResult`）；发布：同一路径 `POST`（`ObjectResult`）。三者均需鉴权与 APP `clientId`，路径 ID 均为 `int64`。发布 body 仅明确 `feedContent` 非空必填；`feedType` 默认 `text`、`mediaOssIds` 为英文逗号分隔 OSS ID、`sortOrder` 默认 `0`、`status` 默认正常 | 列表只见 `property1/property2` 通用项，正文详情和发布也未声明页面可消费 DTO；F01 已删除本地列表，F03 正文不猜字段。F02 只发送 `feedContent`，且只有严格成功信封后才显示已提交；不能把泛型响应当作列表条目或已完成验收；三者均为 `DECLARED_UNVERIFIED` |
| 家族圈一级评论 | 读取：`GET /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}/comments` 返回 `FamilyFeedCommentView[]`；提交：同路径 `POST`，`commentContent:string` 必填且最多 1000 字，`parentCommentId:int64|null` 可选。读取 item 已声明 `commentId/genealogyId/feedId/appUserNickName/commentContent/replyCount/createTime` 等字段 | F03 已删除本地动态/评论 fixture；读取仅展示 `commentId`、昵称、内容、回复数和创建时间的已声明映射；提交只发送 `commentContent`，成功后重新读取服务端列表 | 客户端已接线，但未取得真实登录态响应或人工可观察的提交结果；仍为 `DECLARED_UNVERIFIED`，正文详情 DTO 缺失不影响评论 owner 的独立核对 |
| 谱文列表、详情与创建 | 列表：`GET /genealogy/app/genealogies/{genealogyId}/articles`；详情：`GET .../articles/{articleId}`，均为通用响应。创建：`POST .../articles`，已声明 `articleTitle/articleContent` 必填，`categoryId/articleSummary/coverOssId/authorName/sortOrder/status` 可选 | F04/F05 已删除本地文章、分类、搜索和正文展示，等待稳定 item/详情 DTO；F06 只发送 `articleTitle/articleContent`，无分类 ID 来源时不发送分类。编辑需要可靠详情/文章 ID 来源而关闭 | 创建客户端已接线但未实测，列表/详情/编辑仍为 `DECLARED_UNVERIFIED`；不得用本地预览或泛型成功响应冒充谱文展示闭环 |
| 帮助文章列表 | `GET /genealogy/app/help-articles`，Apifox 显示鉴权、`clientId`（带默认值）与通用 `ListResult`，`data` 为未声明字段的 object 数组；另有详情 endpoint，但尚未作为当前页面 owner 读取 | M06 需要稳定的分类、标题与纯文本正文；当前声明仍只有 `property1/property2`，不能把硬编码 FAQ 冒充远端帮助内容。继续保持本地说明与 M07 反馈入口，远端帮助读取为 `DECLARED_UNVERIFIED` |
| 消息通知列表与已读 | 列表：`GET /genealogy/app/notifications`，鉴权与 APP `clientId` 必填，通用 `ListResult` object 数组；单条已读：`POST /genealogy/app/notifications/{notificationId}/read`，`notificationId:int64`、鉴权与 APP `clientId` 必填、无 body、`VoidResult/data:null`。目录还声明“全部标记已读” | 未发现通知详情读取 operation，列表没有类型、目标、正文或稳定 ID 的消费 DTO；N01/N02 不能由通用数组猜业务跳转，未读不能由分页长度推断。没有登录态和可控通知种子时不发送任何已读 mutation，读取/已读均为 `DECLARED_UNVERIFIED` |
| 我的家谱列表 | `GET /genealogy/app/genealogies/mine`，鉴权与 APP `clientId` 必填，通用 `ListResult` object 数组 | G01 需要稳定的家谱 ID、名称、角色与上下文能力；Apifox 当前仍只给出 `property1/property2`。不把响应存在误记为工作区/切谱闭环，保持 `DECLARED_UNVERIFIED` |
| 相册与图片 | 相册列表：`GET /genealogy/app/genealogies/{genealogyId}/albums`，`genealogyId:int64`、鉴权与 APP `clientId` 必填，通用 `ListResult`。创建 body 仅可安全使用 `albumName`；图片写入要求既有 `ossId` | F07 已删除相册 fixture，创建仅发送 `albumName` 并等待成功信封；F08 已关闭无 DTO 的照片展示；F09 已删除 mock 图片和预览，等待文件上传 owner、真实 OSS 回执和访问 URL 投影。创建待真实响应核验，其他展示/上传为 `DECLARED_UNVERIFIED` / `BLOCKED_BY_MEDIA_OWNER` |
| 备忘录 | 列表：`GET /genealogy/app/genealogies/{genealogyId}/memos`，`genealogyId:int64`、鉴权与 APP `clientId` 必填，响应为通用 `ListResult`。新增：同路径 `POST`，body 明确 `memoTitle` 必填；`memoContent`、`remindTime`、`completed`、`mediaOssIds`、`sortOrder`、`status` 可选，其中 `mediaOssIds` 为逗号分隔 OSS ID。目录另有详情、修改、删除动作 | R10 已删除列表 fixture，创建只发送 `memoTitle/memoContent/remindTime`；完成状态、媒体、排序、状态无来源不发送，详情/修改/删除因无 DTO/ID 来源关闭。创建待真实响应核验，整体仍为 `DECLARED_UNVERIFIED` |
| 成长记录 | 列表：`GET /genealogy/app/genealogies/{genealogyId}/growth-records`，`genealogyId:int64`、鉴权与 APP `clientId` 必填，响应为通用 `ListResult`。新增：同路径 `POST`，body 明确 `recordTitle` 必填；`lineagePersonId:int64`、`recordType`、`recordContent`、`recordDate`、`remindTime`、`mediaOssIds`、`sortOrder`、`status` 可选，其中 `mediaOssIds` 为逗号分隔 OSS ID。目录另有详情、修改、删除动作 | R08 已删除列表 fixture，创建只发送 `recordTitle/recordContent/recordDate`；人物绑定、类型、提醒、媒体、排序、状态无来源不发送，详情/修改/删除因无 DTO/ID 来源关闭。创建待真实响应核验，保持 `DECLARED_UNVERIFIED` |
| 功德记录 | 列表：`GET /genealogy/app/genealogies/{genealogyId}/merit-records`，`genealogyId:int64`、鉴权与 APP `clientId` 必填，响应为通用 `ListResult`。新增：同路径 `POST`，body 的 `donorName`、`meritTitle` 必填；`meritType`、`meritContent`、`amount:double`、`meritTime`、`sortOrder`、`status` 可选。目录仅见删除，未见详情或修改 | R 功德列表及新增响应尚无稳定页面消费 DTO；不可把当前路径与参考项目的人情/贺礼混为一谈。未在无登录态下发送新增或删除 mutation，保持 `DECLARED_UNVERIFIED` |
| 祭祀与祭祀献礼 | 祭祀列表：`GET /genealogy/app/genealogies/{genealogyId}/ceremonies`，通用 `ListResult`；创建：同路径 `POST`，`ceremonyType`、`ceremonyTitle` 必填，`ceremonyDesc`、`ceremonyTime`、`location`、`coverOssId:int64`、`sortOrder`、`status` 可选。献礼列表：`GET /genealogy/app/genealogies/{genealogyId}/ceremonies/{ceremonyId}/gifts`，两个路径 ID 均为 `int64`；新增：同路径 `POST`，`giftAmount:double` 必填，`giverName`、`giftMessage` 可选。上述均要求鉴权与 APP `clientId`，目录还声明祭祀详情/修改、删除活动和删除单条祭品 | 祭祀和献礼均有专属父对象与语义；它们不是人情簿，也不是可发放/绑定的贺礼邀请。列表/新增响应仍无稳定页面 DTO，且未在无登录态下发送写入或删除请求，整体保持 `DECLARED_UNVERIFIED` |
| 亲友记录 | 列表：`GET /genealogy/app/genealogies/{genealogyId}/relative-records`，`genealogyId:int64`、鉴权与 APP `clientId` 必填，响应为通用 `ListResult`。新增：同路径 `POST`，`relativeName` 必填；`relationName`、`eventName`、`eventTime`、`giftAmount:double`、`recordContent`、`mediaOssIds`、`sortOrder`、`status` 可选。目录另有详情、修改、删除动作 | R03/R04 已删除 fixture 列表和详情，创建只提交亲友姓名、关系、事项、时间、金额、备注；媒体/排序/状态无来源不发送。详情/修改/删除无 DTO/ID 来源关闭；创建待真实响应核验，保持 `DECLARED_UNVERIFIED` |
| 人生事件与重要证件 | 已在 Apifox APP/PC 目录分别以“人生”“证件”检索，均未返回对应 operation；相邻的亲友、成长、备忘、功德、祭祀目录不能替代 | R09 没有当前业务 owner，维持硬关闭和可返回状态；`MISSING_OPERATION`，不以本地表单、文件上传或参考项目页面伪造保存 |
| 视频 | Apifox 按“视频”检索只发现 APP 删除视频动作；未发现当前 F10 所需的视频列表、可播放 URL、发布/编辑、评论、点赞或分享闭环 | F10 继续保持非 LIVE；不能把参考短视频动作或单一删除 endpoint 扩展成视频产品能力，`MISSING_OPERATION` |
| 意见反馈 | `POST /genealogy/app/feedback`，鉴权与 APP `clientId` 必填；body 的 `feedbackContent` 必填，`feedbackType` 与 `contactInfo` 可选，响应 `ObjectResult` | 与 M07 的严格 normalizer、POST owner 和提交状态机一致；静态/API 冒烟已通过，未用测试账号提交真实反馈，故远端结果仍为 `DECLARED_UNVERIFIED` |
| 当前用户资料 | `GET /genealogy/app/auth/profile`，鉴权与 APP `clientId` 必填，响应 `ObjectResult`，当前仅给出 `property1/property2`；目录另有 `PUT /genealogy/app/auth/profile` | M01—M03/M05 需要稳定的账号、资料与手机号投影；不能从通用对象猜字段或让资料更新覆盖未知字段。读取、编辑与换绑前置均保持 `DECLARED_UNVERIFIED`，M05 另受人工 TAC/短信窗口约束 |
| 微信登录 | 已以“微信”检索 Apifox APP/PC 目录，未返回登录授权、code 交换、回调、会话创建或结果查询 operation | A01 的微信入口不能借参考项目旧接口接通；保持 `MISSING_OPERATION` 关闭候选，是否长期纳入由用户后续确认 |
| 家谱邀请码 | 已以“邀请码”检索 Apifox APP/PC 目录，未返回邀请码签发、校验、直入加入、撤销或结果查询 operation | G/M 的邀请码能力无当前 owner；普通加入申请、成员维护和人物邀请绑定都不能替代，保持 `MISSING_OPERATION` |
| 行政区划搜索 | Apifox APP 目录声明 `GET /genealogy/region/search`：`keyword` 必填，`level` 可选（1 省、2 市、3 区县、4 街道、5 村社区），`limit` 可选；`clientId` header 可选，响应为通用 `ListResult`。2026-07-24 00:51 的只读部署响应为 HTTP/业务码 `200`，服务器时间 `Thu, 23 Jul 2026 16:51:08 GMT`，单条结果含字符串 `regionCode`、`label`、`parentCode`、`ancestors`、`regionName`、`regionLevel`、`regionType` 与 `leaf`；同目录另有下级查询、路径查询与详情 | 此读取 owner 为 `LIVE_VERIFIED`，G03 可消费返回的字符串 `regionCode`，但不能把 `leaf` 推断为可提交能力。非 APP 前缀为唯一业务 owner；当前部署旧 `/genealogy/app/region/search` 虽同响应，仍只记路径并存证据，不作兼容 owner。G03 两次写入及结果未知恢复仍分别按其独立合同判定，不能由该读取验证代替 |
| 邀请绑定 | 已展开“家谱（12）”“家谱成员（6）”全部接口，并以“邀请”“绑定”检索 APP/PC 目录；仅见普通申请/审核和成员维护，无邀请票据、身份绑定、绑定 mutation 或结果查询接口 | `MISSING_OPERATION`；普通申请不能替代邀请绑定，保持诚实关闭 |

### 5.2 通用判定和实现规则

1. Apifox 用于优先发现和判断接口业务用途；线上 `/v3/api-docs` 和真实请求用于确认当前部署路径、字段及故障表现；受保护 OpenAPI 只作离线补充。参考项目 `api/index.js` 中的旧路径、参数和响应处理不属于当前接口证据。
2. 每个动作先进入统一账本。`LIVE_VERIFIED` 只允许用于本轮开始后、绑定后端可识别版本或时间戳的真实证据；受保护 OpenAPI 有声明但未取本轮真实响应时为 `DECLARED_UNVERIFIED`；文档、部署、权限、静态门禁或页面期望冲突时为 `CONTRACT_CONFLICT`；没有可靠 operation 时为 `MISSING_OPERATION`。operation 是否存在另记为证据字段，不是第五种状态；同一最小动作同时“有声明但已知冲突”时必须取更严重的 `CONTRACT_CONFLICT`，不得写两个 `contractState`。不得把接口名相似、历史 HTTP 200 或参考项目成功写成已接通。
3. 先列出当前批次的“当前页面 → 用户动作 → 对象身份 → 权限来源 → 方法 → 完整路径 → 输入 → 页面消费字段 → 成功/失败/结果未知表现 → 刷新确认”，再写该批次失败测试，随后实现。
4. 只有 `LIVE_VERIFIED` 动作允许记为 LIVE。`DECLARED_UNVERIFIED` 先做只读或可控测试验证；`CONTRACT_CONFLICT` 记录冲突并失败关闭；`MISSING_OPERATION` 保留完整视觉和返回路径，动作显示服务未开放，不伪造保存、发送、上传、支付、邀请、绑定、排行或审核成功。
5. 4xx、5xx、空体、缺字段或身份错配必须展示真实失败，不回退 mock。参考项目成功、受保护 OpenAPI 存在 operation 或当前页面已有 `appApi` 方法，都不能单独解除这一规则。
6. 单个接口排查超过 15 分钟仍无本机解决路径时，立即记录复现证据并继续其他页面，避免阻塞整夜。
7. 每个合同只有一个 owner；新合同落地时同步移除同类 fixture、旧入口、兼容读取和过时测试期望。若一个参考动作无法明确归入现有 owner，先判定是否需要新 owner，不能塞进名称相近的旧接口。
8. 真实写操作仅限测试账号和本轮新建、带“联调测试”标识且已登记 ID 的对象。GET 可按退避规则重试；写操作只有接口明确提供幂等键且结果可判定时才允许重试，超时、5xx、断线或进程终止造成结果未知时立即停止该动作并查只读结果。
9. 新增全域 P0 ID 门禁：`genealogyId`、`personId`、`memberId`、`appUserId`、父母/配偶/子女引用、内容 ID、文件 ID 与 `avatarOssId` 等 `int64` wire 必须验证服务端以十进制字符串返回且请求端接受十进制字符串。任何超出 JavaScript 安全整数的 JSON number 一经解析已不可恢复，禁止再转字符串继续使用；相关读写统一记 `CONTRACT_CONFLICT` 并关闭，直到同一 ID owner 在 schema、运行时、validator 和请求端同时收紧。
10. 三个现有静态门禁本身与已确认规划/快照冲突，收到“开始执行”后的第一项测试工作是先按唯一 owner 重订失败期望，再实施业务：`auth-tac-openapi-contract.ps1` 不得再要求密码登录上传 `validToken`；两个 G03 门禁不得再要求未声明的原子 bootstrap、错误的 `/genealogy/app/region/search` 或不存在的结果查询；`help-center-openapi-contract.ps1` 与 M06 统一为“完整列表是唯一远端 owner、文章阅读由列表项投影承接”，不新增独立远端详情 owner。门禁目标路径不能写成当前 operation，也不能因旧测试期望而覆盖真实后端合同。

每条路由的执行记录至少包含：`route`、真实入口、必填参数、测试角色/种子、四个正交状态字段、参考来源、候选动作、六类甄别结论、接口 owner、权限 owner、主动作、返回结果、页面状态证据、LIVE 请求响应证据、候选包 ID、MuMu 结果和 blocker。

每次汇总必须同时列出这些分母，任何一个都不能被“52/52”代替：

- `baselineRoutes=52`；
- `approvedNewRoutes`（规划确认采纳、但不一定已注册）；
- `registeredRoutes`（候选包实际注册）；
- `traversedRoutes`（绑定该候选包完成结构遍历）；
- `referenceEvidenceRecords=341`，以及六类证据结论数量：直接采用、改造后采用、仅参考交互、后端缺失暂关、冲突舍弃、待用户确认；
- `productActionsTotal=166`、`requiredActions=111`、`candidateActions=55`、`approvedCandidateActions=0`；产品完成分母固定为附件 PA-001—PA-166 中的 111 个必需动作；
- `liveCompletedActions`、各动作的 `productCompletion`，以及按必需/可选、A/G/T/F/R/N/M/共享 owner 的分组结果；
- `inventoryTests`、`scheduledTests`、`executedTests`、`notRunTests`、`timedOutTests` 与各 `checkResult` 数量。

## 六、执行批次与相对时间

以下计时只在用户明确说“开始执行”后启动。在此之前，参考映射与产品取舍必须已在权威附件中完成并由用户确认；执行第 0 批只能重算清单/哈希、冻结确认结果，不得再临场作重大产品决策。

### 6.1 时间模型与降级规则

- `T_start`：收到用户“开始执行”的北京时间。
- `T_due`：用户已更新为 2026-07-24 08:00（北京时间）。
- 正常候选周期为 `T_start + 9h`，但不得越过 `T_due`；要获得完整九小时窗口，最迟须在 2026-07-24 01:00 开始。
- `T_test_cutoff = min(T_start + 6h, T_due - 3h)`。截止前必须完成本轮测试调度和首个候选尝试；截止后反向保留 0.5 小时候选修复/冻结、1.75 小时最终实机和 0.75 小时缓冲，不能用缩短窗口挤占这三段。
- 首个候选固定预留 `firstCandidateWorstCase=30m`：2 分钟重算输入清单并准备全新输出根、15 分钟构建、3 分钟生成输出清单/指纹、7 分钟部署或安装、3 分钟设备身份确认。测试只有在 `now + testWorstCase + firstCandidateWorstCase <= T_test_cutoff` 时才允许启动；全部已调度测试收口后，首个候选只有在 `now + firstCandidateWorstCase <= T_test_cutoff` 时才允许启动。任何在途进程都不得跨越 `T_test_cutoff`：意外超时时在截止点终止本轮进程树，具体测试记 `timedOutTests/INFRA_ERROR`，候选尝试记基础设施失败，然后一次性冻结计数。不得以“已经开始”为由占用后续三小时。
- `T_start >= T_due` 时不启动本轮执行，先请用户重新确认截止时间；`T_test_cutoff <= T_start` 时不启动代码、测试或构建批次，只交付预检与“无冻结候选”的精确原因。
- 有效窗口不足 9 小时时不压缩人工认证和上述尾部三段：6—9 小时优先削减 F/R/N/M 的新增 LIVE 扩展；3—6 小时只在 `T_test_cutoff` 前做 P0 合同/安全修复、七个现有 `appApi` consumer 和首个候选尝试；不足 3 小时时不启动无法留出验证时间的代码批次，只做可完成的预检、现状与报告。所有被削减项记 `NOT_RUN`，不得改写成通过。
- 九小时只是一次可靠候选周期，不是整个产品的完成承诺；明早报告必须把第 2 节五个层级分别结论化。

### 6.2 正常九小时批次

#### 第 0—0.5 小时：冻结基线、合同、角色与夜跑清单

- 以用户手动拉取的当前文件为源码基线，不执行 Git；重算 52 条路由、60 个设计文件、78 条参考活动路由、1 条注释路由声明、7 个未注册参考页面文件、531 个参考媒体资产和权威附件覆盖率。
- 在任何“接口缺失”、接口接线、写操作或页面关闭结论之前，先按第 5.1 节在 Apifox 桌面端完成当前批次动作的目录、请求、响应、鉴权和相邻链路检索；把未导出的接口和与导出文档不一致的字段列入脱敏合同账本，再决定实测、实现或阻塞。不得跳过此步骤直接按导出 OpenAPI 结论推进。
- 冻结线上 `/v3/api-docs` 的取证时间与可识别版本；受保护 OpenAPI 保持只读。接口或参考源相对已确认附件发生变化时，只记录差异并暂停受影响动作，不静默改变产品范围。
- 先在仓库外的本机临时验收目录建立唯一 `role-seed-matrix.json` owner：只记录脱敏角色别名、角色类型、对象类型、十进制字符串对象 ID、来源/创建时间、允许的动作和清理责任；不得写账号、手机号、Token、OTP、TAC proof 或其他凭据。普通成员、家谱所有者或管理员、第二账号，以及测试家谱、人物、申请、内容和媒体均由该矩阵登记。缺少角色、跨账号对象或收码号码时，对应动作标记测试数据阻塞。
- 机械生成当前 204 个可执行脚本的 manifest 基表和显式 override，并冻结 `baselineInventoryTests=204=150 PS1+54 JS`。`tests/night-run.ps1` 与 `tests/night-run.manifest.json` 是编排入口/清单，不计测试项；实施中为本轮变更新建的每个可执行测试都记入 `newExecutableTests` 并追加到 manifest，最终 `inventoryTests=baselineInventoryTests+newExecutableTests`。每项先按第 6.3 节确定风险层级、依赖、是否远端写入及预期结果；第 0 批只校验已确认的 `PA-xxx` 产品动作和来源反链未漂移，禁止重新归并、拆分或改变产品动作分母。任何参考资产复制前另建逐文件 `RAxxx` 记录；资产选择可以在已批准 PA 内发生，但不能新增产品动作或跳过来源门禁。
- 在仓库外的本机临时验收目录准备候选输入清单模板。每次候选构建/部署前，对项目自有源码、配置、资产和 lockfile 重算规范化逐文件 SHA-256；明确排除 `.git`、`unpackage`、依赖/工具缓存、日志、截图、报告和清单自身，并另记 HBuilderX、插件及解析后依赖版本。输入清单的规范化与第 6—6.5 小时输出清单使用同一算法，且不含凭据。
- 检查 remote 配置、网络、磁盘、HBuilderX、MuMu 状态和测试账号，但此时不把任何历史运行结果算入本轮。

#### 第 0.5—1.75 小时：A 认证人工窗口与会话

- 本轮先完成密码登录页、账号密码提交、TAC challenge 展示、challenge/verify 合同、会话保存与 G01 跳转的可自动化验证；密码登录的真实拖动、短信登录、注册和找回密码的短信/TAC 全部保留为早晨人工回归，四条流程不互相替代。
- 不循环发码、不破解或绕过 TAC。测试账号凭据只保留在当前安全会话，绝不写入仓库、文档、截图或日志。
- 人工完成后验证页面重进和应用重启的会话；不记录 token。会话失效时停止身份写操作并熔断，不以临时接口 token 冒充认证页面验收。

#### 第 1.75—4 小时：A/G/T P0 主链与 T01/T03

- 按 A01 → G01 → G05 → T01、G03 两阶段建谱、G06/G08—G12、T03—T08推进；每个动作先过合同、ID、权限和结果未知门禁。
- T01 优先完成头像人物卡、选择态和唯一人物面板；十入口逐项落到 T03/T04/T05/T06/邀请流程。合同不足的入口只允许诚实关闭，其关闭检查可 PASS，但 T01 产品完成度仍为 BLOCKED。
- T03 始终从未完成半成品起算；已有 normalizer、fixture 或旧门禁不得计完成。
- 本批时间用尽即停止扩张并留下可验证断点，不把 T01 大型布局和十条真实写链压缩成单一“完成”。

#### 第 4—4.5 小时：F/R/N/M 风险优先扩展

- 优先处理已经有当前后端声明、且能在剩余时间内完成闭环的读取和小型写入；无视频完整链、人生事件、重要证件、通知详情、支付/提现等保持诚实关闭。
- 换绑、注销、支付、所有者转移、退出家谱、删除真实内容等敏感动作不在无人值守阶段执行。
- 每域更新动作分母与四字段，不要求为了“全绿”把全部参考候选临时实现。

#### 第 4.5—6 小时：分层测试、首个候选与全量硬截止

- 唯一测试清单 owner 为执行时建立的 `tests/night-run.manifest.json`，唯一入口为 `tests/night-run.ps1`；二者只在用户说“开始执行”后创建。manifest 逐项明确脚本、解释器、排序、120 秒默认超时、依赖、预期退出码、预期标记、领域、是否允许写远端及检查点；当前 12 个 allowlist 项必须各自冻结完整且唯一的 `expectedBlockedMarker`，不得用包含匹配；4 个 JSON 数据文件不是可执行脚本。
- 测试分三层：`T0` 为 P0 安全/合同、路由、编译及本轮实际修改 owner 的门禁，是形成候选的必要条件；`T1` 为 A/G/T/F/R/N/M 受影响域的其余 mapper/runtime/合同回归；`T2` 为未受影响域和历史扩展检查。204 个基线项与所有 `newExecutableTests` 全部进入 inventory，但只有 manifest 明确列入当轮的项目计入 `scheduledTests`；先执行 T0，再在硬截止前执行 T1，T2 仅在 T0/T1 完成且仍有时间时调度。未调度或未执行项分别如实进入 `notRunTests`，不得把 inventory 数量写成执行数量。
- 一级顺序固定为 T0 → T1 → T2；每层内部再按纯静态/合同 PowerShell → 纯 Node mapper/runtime → 该层编译/专项检查排序，全部已调度测试收口后才形成候选构建。PowerShell 使用 `powershell.exe -NoProfile -ExecutionPolicy Bypass -File <exact-script>`；Node 使用 `node <exact-script>`。无网络、无共享写入且无相互依赖的本地脚本最多 4 个并发 worker；远端、写操作、编译和构建一律串行。单项失败继续下一项并回收子进程，域熔断只跳过同一远端风险动作。
- 当前 150 个 PowerShell、54 个 Node 脚本以及实施中新增的每个可执行测试必须逐一进入 manifest；runner 和 manifest 自身不计测试项。本轮“预期阻塞”只允许以下 12 条精确脚本，并同时要求非零退出和各自精确 `... BLOCKED` 标记；其他非零均为 `FAIL`：`auth-android-accessibility-release-gate.ps1`、`g11-settings-openapi-contract.ps1`、`g12-generation-poem-openapi-contract.ps1`、`genealogy-workspace-openapi-contract.ps1`、`invite-ticket-openapi-contract.ps1`、`join-application-openapi-contract.ps1`、`lineage-openapi-contract.ps1`、`notification-read-openapi-contract.ps1`、`notification-read-state-openapi-contract.ps1`、`phone-change-openapi-contract.ps1`、`profile-openapi-contract.ps1`、`profile-update-openapi-contract.ps1`。已转绿的 `auth-tac`、两个 G03、F 家族圈、M04、M06、M10 与 T03 门禁不得再被列作预期阻塞；M04/M10 的真实 mutation 仍只进入人工窗口。清单冻结前须核对这些脚本的实际退出语义，不能仅因文件含 “BLOCKED” 字样放行。
- allowlist 脚本若本轮变为退出码 `0` 且出现精确 PASS 标记，按 `PASS` 接受并从预期阻塞清单移除；只有非零退出且精确 BLOCKED 标记匹配才是 `EXPECTED_BLOCKED`。退出码与标记任一不匹配均为 `FAIL` 或 runner 错误，不能因历史预期而放行。
- 夜跑在每项结束后原子写入本机临时验收目录中的 checkpoint（脚本、开始/结束、退出码、标记、耗时、首次结果），续跑只从最后完整记录之后开始。总入口退出码固定为：`0`＝无 FAIL/INFRA 且预期阻塞完全匹配；`2`＝测试或合同断言失败；`3`＝构建、部署、安装或设备基础设施失败；`4`＝manifest 漂移、单项超时、测试执行基础设施或 runner 自身错误；同时出现时按 `4 > 3 > 2 > 0` 聚合。单项超时记该测试 `checkResult=INFRA_ERROR` 并进入 `timedOutTests`；无法归到具体测试的 manifest/runner 故障另记 `runnerInfraErrors`，不塞入测试恒等式。任何 `EXPECTED_BLOCKED` 都必须在摘要中单列，退出 0 不等于产品全绿。
- 全部已调度测试按层级收口后，首个候选严格使用第 6.1 节 30 分钟预算与同一构建入口；任一子段超时即本次候选失败，不把失败段的剩余时间转给另一段，也不在 cutoff 前启动第二次首候选尝试。第 6—6.5 小时只负责复用该候选或进行一次受限修复/最终冻结。
- `T_test_cutoff` 是测试调度与首个候选尝试的硬截止；每项按第 6.1 节 `latestStart` 准入，不能在最坏耗时将越过 cutoff 时启动。截止时终止意外仍在途的项目，排队但未启动的已调度项进入 `notRunScheduledTests`，再一次性冻结 `scheduledTests/executedTests/notRunScheduledTests/notRunTests/timedOutTests` 和最终恒等式。T0 未全部取得允许结果或候选无法追溯时，不进入最终实机验收。
- 构建入口固定为仓库根目录与 `.hbuilderx/launch.json` 中的 `uni-app:app-android`。执行前记录实际 HBuilderX CLI 绝对路径、版本、命令、退出码和输出目录；不得把旧 `unpackage` 产物冒充新包。

#### 第 6—6.5 小时：仅修复候选阻塞并冻结最终候选

- 本阶段只能二选一，不得借用后续 105 分钟实机窗口。若首个候选之后源码输入和生成输出均未变化，前 20 分钟内重算输入/输出 manifest 并逐项确认 hash 完全相同，必须复用该候选且不重复构建；随后最多使用 7 分钟部署/安装、3 分钟设备身份确认。若必须修复，前 5 分钟的组合硬上限同时覆盖一次 P0/P1 外科式修复、受影响的聚焦测试和 `sourceManifestSha256` 重算；随后 15 分钟的组合硬上限同时覆盖最终构建、完整输出 manifest 与 `outputManifestSha256`，再用 7 分钟 DBG 部署或 APK 安装、3 分钟设备身份确认，合计正好 30 分钟。任一组合段内的前置工作耗尽预算，后续工作来不及完成时即判该路径失败，不能把清单/指纹移出预算。
- 任一路径在准入时无法按最坏预算于本阶段结束前收口，或任一硬上限内未完成，立即终止本轮启动的进程树、停止继续安装并记退出码 `3/INFRA_ERROR`，交付“无冻结候选”；不得重试、不得压缩身份核验，也不得挤占 MuMu 窗口。
- 候选分两类且必须二选一取得可追溯、可复验的指纹：APK 使用 `APK-YYYYMMDD-HHMM-<apkSha256前12位>`，记录完整 APK SHA-256；HBuilderX 调试部署使用 `DBG-YYYYMMDD-HHMM-<outputManifestSha256前12位>`。两类都绑定 `sourceManifestSha256`、测试 manifest 结果、开始/结束时间、输出目录、应用包名/版本、HBuilderX/插件/依赖版本、部署或安装回执，以及 MuMu 已安装包的包名、版本、签名摘要和安装时间。
- 源码输入与 DBG 输出清单的规范化算法固定为：以各自声明的根目录生成相对路径，路径分隔符统一为 `/`，按相对路径 ordinal 升序，每行写 `sha256<TAB>bytes<TAB>relativePath`，整体使用 UTF-8 无 BOM 与 LF。源码侧沿用第 0 批明确列出的排除集合。DBG 输出根固定为本轮 HBuilderX 新生成的准确输出目录，输出 manifest 存放在根目录之外并递归纳入全部生成文件；输出侧只允许排除存在时的 `Thumbs.db`、`.DS_Store`，且必须逐项记录，除此之外不得排除。`outputManifestSha256` 是完整规范化输出清单的 SHA-256，`sourceManifestSha256` 同理。
- 找不到可重复构建/部署入口、无法取得上述任一指纹或安装结果与指纹不一致时记 `INFRA_ERROR`，明确报告“无冻结候选”，不得进入 MuMu 最终验收。任何代码或生成输出变化都会使旧设备证据失效，必须取得新候选 ID 并重验。

#### 第 6.5—8.25 小时：冻结候选的最终实机验收

- 本阶段 105 分钟固定拆为：前 10 分钟核对已安装身份、冷启动、证据目录和一次故障恢复余量；随后 65 分钟完成“52 条基线路由＋已批准且已注册新增路由”的合计结构遍历，基线路由优先；最后 30 分钟做 P0 实时 smoke。结构遍历开始时计算 `routeBudgetSeconds=floor(3900/registeredRoutes)`（只有 52 条基线路由时为 75 秒），按基线路由优先的冻结顺序给每条路由一次预算；已启动路由超预算记 `FAIL` 并继续，65 分钟到点仍未启动的路由记 `NOT_RUN`。任何新增路由、低优先路由或故障恢复都不得侵占 P0 时段。
- 结构遍历报告基线、已批准新增、实际注册、实际遍历和 `NOT_RUN` 五个分母/结果。P0 smoke 在同一候选上覆盖认证根页 A01、四个主入口 G01/F01/N01/M01、A/G/T P0 主链以及本轮改变的 F/R/N/M 动作；检查上下文、返回、空/错/无权限、重复点击、取消、前后台与迟到响应。更深的状态矩阵在各实现批次持续取证，最终候选至少重复 P0 smoke，旧候选证据不得沿用。
- 本地故障注入只能证明客户端分支，不能证明远端实时接口；真实服务不做攻击性 4xx/5xx/429 压测。所有设备证据绑定候选 ID、分辨率、density、角色和种子。

#### 第 8.25—9 小时：45 分钟保留缓冲与交付收口

- 本时段是保留缓冲，不安排新功能。前面持续写入的报告在此校验四字段、首次结果、分母、熔断、人工项和继续步骤。
- 若前序超时，缓冲只用于恢复、必要重建和最短复验；未完成项分别记清 `checkResult=NOT_RUN`、`productCompletion=PARTIAL` 或 `productCompletion=BLOCKED`，不得混写成一个状态。若缓冲未使用，可增加探索检查，但不得改变冻结候选或既定结论。

### 6.3 测试风险层级与计数规则

测试层级在第 0 批依据文件名、manifest 元数据和本轮人工变更账本机械生成，不依赖 Git diff，也不能由执行者为了赶时间临时降级：

| 层级 | 确定性纳入规则 | 候选门禁 |
| --- | --- | --- |
| `T0` | `compile-audit.ps1`、路由/导航/会话/运行配置/共享 ID 与权限门禁、第 6.2 节预期阻塞 allowlist，以及本轮每个被修改 owner 对应的合同、runtime 和视觉专项 | 全部必须取得 `PASS` 或精确允许的 `EXPECTED_BLOCKED`；否则无冻结候选 |
| `T1` | 与本轮被修改 owner 同域的其余 A/G/T/F/R/N/M mapper/runtime、文档流、状态和响应式回归 | 在 `T_test_cutoff` 前尽量全部执行；未执行项记 `NOT_RUN` 并降低相应域结论 |
| `T2` | 未受影响域、历史扩展、仓库卫生与探索性检查 | 仅在 T0/T1 完成且时间有余时调度；不以 T2 未跑伪装全量测试通过 |

计数恒等式固定为：

- `baselineInventoryTests=204=150 PS1+54 JS`，4 个 JSON 仅作为数据文件，runner/manifest 仅作编排，均不计可执行测试；
- `inventoryTests=baselineInventoryTests+newExecutableTests`，本轮未新增测试脚本时 `newExecutableTests=0`；
- `scheduledTests=executedTests+notRunScheduledTests`；
- `executedTests=passTests+failTests+expectedBlockedTests+infraErrorTests`，其中 `timedOutTests` 是 `infraErrorTests` 的诊断子集，不重复相加；
- `notRunTests=(inventoryTests-scheduledTests)+notRunScheduledTests`。

`runnerInfraErrors`、构建/部署/安装/设备基础设施错误另列，不进入上述测试项恒等式；只要存在任一此类错误，候选和报告仍按对应退出码失败。报告必须同时给出各层级数量、首次结果和重试结果。默认 120 秒只是单项上限，不是预计耗时；四 worker 也不能用理论并发量承诺完整 inventory 必然在 1.5 小时内跑完。冻结候选只宣称 T0 门禁已满足和实际执行范围，不能把 inventory 数量写成“全通过”。

## 七、三人交叉复核

三人固定为主代理和两位只读评审者，主代理是唯一写入者。三人都必须完整检查本规划，不能把范围割裂后只看自己的一部分；为增强对抗性，主代理重点复核产品全量覆盖与参考甄别，评审一重点攻击后端合同、权限和数据闭环，评审二重点攻击执行顺序、时间预算、测试证据和回归风险，然后互相核对对方领域。

规划评审必须在交给用户确认前完成，至少检查：

1. 是否覆盖 A/G/T/F/R/N/M、共享基础和参考候选，而非只覆盖认证或 T01。
2. 每个采纳动作是否有唯一页面 owner、唯一接口 owner、权限来源、状态矩阵和完成定义。
3. T03 是否始终标为未完成，T01 十个入口是否逐项落到真实流程或诚实关闭态。
4. 两个参考源是否逐页面、逐动作、逐接口留有结论，是否误带旧地址、旧字段、旧组件、凭据、日志或视觉。
5. 52 条基线路由与新增采纳路由是否分母清楚，时间预算是否把阻塞、人工项和最小可靠交付说清。
6. 参考资产是否逐文件绑定已批准 PA 和具体页面状态，是否误把用户的候选复用许可解释为整包批准，是否遗漏第三方、隐私、旧品牌、格式、无障碍和性能风险。

任一评审提出有证据的疑点时，主代理必须修改规划或书面保留为待用户确认项；不能以多数票掩盖未解决的合同冲突。实施开始后，三人仍在批次边界复核接口、业务、交互、异常和视觉，不并发写文件，也不把开放式讨论拖入下一批。

本次规划评审已于 2026-07-23 收口：

| 评审角色 | 最终结论 | 已复核证据 |
| --- | --- | --- |
| 产品主审（主代理） | `PASS` | A/G/T/F/R/N/M 七域、共享 owner、52 条 CUR、T01 十入口、T03 半成品、两个参考源 341 条基记录、166 个 PA、状态分离和 531 项资产逐文件门禁完整；当前项目职责没有被参考项目覆盖 |
| 合同评审 | `PASS` | 122 个合同键唯一且 PA 无未定义引用；125 个唯一当前 operation 均可回到 153-operation 只读快照；M08 家谱邀请、G03、TAC、N02、帮助、家族视频与宣传视频 owner 已拆清 |
| 执行评审 | `PASS` | 204 项测试基线与动态 inventory、`latestStart`、首候选 30 分钟预留、最终候选双路径、输出指纹、65 分钟路由预算、退出码和双门禁均可机械执行 |

最终无剩余 P0/P1；评审提出的 P2 也已处理，包括复合来源证据的稳定 `@browse/@comment/@reaction/@share` 后缀。机械结果为：PA-001—PA-166 连续唯一（111 必需、55 候选），初始 42 `PARTIAL`＋69 `BLOCKED`＋55 `NOT_APPLICABLE`；52 条当前路由全部反链；341 条来源基记录均有 PA 或全局去向；两份权威文档无旧计数和表格列错位。

## 八、无人值守边界

- 本节只有用户明确说“开始执行”后生效；此前只允许规划范围内的只读核对和规划文档写入。
- 执行授权生效后，可以继续读取、创建带测试标识的数据、运行测试、构建和操作 MuMu。
- 不循环请求短信，不破解验证码，不使用生产数据做破坏性试验。除用户指定的最终停止通知外不发送外部消息；本轮真正停止时仅向用户已打开的微信“文件传输助手”发送“已经停下了”。
- 不支付、不换绑、不注销、不删除已有家谱或用户内容。
- 后端、测试账号、发布签名或 MuMu 人工验证码成为硬阻塞时，记录：失败门禁、请求与响应、复现步骤、解除条件、恢复后的第一步。
- 用户有新消息时优先处理。只有已经收到“开始执行”后，“准备睡了”才可作为第 0.5—1.75 小时既定认证人工窗口的提前提醒或提前触发；它不改变 `T_start`、不另起第二套时间线，也不能单独授权代码、测试、构建或 MuMu。
- Authorization、手机号、OTP、TAC proof、邀请码和个人资料不得进入报告、截图文件名或仓库日志。原始运行日志和截图放在本机临时验收目录，限制容量并在报告中只引用脱敏摘要。
- TalkBack、系统大字号和无法可靠自动化的原生辅助功能只做可重复的早晨人工项，自动截图不得冒充无障碍通过。

## 九、明早交付物

1. MuMu 中可启动和遍历、且绑定 `APK-*` 或 `DBG-*` 可追溯/可复验指纹、`sourceManifestSha256` 和设备侧安装身份的冻结测试候选；若两类指纹均无法取得，明确交付“无冻结候选”与 `INFRA_ERROR` 证据，不能用旧安装包代替。
2. 52 条基线路由及所有已采纳新增路由的入口和结构结果，并分别报告 `baselineRoutes`、`approvedNewRoutes`、`registeredRoutes`、`traversedRoutes` 与 `NOT_RUN` 路由。
3. 当前页面—动作—接口映射、真实请求结果，以及两个参考源逐页面/逐动作/逐接口的采纳结论。
4. `referenceEvidenceRecords` 与六类证据数量、权威 PA 动作分母、`liveCompletedActions` 和逐动作四字段结果。
5. `inventoryTests`、`scheduledTests`、`executedTests`、`notRunTests`、`timedOutTests`，以及构建/部署和 MuMu 实机验收结果。
6. 本轮实际评估/采用的 `RAxxx` 参考资产清单、来源确认、改造方式、重复 canonical owner、包体影响及逐状态验收证据；未使用的 531 项不冒充已审。
7. 后端阻塞、测试数据阻塞和需要人工复验的精确清单。
8. 明早从登录开始的最短人工回归步骤。
9. 运行元数据：用户确认的源码基线说明、开始结束时间、后端地址与可识别版本、MuMu 分辨率/density、账号角色、各项耗时和熔断记录；不调用 Git 取得 HEAD/dirty 信息，不包含任何凭据。

## 十、规划阶段只读核对记录

| 核对对象 | 当前事实 | 规划结论 |
| --- | --- | --- |
| 当前源码 | 用户确认已手动拉取 2026-07-23 最新 `main`；本轮未执行任何 Git 命令 | 不再沿用旧 HEAD/dirty 断点；以当前文件事实为准 |
| 当前活动范围 | `pages.json` 有 52 条活动路由，`pages` 下有 53 个 Vue 文件 | 52 是最低基线；最终分母还要加入明确采纳的新增路由 |
| 当前数据接线 | `runtimeConfig.mode` 为 `remote`；仅 A01、A04、A05、G01、G05、T01、M07 七页直接消费 `appApi`；40 页直接导入 `data/mock`，28 页含 `setTimeout` | 七页也须逐动作验真；其余页面逐项归类 LIVE/LOCAL_PREVIEW/CLOSED；timer 不能自动等同假成功，也不能逃过甄别 |
| 当前 T03 | 页面已调用 `appApi.getPerson` 的 Apifox 人物详情 owner，具备严格 normalizer、取消控制与无 fixture 回退；测试目录已有静态与 mapper 门禁 | 仍未取得测试账号下的本轮真实人物响应、权限投影、跨页刷新与重进证据；明确为未完成半成品，不得记为 `LIVE_VERIFIED`、页面完成或产品完成 |
| 受保护 OpenAPI | 本地 JSON/YAML 快照为 112 paths、153 operations，只读 | operation 存在仅记 `DECLARED_UNVERIFIED`，仍需对照线上文档和真实响应 |
| “app设计”源 | `C:\Users\Rain\Desktop\job\app设计` 共 59 PNG＋1 PDF；项目归档与 59 个旧文件哈希一致，新增 `思维导图.png` | 作为第一参考源；新图先用于规划，不在确认前复制 |
| 已完成参考项目 | `C:\Users\Rain\Desktop\job\Jiapu-App` 有 78 条活动路由＋1 条注释路由声明、79 Vue、6 NVue、7 个未注册页面文件、113 个旧 API wrapper；使用旧后端封装且没有可用测试脚本 | 作为第二参考源；78 是活动分母，注释路由和未注册文件单列候选；禁止复制其请求层、旧地址、组件和数据模型 |
| 参考项目资产 | `Jiapu-App\static` 有 531 个媒体文件、约 6.45 MiB；声明扩展名为 307 PNG、221 GIF、2 SVG、1 JPG，文件签名实为 311 PNG、217 GIF、2 SVG、1 JPG；已发现 6 个扩展名/MIME 不一致、14 组完全重复、第三方/商标、旧品牌、固定旧文案、示例头像与短视频实验素材 | 用户允许逐文件复用候选；不整目录复制。高价值候选优先看水墨/宗祠、谱书、人物卡边框和中性功能图标；QQ 表情、短视频实验、支付/微信品牌、VIP/奖励、旧 logo 先排除直接复用 |
| 参考映射 | 权威附件逐一登记 60 个设计文件、78 条活动路由、1 条注释路由声明和 7 个未注册页面文件 | 产品取舍必须在用户确认前完成；执行阶段只重算并冻结，不再用前 30 分钟临场决定范围 |
| 测试与设备 | `tests` 下有 208 个文件：150 PS1、54 JS、4 JSON；当前没有统一夜跑 manifest；本轮没有运行测试、构建或 MuMu | 收到“开始执行”后才建立显式 manifest 并取得新鲜证据，旧 PASS 不冒充本轮 PASS |

### 当前接口覆盖初判

| 域 | 本地受保护快照中的接口证据 | 明确缺口或待验真项 |
| --- | --- | --- |
| A 认证 | 登录、短信登录、注册、找回、发码、资料、安全操作均有声明 | TAC 服务端消费、密码 wire、短信场景、会话撤销和真实错误语义仍需验真；微信登录无当前 APP operation |
| G 家谱 | mine/public/create/detail/update、普通申请/撤回/审核、成员、字辈和行政区划均有声明 | G03 只有“创建家谱＋另建首位人物”两次独立写；`regionCode` 必填，但第一步响应尚未保证稳定返回词法 `genealogyId`，创建结果查询也没有 operation，因此恢复链为 `MISSING_OPERATION`。只有第一步真实响应本身稳定给出字符串 ID 才允许进入第二步；首写超时、断线、5xx、空体或缺 ID 时立即停止并人工对账，禁止按展示名/“联调测试”标识从无正式 item DTO 的 mine 列表猜 ID，也禁止重复建谱；邀请码签发/直接加入、家谱排序、管理员 capability 没有可靠当前 owner |
| T 世系 | tree、人物列表/详情/增改停用、父母/配偶/兄弟姐妹/子女写入均有声明 | 所有读取权限字段缺失；int64 wire、T04 性别字典、T06 原子排行、邀请四段链、两个绑定 mutation owner、头像上传到访问闭环均冲突或缺失 |
| F 家族内容 | 动态、评论/回复/点赞、谱文、相册、照片和文件上传有声明 | 视频仅见删除操作，列表/发布/详情链不完整；视频评论、点赞和分享分别是独立候选，不能借动态互动或视频读取合同；置顶等参考动作无当前 owner |
| R 族务记录 | 亲友记录、祭祀/献礼、成长记录、备忘录、功德记录有声明 | 人生事件和重要证件无明确 APP owner；参考“贺礼”与当前“祭祀献礼”语义必须先拆清 |
| N 消息 | 通知列表、单条已读、全部已读有声明 | 未读计数没有 operation，G01/M01 不得从分页列表长度推断；没有通知详情 operation，列表还是无 item schema 的通用结果；N02 同一会话且列表项含完整正文时的投影单独记 `dataMode=LOCAL_PREVIEW`，冷启动、深链或缓存缺失状态单独记 `dataMode=CLOSED`；业务跳转、消息类型和目标参数均不能从文案猜测 |
| M 我的 | 资料、安全、帮助、反馈、推广内容、VIP 套餐/订单有声明 | M08 保持当前家谱邀请 owner，票据查看、签发、撤销分别由 `C-G-INVITE-LIST/ISSUE/REVOKE` 拥有，复制与系统分享分别由唯一平台剪贴板、分享 owner 负责拒绝/失败/返回；邀请票据 operation 当前缺失。参考 APP 推广/推荐码/奖励无当前路由且保持候选；真实支付、提现/变现及部分敏感操作缺完整结果链；“关于”只用本地静态 owner，不依赖帮助列表 |

## 十一、产品参考功能基线与 T01 世系树重做计划

### 11.1 参考资料的归档与换路径办法

1. 第一参考源固定为 `C:\Users\Rain\Desktop\job\app设计`，只作为本机规划输入，不是运行依赖。业务代码、测试、接口合同和构建脚本均不得硬编码该绝对路径。
2. 该目录当前有 59 张 PNG 和 1 份 PDF。项目相对目录 `docs/design/references/产品参考原稿` 保存了其中 58 张 PNG 和 1 份 PDF，59 个同名文件的 SHA-256 全部一致；源目录新增 `思维导图.png`。在用户确认规划前，不复制新增文件、不删除旧副本。
3. `思维导图.png` 同时包含 APP、后台管理、公司官网和 PC 管理端分支。只有“用户端苹果安卓 APP”分支可直接进入当前产品候选池；其他分支只用于理解角色、权限和服务依赖，不能自动变成当前 UniApp 路由。
4. 第二参考源固定为 `C:\Users\Rain\Desktop\job\Jiapu-App`。第一轮只读盘点已完成路由、页面和 API wrapper 清单；继续甄别时不安装依赖、不运行构建、不修改参考仓库，也不读取或迁移其 Git 历史。
5. 参考项目使用旧的 Vue/uView 结构、旧后端地址和宽松请求封装，且请求层会输出参数和响应；这些实现、环境值、日志方式、Token 处理、组件和数据模型全部禁止迁入当前项目。API wrapper 只用于证明“参考项目曾尝试过某动作”，不能作为当前接口合同。
6. `docs/产品参考页面功能映射表.md` 必须在交给用户确认前完成。第一源使用 `Dxxx-Pxx-Sxx-Axx` 标识文件、PDF 页/区域、页面、状态和动作；每张单页 PNG 默认自身就是独立 `S01` 状态证据，表内可省略 `S01` 作短写。第二源按 `Jxxx-Sxx-Axx` 标识 78 条活动路由的状态与动作，注释路由单列 `JX001`，7 个未注册文件使用 `JUxx-Sxx-Axx`。附件必须有正向逐项表和按当前 A/G/T/F/R/N/M owner 的反向覆盖索引；组合展示不能省略任何源 ID。
7. 参考截图和参考项目不按文件整包采纳。甄别最小单位固定为“一个页面状态下的一个用户动作”。文件名相近、画面相似、路由目标相同或代码结构近似都不能直接判为重复：它们可能是普通、管理、编辑、空、错误、权限、角色或主题状态。只有入口、对象、动作、数据、接口和返回行为均被证明等价后，才能共用当前 owner；共用后仍须保留每个来源状态 ID。查看、创建、编辑、删除、邀请、分享、支付等动作可以分别得出不同结论。
8. 当前项目继续使用已确定的国风资产、色彩和组件语言。参考稿的亮红导航、原卡片比例、旧弹窗、默认 uView 控件和旧图标只表达信息结构，不默认成为视觉验收目标。
9. 参考源出现、当前项目没有路由或接口 owner 的功能先进入“候选缺口”，必须判断是复用现有页面、增加新路由、后端缺失暂关，还是与当前产品冲突舍弃；不得为了保持 52 条路由而遗漏，也不得为追求功能数量临时创建假页面。隐私资料、重要证件、资金、删除、退出家谱、所有者转移和账号注销一律作为敏感候选单列，参考源存在不构成采纳授权。
10. 两个源再次变化时，重复“只读文件清单与哈希差异 → 更新页面/动作映射 → 记录新旧结论”的流程；不因源目录缺文件自动删除项目内归档，也不在业务代码里保存机器绝对路径。

### 11.2 T01 目标画面与交互

T01 的验收目标不是“能显示一棵文字树”，而是能够识别人、关系、代际并对选中人物执行明确动作的长世代世系树：

1. 人物节点使用头像卡片，至少呈现头像、姓名、关系标签和代际信息；配偶位于同一代并保持成组关系，父母、子女、兄弟姐妹的连接线不能断裂或指向错误人物。
2. 有真实头像时通过统一文件投影显示；无头像、文件缺失或加载失败时使用确定性的国风默认头像，不使用随机网络图片或伪造真人照片。不能把 `avatarOssId` 直接拼成 URL。
3. 支持横向与纵向浏览长世代内容；选中人物需有清晰高亮。长姓名、大字号、大量成员和数十代数据下，卡片、代际标签和连接线仍可辨认。
4. 点击人物卡后打开唯一的人物操作面板，取代互相竞争的旧底部操作条。面板中央放大展示当前人物卡，头像区域提示并支持“点击头像查看资料”。
5. 操作面板必须包含以下功能入口，并始终携带当前 `genealogyId` 和 `personId`：
   - 点击头像查看资料；
   - 添加父亲；
   - 添加母亲；
   - 添加配偶；
   - 添加兄弟姐妹；
   - 调整排行；
   - 添加儿子；
   - 添加女儿；
   - 邀请绑定；
   - 编辑信息。
6. 面板遮罩点击、关闭按钮、Android 系统返回键、页面返回键、重复点击和焦点恢复行为必须一致。提交中的动作禁用重复触发；页面离开或响应迟到时不得把结果写入错误人物。
7. 当前 Apifox 的 tree/person/member 投影均没有稳定 `canEdit/canInvite/canManage/actionCapabilities` 字段，前端不得猜测角色或伪造 capability。十个必需入口保持可发现；已有单一 declared write operation 的入口可提交最小白名单请求，由服务端最终裁决，并对 403/409/5xx/超时明确失败且不本地假成功。403 只能证明该次请求被拒绝，不能反推出可持续的前端权限。每个动作账本仍须记录权限字段、来源 operation、撤权后的刷新和 403 语义。

已完成参考项目只证明这组动作是产品候选，不证明实现可迁移：其树页面中“添加女儿”仍复用了 `addSon` 意图、“添加母亲”存在注释掉的入口、“邀请绑定”按钮没有闭合动作，删除又混用旧通用用户接口。因此 T01 必须按十个入口分别定义意图和合同，不能复制参考页面后把同名按钮视为完成。

### 11.3 页面职责与唯一 owner

| 页面 | 唯一职责 | 不得承担 |
| --- | --- | --- |
| T01 世系树 | 读取树、布局、浏览、选择人物、展示操作面板并导航到对应流程 | 不直接伪造任何写操作成功，不保存另一份成员详情 |
| T03 成员详情 | 读取并展示真实人物资料；承接“点击头像查看资料” | 不以本地 fixture 冒充服务端人物 |
| T04 添加亲属 | 统一承接父亲、母亲、配偶、兄弟姐妹、儿子、女儿六类新增关系 | 不为六个入口复制六套提交合同，不猜测缺失 ID |
| T05 编辑成员 | 修改头像和允许编辑的基础人物资料 | 不承担排行或关系拓扑修改 |
| T06 排行调整 | 原子调整同辈排行 | 不退化为另一份通用人物编辑页，也不保留旧“关系修正本地预览”假成功路径；关系修正若以后获批必须另立产品动作和原子合同 |
| 邀请绑定流程 | 在独立合同下邀请用户并绑定人物 | 不与普通加入家谱申请或邀请码直接加入混为一条链 |
| T07/T08 | 成员目录、成员状态等辅助读取 | 不成为 T01 写操作的旁路 owner |

T04 的六个入口只在路由内部传递经 validator 验证的十进制字符串 ID、内部 `relationType` 枚举和必要意图提示；`relationType` 不是 wire 字段，严禁发送到 `additionalProperties:false` 的 `LineagePersonBody`。页面先展示当前人物和待添加关系，只有性别字典、关系约束和真实响应共同确认后才允许提交。不得复制人物模拟配偶，也不得仅凭中文按钮在本地猜测 wire 值。

| UI 意图 | 完整 endpoint | 请求意图约束 | 当前状态 |
| --- | --- | --- | --- |
| 添加父亲 | `POST /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/parents` | 关系方向由 `/parents` owner 决定；只发送当前已声明并采集的基础人物字段，不发送 `relationType` 或猜测的性别 code | `DECLARED_UNVERIFIED`，待测试账号实测服务端性别/冲突/权限与读后刷新 |
| 添加母亲 | `POST /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/parents` | 同上；不得将“母亲”中文标签直接当成 `sex` wire | `DECLARED_UNVERIFIED`，待实测 |
| 添加配偶 | `POST /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/spouses` | 不发送 `relationType`；`relationName` 未由页面采集，暂不猜测 | `DECLARED_UNVERIFIED`，待关系方向、重复/冲突、权限与读后刷新实测 |
| 添加兄弟姐妹 | `POST /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/siblings` | 不发送 `relationType`；不把单人 `sortOrder` 当同辈排行 | `DECLARED_UNVERIFIED`，待字典/冲突/权限实测 |
| 添加儿子 | `POST /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/children` | 关系方向由 `/children` owner 决定；不猜测性别 code | `DECLARED_UNVERIFIED`，待实测 |
| 添加女儿 | `POST /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/children` | 同上 | `DECLARED_UNVERIFIED`，待实测 |

### 11.4 接口映射与启用条件

| 用户动作 | 页面 owner | 计划接口 | 启用条件 |
| --- | --- | --- | --- |
| 展示世系树 | T01 | `GET /genealogy/app/genealogies/{genealogyId}/lineage/tree` | 树 DTO、稳定 ID、代际、配偶与父子连接关系已收紧并通过运行时测试 |
| 查看人物资料 | T03 | `GET /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}` | 路由参数与响应投影一致，不回退 fixture |
| 添加儿子/女儿 | T04 | `POST /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/children` | 性别 enum、请求 DTO、写入结果、重复提交与结果未知规则明确 |
| 添加父亲/母亲 | T04 | `POST /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/parents` | 同上，并由服务端校验关系冲突 |
| 添加兄弟姐妹 | T04 | `POST /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/siblings` | 性别/排行合同明确，不通过复制已有节点伪造 |
| 添加配偶 | T04 | `POST /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/spouses` | 请求合同明确，并能读取提交后的真实关系 |
| 编辑人物资料/头像引用 | T05 | `PUT /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}` | 字段白名单、头像上传/引用/访问 URL 闭环和结果确认完整 |
| 调整排行 | T06 | 仅有候选 `PUT /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}` 的 `sortOrder` | 当前为 `CONTRACT_CONFLICT`：无批量/原子同辈重排、版本或冲突协议，不得逐人写出部分成功 |
| 邀请签发、送达与接受 | 独立邀请流程 | 无可靠 operation | `contractState=MISSING_OPERATION`，保持关闭 |
| 邀请目标身份查找 | 独立邀请流程 | 无隐私安全的可靠 operation | `contractState=MISSING_OPERATION`，保持关闭 |
| 绑定 mutation | 独立邀请流程 | 成员 PUT 的 `lineagePersonId` 与人物 PUT 的 `appUserId` 是两个候选 | `contractState=CONTRACT_CONFLICT`，确认唯一 owner 前禁止双写 |
| 邀请绑定结果查询 | 独立邀请流程 | 无可恢复查询 operation | `contractState=MISSING_OPERATION`，结果未知时禁止重试 |

`avatarOssId` 的 owner 是统一上传与文件访问链路；未确认上传、业务实体更新、文件引用和可访问 URL/重进显示四段闭环前，T05 不显示假上传成功。

邀请绑定拆成四段独立账本：

1. 邀请签发、送达、接受：当前没有 operation，保持关闭。
2. 查找目标身份：当前没有隐私安全的独立 operation，保持关闭。
3. 绑定已有成员/用户：`PUT /genealogy/app/genealogies/{genealogyId}/members/{memberId}` 的 `lineagePersonId` 与 `PUT /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}` 的 `appUserId` 是两个冲突候选；真实合同确认后只能选择一个 owner。
4. 结果查询：当前没有可恢复 operation，结果未知时不得重试或双写。

邀请绑定不能借用普通加入申请、邀请码直入或同时调用两个候选 mutation。关闭态检查可以为 `PASS`，但该必需动作的 `productCompletion` 仍为 `BLOCKED`。

所有写操作都必须定义提交中、成功、明确失败和结果未知四种结果。只有后端合同明确支持幂等或存在无副作用的结果查询时才允许安全恢复；超时、断网或 5xx 后不能用 timer 自动提示成功，也不能把本地草稿当成服务端已提交。

### 11.5 数据与状态约束

- `genealogyId`、`personId`、`memberId`、`appUserId`、文件与亲属引用都以十进制字符串为唯一 ID owner。当前 OpenAPI 的 `integer/int64` 与 JavaScript 安全精度冲突；只有服务端响应以字符串返回且请求接受字符串后才能启用。超过安全整数的 number 不得在解析后转字符串补救。
- 树投影至少明确头像访问结果、姓名、关系类型、代际、父母引用、配偶引用、同辈排行 `sortOrder` 和权限/能力；当前 capability 未声明，所有写入口先关闭。字段缺失必须进入可解释失败或降级状态，不能静默拼错树。
- 关系类型采用单一枚举 owner，页面、API adapter、validator、测试和文档共同消费，禁止各页面维护中文字符串分支。
- `sex`、关系、人物状态和排行语义都必须由真实合同提供 enum；T04 内部意图不能充当 wire 字典。
- 排行调整当前为 `CONTRACT_CONFLICT`。在后端提供原子同辈顺序结果或明确并发协议前，前端只可展示关闭说明，不得逐人物写 `sortOrder` 或在失败后保留假顺序。
- 恢复信息不得持久化手机号、头像原图、身份证明、邀请凭据等 PII；只保留完成恢复所需的最小非敏感标识和状态。

### 11.6 测试先行与实施顺序

只有规划经用户确认且用户随后明确说“开始执行”后，T01/T03—T06 才按以下独立小批次执行。每批由主代理写入、两位评审者只读复核接口、业务、交互、异常和视觉，当前批通过后才进入下一批：

1. **T01-0 失败门禁**：先新增会失败的合同，锁定头像节点、姓名/关系/代际、唯一人物操作面板、十个动作入口，并禁止旧底部操作条与新面板并存。
2. **T01-1 树 DTO 与布局**：收紧树 normalizer 和 validator，验证父母、配偶、子女、代际、排行、缺头像、失真 ID、重复节点、断链及循环关系；旧宽 DTO 必须失败。
3. **T01-2 视觉与交互**：实现头像人物卡、连接线、选中态、横纵浏览和操作面板；覆盖遮罩、返回键、焦点恢复、重复点击、快速切换人物和迟到响应。
4. **T01-3 页面导航合同**：逐项验证 T01 → T03/T04/T05/T06 的参数、返回后选中态和树刷新；邀请绑定若无合同，只验证诚实关闭态。
5. **T03/T04/T05/T06 真实接线**：每个页面先写 mapper/runtime 失败测试，再接对应 GET/POST/PUT；六种亲属动作分别验证请求意图，但复用一份 T04 提交合同。
6. **异常与恢复**：覆盖空树、加载失败、403、404、409、429、500、超时、断网、离页取消、结果未知、权限变化、头像加载失败和提交后重新读取不一致。
7. **性能与视觉验收**：以小树、数十代、数百成员、长姓名、无头像和多配偶数据检查布局预算、滚动流畅度、连接线及内存；不以无限数据承诺替代明确上限。
8. **MuMu 与无障碍**：先在 720×1280 实机检查，再补 320/412 响应式检查；验证触控尺寸、文本缩放、读屏名称、焦点顺序、弹层焦点约束、系统返回和低性能设备操作反馈。TalkBack 等无法稳定自动化的项保留可复现人工步骤。

### 11.7 T01 检查结果与产品完成定义

T01 必须分别报告结构/关闭态检查和产品完成度：

- 头像卡、连接线、选择态、唯一操作面板、十个入口可发现、禁用原因、返回行为等可以分别得到 `checkResult=PASS/FAIL`。
- 某入口因真实后端缺失而正确显示“服务暂未开放”，只表示该关闭态检查 `PASS`；该入口的 `productCompletion=BLOCKED`，T01 产品完成度也不得为 `COMPLETE`。
- T01 只有以下全部成立时才可记 `productCompletion=COMPLETE`：

1. 真实头像或确定性默认头像可见，姓名、关系、代际和连接线正确。
2. 点击任一人物只打开一个完整操作面板；查看资料、父亲、母亲、配偶、兄弟姐妹、排行、儿子、女儿、邀请绑定和编辑十个入口均完成真实权限与业务闭环。
3. T03 展示真实详情；T04 六类关系写入、T05 编辑、T06 原子排行及独立邀请绑定各自遵守唯一 owner，没有 fixture、timer、兼容旁路或假成功。
4. 树刷新和重进后能以服务端数据确认变更；写结果未知时停止重复写并提供只读恢复路径。
5. 当前国风视觉一致，长世代滚动、卡片、连接线、遮罩和返回行为在目标尺寸上稳定，无白块、截断、误触和不可读状态。
6. 接口、业务、交互、异常、视觉、性能和无障碍门禁通过三人交叉评审；自动测试、编译检查和绑定冻结候选包的 MuMu 实机证据齐全。

### 11.8 当前暂停项

- T03 的远端 `GET` 已按 Apifox 人物详情 owner 接线并通过静态/运行时映射门禁，但尚未以测试账号取得本轮脱敏真实响应，仍是 `DECLARED_UNVERIFIED`，不能计入 `LIVE_VERIFIED` 或页面完成。
- T01 旧的固定底部“查看资料/添加亲属”抽屉已经移除；当前只有点击人物卡打开的唯一人物操作面板。任何单张 MuMu 预览都不构成本节完整验收证据。
- 在用户明确说“开始执行”前不继续修改 T01/T03—T06，不批量处理参考图，不运行测试、构建或 MuMu 验收。

### 11.9 已完成参考项目的逐项甄别门禁

参考项目与当前项目可能属于不同版本、不同产品边界、不同技术实现或不同后端合同，因此采用优先级固定为：

1. 用户对当前产品明确确认的需求和取舍；
2. 当前真实后端、Apifox、线上接口文档及可复现响应；
3. 当前 UniApp 的路由、架构、安全约束和已确定国风视觉基线；
4. 参考截图与已完成参考项目。

参考项目中的每个候选功能必须逐项回答：

- 业务目标是否与当前产品一致；
- 使用角色、权限来源和数据归属是否一致；
- 当前后端是否有对应 operation，请求、响应、枚举和错误语义是否一致；
- 是否适合当前 UniApp、Android、导航结构和低性能设备；
- 正常、加载、空、失败、无权限、重复提交和结果未知状态是否完整；
- 视觉是否能融入当前国风体系，无障碍和触控要求是否满足；
- 是否包含旧接口、硬编码、兼容分支、fixture、PII、凭据或其他不可继承风险。

每个候选功能只能得出以下一种书面结论：

| 结论 | 含义 | 后续动作 |
| --- | --- | --- |
| 直接采用 | 业务、合同、交互和视觉均与当前项目一致 | 先写当前项目失败测试，再按本项目结构实现 |
| 改造后采用 | 功能有价值，但接口、权限、状态或视觉需要调整 | 在映射表中列出差异和改造边界后实施 |
| 仅参考交互 | 只能借鉴信息结构或操作方式 | 不复制其数据层、API 代码和环境配置 |
| 后端缺失，暂时关闭 | 当前服务没有可靠 operation 或结果确认链 | 保留诚实关闭态并登记解除条件 |
| 与当前产品冲突，明确舍弃 | 违反当前需求、架构、安全或视觉口径 | 记录舍弃原因，禁止后续人员再次误迁移 |
| 待用户确认 | 证据足够但会扩大产品范围、引入敏感能力或改变既有需求 | 保留书面选项，不进入代码批次 |

`docs/产品参考页面功能映射表.md` 对完成项目增加以下列：参考仓库相对路径、参考路由、候选动作、参考状态流、当前目标路由、当前接口证据、差异、甄别结论、改造边界、测试 owner 和用户待确认项。存在分歧或证据不足时标记“待确认”，不得由代理静默选择。

参考项目不得向当前仓库带入旧后端地址、账号、Token、密钥、签名、应用标识、用户数据、构建产物、依赖缓存或 Git 历史。采用其功能也必须重新通过当前项目的合同测试、运行时测试、编译、MuMu 视觉与三人交叉评审；“参考项目里能运行”不能作为当前项目完成证据。

### 11.10 参考项目资产逐文件复用门禁

用户已经允许把参考项目中的图标等资产拿来补足当前产品。该许可按“可进入逐文件甄别池”执行，不按“整包照搬”执行。规划期只读盘点得到：

- `C:\Users\Rain\Desktop\job\Jiapu-App\static` 共 531 个媒体文件、6,764,740 bytes（约 6.45 MiB）；`assets` 只有 JS/CSS/SCSS，`uni_modules\uni-id.zip` 是依赖包而非产品资产。
- 声明扩展名为 PNG 307、GIF 221、SVG 2、JPG 1；文件签名实为 PNG 311、GIF 217、SVG 2、JPG 1。6 个文件扩展名与 MIME 不一致，迁入前必须规范重导出。
- SHA-256 完全重复 14 组、28 个文件，迁入时每组只能选择一个 canonical owner。
- `static/emojis/qq` 434 项、`static/douyin` 18 项及旧视频实验图标、微信/支付宝/支付/VIP/奖励素材、旧 logo 和固定旧文案均有第三方、旧品牌或未批准业务风险，不能因文件存在而启用对应产品功能。
- 水墨/宗祠、谱书、人物卡边框、中性功能图标和默认头像风格是高价值候选；其中固定姓氏、口号、生成者/提示词式文件名、示例人物、水印及低分辨率仍须逐文件处理。

每个实际考虑复用的文件在复制前建立 `RAxxx` 记录，至少包含：源绝对/相对路径、SHA-256、重复组与 canonical ID、声明扩展名/检测 MIME、尺寸/帧数/透明度/bytes、来源页面和状态、目标 PA/路由/组件/状态、语义用途、决策、复用方式、用户对参考项目的许可记录、第三方/商标信号、个人数据/旧品牌/固定文字/无障碍/性能风险、必要改造和验收证据。决策仍使用六类口径；复用方式固定为原文件、裁切重导出、重绘、仅构图参考或禁用。

逐文件门禁为：

1. **产品门**：必须绑定已批准 PA、页面、状态和动作；资产不能反向新增功能、解除后端关闭或扩大 55 个候选 PA。
2. **状态门**：相似图标或画面也可能代表普通、选中、禁用、权限、错误等不同状态；未证明语义和行为等价前分别记录、分别验收。
3. **来源门**：用户已允许评估并复用参考项目资产；带 QQ、抖音、微信、支付宝等第三方/商标信号的文件还需满足当前平台规范，来源不清时只能重绘或不用，规划不写“已拥有版权”结论。
4. **隐私与品牌门**：不带示例真人/头像、二维码、手机号、姓名、水印、定位、旧 logo、旧口号、奖励/VIP/支付旧文案或固定姓氏。无 EXIF 不等于无个人数据，仍须看画面。
5. **技术与安全门**：扩展名与 MIME 一致；SVG 不含脚本、外链或未经审查的 data URI；位图去无用元数据；重复哈希只保留 canonical；不得沿用旧绝对路径或外部 URL。
6. **视觉与无障碍门**：服从当前国风 token；覆盖普通、选中、禁用、加载、错误和关闭态；小图放大不糊，功能图标有语义文本，装饰图不进入读屏，动图提供静态降级和减少动态效果。
7. **性能与验证门**：记录解码尺寸、包体和首屏影响；超预算就压缩、重绘或按需加载。只对实际采用的 RA 在目标路由各批准状态做 MuMu 截图、缩放、离线/失败检查，并绑定冻结候选 ID。

首批优先甄别而非预先批准的候选包括 `static/iconpng/902.png`、`static/iconpng/z8526@2x.png`、`static/login/bj.jpg`（实为 PNG）、`static/iconpng/treeBJ.png`、`static/iconpng/book.png`、`static/icon/index.svg`、`static/navigation/*`、`static/tabulation/*`、`static/pu/*`、`static/jr.png`、默认头像风格和 `static/login/hd*.gif`。`jiap.svg` 约 397 KiB 且内嵌大位图与固定文字，只作构图参考。规划确认时固定 `referenceAssetFiles=531`、`approvedDirectReuseAssets=0`、`approvedAdaptReuseAssets=0`；收到“开始执行”后，只有通过上述逐文件门禁的 RA 才增加采用数，这属于已批准 PA 内的实现选择，不改变产品动作分母。九小时批次只甄别本轮已批准 PA 实际需要的资产，未选中的候选保持未审、未复制，不把“531 个进入候选池”写成“531 个必须在今晚迁入”。

### 11.11 全项目功能补足矩阵

下表是本轮权威规划的全项目检查骨架；逐页、逐动作和逐接口结论已经落在权威附件中。执行第 0 批只重算并冻结这些结论，不得再临场扩大产品范围。

| 当前域 | 当前活动路由 | 两个参考源提供的候选 | 本轮必须做出的结论 |
| --- | --- | --- | --- |
| A 认证 | A01、A04、A05 | `登陆.png`、参考项目登录/注册/找回页，以及账号密码、短信、注册、找回、微信登录等动作 | 四条现有认证流程继续以 TAC 和当前后端为准；微信登录没有当前 APP operation，只能标记候选关闭或待用户确认，不能借旧接口接入 |
| G 家谱工作区 | G01、G03、G05、G06、G08—G12 | 家谱列表、创建、加入、邀请码、家谱主页、字辈、家谱排序、始祖世代、管理员及权限 | G03 固定为“创建家谱→创建首位人物”两阶段，但恢复链按 `MISSING_OPERATION` 关闭：`regionCode` 由共享行政区划 owner 提供；只有第一步真实响应本身稳定返回词法 `genealogyId` 才登记待续办 ID 并进入第二步。首写结果未知或缺 ID 时停止并人工对账，禁止从 mine 列表按展示名/测试标识猜 ID，禁止假定通用对象壳含 ID，也禁止重复建谱。其余列表/搜索/普通申请/审核/设置/字辈逐项验真，邀请码直入、家谱排序、始祖世代和管理员权限分别判断 owner |
| T 世系与成员 | T01、T03—T08 | 头像树、表格/树谱模式、人物资料、父母/配偶/兄弟姐妹/儿女、排行、邀请绑定、编辑及参考项目中的删除 | T01 十个必需入口逐项落到 T03/T04/T05/T06/独立邀请流程；T03保持未完成；删除人物/配偶不是本轮十个入口之一，须单列敏感候选，不能因参考项目有按钮而默认加入 |
| F 家族内容 | F01—F10 | 家族圈、发布/删除/评论、谱文分类与增改删、相册分类与照片管理、视频列表/发布/编辑及短视频评论/点赞/分享 | 动态、谱文、相册、上传逐动作核对当前合同；视频浏览、评论、点赞、平台分享已拆成独立候选 owner，缺合同时诚实关闭，不用旧 API、动态评论 owner 或本地计数假成功 |
| R 人物与族务 | R01—R11 | 人物、人情簿、贺礼邀请、成长日志、备忘录、功德录、重要证件 | R01/R02 分别作为人物目录、人物资料的独立路由状态，数据只消费 T07/T03/T05 的唯一列表/详情/编辑 owner；R02 不保留通用“新建人物本地预览”，编辑入口只导航 T05。亲友记录、祭祀/献礼、成长、备忘、功德按当前业务语义接线；“贺礼邀请”与“祭祀献礼”先拆分语义；人生事件和重要证件缺 owner 时进入候选缺口 |
| N 消息 | N01、N02 | 加入申请、生日、贺礼、备忘、疫苗、点赞评论、推广、广告消息及详情 | 当前只有列表与已读合同，未读计数缺 operation，G01/M01 使用同一个关闭 owner 而不从分页长度推断；N02 无详情 operation。同一会话且列表项含完整正文时的投影是独立状态，记 `dataMode=LOCAL_PREVIEW`；冷启动、深链或缓存缺失是另一独立状态，明确返回 N01 并记 `dataMode=CLOSED`。只有服务端提供闭合详情、消息类型、目标 route key、参数和权限失效语义后才恢复 LIVE 详情与业务跳转 |
| M 我的 | M01—M10 | 个人资料、帮助、设置、修改密码/手机、反馈、家谱邀请、VIP、注销、提现/变现 | M08 保持“选择家谱并管理家谱邀请票据”的当前职责，票据查看/签发/撤销与本地复制/系统分享分别归 `C-G-INVITE-LIST/ISSUE/REVOKE`、`C-S-PLATFORM-CLIPBOARD/SHARE`，缺真实 operation 时保持关闭；参考 APP 推广、推荐码、奖励和变现不得覆盖 M08，均维持无当前路由候选。支付、注销、换绑和提现属于敏感动作，必须有独立合同、人工窗口和结果确认 |

跨域共享项也必须进入映射：登录态与账号切换、当前家谱上下文、角色/capability、文件上传与访问 URL、通知回流、深链参数、缓存失效、写结果未知、Android 返回、触控、系统字号、TalkBack 和长列表性能。任何一个共享项不得在 A/G/T/F/R/N/M 各自复制一份合同。

第一轮已识别但不能静默纳入今晚代码的参考候选如下：

| 候选 | 参考证据 | 当前判定 |
| --- | --- | --- |
| 微信一键登录 | 思维导图与参考登录页 | 当前后端无 APP operation，`后端缺失，暂时关闭`；是否长期需要由用户后续确认 |
| 管理员列表与细粒度权限 | 思维导图、参考 `admin` 三页 | 当前只有成员类接口证据，没有闭合的管理员角色/权限 owner，先列 `待用户确认` 与后端缺口 |
| 家谱排序、始祖世代调整 | 参考 `sortGenealogy`、`ancestorsOrder` 与设计图 | 与 T01 人物排行、G12 字辈排序不是同一合同；分别缺可靠 owner，不能互相借用 |
| 重要证件 | 参考 `document` 页面 | 当前 52 路由和 APP 合同均无 owner，列产品候选，不临时新增假入口 |
| 家族圈置顶 | 思维导图 | 当前动态合同未见置顶 capability，暂时关闭 |
| 广告/宣传视频 | 参考消息广告和宣传视频页面 | 与当前普通通知、通用推广和 F10 家族视频分开甄别；独立使用 `C-M-PROMO-VIDEO` 及其评论/点赞/分享候选 owner，无可靠 operation 时不采用 |
| 提现、分享变现 | 参考“我的”页面 | 涉及真实资金且不属于已确认当前需求，保持 `待用户确认`，今晚不执行 |
| 删除世系人物/配偶 | 参考 T01 操作面板 | 当前后端虽有停用人物声明，但用户本轮明确的是十个其他入口；删除必须另设权限、影响预览和二次确认后再决定 |
| 扩展个人隐私资料 | 设计人物表单中的微信、QQ、住址、学历、职业等字段及参考重要证件页 | 当前需求未授权扩展收集，后端也无闭合隐私/可见性 owner，结论为 `与当前产品冲突，明确舍弃`；只保留反例证据，不采纳、不存储、不上传 |
| 移除成员、退出家谱、所有者转移、账号注销 | 参考家谱列表/我的页与当前成员类声明 | 均为破坏性或身份敏感动作，必须单独产品确认、影响预览、再认证、结果查询和人工窗口；不因存在 operation 自动启用 |

### 11.12 确认与执行门禁

1. 用户已明确“需求说完了”，需求收集门禁已关闭。
2. 主代理完成本文修订后，由三人按第七节交叉评审；只允许主代理吸收意见修改本文。
3. 三人评审收口后，把完整修订版、主要变化、评审结论和仍待确认项交给用户。
4. 交付用户时必须把两项单独列明并取得确认：`T_due=2026-07-24 08:00` 是否接受；55 个候选 PA 本轮是否维持 `approvedCandidateActions=0`。笼统沉默不视为接受具体截止时间或批准候选。
   - 用户已于 2026-07-23 确认将截止更新为 08:00，并确认 55 个候选 PA 本轮维持 `approvedCandidateActions=0`。
5. 用户确认规划只代表规划定稿，业务代码、接口接线、样式、测试、构建和 MuMu 仍保持冻结。
6. 只有用户明确说“开始执行”，第六节计时和第 0 批才启动；第 0 批只重算、冻结已确认映射和环境，不得重新解释为需求收集。
7. 用户未说“开始执行”时，不因时间已到“今晚”而自行开工，也不把只读规划核对解释为代码阶段已经开始。