# 后端开发对接任务单

> 本文件是 2026-08-17 的历史任务单。最新后端源码已实现其中多项当时缺失的能力；当前有效结论和剩余任务以 [《APP 前后端联调结果与后端处理单（2026-08-22）》](./backend-integration-report-2026-08-22.md) 为准。

更新时间：2026-08-17

收件人：家谱项目后端开发、测试及接口维护人员

## 后端执行结论

请按本任务单完成缺失接口、数据库字段、权限校验和自动化测试。前端页面及调用逻辑已经完成，不需要后端等待前端再次开发；接口实现后可直接联调。

建议执行顺序：

1. P0：族人档案字段、微信登录、VIP 多支付、内容密码找回、家谱永久注销。
2. P1：推荐关系、动态权限目录、平台评论契约收紧。
3. 联调后端已存在的公开家谱搜索、视频评论、平台视频和回收站接口。

接口路径、字段、枚举、必填规则及响应 schema 只以随文提供的 `genealogy-app-openapi.yaml` 为准。后端实现与 OpenAPI 不一致时，应同步修正实现或契约，不能要求前端增加旧字段、snake_case 别名或猜测式兼容代码。

## 1. 结论与契约归属

前端已补齐本轮确认保留的能力。后端尚未提供的能力没有使用假数据或旧接口兼容：页面、入口、表单、提交状态、失败提示、取消请求和严格响应校验均已完成，接口可用后直接进入联调。

`genealogy-app-openapi.yaml` 是本项目 APP 接口的唯一契约所有者。本文件只记录前后端差距、责任和验收方式，不重复定义请求或响应结构；实现字段与枚举一律以 OpenAPI 为准。

核对基线：

- 参考前端：`C:\Users\Rain\Desktop\job\Jiapu-App`
- 当前前端：`C:\Users\Rain\Desktop\job\jiapuapp`
- 当前后端源码：`C:\Users\Rain\Desktop\job\Genealogy`
- 参考项目注册了 78 个活动路由；`video2.nvue`、`video3.nvue`、`video4.nvue` 均为有效且可达的视频页，已纳入前端比对。`ancestorsOrder.vue` 是 67 字节空壳，不作为正式功能。
- 当前项目有 59 个有效路由。旧版多页面流程已按当前产品职责合并，因此验收按业务能力和用户路径，不按旧文件数量一一复制。

> “后端源码现状”来自 2026-08-17 静态源码核对。前端侧没有修改、构建或运行后端工程，后端开发完成后需自行执行后端构建与自动化测试。

## 2. 总体差距表

