# PC 后端补齐清单（交给后端 GPT）

> 状态：待后端确认与实施
>
> 前端基线：`ac58235`（“验证20%”）之后的 PC 工作区。当前前端回归为 362 项通过。
>
> 本文目的：让后端直接知道 PC 端还缺什么能力、每项最小需要补什么，以及如何验收。它是 `PC接口对接规划.md` 中 C01–C46 的精简交接版；详细的历史证据仍以该文档为准。

## 0. 不可违反的边界

1. 这是 **PC** 契约补齐，不是把 `Jiapu-App` 的接口、参数、缓存键或数据结构搬过来。路径和 DTO 以 PC 后端为唯一 owner。
2. 请先在 PC 的 Apifox/OpenAPI 中定义完整请求、响应、权限、枚举和错误码，再实现 Controller/Service；完成后重新导出契约。前端只会通过 `utils/ApiClient.js` 接入已确认的 PC 契约。
3. 不要以泛型 `ObjectResult`、无元素类型的列表或“前端自行猜字段”作为交付。每个列表、详情和写入结果都必须有明确 DTO。
4. 所有资源 ID、OSS ID、订单号等可能超过 JavaScript 安全整数的值，统一以十进制字符串传输和返回；不得要求用户手填内部 ID。
5. 不返回或展示成员、邀请人、通知发送人的原始手机号。确有业务必要的内部用户 ID 只在受权限保护的选项或写入场景返回，PC 页面不会展示它。
6. 不记录、更不要求提交真实测试账号、密码、令牌或真实家谱数据。角色验收使用既有隔离身份或后端准备的隔离夹具。

## 1. 已有能力，不要重复实现

以下 PC 能力已被当前前端使用：登录/账户基础资料、家谱列表与创建、申请加入与审核、成员名册与角色维护、成员选项、世系人物及四类关系新增、字辈、家族圈常规 CRUD、视频、成长/亲友/备忘/功德记录、谱文、相册/照片、祭祀活动/祭品/活动邀约、通知已读、反馈工单、会员套餐与会员订单、帮助文章、PC 推广和官网资讯。

本清单要求补的是这些能力的缺口或契约精度，不要求重新设计上述已有流程。已有写入接口仍必须由后端做最终权限校验，不能只依赖前端隐藏按钮。

## 2. P0：PC 当前完全缺失的业务契约

