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

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

收件人：后端开发、运维、测试负责人

整理日期：2026-09-09

前端项目：jiapuapp

后端源码：C:\Users\Rain\Desktop\job\Genealogy

参考项目：C:\Users\Rain\Desktop\job\Jiapu-App

本文只汇总当前仍需要后端、运维或测试环境处理的有效问题。已经由前端完成的问题不再重复要求后端开发，历史文档与本文冲突时以本文为准。

问题一（P0）：线上世系排行接口成功但返回空数组

2026-09-09 后端更新后复验

前端拉取后端最新更新、重新编译并同步到 MuMu 后，该问题仍未解决：

• 测试成员：MANUALCHILD01；
• 成员条件：第 2 世、男性（前端请求参数为 generation=2&sex=0）；
• 编辑成员页“排行称谓”显示“暂无可选排行”；
• 返回树状图后，该成员节点仍显示“排行待补”；
• 同一页面的成员详情、父亲关系等数据均能正常读取，因此不是整个成员详情页或登录会话失效。

前端状态逻辑会把接口异常显示为“暂时无法读取”，把成功返回的空列表显示为“暂无可选排行”。本次 MuMu 实际显示的是后者，说明请求流程已经完成，但当前条件没有取得任何可用排行记录。该判断来自页面状态；下方 2026-09-04 的四组 JSON 是此前直接请求接口取得的响应证据。

请后端本次不要只确认“接口代码已存在”，需要在已部署环境、当前租户和当前测试家谱下实际请求并回传脱敏响应。至少验证：

GET /genealogy/app/genealogies/{genealogyId}/lineage/ranks?generation=1&sex=0
GET /genealogy/app/genealogies/{genealogyId}/lineage/ranks?generation=2&sex=0
GET /genealogy/app/genealogies/{genealogyId}/lineage/ranks?generation=2&sex=1

其中第二世男性结果必须包含“长子、次子”等，第二世女性结果必须包含“长女、次女”等；只返回 code=200 但 data=[] 仍视为未解决。

当前现象

前端已接入正式接口：

GET /genealogy/app/genealogies/{genealogyId}/lineage/ranks?generation={generation}&sex={sex}

2026-09-04 使用 MuMu 当前有效登录会话，针对联调家谱 2086296260134936577、租户 000000 直接请求线上环境。接口没有报错，所有请求均返回业务成功，但 data 是空数组：

generation=1&sex=0  -> {"code":200,"msg":"操作成功","data":[]}
generation=2&sex=0  -> {"code":200,"msg":"操作成功","data":[]}
generation=2&sex=1  -> {"code":200,"msg":"操作成功","data":[]}
generation=2&sex=2  -> {"code":200,"msg":"操作成功","data":[]}

这不是前端未发请求、鉴权失败或响应解析失败。普通成员因此无法选择“长子、次子、三子”等排行，人物保存后也没有可回显的 rankId、rankName。世系树只能显示“排行待补”，无法准确显示其与上一辈的排行关系。配偶不使用排行选项，仍由世系树的 spouses 结构显示“配偶”。

已核对的后端逻辑

后端接口与查询实现均已存在：

• AppLineagePersonController.rankOptions 接收 genealogyId、generation、sex；
• AppLineagePersonServiceImpl.rankOptions 完成家谱查看权限校验后查询排行配置；
• LineageRankConfigServiceImpl.queryOptions 只返回 status=0、性别适用且排行类型匹配的数据；
• 第一世查询 rank_type=ANCESTOR，其他世代查询 rank_type=GENERATION；
• 查询表为 gen_lineage_rank_config。

当前代码中的 genealogyId 只用于权限校验，实际排行查询没有按家谱 ID 过滤，而是读取当前租户下的公共排行配置。因此本问题优先检查租户 000000 的全局排行配置和租户拦截条件，不要只检查联调家谱本身。

仓库中的 script/sql/update/2026-07-29-genealogy-lineage-generation-rank.sql 已定义 37 条默认数据：1 条“始祖”、18 条男性排行、18 条女性排行。现有 2026-08-03 数据库备份中该表结构存在，但记录区为空。这与线上接口返回空数组一致，需由后端或运维核对线上库，不能由前端硬编码排行数据。

后端/测试数据处理要求

1. 先在线上实际租户库执行以下只读检查，确认数据是缺失、停用还是被逻辑删除：

   select rank_id, tenant_id, rank_code, rank_name, rank_type,
          gender_scope, rank_order, sort_order, status, del_flag
   from gen_lineage_rank_config
   where tenant_id = '000000'
   order by rank_type, gender_scope, rank_order;
   

2. 若记录不存在，先备份线上表，再按发布流程执行并核验 2026-07-29-genealogy-lineage-generation-rank.sql；不要直接在前端写死“长子、次子”等数据；

3. 若记录存在，检查 status='0'、del_flag='0'、rank_type 和 gender_scope 是否满足查询条件，并检查租户隔离是否错误过滤 000000 数据；

