jiapuapp/docs/后端线上联调故障与数据准备清单.md

后端线上联调故障与数据准备清单

收件人：后端开发、运维、测试负责人
整理日期：2026-08-24
联调环境：正式接口 https://backend-api.ddxcjp.cn，租户 000000

一、结论

前端已按最新 App OpenAPI 和后端提交 de4cc9a 完成适配，并已移除预览数据回退。当前页面中的“无内容”分为两类：

类型	数量	结论
线上接口或配置故障	3 项	需要后端、运维处理
接口成功但测试数据为空	8 类	不是前端故障，需要后端测试环境准备数据
本轮确认的前端问题	2 项	已修复并通过自动检查

本轮前端检查结果：60 个页面与 60 条路由一致；参考项目 78 条功能路由均已有对应关系；导航恢复、契约回归和 12 项运行时资产测试全部通过。

二、必须处理的线上问题

问题一：我的家谱接口无法完成首页读取

接口：GET /genealogy/app/genealogies/mine

现象：2026-08-24 22:17 将本轮新构建运行到 MuMu 后，已登录账号点击“重新加载”，家谱首页仍稳定进入“暂时无法读取家谱”状态，具体提示为“家谱服务暂时无法读取，请稍后重试”。该登录态访问个人资料和其他家族业务接口能够成功，因此不能归因于模拟器断网或整体登录失效。

前端已确认：

• 正式包请求地址和接口路径正确；
• 请求失败和成功空数组使用不同页面状态；
• 前端没有家谱预览数据或假数据回退；
• 本轮已增加错误类型显示。重新编译后，若后端响应结构不符合契约，会显示“服务返回的家谱数据不完整”；网络、登录、权限和服务异常也会分别提示。

本次实际命中的是服务异常提示，不是网络异常、登录失效、无权限或前端响应结构校验异常。因此排查重点应放在线上接口业务异常、SQL 异常和部署版本，不需要前端放宽字段校验来掩盖故障。

后端最新代码中，该接口会读取家谱实体并返回 AppGenealogyVo。2026-08-24 迁移又为 gen_genealogy 增加了 create_request_id、first_ancestor_name、root_person_id。因此请优先排查以下三项：

1. 线上是否确实部署了提交 de4cc9a，而不是只合并到代码仓库；
2. 是否按顺序执行 2026-08-24-app-legacy-parity-closure-precheck.sql、迁移脚本和后置检查；
3. 后置检查的 app_legacy_parity_postcheck_blocking_count 和 blocking_count 是否都为 0。

同时请用当前测试账号直接调用接口并保存完整响应及服务端异常日志，重点核对每条家谱是否稳定返回：

• genealogyId：正整数；
• genealogyName：非空；
• memberCount：非负整数；
• personCount：空或非负整数；
• visibility、joinMode、lifecycleStatus：合法枚举；
• canManage、canEditContent、canArchive、canRestore：布尔值。

验收标准：同一账号连续调用三次均返回 code=200，data 为合法数组；MuMu 点击“重新加载”后正常显示家谱卡片或真实空状态。

问题二：用户协议和隐私政策免登录接口返回 500

接口：

• GET /genealogy/app/compliance/documents/user_agreement
• GET /genealogy/app/compliance/documents/privacy_policy

2026-08-24 复测原始响应，两条接口均为：

{"code":500,"msg":"发生未知异常，请联系管理员","data":null}

这是不携带登录令牌即可复现的后端问题，与前端页面、登录态和 MuMu 无关。后端当前实现预期在未发布时返回“合规文档尚未发布”，线上却变成未知异常，说明仍需检查线上表结构、发布数据、租户数据隔离或异常处理。

请执行并提供以下检查结果：

1. 合规文档首次发布及换行修复 SQL 的后置检查结果，所有 blocking_count 必须为 0；
2. 租户 000000 下两份文档、当前版本、版本状态和内容摘要的查询结果；
3. 两条免登录请求对应的后端异常堆栈；
4. 确认请求只需要正确的 clientid 和租户头，不应依赖登录令牌。

验收标准：两条接口均返回 code=200、非空标题、版本号、正文和内容摘要；不携带 Authorization 仍可读取。

问题三：应用推广资料读取失败

接口：GET /genealogy/app/referrals/me

现象：2026-08-24 22:21 MuMu 点击进入“应用推广”，推广内容列表能够正常展示，但顶部推荐资料卡明确显示“推荐码暂时无法读取”。这说明页面和推广内容接口正常，故障集中在推荐资料接口。前端已使用后端返回的 shareUrl，没有自行拼接内部用户编号。

后端 ReferralService.buildShareUrl 明确依赖当前租户品牌配置中的 h5Domain，配置为空、格式错误或不是 HTTPS 都会直接抛出业务异常。请核对租户 000000 的启用品牌配置，并确保 h5Domain 是可访问的 HTTPS H5 注册地址。

验收标准：接口返回 code=200，包含稳定推荐码、推荐人数、分享标题、分享文案和 HTTPS shareUrl；链接不暴露内部用户编号，打开后能进入注册流程并携带推荐凭据。

三、需要准备的联调数据

以下页面已确认能够区分“读取失败”和“成功但为空”。当前显示无内容，是接口成功返回空数组或零条记录，不属于前端渲染故障。请在测试环境为当前测试家谱准备最小可点击数据：

数据类别	当前结果	最小验收数据
家族动态	成功，空列表	1 条带图片动态、1 条纯文字动态，可进入详情
谱文	分类接口可读，谱文为空列表	1 篇带封面谱文、1 篇设有内容密码的谱文
礼仪活动	成功，空列表	1 条带封面活动，可进入详情并读取献礼列表
家族备忘	成功，空列表	general 和 benefactor 各 1 条
亲友往来	成功，空列表	1 条带图片记录，可查看完整详情
功德记录	成功，空列表	1 条带金额和图片记录
家族视频与平台宣传视频	家族视频为空；首页平台视频因家谱首页故障暂不能完成内容态验收	各 1 条带封面且视频地址可播放的数据，并正确配置平台视频投放位
相册照片	已有相册 CHECKDELETE01，照片数为 0	在该相册中加入至少 2 张当前账号可访问的图片

这些数据的文件字段必须返回当前账号可访问的 HTTPS 地址，不能只返回 OSS 文件编号。

四、本轮前端已处理

1. 家谱首页不再把所有异常统一显示成“网络或服务不可用”，现在会区分网络、登录、权限、服务失败和响应结构不完整。
2. 谱文分类接口失败时不再静默转换为空分类；页面会明确提示“分类读取失败”，同时保留已成功读取的全部谱文。
3. 已增加对应回归检查，防止以后再次把请求失败伪装为空数据。

五、后端回传材料

完成后请一次性提供：

1. 线上实际部署提交编号和部署时间；
2. 2026-08-24 迁移及所有相关后置检查结果，最终 blocking_count=0；
3. 上述三项故障接口的完整响应示例和对应服务端日志结论；
4. 测试数据所属家谱编号、数据编号和账号权限；
5. 更新后的正式 App OpenAPI（如接口字段、枚举或错误码发生变化）。

仅提供“代码已提交”“自动测试通过”或“域名可以访问”不能作为线上联调完成依据，最终以同一部署环境中的接口响应和 MuMu 点击回归为准。