# 家谱 APP 换机继续任务交接（2026-07-22）

> 用途：把当前项目完整复制到另一台电脑后，让新的 Codex/GPT 会话无需重新推翻既有设计，直接从正确停点继续。
>
> 当前权威状态：2026-07-21 的全项目响应式审核、MuMu 复核、两位专家评审与第一轮产品优化已经闭环。本文件覆盖 `docs/交接记录.md`、`docs/新会话审批交接_2026-07-19.md`、`docs/夜间批量收敛交接_2026-07-20.md` 中与当前进度冲突的旧停点；旧文件只保留为历史证据。

## 1. 换机时必须复制什么

最稳妥的方式是复制整个 `jiapuapp` 项目目录，而不是只重新拉取远端代码。当前工作包含源码、测试、规划和可能尚未同步到远端的文件，不能假设远端仓库已经拥有本轮全部成果。

新电脑上的项目路径可以变化。下文把项目根目录记为：

```text
<JIAPUAPP_ROOT>
```

必须保留：

- `AGENTS.md`
- `App.vue`、`pages/`、`components/`、`styles/`、`utils/`
- `tests/`，尤其是响应式覆盖、白名单和本轮新增合同
- `docs/`，尤其是 2026-07-21、2026-07-22 的规格、计划和本交接
- `static/` 与 `design-pipeline/` 中的正式资产、清单和重建脚本
- `pages.json`、`package.json` 及项目配置文件

本地证据目录：

- `tmp/project-audit/`：G10 之后逐页 MuMu 审核截图
- `tmp/project-optimization/`：专家优化后的 MuMu 复核截图

`tmp/` 通常不属于长期仓库资料。如果希望在新电脑继续查看本轮截图，必须单独复制上述两个目录；不复制不会影响源码和合同，但会失去本轮临时视觉证据。

可在换机后重新生成、无需作为权威资料的目录包括 `node_modules/`、`unpackage/`、`.vite/` 和其他构建缓存。不要删除正式资产、测试、规划、母版或长期证据来缩小目录。

## 2. 新会话必须按顺序阅读

新的 Codex/GPT 接管后，在修改代码前完整阅读：

1. `AGENTS.md`
2. `docs/换机继续任务交接_2026-07-22.md`（本文件）
3. `docs/superpowers/specs/2026-07-21-project-wide-responsive-layout-design.md`
4. `docs/superpowers/plans/2026-07-21-responsive-foundation-phase-1.md`
5. `tests/responsive-layout-coverage.json`
6. `styles/adaptive-frame-profiles.scss`
7. `docs/superpowers/plans/2026-07-21-project-wide-audit-and-expert-optimization.md`
8. `docs/superpowers/specs/2026-07-21-whole-product-enrichment-design.md`
9. `docs/superpowers/plans/2026-07-21-whole-product-enrichment-implementation.md`

发生冲突时，权威顺序为：

1. 用户在新会话中的最新明确要求。
2. 本交接文件。
3. 2026-07-21 的响应式、专家优化规格和计划。
4. 当前源码、测试和配置。
5. 更早的交接、设计记录和历史截图。

旧文档中“从 G01 开始”“只审核 H5”“Android 尚未验证”“仍剩 52 页待审”等说法已经失效，不得据此回退当前进度。

## 3. 当前真实完成状态

- `App.vue`、公共组件和所有活动页面共 **66 个 Vue 文件**已全部纳入响应式扫描。
- 最近一次闭环结果：实际 Vue `66`、覆盖 `66`、缺失 `0`、陈旧 `0`。
- A 系列与 G01—G10 由用户在 MuMu 中逐页确认过；正式人工验收断点曾是 G10。
- G11、G12 以及后续 T、F、R、N、M 页面已经按用户授权，由主代理在 MuMu 中逐页、逐状态继续审核并完成问题修复，不再停在 G11。
- G10 之后已覆盖 G11—G12、T01/T03—T08、F01—F10、R01—R11、N01—N02、M01—M10。
- 两位专家已经完成评审和交叉质询：
  - 视觉交互专家：Dirac
  - 功能代码专家：Leibniz
- 不要重新创建两位专家或重复第一轮专家评审，除非用户在新会话明确要求第二轮。
- 两位专家的结论已经汇总到产品丰富化设计和实施计划；第一轮接受的六个优化批次已经实现。
- 规划文件中的实施检查项已经全部标记完成。

