rain/jiapuapp

Fork 0

Files

T

rain 9ad572907b feat: 完成前端业务闭环与后端联调

2026-08-24 23:37:56 +08:00

14 KiB

Raw Blame History

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 中“家谱设置”因此无法读取。

源码原因

AppGenealogyServiceImpl.detail() 为谱主拼装永久删除能力时调用 permanentDeletionService.capability()。
GenealogyPermanentDeletionService.capability() 调用 requireOwner()。
requireOwner() 不只校验所有者，还强制生命周期必须为 ARCHIVED，否则直接抛错。
但 GenealogyDeletionEligibilityService 本身已经能用 GENEALOGY_NOT_ARCHIVED 表达“当前不可永久删除”。生命周期不满足应是 capability 的禁用原因，不应让详情和 capability 查询失败。

后端修复要求

将“所有者鉴权”和“已归档资格”拆开。
capability 查询：谱主 + 普通家谱应成功返回 canDeletePermanently=false，disabledReasons 包含 GENEALOGY_NOT_ARCHIVED。
发码和提交永久删除：继续通过 eligibility 严格拒绝未归档家谱。
AppGenealogyServiceImpl.detail() 对普通谱主必须成功，不能因附加删除能力投影而失败。
增加自动化测试：普通谱主详情、普通谱主 capability、归档谱主 capability、非谱主 capability、未归档发码/提交拒绝。

P1：后端 OpenAPI 与 Java 返回对象不一致

VIP capability 字段

实际 Java VO VipPaymentMethodCapabilityVo 和线上响应均返回：

{ "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 是“视频 + 可选封面”模型，不支持独立的纯图片宣传项。如果产品要求图片也作为可点击宣传内容，需要后端另行定义混合媒体类型、目标行为和唯一响应契约，前端不应把封面伪装成独立图片内容。

验收

首页显示最多两条封面，点任一封面直接打开对应视频。
“查看更多”显示 video_center 封面列表，点封面进入纵向播放器。
视频可播放、上下切换、点赞、评论和返回；过期或停用内容不返回。

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 直达播放。

后端回传验收材料

修复后请提供：

上述 P0 场景的自动化测试结果。
更新后的 canonical APP OpenAPI。
已部署环境版本号或提交号。
普通谱主详情和永久删除 capability 的实际响应样例。
home_featured、video_center 各至少一条可用宣传视频及封面，由测试环境实际接口返回。
功德图片、始迁祖、推广 shareUrl、封面清空语义和五类已确认映射记录 createTime 的更新后契约与自动化测试结果；家族恩人契约等待产品选型后另行确认。

收到部署确认后，前端只需再次在 MuMu 点击“家谱设置”，并回归详情、归档、恢复和永久删除能力状态；不会再补旧字段兼容。

2026-08-23 运行时复验补充

本轮在用户已登录的 MuMu 中重新实点“家谱总览 → 家谱设置”，首次读取仍进入“家谱设置暂时无法读取”；点击“重新读取”后截图哈希完全相同，说明当前部署环境的 P0 阻断仍然存在。证据见当前设置失败和重试后状态。

同时在参考项目浏览器中确认了以下后端交接需求的真实产品用途：

推广 shareUrl 用于页面二维码与注册链接分享，不是用推荐码文本可以完全替代的字段。
参考列表的 createTime 是记录创建时间，不能用礼仪时间、功德时间、提醒时间等业务发生时间冒充；五类已确认映射记录先补，家族恩人随选定契约补。
当前重要证件查询能力已足够支持家谱级聚合页，不需要为入口另造接口。
VIP 的 orderNo/payTime/expireTime 均是参考购买记录直接显示的独立字段，前端修复后需要后端继续稳定返回。

暂不交给后端开发的产品确认项

参考项目 pages/index/memorandum/* 的真实页面名称是“家族恩人”，不是普通“备忘录”；MuMu 实点确认当前入口和表单都是提醒型“家族备忘”，最新后端主业务代码也只有 Memo，没有恩人类型。因此业务语义缺口已确认，但后端实现需先由产品选择以下二选一：

“家族恩人”是独立家族档案：再由前后端共同定义唯一数据契约、权限和迁移方式。
“家族恩人”只是备忘录的一种分类：由 Memo 契约增加明确且受校验的业务类型，前端按类型提供入口和文案。

确认前请勿仅按路由英文名把两者合并，也不要先增加猜测字段。参考“贺礼簿”则已确认对应当前更结构化的 RelativeRecord/“往来记录”，不需要另建一套后端接口。

完整截图与前后端责任拆分见 2026-08-23 点击对比审查。

14 KiB Raw Blame History Unescape Escape