146 lines
8.1 KiB
Markdown
146 lines
8.1 KiB
Markdown
# 剩余九项后端与产品任务及参考项目证据
|
||
|
||
日期：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. 换绑重新认证及旧令牌失效的安全测试结果。
|