# 全量页面接口联调交接说明

更新日期：2026-07-24  
适用项目：家谱 APP 前端（`jiapuapp`）

## 一、交接结论

本轮已按 `pages.json` 对 **52 个已注册页面**做了重新复核：页面可进入、页面调用的接口方法存在、真实服务端可读取的数据已回读验证、没有继续以页面 mock/fixture 冒充服务端结果。

不能把本轮结论简化成“所有接口均已联调通过”。世系首位成员创建目前由服务端返回业务 `code: 500`，导致依赖真实成员的详情、编辑与关系链路没有可用测试实体，仍是明确阻塞项。

## 二、本轮已验证的范围

### 2.1 页面路由与接线

| 模块 | 页面数 | 浏览器逐页打开 | 结论 |
| --- | ---: | ---: | --- |
| A 认证 | 3 | 3/3 | 页面入口、表单和会话态下的路由行为已检查；未触发短信、注册、找回密码等敏感写入。 |
| G 家谱 | 9 | 9/9 | 家谱列表、创建、概览、搜索、申请、审核、设置、字辈页面均可稳定进入。 |
| T 世系 | 7 | 7/7 | 树、成员目录及安全错误态可进入；真实成员读写见“阻塞项”。 |
| F 家族 | 10 | 10/10 | 动态、谱文、相册、上传等页面均可进入；真实动态/谱文/相册数据已读回。 |
| R 记录 | 11 | 11/11 | 人物、亲友往来、礼仪、成长、备忘、功德等页面均可进入；多类真实创建已回读。 |
| N 通知 | 2 | 2/2 | 通知中心可读取；消息详情保持缺少读取 owner 的关闭态。 |
| M 我的 | 10 | 10/10 | 资料、帮助、推广、VIP 等页面可进入；敏感安全操作未执行。 |
| 合计 | **52** | **52/52** | 路由稳定渲染通过。 |

页面内共扫描到 71 个 `appApi` 调用，均能在 `utils/api.js` 找到对应方法；页面目录未发现 `data/mock` 或 fixture 导入。

### 2.2 已做过真实服务端读回的业务

以下均只使用测试账号和测试家谱数据，未做删除、退出、改密、短信或支付操作。

| 业务 | 已验证闭环 |
| --- | --- |
| 家谱创建 | G03 创建后，可在 G01 列表和 G05 概览读回。 |
| 家族动态 | F02 创建后，可在 F01 列表、F03 详情读回。 |
| 谱文 | F06 创建后，可在 F04 列表、F05 详情读回。 |
| 相册 | F07 创建后，可在 F08 相册详情读回。 |
| 亲友往来 | R04 创建后，可在 R03 列表读回。 |
| 礼仪活动 | R07 创建后，可在 R05 列表读回。 |
| 成长记录 | R08 创建后重新读取列表。 |
| 家族备忘 | R10 创建后重新读取列表。 |
| 功德记录 | R11 创建后重新读取列表。 |
| 个人资料、帮助、推广、VIP、通知 | 已完成真实读取页面验证；不输出账号或会话敏感信息。 |

### 2.3 本轮修正

- F01/F03 不再把服务端 `feedType=text` 原码直接展示给用户，统一显示为“文字动态”。
- 更新了 F 模块业务合同测试，使其校验当前真实 API 读写路径，而非旧 fixture/预览路径。
- 新增全页面浏览器审查脚本：`tests/all-page-route-runtime-smoke.js`。

## 三、明确阻塞：世系首位成员创建

### 现象

测试家谱为空世系时，T04 “录入首位成员”已完成前端表单校验与请求组装；使用合法最小请求（姓名、第一世）调用：

```text
POST /genealogy/app/genealogies/{genealogyId}/lineage/persons
```

HTTP 返回成功，但业务响应为 `code: 500`，未创建成员；之后读取世系树仍为空。

### 影响范围

- T03 成员档案：没有真实 `personId`，无法完成真实详情读回。
- T04 新增亲属：没有首位成员，不能继续建立亲属关系。
- T05 编辑成员、T06 调整排行、T08 成员状态：没有真实成员实体，不能完成真实读写验证。
- R01/R02 的真实人物详情同样没有可用实体可验证。

### 需要后端协助确认

