jiapuapp/docs/backend-reference-gap-tasks-2026-08-23.md

剩余九项后端与产品任务及参考项目证据

日期：2026-08-23
收件人：后端开发、接口维护、测试及产品负责人

结论

前端能够独立完成的十三项已经处理。剩余九项中：

• 六项在参考项目中有直接页面或字段证据；
• 两项有等价流程或部分实现证据，不能逐字段照搬；
• 一项在参考项目前端中没有实现证据，但属于当前项目必须独立收口的安全要求。

后端可以直接排期八项；“家族恩人”必须先由产品确定是独立档案还是备忘录分类，再确定唯一契约。

参考项目只用于确认产品行为，不作为接口字段命名、安全设计或数据模型的权威来源。当前项目最终契约仍以 genealogy-app-openapi.yaml 和后端实现共同确认的单一版本为准。

九项核对表

序号	剩余事项	参考项目是否存在	证据与判断	当前责任
1	功德记录图片保存和回显	是	pages/index/meritsVirtues/add.vue 可上传多图，列表使用 item.imgs[0]，详情遍历 datas.imgs	后端直接开发
2	推广注册链接和二维码	是	pages/mine/fenxiang.vue 生成带推荐人参数的注册链接二维码	后端直接开发；链接必须由服务端生成，不能照抄旧域名或直接暴露用户 ID
3	谱文、礼仪、视频封面清空	部分存在	谱文共用图片组件支持删除，礼仪编辑页明确可清空 cover；视频封面删除后的父表单同步不完整，不能作为可靠契约	后端按当前模型统一清空语义
4	多类内容的创建时间	是	参考相册、礼仪、功德、成长记录、贺礼簿列表直接显示 create_time	后端直接开发
5	家族恩人业务语义	是	pages/index/memorandum/index.vue、add.vue、details.vue 均明确使用“家族恩人”名称，并支持图片和创建时间	产品先选模型，随后后端开发
6	创建家谱时落库始迁祖	是	pages/index/createGenealogy.vue 将 first_ancestor_name 作为必填项，与家谱资料一同提交	后端直接开发
7	谱主与世系人物绑定闭环	有等价流程	参考创建请求同时携带当前 user_id 和 first_ancestor_name，树编辑也提供“绑定账号”；更合理的闭环是创建家谱时原子绑定谱主，而不是开放谱主角色编辑	后端直接开发
8	换绑手机号前重新验证当前身份	是	pages/mine/changemobile.vue 要求 oldPassword + newMobile	后端直接开发，但建议保留当前新手机号短信验证，形成双重验证
9	改密、换绑后的既有会话失效	未发现	参考改密和换绑成功后直接返回个人中心，没有清理令牌或重新登录逻辑；仅凭参考前端无法证明服务端是否失效旧令牌	当前项目独立安全任务，后端直接开发

后端接口任务

1. 功德记录媒体

当前 AppMeritRecordBody、AppMeritRecordVo 没有媒体请求和响应字段。

处理要求：

• 创建和更新接收 mediaOssIds，由后端维护业务文件引用；
• 列表和详情返回授权后的 mediaFiles；
• 明确空集合表示清空全部图片；
• 回收站、恢复和越权访问同步处理文件权限。

验收：新增、编辑保留、逐项移除、列表首图、详情预览和回收站恢复均通过。

2. 推广分享链接

当前推荐资料只有推荐码、邀请人数和文案，没有可信 shareUrl。

处理要求：

• 在推荐资料响应中增加服务端生成的 HTTPS shareUrl；
• 链接中的推荐凭据使用可校验、可控生命周期的业务标识，不能直接拼接内部用户 ID；
• 注册时继续执行防自邀、一次性绑定和并发幂等校验。

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

3. 封面清空契约

谱文、礼仪和视频已有 coverOssId，但 OpenAPI 没有统一声明显式清空语义。

处理要求：