| 编号 | 前端位置与业务目标 | 后端必须补齐的最小能力 | 验收标准 |
| --- | --- | --- | --- |
| P0-01 | `profile-data-reminders.html`：查看当前家谱中待完善的成员资料 | 只读“资料缺项提醒”列表，按当前家谱和当前操作者权限过滤。每项至少返回稳定的成员/世系人物定位 ID、脱敏展示名、缺失字段枚举、可处理状态和更新时间；缺失字段至少能区分头像、出生日期、关系等。联系方式只能表达“缺失/已填写”，不能下发原始号码。 | 有权限角色能读取真实空列表和非空列表；无权限、无家谱、资源不存在分别有可区分失败；前端能从响应跳到已有成员/世系编辑页。 |
| P0-02 | `profile-invite.html`、家谱主页：邀请家人加入家谱 | 家谱成员邀请的创建、活动邀请列表、撤销/失效、受邀人校验和受邀人接受流程。邀请方式如为链接或邀请码，响应需给出 `inviteId`、受限邀请凭据/链接、过期时间、使用次数或上限、状态及可展示的创建时间；不得把可枚举的内部 ID 当邀请码。 | 仅后端定义的可管理角色可创建和撤销；过期、撤销、次数用尽、非受邀人、重复接受均有稳定业务错误；接受后能在家谱成员/审核链路中重读结果。 |
| P0-03 | `profile-family-home.html`：重要证件 | 家谱重要证件的列表、详情、新增、修改、删除（或明确仅支持其中一部分）。证件 DTO 至少含稳定 ID、家谱 ID、标题/类型、说明、文件对象、创建/更新时间、状态和权限能力。文件必须使用第 3.1 节的安全文件对象。 | 无权用户不能读写他人家谱证件；上传后重读同一条记录；删除后的可见性和是否可恢复有明确定义。 |
| P0-04 | `profile-families.html`：我的家谱自定义排序 | 读取当前账号的家谱顺序及保存顺序的接口。保存请求应提交完整有序的“当前账号可见家谱 ID”数组，后端在一个事务内校验归属、去重和完整性，不接受跨账号或不可见家谱 ID。 | 重排后重新读取顺序一致；重复、缺失、越权 ID 返回明确校验/权限错误；并发保存不会产生重复排序值。 |
| P0-05 | `profile-family-home.html`：删除家谱 | 先由产品/后端确定唯一语义：**逻辑归档** 或 **物理删除**，不能接口名叫删除而实际效果不明确。接口需只允许谱主执行，并返回影响范围（成员、人物、内容、文件、订单等）、最终状态和可否恢复；如需二次确认，应采用后端签发的一次性确认令牌或明确确认字段。 | 非谱主必定拒绝；成功后“我的家谱”重读不再出现或以归档状态出现；重复请求幂等；关联资源处理与定义一致。 |
| P0-06 | `profile-share.html`、`profile-services.html`：应用分享、奖励、推广收益、提现 | 一套完整账户权益契约：分享规则/分享凭据、分享记录、奖励或收益流水、账户可用/冻结/累计余额、提现方式选项、提现申请及提现记录。金额和状态必须由服务端计算与驱动，前端不能传入奖励金额、余额或审核状态。 | 普通用户只能读取自己的记录；提现前校验可用余额、金额精度、最低/最高额、风控状态和收款方式；重复提交幂等；流水、余额与提现状态可重读且一致。 |
| P0-07 | `profile-services.html`：个性化推荐开关 | 当前用户的推荐偏好读取与保存。至少定义可配置项枚举、默认值、保存后的版本/更新时间，以及未登录、无权限或功能未开通的处理。 | 未知枚举和值非法会被拒绝；保存后重读一致；不允许操作其他用户的偏好。 |
| P0-08 | `profile-services.html`：会员订单在线支付 | 现有“创建订单/读取订单”之外，补支付发起、支付参数、安全回跳/异步通知后的订单状态查询和关闭/超时语义。`payType` 必须有正式枚举，订单状态机由后端维护，不能让前端提交“已支付”。 | 创建支付后返回可安全使用的支付会话参数；支付成功、失败、取消、超时、退款均能重读到准确状态；重复通知和用户刷新幂等。 |

## 3. P1：已有 PC 页面被契约限制的能力

### 3.1 统一安全文件访问能力（C21、C23、C25、C28、C30、C36、C38、C40）

下列资源目前大多只返回 `ossId` 或 `mediaOssIds`，PC 无法安全回显图片、封面、视频、附件名称或下载入口：家族圈、视频、成长记录、亲友记录、备忘录、谱文、相册/照片、祭祀活动。

请在资源 View 内直接返回文件对象数组，或提供一个受资源权限保护的 PC 文件解析接口。两种方案只保留一种，推荐统一文件对象：

| 字段 | 要求 |
| --- | --- |
| `ossId` | string，原始文件稳定标识 |
| `fileName` | 可安全展示的文件名 |
| `mediaType` | 明确枚举，例如 image/video/document |
| `accessUrl` | 短时授权 URL；不能由前端用 OSS ID 拼接 |
| `expiresAt` | 授权 URL 失效时间，使用统一日期时间格式 |

文件解析必须根据“该文件所属业务资源 + 当前操作者”校验权限，不能做成任意登录用户可按 OSS ID 探测或下载文件的接口。

### 3.2 停用记录的管理、详情与恢复（C22、C24、C26、C29、C31、C33、C37、C39、C41）

以下资源可以或可能写入 `status=1`，但普通列表不返回、普通详情拒绝读取，导致管理员无法恢复或验证：家族圈、视频、成长记录、亲友记录、备忘录、功德、谱文、相册/照片、祭祀活动。

请为每类资源提供唯一且一致的方案：

1. 给有管理权限的用户提供 `management` 列表和详情，包含正常/停用状态；或
2. 提供受权限保护的独立状态读取与恢复接口。

