jiapuapp/docs/后端待处理事项与验收标准.md

后端待处理事项与验收标准

本文件保留前期任务和验收历史。2026-08-24 最新线上复测结论请发送《后端线上联调故障与数据准备清单》，不要再把下文已完成的旧任务整体当作当前待办发送。

收件人：后端开发、接口维护、测试负责人
整理日期：2026-08-23
适用项目：家谱 App

2026-08-24 联调状态更新

• 已确认后端提交 de4cc9a（“完成旧版 APP 业务契约闭环”）已进入当前后端 main 分支，后端交接单所列八项契约均已落库到正式 App OpenAPI。
• 前端已完成对应适配：建谱幂等与始迁祖、封面三态清空、功德图片、家族恩人分类、创建时间、推广链接、换绑当前密码校验以及安全操作后重新登录。
• 前端自动检查已通过；MuMu 已点击确认“家族恩人”入口/新建表单、“换绑手机号”的当前密码字段、“应用推广”的复制链接和系统分享入口。
• 2026-08-24 21:33 复测：正式域名和 MuMu 网络均已恢复，地区接口返回 code=200，登录验证策略接口也返回 code=200；但家谱首页、推荐卡仍在 MuMu 读取失败，user_agreement 与 privacy_policy 两个免登录合规接口均返回 code=500、发生未知异常，请联系管理员。因此接口数据写入、旧令牌失效及服务端回读仍未完成线上联调验收。请后端核对线上部署提交、迁移数据库与 postcheck 结果，不能把“域名可访问”或“代码已提交”视为“线上联调已通过”。

下文保留为原始后端任务与回归基线；其中“待处理”表示本轮交接前的状态，最终以本节联调状态为准。

一、总体结论

前端当前能够独立完成的差异项已经处理并通过代码检查。真机点击回归后，仍有以下后端事项需要处理：

1. 一项现有接口故障需要修复；
2. 八项后端能力或契约需要补齐；
3. 七类联调数据需要在测试环境准备；
4. 所有完成后的接口契约必须同步回写到 genealogy-app-openapi.yaml，不能只改实现、不改文档。

接口路径和英文字段名属于技术契约，下面保留在括号中；任务名称、业务说明和验收标准均使用中文。

二、最高优先级：修复家谱设置读取

任务名称：家谱基础设置正常读取

当前现象：进入“家谱设置”后直接显示“家谱设置暂时无法读取”。

涉及接口：

• 查询家谱基础资料：GET /genealogy/app/genealogies/{家谱编号}
• 查询永久注销资格：GET /genealogy/app/genealogies/{家谱编号}/permanent-deletion/capability

处理要求：

1. 已加入且有查看权限的普通家谱成员必须能够正常读取家谱基础资料。
2. 家谱基础资料接口不得依赖永久注销资格接口成功后才返回。
3. 普通家谱不满足永久注销条件时，资格接口应正常返回“不可永久注销”和明确原因，不能因为家谱未归档直接抛系统错误。
4. 家谱基础资料至少稳定返回：家谱编号、家谱名称、姓氏、地区编码、公开范围、简介、成员数量、世系人物数量、归档状态。
5. 权限不足、家谱不存在、参数错误和系统异常必须使用不同的业务错误码。

验收标准：

• 测试家谱 MANUALTEST20260809 可以正常进入设置表单；
• 普通家谱返回“不可永久注销”时，设置表单仍然可以读取和编辑；
• 无权限账号被明确拒绝，但不能返回模糊的系统错误。

三、需要补齐的后端能力

任务一：功德记录支持图片

处理要求：

• 创建和更新功德记录时接收图片文件编号集合（mediaOssIds）；
• 列表和详情返回有权访问的图片文件集合（mediaFiles）；
• 空集合表示清空全部图片；
• 删除、回收站恢复和权限校验必须同步处理文件引用。

验收标准：新增多图、编辑保留图片、逐张移除、列表显示首图、详情预览全部图片和回收站恢复均正常。

任务二：推广注册链接和二维码

处理要求：

• 推广资料接口返回由服务端生成的 HTTPS 注册链接（shareUrl）；
• 链接只能携带可校验、可控制生命周期的推荐凭据，不能直接暴露内部用户编号；
• 注册绑定需要防止自我邀请、重复绑定和并发重复写入。

验收标准：前端可直接复制链接、生成二维码和调用系统分享；扫码注册后推荐关系只绑定一次。

任务三：统一封面清空规则

适用内容：谱文、礼仪活动、家族视频。

处理要求：

• 更新请求中的封面文件编号（coverOssId）为 null 时，表示删除现有封面；
• 请求中不包含该字段时，表示保持原封面不变；
• 删除封面后需要释放旧业务文件引用；
• 不再使用空字符串、零或其他第二套清空方式。

验收标准：清空后详情返回的封面文件（coverFile）为 null，其他业务字段保持不变，旧文件不再保留业务引用。

任务四：统一返回创建时间

至少需要补齐以下内容的只读创建时间（createTime）：

• 相册；
• 礼仪活动；
• 功德记录；
• 成长记录；
• 亲友往来记录；
• 产品确认后的家族恩人记录。

处理要求：创建时间由服务端生成，客户端不能提交或修改；业务日期、活动日期和提醒日期不能代替创建时间。

验收标准：新增后创建时间非空；编辑业务内容不会改变创建时间。

任务五：确定并实现“家族恩人”模型

产品和后端需要在以下方案中确定唯一方案：