## 4. 已完成的关键修复与优化

### 4.1 全项目响应式基础

- 九宫格边框和可变高度装饰面的唯一所有者：`styles/adaptive-frame-profiles.scss`。
- 页面和普通组件不得自行定义 `border-image-slice`。
- 可变高度内容由内容自然撑高，不使用固定高度掩盖问题。
- 弹窗只允许使用视口 `max-height`，内容区域内部滚动。
- 页面内禁止重新出现 `background-size: 100% 100% no-repeat`。
- 固定比例图标、头像、印章、缩略图等例外只允许登记在 `tests/responsive-layout-allowlist.json`。
- 响应式扫描范围唯一清单：`tests/responsive-layout-coverage.json`。

### 4.2 第一轮专家优化的六个批次

1. **原生路由参数**
   - G01、G03、G06 不再依赖 `location.hash`、`URLSearchParams` 或 `hashchange`。
   - Android 活动页参数由各页 `onLoad(query)` 唯一持有。
   - 保护合同：`tests/native-route-query-contract.ps1`。

2. **AppDialog 高度预算**
   - `components/AppDialog.vue` 统一持有顶部、底部安全区和唯一最大高度公式。
   - 外层弹窗使用 Flex 列布局，内容区 `min-height: 0` 并独立滚动。
   - 已在 G10、R04、R08、F07、M10 等短/长弹窗复核。

3. **共享点击语义**
   - `components/AppTabbar.vue` 提供 `tablist`、`tab`、`aria-selected` 和按压反馈。
   - `components/GenealogyCard.vue` 提供按钮语义、组合可访问名称和按压反馈。
   - 保护合同：`tests/shared-interaction-accessibility-contract.ps1`。

4. **G10 拒绝原因校验**
   - 文本域具有稳定 ID、`aria-invalid`、`aria-describedby`。
   - 错误元素使用 `role="alert"`；空提交后文本域自动聚焦。
   - 页面：`pages/genealogy/g10-application-review.vue`。

5. **唯一密码策略**
   - 唯一所有者：`utils/validation.js`。
   - A04、A05、M04 统一要求 8—32 位且同时包含字母和数字。
   - M04 额外拒绝新密码与当前密码相同。
   - 保护合同：`tests/password-policy-contract.ps1`、`tests/password-policy-runtime-smoke.js`。

6. **T01 回到当前成员**
   - 页面：`pages/tree/t01-tree-overview.vue`。
   - 用户横向拖离当前节点后才显示“回到当前”。
   - 最终实现不是固定偏移或简单 `scroll-into-view`，而是测量滚动视口和选中节点中心后设置精确 `scroll-left`。
   - MuMu 最终实测中心误差约 `0.24 CSS px`。

### 4.3 本轮逐页审核中已经解决的典型问题

- G11、G12、T03—T06 等内容面板移除强制 `min-height`，恢复内容驱动高度。
- F02、F06、F09 等长文本输入改为自然增长的 `auto-height`。
- F04/F03 和 F09/F08 修复固定页头在长列表、原生媒体滚动时的层叠问题。
- F10 的可变高度装饰面迁移到共享九宫格档案。
- R01 卡片移除固定高度和百分比内边距，并改用原生 `onLoad` 状态参数。
- T01 的代际栏、横向提示、树画布和非树状态已分别约束，不能再退回固定大画布补丁。

完整逐页记录见：

- `docs/superpowers/plans/2026-07-21-project-wide-audit-and-expert-optimization.md`
- `docs/superpowers/specs/2026-07-21-whole-product-enrichment-design.md`
- `docs/superpowers/plans/2026-07-21-whole-product-enrichment-implementation.md`

## 5. 最近一次验证基线

2026-07-21 最终闭环时：

- 全部 `tests/*.ps1`：`129/129 PASS`
- `tests/password-policy-runtime-smoke.js`：PASS
- 四个用户指定核心基线：全部 PASS
- Vue 文件：`66/66`
- Vue 中 `100% 100% no-repeat`：`0`
- Vue 中直接 `border-image-slice`：`0`
- MuMu 设备：`emulator-5554` 在线
- MuMu 物理尺寸：`900×1600`
- MuMu density：`320 dpi`
- Android WebView 逻辑视口约为 `451×800 CSS px`

这些数字是上次闭环事实。换机后必须重新运行验证，不能因为本文件写着通过就直接宣称新环境通过。