必须明确 `status=0/1` 的中文业务含义、谁可停用/恢复、停用后文件和关联数据如何处理、普通用户是否仍可读取。前端在此完成前会持续固定提交正常状态，避免产生不可重读数据。

### 3.3 金额、分类与可清空字段（C18、C27、C32、C35、C42）

| 范围 | 缺失内容 | 必须定义 |
| --- | --- | --- |
| 亲友往来 `giftAmount`、功德金额、祭品金额 | 只有 number/BigDecimal，缺少精度和边界 | 货币单位、`precision`、`scale`、`minimum`、`maximum`、是否允许负数及其业务含义。建议金额响应使用十进制字符串，避免浮点误差。 |
| 谱文分类 | 列表的 `categoryId` 未进入正式契约，且没有分类选项来源 | 正式 query、当前家谱文章分类选项接口、分类 DTO、是否允许无分类和分类停用后的处理。 |
| 所有可选更新字段 | 未定义“不传字段”、`null`、空字符串、空数组的差别 | 每个更新 DTO 对每个可清空字段写明语义，并用后端测试覆盖。特别是备忘录提醒时间、说明、附件和成员绑定。 |

### 3.4 个人资料、成员、通知与关系契约（C04–C08、C11–C13、C19、C34、C43–C46）

| 范围 | 当前问题 | 后端补齐要求 |
| --- | --- | --- |
| 当前用户资料 | 资料读取仍可能是泛型响应；更新 DTO 没有地区字段 | 提供完整 `ProfileView`；如产品保留现居地区，更新/读取都使用 `regionCode`；明确头像 ID 类型和所有可清空字段语义。 |
| 行政区划 | 历史上存在双路径和无元素 DTO | 只保留一套 PC 正式路径；`RegionView` 固定 `regionCode`、`regionName`、`regionLevel`、父级关系；删除旧路径。 |
| 世系树 | `LineagePersonTreeView` 曾无属性 | OpenAPI 展开递归节点：人物 ID、基础展示资料、配偶、子女及必要的状态/权限。所有日期必须声明 `date` 或带时区规则的 `date-time`。 |
| 枚举与能力 | `completed`、`feedType`、`recordType` 等可能无完整枚举；多数 View 缺 `canEdit/canDelete` | 明确自由文本或完整枚举；对页面需要的操作返回稳定的严格布尔能力字段，例如 `canManage`、`canEditContent`、`canEdit`、`canDelete`。后端仍做最终鉴权。 |
| 通知 | 声明的家谱名、发送人、业务摘要等字段实际常为空，且含隐私风险 | 补齐真正可用的非敏感字段，或从 Schema 删除不会返回的字段；提供安全、明确的 `bizType/bizId` 深链规则，不能让前端猜路径；始终不返回发送人手机号。 |
| 家谱成员 | `GenealogyMemberVo` 声明字段与实际填充不一致，角色枚举也不一致 | View 补齐真实需要的非敏感展示字段，或收紧 Schema；可分配角色正式收敛为后端实际支持的 `admin`、`editor`、`member`，不能接受 `owner`、`visitor`。 |
| 世系关系解除 | 只有新增关系，没有解除关系 | 新增带家谱权限与关系完整性校验的解除接口；需明确父母、配偶、子女、兄弟姐妹解除后的双向影响。 |
| 成员与世系人物解绑 | 当前更新中空 `lineagePersonId` 只代表不修改 | 提供专用解绑动作，或正式约定 `null`/空值表示解绑并给出可验证示例；不能由前端猜测。 |
| 个人亲属关系 | `profile-data.html` 当前无个人关系数据 | 这是独立于家谱世系的产品决策：若保留个人关系页，请提供当前用户私有的列表/维护契约；若不做，请明确下线该需求，继续引导到家谱世系维护。 |

## 4. P2：契约质量与一致性必须同时修复

这些事项不一定新增页面，却会使 PC 前后端长期出现“接口能调但不知道如何正确用”的问题：