1. 独立家族恩人档案；
2. 家族备忘录中的受控业务分类。

无论选择哪种方案，都需要明确：身份或类别、说明、图片、创建时间、访问权限、删除与恢复规则。不能只把现有“家族备忘”标题改成“家族恩人”。

验收标准：OpenAPI、数据库模型、服务实现和前端使用的字段属于同一套契约，不保留两套并行模型。

任务六：创建家谱时建立始迁祖和谱主绑定

处理要求：

• 创建家谱请求接收始迁祖姓名（firstAncestorName）；
• 创建家谱、创建第一代世系人物、绑定当前谱主成员必须在同一事务中完成；
• 任一步骤失败时整体回滚；
• 重复请求不能生成重复人物或重复绑定；
• 旧家谱需要提供受权限控制的补绑定路径。

验收标准：新建家谱后，世系树立即出现始迁祖，且唯一谱主成员具有明确的人物绑定。

任务七：换绑手机号前重新验证当前身份

当前换绑请求只验证新手机号，不能证明操作人仍掌握当前账号凭据。

处理要求：

1. 验证当前登录密码，或者验证近期完成的重新认证票据；
2. 验证新手机号短信票据；
3. 两项验证通过后才能更新手机号；
4. 记录安全审计事件；
5. 旧密码错误、认证票据过期、验证码错误和手机号被占用必须分别拒绝。

验收标准：仅掌握当前登录会话、但不知道密码或没有重新认证票据时，无法换绑手机号。

任务八：修改密码和换绑手机号后使旧会话失效

处理要求：

• 修改密码后，使该用户其他既有令牌失效；
• 换绑手机号后，建议使全部既有令牌失效，并要求使用新手机号重新登录；
• 如果保留当前设备会话，必须明确区分当前令牌和其他令牌；
• 会话失效必须由服务端执行，不能只依赖前端清理本地缓存。

验收标准：安全操作前签发的旧令牌再次访问受保护接口时返回未登录；使用新凭据可以重新登录。

四、测试环境需要准备的联调数据

以下接口目前能够访问，但返回空列表或缺少关键字段，导致前端无法完成内容态点击验收。请只在测试环境准备数据。

一、平台宣传视频

接口：GET /genealogy/app/platform-videos

至少准备一条当前时间可见的数据，包含：

• 视频编号；
• 视频标题；
• 展示位置；
• 平台范围；
• 封面文件；
• 可播放视频文件；
• 视频时长；
• 点赞、播放、评论数量；
• 当前用户是否点赞。

验收目标：列表显示真实封面，点击封面后能够打开播放器并播放视频。

二、礼仪活动

接口：GET /genealogy/app/genealogies/{家谱编号}/ceremonies

为测试家谱准备至少一条带封面的礼仪活动，封面文件必须具有当前用户可访问的临时地址。

验收目标：礼仪活动列表显示封面，点击卡片可进入详情。

三、谱文

接口：GET /genealogy/app/genealogies/{家谱编号}/articles

为测试家谱准备至少一条带封面的谱文，并保证分类、标题、摘要、封面文件和权限字段完整。

验收目标：谱文列表显示封面，点击卡片可进入详情。

四、完整的会员订单

接口：GET /genealogy/app/vip/orders

当前样本只有套餐、金额、订单号和状态。请准备至少一条完整订单，包含：

• 订单编号（orderNo）；
• 套餐名称（packageName）；
• 支付金额（payAmount）；
• 支付方式（payType）；
• 支付状态（payStatus）；
• 支付时间（payTime）；
• 失效时间（expireTime）。

验收目标：订单卡完整显示已有字段，不再只能显示基础四项。

五、提现记录

接口：GET /genealogy/app/earnings/withdrawals

至少准备一条提现记录，包含：提现编号、提现单号、金额、状态、收款人、创建时间；根据状态补充审核备注、打款参考号、到账时间或失败原因。

验收目标：提现记录页能够验证金额、状态、账户、时间以及各状态的扩展信息。

六、带图片的亲友往来记录

接口：GET /genealogy/app/genealogies/{家谱编号}/relative-records

至少准备一条当前用户可查看的亲友往来记录，包含：亲友姓名、关系名称、事件、时间、内容和图片文件集合（mediaFiles）。

验收目标：列表使用第一张图片作为缩略图，详情可以查看全部图片。

七、重要证件内容数据

当前“家谱重要证件”汇总入口已经可以打开，但列表为空。请为测试家谱至少准备一条当前账号有权查看的重要证件，并保证文件授权地址有效。

验收目标：汇总页能展示证件所属人物、证件名称和文件预览；无权限证件不能泄露。

五、后端完成后必须回传

请后端完成后统一提供以下材料，便于前端直接复测：

1. 更新后的正式 App OpenAPI 文件；
2. 对应后端提交编号和测试环境部署版本；
3. 新增或更新接口的自动化测试结果；
4. 上述测试数据对应的测试家谱编号、账号权限和数据编号；
5. 家谱设置、平台视频、谱文、礼仪活动、会员订单、提现记录、亲友往来和重要证件的真实响应示例；
6. 换绑重新认证和旧令牌失效的安全测试结果。

六、前后端边界

• 前端已经完成页面入口、空状态、封面展示、播放器入口、订单字段展示、提现字段展示、亲友首图展示和重要证件汇总页。
• 后端未完成前，前端不会伪造线上数据，也不会增加第二套临时接口。
• 最终字段、状态和错误码以双方确认后的唯一 OpenAPI 契约为准。