| 优先级 | 业务能力 | 当前前端状态 | 后端源码现状 | 后端下一步 | 联调通过标准 |
| --- | --- | --- | --- | --- | --- |
| P0 | 微信快捷登录 | 已完成授权码登录入口、取消/失败状态、重复提交保护；前端不接收 AppSecret | `AppAuthController` 只有注册、密码登录和短信登录，没有 `/auth/login/wechat` | 按 OpenAPI 新增授权码交换、账号匹配/绑定与冲突响应；正式开放平台参数只放服务端和打包配置 | Android/iOS 正式包完成首次授权、已有账号登录、取消授权、重复登录和账号冲突路径 |
| P0 | VIP 多支付方式 | 已完成微信、支付宝、余额选项；选项完全由 capability 下发；三类支付结果严格分支校验 | capability 只返回 `enabled/disabledReason`；下单体没有 `paymentMethod`；支付响应仍是微信单一形态 | capability 下发支付方式；下单接收 `paymentMethod`；按渠道返回互斥参数；余额支付在服务端原子扣款并开通会员 | 三种支付各走通成功、取消、失败、超时查询；同一订单不能跨渠道重复支付或重复开通 |
| P0 | 族人完整档案 | 新增、编辑、详情展示及校验均完成；遗传病史按服务端能力字段控制 | `LineagePerson/Bo/Vo` 仅已有 `aliasName`，其余新增字段缺失 | 增加数据库列、实体、请求体、VO、映射与服务校验；敏感字段必须服务端鉴权后才返回 | 新增和编辑可回显全部字段；无权限响应不包含遗传病史；旧数据读取不报错 |
| P0 | 内容密码找回 | 谱文、成长记录、重要证件已接入短信验证找回；有发送倒计时、重置状态和未知结果防重 | 已有内容密码保护/解锁/移除和通用认证验证，但没有 recovery 三个 APP 端点 | 复用服务端短信验证能力，实现 capability、发码、重置；只允许资源所有者或获授权管理员操作 | 三类资源均覆盖发码限频、错码、过期码、无权限、成功重置；全链路有审计记录 |
| P0 | 家谱永久注销 | 设置页已完成归档前置、不可用原因、脱敏手机号、家谱名+短信双确认和非幂等未知结果处理 | 后端已有管理员删除引擎与资格检查，但没有 APP 谱主入口；`AppGenealogyVo` 没有注销能力字段 | 用现有删除引擎增加 owner-only APP 包装；投影 capability；成功提交后撤销所有成员家谱上下文 | 非谱主、未归档、名称不符、错码、资金/任务阻塞均拒绝；成功后不可再进入并异步完成清理 |
| P0 | 创建家谱始迁祖 | 创建表单已增加“始迁祖”，请求字段为 `firstAncestorName` | 当前创建家谱请求体和服务没有该字段，也不会原子创建首位世系人物 | 按 OpenAPI 接收字段，并在创建家谱事务内创建对应第一代人物；失败时家谱和人物一起回滚 | 填写始迁祖创建后，世系树立即出现同名第一代人物；重复提交不产生重复人物 |
| P1 | 功德记录图片 | 功德表单已支持图片上传、逐项移除、编辑保留和详情预览；请求 `mediaOssIds`，响应 `mediaFiles` | 当前功德记录请求体和 APP VO 没有媒体字段 | 按 OpenAPI 复用业务文件关联；更新按传入 ID 集合替换关联，空字符串表示清空；列表和详情返回授权后的 `BusinessFileAccess[]` | 新增、编辑、移除和详情均能正确回显；越权和失效文件不可访问；移入回收站后附件权限同步失效 |
| P1 | 推广关系 | 注册页可填写推荐码；个人中心有“我的推荐”、复制和分享入口；全部使用正式响应，不伪造收益 | 注册体没有 `referralCode`，没有推荐资料接口或推荐关系服务 | 注册支持一次性绑定推荐人；新增 `/referrals/me`；落实防自邀、防重复绑定和收益归属幂等 | 首次绑定、无推荐码、自邀、重复绑定、并发注册和推荐资料查询均有自动化测试 |
| P1 | 动态权限项 | 成员管理可从服务端目录渲染分组权限、读取和保存成员授权；前端不硬编码 `auth_str` | 成员权限 GET/PUT 已存在；缺少 `/permission-catalog` | 基于后端唯一权限定义输出当前家谱可授权目录、名称、分组和禁用原因；保存响应返回最终授权集合 | 后端新增权限无需发版即可显示；越权勾选被服务端拒绝；保存后回显与实际鉴权一致 |
| P1 | 家谱视频评论 | 已完成一级评论、一级回复展示/发表、本人或管理员删除；回复入口只允许根评论 | 根评论、回复列表、发表、删除均已存在，字段与前端契约基本一致 | 按 OpenAPI 联调并补自动化契约测试；保持只允许一层回复 | 根评论和直属回复顺序正确；删除权限可信；弱网重复提交不会静默生成多条 |
| P1 | 平台宣传视频 | 已完成列表、播放、点赞、一级评论和删除；链接统一通过业务文件访问层处理 | 列表/详情/点赞/评论均已存在；评论请求仍允许 `parentCommentId` 并在服务内支持回复 | 本期产品决定为平台视频只保留一级评论：删除 `parentCommentId` 输入并清理/迁移已有回复数据 | APP 位置筛选正确；过期内容不返回；点赞幂等；平台评论响应中不存在子回复 |
| P1 | 公开家谱搜索 | 已完成关键词输入、清空、加载/空/错状态及本地二次过滤 | `/genealogies/public` 已支持可选 `keyword` | 无新增接口，按 OpenAPI 联调并确认匿名/登录策略 | 姓氏、谱名、堂号等后端约定字段可查；空关键词恢复列表；分页/数量限制明确 |
| P1 | 相册批量管理 | 已完成批量选择、全选、逐张移至回收站、部分失败保留选择及结果提示 | 单张删除和回收站机制已存在，资源引用可恢复 | 不阻塞上线；如后续数据量需要，再单独设计服务端批量接口和部分成功语义 | 选中项逐张处理可见；失败项仍被选中；成功项可从回收站恢复 |
| P1 | 内容删除与回收站 | 前端所有相关文案统一为“移至回收站”，不再错误声称立即永久删除 | `ContentRecycleBinService` 及恢复链路已存在 | 按现有接口联调，确认各资源类型映射完整 | 删除后列表移除、回收站出现、恢复后关系与文件引用完整 |