1. 删除/废弃缺少开头 `/` 的旧短信路径，只保留正式 PC 路径。
2. 未登录可调用的注册、登录、短信、找回密码、验证接口在 OpenAPI 中标为公开；登录后接口标明 Bearer 鉴权。不要让公开接口错误继承 Authorization。
3. 所有列表、详情、上传初始化/完成、写入结果都展开具体 Schema，尤其不能保留无元素的通用列表。上传初始化要明确 `uploadId`、秒传、已传分片、完成后的 OSS 信息。
4. 用统一错误响应表达：未登录、无权限、资源不存在、字段校验失败、业务冲突、状态不可操作、频率/幂等冲突。每一类要有稳定 code 和用户可读 message；不要只返回模糊失败文本。
5. 统一日期格式、时区、分页字段和排序字段；同一资源的列表、详情、创建、更新应使用同一 ID 类型和状态枚举。
6. 更新 Apifox/OpenAPI、DTO、Controller、Service 和集成测试必须在同一提交完成；不要只改其中一处，也不要保留 APP 路径 fallback。

## 5. 权限与数据安全验收矩阵

后端实施每个新增或补齐接口后，至少用既有隔离的谱主、管理员/编辑、普通成员、非成员和未登录身份验证。不要为了验收在真实家谱中创建成员或写入数据。

| 场景 | 必须验证 |
| --- | --- |
| 未登录 | 仅公开认证接口可用；所有用户/家谱资源拒绝。 |
| 非成员 | 不能读取私有家谱内容、成员、文件、邀请或管理列表。 |
| 普通成员 | 只能使用后端允许的只读或本人操作，不能修改成员角色、家谱设置、排序、删除、证件或全局邀请。 |
| 管理员/编辑 | 仅获得已声明能力范围内的内容或成员维护权限；不得越过谱主做家谱删除、谱主转让等操作。 |
| 谱主 | 可执行后端定义的家谱级管理动作，但仍受资源状态、确认和业务完整性约束。 |

每个写入接口还要验证：重复请求幂等、写后可精确重读、越权返回明确错误、停用/恢复状态可验证、敏感字段不会越权泄漏。

## 6. 建议实施顺序

1. 先完成第 4 节的 OpenAPI/DTO 基础收口，并冻结唯一 PC 契约。
2. 其次完成 3.1 文件访问和 3.2 停用管理；这两项能同时解除多个已有内容页的展示和状态闭环。
3. 再完成 3.3、3.4 的金额、分类、资料、成员和关系精度。
4. 最后按 P0-01 至 P0-08 补齐新业务；其中家谱删除、提现和支付必须先确认产品状态机与风控规则，不能只给一个无约束写接口。

## 7. 给后端 GPT 的执行指令

```text
你负责为现有“家谱”项目补齐 PC API，不得复用或复制 Jiapu-App API。

先阅读 docs/PC后端补齐清单.md 与 docs/PC接口对接规划.md，确认当前 PC OpenAPI 和 Controller 的实际差异；不要重做“已有能力”章节列出的功能。

按第 6 节顺序实施。每个模块都要在同一改动中完成：PC OpenAPI/Apifox、请求 DTO、响应 View、Controller/Service、权限校验、错误码和集成测试。不要返回泛型 Object，不要让前端手填内部 ID，不要返回原始手机号，也不要新增 APP 路径兼容层。

实施前先输出：将新增/修改的 PC 接口、每个请求和响应字段、角色权限、状态机、数据库迁移（如有）以及与本清单的对应编号。实施后用隔离角色完成读写、越权、重复提交和写后重读验证，并重新导出 OpenAPI。
```

## 8. 交付回执模板

后端完成后，请按以下格式回传，便于前端逐项接入：

| 清单编号 | 状态 | 正式 PC method/path | 请求 DTO | 响应 View | 权限/状态机 | OpenAPI 位置 | 集成测试证据 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 例如 P0-01 | 已完成/不做（附产品结论） | 仅填 PC 路径 | 字段和必填性 | 字段和类型 | 可用角色与错误码 | tag/schema 名 | 隔离测试名称，不含真实凭据 |

如某项决定不做，必须给出明确产品结论和对应前端页面应继续保留的不可操作文案；不能以“暂时没有接口”结束。