## 6. 新电脑首次启动后的验证顺序

在 `<JIAPUAPP_ROOT>` 中运行：

```powershell
powershell -ExecutionPolicy Bypass -File tests/adaptive-frame-profiles-contract.ps1
powershell -ExecutionPolicy Bypass -File tests/project-responsive-layout-contract.ps1
powershell -ExecutionPolicy Bypass -File tests/ag-responsive-surfaces-contract.ps1
powershell -ExecutionPolicy Bypass -File tests/compile-audit.ps1
node tests/password-policy-runtime-smoke.js
```

运行全部 PowerShell 合同：

```powershell
$files = Get-ChildItem -LiteralPath tests -Filter '*.ps1' | Sort-Object Name
$pass = 0
$fail = 0
$failed = @()
foreach ($file in $files) {
  & powershell -NoProfile -ExecutionPolicy Bypass -File $file.FullName *> $null
  if ($LASTEXITCODE -eq 0) {
    $pass++
  } else {
    $fail++
    $failed += $file.Name
  }
}
Write-Output "TOTAL=$($files.Count) PASS=$pass FAIL=$fail"
$failed
```

核对 Vue 覆盖：

```powershell
$coverage = (Get-Content -Raw tests/responsive-layout-coverage.json | ConvertFrom-Json).covered | Sort-Object
$actual = @(rg --files -g '*.vue' | ForEach-Object { $_ -replace '\\','/' }) | Sort-Object
$missing = @($actual | Where-Object { $_ -notin $coverage })
$stale = @($coverage | Where-Object { $_ -notin $actual })
"ACTUAL=$($actual.Count) COVERED=$($coverage.Count) MISSING=$($missing.Count) STALE=$($stale.Count)"
```

核对两项禁用规则：

```powershell
rg -n --glob '*.vue' '100%\s+100%\s+no-repeat' .
rg -n --glob '*.vue' 'border-image-slice\s*:' .
```

两条 `rg` 命令无输出才是正确结果。

## 7. MuMu 验证规则

- 只使用 MuMu 安卓模拟器作为视觉验收依据，不使用浏览器截图代替。
- 不要启动、关闭或改变用户的模拟器配置，除非用户明确要求。
- 新电脑上的设备序列号可能不再是 `emulator-5554`，先用 `adb devices` 读取真实值，不要硬编码旧值。
- 上次设备为 `900×1600 / 320dpi`；如果新电脑已有不同配置，先报告，不要擅自调整。
- 忽略截图中的“3D研究室”等系统水印。
- 每次修改页面后，先跑聚焦合同、全局响应式合同和编译审计，再等待 HBuilderX 热更新，最后在 MuMu 复核。
- 视觉截图必须等待页面稳定；拒绝过渡帧、空白页、错误路由、未加载完成和被软键盘意外遮挡的截图。
- MuMu WebView 调试端口在上次环境为 `9223`，每次导航后 target ID 都可能变化，可用以下命令重新查询：

```powershell
curl.exe -s http://127.0.0.1:9223/json
```

- CDP 只能辅助导航、读取 DOM 和逻辑状态；最终视觉结论必须来自 ADB 获取的 MuMu 屏幕截图。

## 8. 后续开发必须继续遵守的原则

- 整个项目自适应，不接受只针对某个尺寸的单页补丁。
- 内容高度由内容决定。
- 弹窗只使用视口最大高度和内部滚动。
- 不通过压缩字号、降低行高或随意缩小按钮掩盖布局错误。
- 每个确认问题先提出五个可行方案，比较全局合同、回归风险、影响范围、维护成本和 MuMu 可验证性，再自主选择最优方案。
- 共享规则必须由唯一公共所有者持有；页面不得复制九宫格切片、密码规则或共享弹窗高度公式。
- 修改合同必须同时更新唯一所有者、运行代码、验证器、测试和文档，删除旧路径，不保留“以防万一”的兼容读取。
- 页面提示文案不得使用“汤正华堂侄”等具体姓名示例，应使用“某某某堂侄”等通用提示；已有 fixture/mock 数据本身无需清理。
- 不重复修改已经通过的 G01—G10，除非有明确证据证明全局改动造成回归。
- 不执行 `git add`、`commit`、`push`、`restore`、`checkout`、`reset` 等 Git 变更操作。
- 不删除或覆盖用户现有改动、未跟踪文件、资产、测试和文档。

## 9. 下一阶段推荐入口