## 3. 族人档案字段表

以下键名已经写入前端契约和 OpenAPI。后端需要把 OpenAPI 作为唯一字段来源，不增加 snake_case 别名或双读兼容分支。

| 字段 | 含义 | 前端行为 | 后端要求 |
| --- | --- | --- | --- |
| `courtesyName` | 字 | 新增、编辑、详情显示；文本长度校验 | 新增数据库字段并原样回显 |
| `aliasName` | 别名 | 已接入；空值不显示 | 后端已有，核对映射与长度即可 |
| `zodiac` | 生肖 | 选择并显示 | 校验 OpenAPI 枚举，不接受任意文本 |
| `currentAddress` | 现居住地 | 文本输入和详情显示 | 长度校验，空值保持为空而非虚构默认值 |
| `mobile` | 手机号 | 格式校验，详情显示 | 格式和权限由服务端再次校验 |
| `email` | 邮箱 | 格式校验，详情显示 | 规范化大小写规则并回显 |
| `education` | 学历 | 文本输入和显示 | 按 OpenAPI 长度保存，不自行映射未知字典 |
| `occupation` | 职业 | 文本输入和显示 | 按 OpenAPI长度保存 |
| `deathAge` | 享年 | 数字输入；仅逝者相关资料使用 | 使用明确整数范围；不能以真假判断吞掉 `0` |
| `deathType` | 去世原因/类型 | 文本输入和显示 | 依 OpenAPI长度保存；不要与生存状态混成同一字段 |
| `burialDate` | 安葬日期 | 日期选择和格式化显示 | 使用 OpenAPI 日期格式，避免时区转换导致日期偏移 |
| `hereditaryMedicalHistory` | 遗传病史 | 仅 `canManageSensitiveMedicalHistory=true` 时编辑/显示 | 服务端强制鉴权；无权限时响应不得泄露字段内容；需审计访问与修改 |
| `canManageSensitiveMedicalHistory` | 敏感病史能力 | 决定表单和详情是否出现敏感字段 | 由当前用户、家谱和成员关系实时计算，客户端提交不能覆盖 |

建议后端改动顺序：数据库迁移 → Entity/Bo/请求 DTO/Vo → Mapper → Service 校验和鉴权 → Controller 契约测试。不能只扩 DTO 而遗漏数据库、详情 VO 或树节点回显。

## 4. 后端已存在、直接进入联调的接口

| 能力 | OpenAPI 路径 | 源码核对结论 |
| --- | --- | --- |
| 公开家谱搜索 | `GET /genealogy/app/genealogies/public?keyword=` | 已支持可选关键词 |
| 家谱视频根评论 | `GET/POST /genealogy/app/genealogies/{genealogyId}/videos/{videoId}/comments` | 已存在 |
| 家谱视频回复 | `GET /genealogy/app/genealogies/{genealogyId}/videos/{videoId}/comments/{commentId}/replies` | 已存在 |
| 家谱视频评论删除 | `DELETE /genealogy/app/genealogies/{genealogyId}/videos/{videoId}/comments/{commentId}` | 已存在 |
| 平台视频 | `GET /genealogy/app/platform-videos?placement=` | 已存在，当前 Controller 要求 placement |
| 平台视频点赞/评论 | `/genealogy/app/platform-videos/{videoId}/likes`、`/comments` | 已存在；评论需收紧为一级 |
| 成员权限读取/保存 | `GET/PUT /genealogy/app/genealogies/{genealogyId}/members/{memberId}/permissions` | 已存在；保存响应需严格返回最终集合 |
| 内容回收站 | `/genealogy/app/genealogies/{genealogyId}/recycle-bin/...` | 已有查询与恢复服务 |

## 5. 后端需要新增或调整的契约

具体 schema、required、枚举和响应包装见 `genealogy-app-openapi.yaml`，这里仅列责任边界。