1. 查询上述创建请求对应的服务端异常栈和租户/家谱初始化条件。
2. 确认创建首位成员是否还存在 Apifox 未声明的必填字段或前置初始化操作；如有，补充到 APP 接口合同。
3. 修复后提供一个可创建或可读取的测试成员，再继续 T03–T08、R01–R02 的真实闭环验证。

前端不会猜测额外字段，也不会用本地假成员伪造成功。

## 四、正确关闭的页面/动作

下列不是漏接，而是当前 APP 接口没有足以支撑该页面真实业务的 owner，或操作超出本轮授权范围：

| 页面/能力 | 当前处理 | 原因 |
| --- | --- | --- |
| F10 家族视频 | 明确提示暂未开放 | 仅见删除 operation，未见视频列表、详情、播放、发布等读取/写入合同。 |
| R09 人生事件 | 明确提示暂未开放 | APP 目录中无独立人生事件资源。 |
| N02 消息详情 | 明确提示暂未开放 | 只有通知列表和标已读，没有单条详情读取 owner。 |
| M03 安全概览 | 不展示假账号/设备摘要 | 无安全概览、设备、登录记录读取合同。 |
| M05 换绑手机号 | 等待人工 TAC/短信验证 | 缺少可安全消费的当前手机号 DTO 与已核实验证码链路。 |
| 删除、退出、改密、支付 | 未执行 | 本轮测试范围禁止敏感操作。 |

## 五、复测方式

### 5.1 前置条件

- 启动本地 Web 预览，默认地址：`http://localhost:5173`。
- 使用已登录的测试账号浏览器，Chrome 远程调试端口为实际可用端口。
- 设置一个测试家谱 ID；不要使用生产数据。

### 5.2 全页面路由复核

为避免一次跑完整 52 页超过终端时限，可分四段执行：

```powershell
$env:CDP_PORT='9777'
$env:GENEALOGY_ID='<测试家谱ID>'
$env:PAGE_AUDIT_START='0';  $env:PAGE_AUDIT_END='26'; node tests\all-page-route-runtime-smoke.js http://localhost:5173
$env:PAGE_AUDIT_START='26'; $env:PAGE_AUDIT_END='34'; node tests\all-page-route-runtime-smoke.js http://localhost:5173
$env:PAGE_AUDIT_START='34'; $env:PAGE_AUDIT_END='45'; node tests\all-page-route-runtime-smoke.js http://localhost:5173
$env:PAGE_AUDIT_START='45'; $env:PAGE_AUDIT_END='52'; node tests\all-page-route-runtime-smoke.js http://localhost:5173
```

脚本会为有测试实体的页面读取真实数据；成员专属页面在后端首位成员故障未修复前只验证安全错误态，不把这当作真实成员接口通过。

### 5.3 静态和编译检查

```powershell
powershell -ExecutionPolicy Bypass -File tests\compile-audit.ps1
powershell -ExecutionPolicy Bypass -File tests\interface-page-mapping-contract.ps1
powershell -ExecutionPolicy Bypass -File tests\active-page-business-ownership-contract.ps1
powershell -ExecutionPolicy Bypass -File tests\f-business-flow-contract.ps1
powershell -ExecutionPolicy Bypass -File tests\r-business-flow-contract.ps1
git diff --check
```

## 六、继续推进顺序

1. 后端先解决首位成员创建 `code:500`，或提供可读取的测试成员。
2. 用真实成员复测 T03–T08、R01–R02 的读取和允许的写入闭环。
3. 对接口已存在但页面因没有稳定 ID 暂未开放的单条详情/编辑能力，拿到响应 DTO 和 ID 后逐项补齐。
4. 需要判断视觉问题时，以模拟器为准；浏览器主要用于接口、路由和网络请求验证。

## 七、交接边界

- 不应把“页面能打开”或“表单显示成功”写成后端业务成功；必须以服务端返回和后续读取回显为准。
- 不应添加 mock 成员、mock 视频、mock 消息详情或本地成功态补齐后端缺口。
- 不应在无人值守时执行短信、换绑、改密、退出、删除、审核或支付。
- 测试过程中产生的是测试家谱中的测试数据；后续清理需要由具备删除授权的人员单独确认后执行。