4. 第一世至少返回“始祖”，其他世代按性别返回“长子、次子、长女、次女”等可用选项；

5. 保存人物 rankId 后，人物详情和世系树必须回显一致的 rankId、rankName；

6. 已停用、已删除或不适用当前性别的排行不得出现在可选列表中；

7. 增加线上同结构数据库的集成测试，防止只验证 Mock 数据而没有验证迁移结果。

验收标准

• 第二世男性请求返回至少一个男性排行选项，且包含稳定的 rankId 和非空 rankName；
• 第一世请求返回“始祖”，第二世女性请求返回“长女、次女”等女性排行；
• 前端选择并保存后，重新进入调整排行页面仍选中原值；
• 返回世系树后节点显示保存的排行名称，不再出现“后代”兜底文案。

问题二（待部署验收）：我的家谱真实创建时间

当前现象

新版家谱首页需要在家谱卡片中展示“创建于”。此前以下两个正式接口只返回当前用户的加入时间 joinTime，没有返回家谱创建时间 createTime：

• GET /genealogy/app/genealogies/mine
• GET /genealogy/app/genealogies/{genealogyId}

joinTime 表示用户加入家谱的时间，不能替代家谱创建时间。

2026-09-05 更新：后端提交 0e8d094 已增加只读 createTime，前端也已完成响应保留和“创建于”展示。当前仅等待后端部署后进行真实接口验收；线上网关现阶段返回 502，尚不能判定线上完成。

后端处理要求

1. 由家谱响应模型统一拥有只读字段 createTime，我的家谱列表和家谱详情使用同一字段定义；
2. 字段取家谱记录的真实创建时间，不取成员关系创建时间或 joinTime；
3. 创建时间由服务端生成，创建后不可被客户端修改；
4. 已有家谱需要从现有家谱数据的创建时间完整回读，不允许只对新建家谱生效；
5. 同步更新正式 App OpenAPI、响应示例和接口契约测试。

验收标准

• 两个接口均稳定返回非空 createTime；
• 同一家谱在列表和详情中的 createTime 完全一致；
• 不同时间加入同一家谱的成员读取到相同的 createTime，但各自的 joinTime 可以不同；
• 编辑家谱名称、地区或简介后，createTime 不发生变化；
• 前端接入后将卡片文案由“加入于”调整为“创建于”。

当前待办总览

本清单已按后端最新源码重新核对，旧文档中的以下事项已经不再列为后端待办：

• AppGenealogyVo 已有稳定家谱编号 genealogyNo，前端已接入保留；
• 功德记录已经具备请求字段 mediaOssIds 和响应字段 mediaFiles；
• 谱文、成长记录、重要证件已经分别具备内容密码设置、解除、验证和短信找回接口；
• 前端可以用现有单条删除接口完成批量管理，不要求后端新增批量删除接口；
• 先前的“我的家谱无法读取”和合规文档接口异常已不再作为本轮待办。

当前需要后端、运维或测试环境处理的事项共五类：

优先级	事项	责任方	是否阻塞对应功能验收
P0	世系排行接口返回空数组	后端/运维	是
待部署	家谱真实创建时间	后端/运维	是
待部署	谱文正文多图片保存与回显	后端/运维	是
P1	应用推广 HTTPS 分享地址配置	后端/运维	是
P1	联调环境缺少可点击业务数据	后端/测试/运营	是

问题三（待部署验收）：谱文正文多图片保存与回显

1. 参考项目行为

参考项目 pages/index/puwen/add.vue 的谱文新增和编辑表单使用图片上传组件，维护 form.imgs 图片数组；谱文不仅有文字正文，也允许上传、删除和回显多张正文图片。

2. 最新实现状态

2026-09-05 更新：后端提交 0e8d094 已增加 mediaOssIds、mediaFiles 及文件引用和回收站处理；前端已完成正文多图添加、编辑回显、单图移除、顺序提交和详情预览。当前剩余事项是执行后端三段迁移、部署并使用真实 OSS 数据验收。

后端其他内容类型已经采用统一媒体契约，可直接沿用该方式。例如 AppMeritRecordBody.mediaOssIds 使用英文逗号分隔的正整数 OSS 编号，AppMeritRecordVo.mediaFiles 返回授权后的文件访问对象列表。

3. 后端处理要求

1. 数据库为谱文增加正文媒体 OSS 编号字段，名称和类型与现有内容媒体模型保持一致；
2. Article、创建/更新 DTO、查询 VO、Mapper 和 Service 同步增加对应字段；
3. 请求字段使用 mediaOssIds，格式与现有内容接口保持一致：空字符串表示清空，多项为英文逗号分隔的正整数 OSS 编号；
4. 响应字段使用 mediaFiles，类型为 List<BusinessFileAccessVo>，不得把数据库中的 OSS 编号直接暴露成可访问地址；
5. 封面 coverFile 与正文图片 mediaFiles 分开管理：封面用于列表缩略图，正文图片用于详情展示；
6. 创建、编辑、移入回收站、恢复和永久删除时，同步维护业务文件引用，避免文件被误删或形成无主引用；
7. 同步更新正式 App OpenAPI、字段格式校验、HTTP 契约测试和数据库事务测试。