响应式和第一轮专家优化已完成。下一阶段不要重新做全项目响应式迁移，优先从已记录但尚未进入第一轮实现的产品深化项中选择：

1. **导航栈语义统一**：区分 `navigateTo`、`redirectTo`、`reLaunch`、`switchTab` 的业务边界，避免深层页面堆栈和错误返回。
2. **短信验证码完整状态机**：发送、倒计时、重发、失败、过期、提交锁定及页面离开清理。
3. **跨页面领域数据持久化**：替换部分只在当前页面生效的演示状态，使创建、编辑、删除后的结果在返回列表时一致。
4. **全局文字层级与可访问性第二轮**：在不缩小字号的前提下统一正文、辅助信息、错误提示和可触控语义。

推荐先处理“导航栈语义统一”，因为它影响页面返回、跨模块入口和后续数据持久化，但实施前仍要先形成独立设计与迁移计划。不要一次混合实施以上四项。

## 10. 新会话首次回复必须报告

接管者完成阅读和只读检查后，先向用户报告：

1. 读到了哪些当前权威文件。
2. 当前已经完成到哪里。
3. 五个核心验证和全量合同是否仍通过。
4. Vue 覆盖是否仍为精确相等，禁用规则是否仍为零。
5. MuMu 是否在线、实际设备序列号、尺寸和 density。
6. 准备从哪个第二阶段深化项开始，以及为什么。

在这些事实没有核对前，不要一上来修改代码。

## 11. 可直接复制到新会话的提示词

```text
请全程使用中文。项目根目录是：
【替换成新电脑上的 jiapuapp 绝对路径】

开始前必须完整阅读：
1. AGENTS.md
2. docs/换机继续任务交接_2026-07-22.md
3. docs/superpowers/specs/2026-07-21-project-wide-responsive-layout-design.md
4. docs/superpowers/plans/2026-07-21-responsive-foundation-phase-1.md
5. tests/responsive-layout-coverage.json
6. styles/adaptive-frame-profiles.scss
7. docs/superpowers/plans/2026-07-21-project-wide-audit-and-expert-optimization.md
8. docs/superpowers/specs/2026-07-21-whole-product-enrichment-design.md
9. docs/superpowers/plans/2026-07-21-whole-product-enrichment-implementation.md

当前全项目响应式、G10 后续页面 MuMu 审核、两位专家评审和第一轮六个优化批次已经完成。不要重新推翻已通过设计，不要回到 G01/G10 重新开始。两位专家 Dirac 与 Leibniz 已完成工作，不要重复创建。

先运行并报告：
powershell -ExecutionPolicy Bypass -File tests/adaptive-frame-profiles-contract.ps1
powershell -ExecutionPolicy Bypass -File tests/project-responsive-layout-contract.ps1
powershell -ExecutionPolicy Bypass -File tests/ag-responsive-surfaces-contract.ps1
powershell -ExecutionPolicy Bypass -File tests/compile-audit.ps1
node tests/password-policy-runtime-smoke.js

然后运行全部 tests/*.ps1，并核对：
- 实际 Vue 与 tests/responsive-layout-coverage.json 是否完全相等；
- 是否仍有 100% 100% no-repeat；
- Vue 是否仍直接写 border-image-slice；
- MuMu 是否在线及其实际尺寸、density。

只使用 MuMu 做视觉审核，不使用浏览器截图代替；不要启动或关闭模拟器，不要擅自修改模拟器尺寸。不要执行任何 Git 变更操作，不要删除或覆盖现有文件。

下一阶段优先评估“导航栈语义统一”。遇到真实问题时提出五个方案，自主选最优方案；修改前写失败合同，修改后必须在 MuMu 复核。先报告读到的内容、当前完成状态、测试、覆盖、MuMu 状态和下一步，不要一上来改代码。
```

## 12. 交接完成判定

新电脑满足以下条件后，才算成功接管：

- 能完整打开项目且正式资产没有缺失。
- 五个核心验证通过。
- 全部 PowerShell 合同通过，或明确列出只在新环境失败的合同及根因。
- Vue 覆盖精确相等，两个禁用扫描为零。
- HBuilderX 能把项目热更新到用户当前 MuMu。
- MuMu 截图中的 G10、T01、G01 或另一个代表页与本轮视觉基线一致。
- 接管者能准确复述唯一所有者、禁止事项和下一阶段入口，没有回退到旧 H5 审核停点。