• 更新请求中的 coverOssId: null 统一表示移除封面；
• 字段未出现表示保持原封面不变；
• 同步释放旧业务文件引用；
• Java DTO、更新服务、OpenAPI 和契约测试保持一致，不保留空字符串等第二套清空方式。

验收：移除后详情返回 coverFile=null，其他字段不变，旧文件不再保留业务引用。

4. 只读创建时间

处理要求：

• 为 AppAlbumVo、AppCeremonyVo、AppMeritRecordVo、AppGrowthRecordVo、AppRelativeRecordVo 增加只读 createTime；
• 家族恩人选定模型后，由对应唯一 VO 持有 createTime；
• 不允许客户端提交或修改创建时间，也不能使用礼仪时间、记录日期、提醒时间等业务字段代替。

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

5. 家族恩人契约

产品必须二选一：

1. 独立家族档案：定义独立实体、身份或类别、说明、图片、创建时间、权限和回收站类型；
2. 备忘录分类：由 Memo 的唯一契约增加受校验的业务类型，并明确恩人专属字段、提醒字段是否适用以及旧数据迁移规则。

确认前不要仅把“家族备忘”改标题，也不要先加入无法验证的猜测字段。

6. 始迁祖与谱主绑定

这两项应在同一创建事务中完成：

• AppGenealogyCreateBody 接收必填或按产品规则校验的 firstAncestorName；
• 创建家谱后创建同名第一代世系人物；
• 将当前谱主成员记录绑定到该人物，或按产品确认的关系建立明确绑定；
• 任一步失败时家谱、人物、成员关系整体回滚；
• 重放同一创建请求不能产生重复人物或重复绑定。

如果业务允许谱主后续改绑，应新增只允许谱主修改“本人世系人物绑定”的窄接口。该接口不得同时开放角色修改、谱主移除或任意成员资料编辑。

验收：新建家谱后世系树立即出现始迁祖，唯一谱主成员具有明确人物绑定；旧家谱谱主也有受控补绑路径。

7. 换绑手机号的重新认证

当前 AppPhoneChangeBody 只有 phone + smsCode，只证明操作者控制新手机号。

建议唯一流程：

1. 校验当前登录密码，或校验近期完成的重新认证票据；
2. 校验新手机号短信票据；
3. 在同一服务端操作中更新手机号和密码登录标识；
4. 记录安全审计事件。

不要用行为验证码代替当前身份验证。行为验证码只能降低自动化攻击，不能证明操作者仍掌握账号凭据。

验收：旧密码错误、重新认证过期、新手机号错码、新手机号已占用均拒绝；全部验证通过后才换绑。

8. 安全操作后的会话失效

当前 AppAuthServiceImpl.changePassword() 和 changePhone() 中没有发现令牌注销或其他会话踢除逻辑。

处理要求：

• 修改密码后使该用户的其他既有令牌失效；
• 换绑手机号后建议使全部令牌失效，并要求使用新手机号重新登录；
• 如果保留当前设备会话，必须明确区分当前令牌与其他令牌，并通过自动化测试证明；
• 失效必须由服务端执行，不能只让前端删除本地缓存。

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

另行保留的既有 P0

普通谱主读取永久注销 capability 时，后端仍会因家谱未归档而报错。前端已经把基础设置读取与永久注销资格读取拆开，避免整个设置页被连带阻断，但后端仍需让普通家谱成功返回 canDeletePermanently=false 和明确禁用原因。该问题已经记录在 backend-integration-report-2026-08-22.md，不重复计入以上九项。

后端回传材料

完成后请提供：

1. 更新后的 canonical APP OpenAPI；
2. 对应后端提交号和部署环境版本；
3. 新增或更新的接口自动化测试结果；
4. 功德媒体、分享链接、封面清空、创建时间、始迁祖和谱主绑定的真实响应样例；
5. 换绑重新认证及旧令牌失效的安全测试结果。