涉及接口：

• POST /genealogy/app/genealogies/{genealogyId}/articles
• PUT /genealogy/app/genealogies/{genealogyId}/articles/{articleId}
• GET /genealogy/app/genealogies/{genealogyId}/articles
• GET /genealogy/app/genealogies/{genealogyId}/articles/{articleId}

4. 验收标准

• 新建谱文上传至少三张正文图片，保存后列表封面正常，详情按提交顺序显示三张正文图片；
• 编辑时删除一张、保留一张、新增一张，重新读取结果准确且顺序稳定；
• 提交 mediaOssIds="" 后正文图片清空，但 coverFile 不受影响；
• 无文件访问权限时不得返回可用下载地址；
• 谱文进入回收站和恢复后，正文图片引用保持一致；永久删除后按现有文件生命周期规则清理引用。

问题四（P1）：应用推广缺少可用的 HTTPS 分享地址

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

后端 ReferralService.buildShareUrl 依赖当前租户启用品牌配置中的 h5Domain。请核对联调租户的品牌配置，确保：

• h5Domain 非空；
• 使用可公开访问的 HTTPS 地址；
• 地址指向真实 H5 注册流程；
• 服务端生成的 shareUrl 携带推荐凭据，但不直接暴露内部用户编号。

验收标准：接口返回 code=200，并包含稳定的 referralCode、邀请人数、分享标题、分享文案和 HTTPS shareUrl；前端可据此生成二维码、复制链接并进入带推荐关系的注册流程。

问题五（P1）：联调环境缺少完整可点击业务数据

以下项目已有前端页面和接口调用，但仅有空数据时无法完成图片预览、视频播放、内容密码、编辑和删除等点击回归。请为同一测试账号、同一家谱准备最小数据：

数据类型	最小验收数据
家族动态	一条纯文字动态、一条带图片动态
谱文	一篇带封面和正文多图的普通谱文、一篇已设置内容密码的谱文
礼仪活动	一条带封面活动，并包含可查看的献礼记录
家族视频	一条带封面且视频文件可播放的数据
平台宣传视频	home_featured、video_center 各至少一条带封面且可播放的数据
功德记录	一条带金额和至少两张图片的数据
家族备忘	general、benefactor 各至少一条带图片的数据
亲友往来	一条带图片的记录
成长记录	一条带图片的普通记录、一条已设置内容密码的记录
重要证件	一份带图片的普通证件、一份已设置内容密码的证件
家族相册	一个至少包含两张可预览图片的相册

所有文件响应必须通过 BusinessFileAccessVo 返回当前账号可访问的 HTTPS 地址，不能只返回 OSS 编号。

前端已经完成，不需要后端重复开发

1. 谱文、成长记录、重要证件的新建表单已支持选填 8 至 128 位内容密码；前端先创建内容，再调用现有内容保护接口。第二步失败时会明确提示“内容已创建、当前可能尚未受密码保护”，不会重复创建；
2. 谱文、家族视频、礼仪、功德记录、亲友往来、家族备忘、成长记录和重要证件列表已补批量管理；只允许选择具有删除权限的内容，逐条调用现有删除接口，失败项保留选择；
3. 我的家谱响应已保留后端返回的 genealogyNo；
4. 宣传视频无封面时使用可点击占位封面，点击后进入播放器，不再在首页直接铺开播放器；
5. 首页结构、浅色页面底色、固定双图内容区、底部导航名称和家族内容归位均已在前端完成；
6. 出生日期选择器已经限制未来年份和未来月份，不需要后端修改日期接口；
7. 世系树头像框、姓名、排行标签、配偶标签和节点布局已经按参考项目调整；后端只需解决排行选项及 rankId、rankName 回显；
8. 前端已通过项目页面、审计回归、导航恢复、参考功能映射和运行时资产检查。

后端完成后请回传

1. 后端提交编号和联调环境部署时间；
2. gen_lineage_rank_config 的线上检查结果、补数或迁移记录，以及四组排行请求的脱敏响应；
3. 家谱列表和详情接口新增 createTime 后的脱敏响应；
4. 谱文媒体字段的数据库迁移名称及后置检查结果；
5. 更新后的正式 App OpenAPI；
6. 谱文多图创建、更新、清空、回收站和恢复的自动化测试结果；
7. /referrals/me 的脱敏响应示例；
8. 测试数据所属家谱编号、各资源编号和测试账号权限说明。

建议后端按“问题一 → 问题二 → 问题三 → 问题四 → 问题五”的顺序处理。问题一是当前世系树排行功能的直接阻塞项，补齐数据后即可由前端在 MuMu 上复验；问题二和问题三涉及正式响应契约，需要同时更新运行时代码、OpenAPI 和测试；问题四、问题五主要是线上配置与联调数据准备。

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