jiapuapp/docs/全量页面接口联调交接说明-2026-07-24.md

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

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

一、交接结论

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

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

2026-07-26 的浏览器真实上传复测还确认了第二个合同阻塞：H5 已能从页面选择本地图片并完成 init/chunk/complete 上传，但 complete.ossId 是 19 位字符串，而照片/封面等业务 DTO 仍要求数值 int64。前端不能安全地把该值转成 JavaScript number，因此目前不会伪造照片创建成功。完整请求、响应和后端所需统一字段合同见 docs/后端接口缺口与首位成员阻塞清单-2026-07-24.md 的“八”。

二、本轮已验证的范围

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 “录入首位成员”已完成前端表单校验与请求组装；使用合法最小请求（姓名、第一世）调用：

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 安全概览	已接真实 profile 只读概览	2026-07-26 实测 GET /auth/profile 返回 phone、userNo、status；页面仅展示掩码手机号、账号编号和状态。设备与登录记录仍无独立读取 operation，不展示或推断。
M05 换绑手机号	等待人工 TAC/短信验证	缺少可安全消费的当前手机号 DTO 与已核实验证码链路。
删除、退出、改密、支付	未执行	本轮测试范围禁止敏感操作。

五、复测方式

5.1 前置条件

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

5.2 全页面路由复核

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

$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 -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 消息详情或本地成功态补齐后端缺口。
• 不应在无人值守时执行短信、换绑、改密、退出、删除、审核或支付。
• 测试过程中产生的是测试家谱中的测试数据；后续清理需要由具备删除授权的人员单独确认后执行。