| 端点/契约 | 类型 | 后端责任 |
| --- | --- | --- |
| `POST /genealogy/app/auth/login/wechat` | 新增 | 只接收微信一次性授权码；服务端换取身份并处理账号冲突 |
| `POST /genealogy/app/auth/register` 的 `referralCode` | 调整 | 注册事务内一次绑定，防自邀、防重复与并发覆盖 |
| `GET /genealogy/app/referrals/me` | 新增 | 返回稳定推荐码和服务端统计；无数据也返回合法空统计 |
| `GET /genealogy/app/vip/capability` 的 `paymentMethods` | 调整 | 返回当前租户、平台、用户可用渠道及禁用原因 |
| `POST /genealogy/app/vip/orders` 的 `paymentMethod` 与响应 | 调整 | 按微信/支付宝/余额返回互斥结果；响应必须带渠道判别字段 |
| `/content-password-recovery/{resourceType}/{resourceId}` | 新增三步接口 | 查询能力、发送验证码、验证并重置；服务端掌握手机号与权限 |
| `GET /genealogy/app/genealogies/{genealogyId}/permission-catalog` | 新增 | 输出动态权限目录，权限编码只由后端唯一权限定义产生 |
| `AppGenealogyVo` 注销能力字段 | 调整 | 返回 `canDeletePermanently`、禁用原因和已验证手机号脱敏值 |
| 家谱永久注销发码与提交 | 新增 | owner-only，校验归档、阻塞任务、精确家谱名、短信码并调用现有删除引擎 |
| 族人档案字段 | 调整 | 数据库到请求/响应全链路一致；敏感病史单独服务端鉴权 |
| 平台视频评论请求 | 收紧 | 去掉 `parentCommentId`，拒绝并清理不符合一级评论契约的数据 |

## 6. 本轮明确的产品取舍

| 参考项目做法 | 当前实现 | 原因 |
| --- | --- | --- |
| 安全问题找回内容密码 | 已验证手机号短信找回 | 安全问题答案弱且容易被猜测，不能作为敏感内容的正式凭据 |
| 直接点击永久删除家谱 | 归档前置 + 家谱名 + 短信双确认 + 后台异步任务 | 家谱关联数据多，必须由服务端做资格检查和可审计的高风险操作 |
| 固定 `auth_str` 权限字符串 | 服务端动态权限目录 + 成员授权集合 | 权限语义必须由服务端唯一拥有，避免客户端版本与鉴权漂移 |
| 删除提示为永久删除 | 内容先进入回收站 | 与当前后端实际生命周期一致，避免误导用户 |
| 宣传视频直接信任旧 URL | 平台视频资源走统一文件访问层 | 避免 HTTP、过期或未授权资源地址绕过现有文件契约 |
| 客户端保存微信密钥或信任用户资料 | 客户端仅提交一次性授权码 | AppSecret 必须只在服务端；展示资料不能作为登录身份凭据 |

## 7. 后端验收与安全底线

- 所有写接口继续在服务端校验家谱成员关系、角色和具体权限，不能以页面按钮是否显示作为安全边界。
- 微信登录、短信发码、内容密码重置和永久注销必须有限频、过期、一次性消费、失败次数限制和审计记录。
- 遗传病史属于敏感字段：无权限时不只是禁止修改，也不得从列表、详情、树节点或日志中返回原文。
- 余额购买 VIP 必须在一个服务端事务中完成余额校验、扣款、订单成功和权益开通，并使用稳定幂等键防重复扣款。
- 支付宝仅返回 APP 支付所需订单字符串；微信返回完整 APP 预支付签名参数；不同渠道字段不能混合猜测。
- 永久注销成功提交后应立即让所有成员端失去该家谱操作上下文；异步删除失败要可追踪、可重试，但不能把家谱恢复成可写状态。
- 运行时响应必须通过 OpenAPI 定义；不要长期保留旧字段、snake_case 别名或“缺字段时客户端猜测”的兼容路径。

## 8. 前端验收状态与待联调项

前端静态契约、59 个页面注册、导航、隐私审计、设计回归和资源引用均已通过项目检查。以下事项只能在后端完成后验证：

- 真机微信登录和微信/支付宝支付回跳；
- 余额真实扣款、订单查询和重复支付防护；
- 短信发送、限频、过期和服务端审计；
- 族人字段数据库持久化与敏感病史服务端脱敏；
- 永久注销任务、成员上下文撤销和关联数据清理；
- 推广关系的注册事务、归属和收益统计；
- 权限目录与各业务接口实际判权的一致性。

联调时若运行时响应与 OpenAPI 不一致，应优先修正后端实现或 OpenAPI 的唯一契约，不应在前端增加第二套字段读取逻辑。