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

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

整理日期：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 是此前直接请求接口取得的响应证据。

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

```text
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` 是空数组：

```text
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. 先在**线上实际租户库**执行以下只读检查，确认数据是缺失、停用还是被逻辑删除：

   ```sql
   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 点击回归为准，不能只以“代码已提交”或“自动测试通过”作为联调完成依据。