169 lines
14 KiB
Markdown
169 lines
14 KiB
Markdown
# APP 前后端联调结果与后端处理单
|
||
|
||
更新时间：2026-08-22
|
||
|
||
收件人：后端开发、接口维护、测试与部署人员
|
||
|
||
## 结论
|
||
|
||
本轮已按后端最新源码 `C:\Users\Rain\Desktop\job\Genealogy`（核对提交 `16600afb57e79569907d673ce6742595a27dfecc`）重新接入前端，并在已登录的 MuMu 模拟器中完成真实点击验证。
|
||
|
||
微信登录/绑定、VIP 多支付契约、推荐关系、动态权限、内容密码找回、家谱永久删除、动态业务字典和族人敏感资料等能力在最新后端源码中已经存在。2026-08-17 文档中将这些能力标为“后端缺失”的描述已过期，不应继续据此重复开发。
|
||
|
||
当前已确认 1 个阻断正常功能的后端源码缺陷、2 个既有 OpenAPI 错误、5 项新增业务契约缺口，以及 1 项宣传视频投放数据待配置。此前联调发现的编译、并发取消、VIP capability 字段读取、家谱总览和宣传视频入口问题已处理；参考项目复核发现的订单展示等纯前端问题不列为后端任务。
|
||
|
||
## MuMu 点击验收表
|
||
|
||
| 用户路径 | 结果 | 实际表现 | 责任/下一步 |
|
||
| --- | --- | --- | --- |
|
||
| 我的 → 账号与安全 | 通过 | 登录资料、改密、换绑手机、绑定微信入口正常显示 | 正式微信能力仍需正式签名包和开放平台参数验证 |
|
||
| 我的 → 应用推广 | 部分通过 | 推荐码、邀请人数、复制推荐码和系统分享文字正常显示 | 参考项目还有注册链接二维码/复制链接；当前后端未返回可信 `shareUrl` |
|
||
| 我的 → 意见反馈 | 通过 | 动态类型“建议/故障/投诉/其他”和历史记录正常显示 | 未提交测试数据，避免污染线上数据 |
|
||
| 我的 → VIP 服务 | 部分通过 | 套餐和订单正常显示；服务端禁用购买时显示“VIP购买暂未开放” | 购买成功路径需开启渠道后再测；订单号与双时间缺失属于前端展示问题 |
|
||
| 家谱 → 我的家谱 | 通过 | 多个家谱可加载、切换，当前家谱和成员数正常显示 | 无 |
|
||
| 家谱 → 家谱总览 | 通过（前端绕开缺陷） | 谱名、地区、成员数、世系数、加入日期正常显示 | 当前临时从 `mine` 列表取得总览资料；后端详情缺陷修复后应恢复详情单一来源 |
|
||
| 家谱总览 → 申请审核 | 通过 | 空状态正常显示 | 无 |
|
||
| 家谱总览 → 世系树 | 通过 | 3 位人物和关系图正常渲染；人物操作面板可打开 | 无 |
|
||
| 世系树 → 人物资料/编辑 | 通过 | 详情和编辑页正常打开 | 未保存修改，避免污染线上数据 |
|
||
| 编辑成员 → 学历分类 | 通过 | MuMu 中选择器显示“文盲、私塾、幼儿园、小学……”等动态字典项 | 前端已修复并发请求互相取消问题 |
|
||
| 家谱首页 → 宣传视频 | 部分通过 | 首页宣传视频区域正常显示，“查看更多”可进入宣传视频页，不再被路由拦截；`home_featured` 和 `video_center` 均为空 | 后端/运营需按下述投放要求配置可用视频和封面后再测播放 |
|
||
| 家谱总览 → 家谱设置 | 阻断 | 前端不再无限加载，能进入明确的读取失败状态 | 后端需修复下述 P0 源码缺陷 |
|
||
| 家谱首页 → 功德记录图片 | 阻断 | MuMu 选择图片并创建记录成功，但重新打开详情没有图片；测试记录随后已删除 | `AppMeritRecordBody/Vo` 缺媒体字段，后端需补文件关联契约 |
|
||
|
||
本轮只执行读取、导航、打开选择器等非破坏性点击；没有提交反馈、修改成员、发验证码、绑定微信、购买 VIP、归档或永久删除。
|
||
|
||
## P0：普通家谱所有者无法读取家谱详情和设置
|
||
|
||
### 复现
|
||
|
||
使用普通生命周期 `NORMAL` 的家谱所有者请求：
|
||
|
||
- `GET /genealogy/app/genealogies/{genealogyId}`
|
||
- `GET /genealogy/app/genealogies/{genealogyId}/permanent-deletion/capability`
|
||
|
||
服务端返回业务错误：`家谱必须先归档`。MuMu 中“家谱设置”因此无法读取。
|
||
|
||
### 源码原因
|
||
|
||
1. `AppGenealogyServiceImpl.detail()` 为谱主拼装永久删除能力时调用 `permanentDeletionService.capability()`。
|
||
2. `GenealogyPermanentDeletionService.capability()` 调用 `requireOwner()`。
|
||
3. `requireOwner()` 不只校验所有者，还强制生命周期必须为 `ARCHIVED`，否则直接抛错。
|
||
4. 但 `GenealogyDeletionEligibilityService` 本身已经能用 `GENEALOGY_NOT_ARCHIVED` 表达“当前不可永久删除”。生命周期不满足应是 capability 的禁用原因，不应让详情和 capability 查询失败。
|
||
|
||
### 后端修复要求
|
||
|
||
- 将“所有者鉴权”和“已归档资格”拆开。
|
||
- capability 查询：谱主 + 普通家谱应成功返回 `canDeletePermanently=false`，`disabledReasons` 包含 `GENEALOGY_NOT_ARCHIVED`。
|
||
- 发码和提交永久删除：继续通过 eligibility 严格拒绝未归档家谱。
|
||
- `AppGenealogyServiceImpl.detail()` 对普通谱主必须成功，不能因附加删除能力投影而失败。
|
||
- 增加自动化测试：普通谱主详情、普通谱主 capability、归档谱主 capability、非谱主 capability、未归档发码/提交拒绝。
|
||
|
||
相关源码：
|
||
|
||
- `ruoyi-modules/ruoyi-genealogy/src/main/java/cn/ddxcjp/genealogy/service/impl/AppGenealogyServiceImpl.java:220`
|
||
- `ruoyi-modules/ruoyi-genealogy/src/main/java/cn/ddxcjp/genealogy/service/GenealogyPermanentDeletionService.java:29`
|
||
- `ruoyi-modules/ruoyi-genealogy/src/main/java/cn/ddxcjp/genealogy/service/GenealogyPermanentDeletionService.java:72`
|
||
|
||
## P1：后端 OpenAPI 与 Java 返回对象不一致
|
||
|
||
### VIP capability 字段
|
||
|
||
实际 Java VO `VipPaymentMethodCapabilityVo` 和线上响应均返回：
|
||
|
||
```json
|
||
{ "method": "WECHAT", "enabled": false, "disabledReason": "VIP购买暂未开放" }
|
||
```
|
||
|
||
后端自带 `doc/apifox/genealogy-app-openapi.yaml` 却声明 `paymentMethod`，相关 OpenAPI 契约测试也按 `paymentMethod` 断言。前端已按真实 Java 契约统一使用 `method`，仓库内 OpenAPI 副本也已同步。
|
||
|
||
后端需要把 canonical OpenAPI 和 `FrontendHandoffFinalOpenApiContractTest` 改为 `method`；不要同时返回两个别名。
|
||
|
||
### 谱文分类写接口响应
|
||
|
||
后端 OpenAPI 中以下接口的 `200` 响应误写成“APP 微信支付下单参数”并引用 `PaymentOrderVo`：
|
||
|
||
- `POST /genealogy/app/genealogies/{genealogyId}/article-categories`
|
||
- `PUT /genealogy/app/genealogies/{genealogyId}/article-categories/{categoryId}`
|
||
|
||
应改为真实的谱文分类结果 `AppArticleCategoryResult`，并同步契约测试。前端仓库内 OpenAPI 副本已纠正。
|
||
|
||
## P1：宣传视频投放位当前没有可验收数据
|
||
|
||
### MuMu 实测
|
||
|
||
- `GET /genealogy/app/platform-videos?placement=home_featured` 返回空列表，首页只能显示“暂时没有推荐视频”。
|
||
- `GET /genealogy/app/platform-videos?placement=video_center` 返回空列表，点击“查看更多”后页面显示“暂时没有可观看的平台视频”。
|
||
- 请求成功且不是错误响应，说明前端入口和读取契约已生效，当前缺的是处于有效发布时间范围内的投放数据。
|
||
|
||
### 后端/运营处理要求
|
||
|
||
- 至少配置一条 `home_featured` 和一条 `video_center` 数据；同一视频如需同时出现，应按后端投放模型明确配置，不能要求客户端跨投放位猜测。
|
||
- 每条数据必须返回可访问的 `videoFile`；建议同时提供 `coverFile`，首页和列表会先显示封面，点击后播放指定视频。
|
||
- 确认数据状态、`startAt`、`endAt` 与当前服务器时间满足可见条件，业务文件访问地址可在 App 端读取。
|
||
- 当前 `PlatformVideoVo` 是“视频 + 可选封面”模型，不支持独立的纯图片宣传项。如果产品要求图片也作为可点击宣传内容，需要后端另行定义混合媒体类型、目标行为和唯一响应契约，前端不应把封面伪装成独立图片内容。
|
||
|
||
### 验收
|
||
|
||
1. 首页显示最多两条封面，点任一封面直接打开对应视频。
|
||
2. “查看更多”显示 `video_center` 封面列表，点封面进入纵向播放器。
|
||
3. 视频可播放、上下切换、点赞、评论和返回；过期或停用内容不返回。
|
||
|
||
## P1：第四轮对比新增的后端契约任务
|
||
|
||
| 事项 | 当前源码/契约事实 | 后端处理要求 | 联调通过标准 |
|
||
| --- | --- | --- | --- |
|
||
| 功德记录图片 | `AppMeritRecordBody`、`AppMeritRecordVo` 没有 `mediaOssIds/mediaFiles`；MuMu 已复现上传后不回显 | 复用业务文件引用，创建/更新接收媒体 ID 集合，列表和详情返回授权文件；明确空数组为清空 | 新增、编辑保留、移除、列表首图、详情预览、回收站权限全部通过 |
|
||
| 创建家谱始迁祖 | 前端创建请求已有 `firstAncestorName`，`AppGenealogyCreateBody` 和创建事务没有该字段 | 在创建家谱事务内原子创建第一代人物；失败整体回滚，避免只建家谱未建人物 | 创建完成后世系树立即出现同名第一代人物；重复提交不产生重复人物 |
|
||
| 推广注册链接 | `ReferralMeVo` 只有推荐码、人数、标题和文案，没有可用于二维码/复制的可信链接 | 增加由服务端配置并生成的 `shareUrl`，不要要求前端拼接旧 H5 域名或暴露内部用户 ID | App 可复制链接、生成二维码；扫码进入注册后推荐关系只绑定一次 |
|
||
| 封面清空语义 | Java 更新服务可把 `coverOssId` 设为 `null` 并替换文件引用，但 OpenAPI 未声明 nullable，前端规范化会丢弃显式空值 | 统一谱文、礼仪、视频更新契约：明确 `null` 表示移除封面并释放旧引用；同步 OpenAPI 和契约测试 | 有封面的记录执行移除后，详情返回 `coverFile=null`，旧文件引用释放，其他字段不变 |
|
||
| 列表记录创建时间 | 参考相册、礼仪、功德、成长记录、贺礼簿和家族恩人列表均显示 `create_time`；当前对应 APP VO 没有 `createTime`，现有业务时间字段不是同一语义 | 先为已确认映射的 `AppAlbumVo/AppCeremonyVo/AppMeritRecordVo/AppGrowthRecordVo/AppRelativeRecordVo` 和 OpenAPI 增加只读 `createTime`；家族恩人确认存储方案后，复用 Memo 时再补 `AppMemoVo.createTime`，独立建模时由唯一新 VO 持有；不要要求客户端提交，也不要用业务时间回填 | 列表和详情均返回稳定时间；新增后非空；编辑业务日期不改变创建时间；客户端可同时显示创建时间和业务时间 |
|
||
|
||
提现记录已有 `auditRemark/payoutReference/paidAt`，前端会先展示这些现有字段。只有产品明确要求区分“审核时间”和“到账时间”时，后端才需要新增独立 `reviewedAt`；不得把 `paidAt` 改名或冒充审核时间。
|
||
|
||
## 前端本轮已完成
|
||
|
||
- 修复 `ceremony-service.js` 导入不存在导出导致 HBuilderX 编译失败。
|
||
- VIP capability 按真实后端 VO 的 `method` 字段读取，MuMu 已验证套餐和订单恢复显示。
|
||
- 家谱基础列表不再读取由独立永久删除 capability 接口拥有的字段。
|
||
- 家谱总览暂时从 `GET /genealogies/mine` 读取当前家谱，避免被后端详情缺陷连带阻断。
|
||
- 家谱设置的两条并发读取使用独立取消控制器，修复无限加载。
|
||
- 编辑成员的 3 条、添加亲属的 5 条动态字典请求分别使用独立取消控制器，修复选择器空白。
|
||
- 族人资料已使用 `zodiacCode`、`educationCode`、`deathExpressionCode`、`relationVariantCode`，遗传病史等敏感资料使用独立 `/sensitive-profile` 契约。
|
||
- 微信绑定、推荐资料、权限目录、视频分页评论、内容密码找回、VIP 多支付和永久删除页面已接入最新接口。
|
||
- 家谱首页已接入 `home_featured` 两条封面预览，宣传视频列表已改为封面优先展示并支持 `videoId` 直达播放。
|
||
|
||
## 后端回传验收材料
|
||
|
||
修复后请提供：
|
||
|
||
1. 上述 P0 场景的自动化测试结果。
|
||
2. 更新后的 canonical APP OpenAPI。
|
||
3. 已部署环境版本号或提交号。
|
||
4. 普通谱主详情和永久删除 capability 的实际响应样例。
|
||
5. `home_featured`、`video_center` 各至少一条可用宣传视频及封面，由测试环境实际接口返回。
|
||
6. 功德图片、始迁祖、推广 `shareUrl`、封面清空语义和五类已确认映射记录 `createTime` 的更新后契约与自动化测试结果；家族恩人契约等待产品选型后另行确认。
|
||
|
||
收到部署确认后，前端只需再次在 MuMu 点击“家谱设置”，并回归详情、归档、恢复和永久删除能力状态；不会再补旧字段兼容。
|
||
|
||
## 2026-08-23 运行时复验补充
|
||
|
||
本轮在用户已登录的 MuMu 中重新实点“家谱总览 → 家谱设置”，首次读取仍进入“家谱设置暂时无法读取”；点击“重新读取”后截图哈希完全相同，说明当前部署环境的 P0 阻断仍然存在。证据见 [当前设置失败](audit-2026-08-23/27-current-settings.png) 和 [重试后状态](audit-2026-08-23/28-current-settings-retry.png)。
|
||
|
||
同时在参考项目浏览器中确认了以下后端交接需求的真实产品用途：
|
||
|
||
- 推广 `shareUrl` 用于页面二维码与注册链接分享，不是用推荐码文本可以完全替代的字段。
|
||
- 参考列表的 `createTime` 是记录创建时间，不能用礼仪时间、功德时间、提醒时间等业务发生时间冒充；五类已确认映射记录先补，家族恩人随选定契约补。
|
||
- 当前重要证件查询能力已足够支持家谱级聚合页，不需要为入口另造接口。
|
||
- VIP 的 `orderNo/payTime/expireTime` 均是参考购买记录直接显示的独立字段，前端修复后需要后端继续稳定返回。
|
||
|
||
### 暂不交给后端开发的产品确认项
|
||
|
||
参考项目 `pages/index/memorandum/*` 的真实页面名称是“家族恩人”，不是普通“备忘录”；MuMu 实点确认当前入口和表单都是提醒型“家族备忘”，最新后端主业务代码也只有 `Memo`，没有恩人类型。因此业务语义缺口已确认，但后端实现需先由产品选择以下二选一：
|
||
|
||
1. “家族恩人”是独立家族档案：再由前后端共同定义唯一数据契约、权限和迁移方式。
|
||
2. “家族恩人”只是备忘录的一种分类：由 `Memo` 契约增加明确且受校验的业务类型，前端按类型提供入口和文案。
|
||
|
||
确认前请勿仅按路由英文名把两者合并，也不要先增加猜测字段。参考“贺礼簿”则已确认对应当前更结构化的 `RelativeRecord`/“往来记录”，不需要另建一套后端接口。
|
||
|
||
完整截图与前后端责任拆分见 [2026-08-23 点击对比审查](click-comparison-audit-2026-08-23.md)。
|