jiapu/docs/PC后端补齐清单.md

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 的执行指令

你负责为现有“家谱”项目补齐 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 名	隔离测试名称，不含真实凭据

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