rain/jiapu

Files

T

2026-07-25 19:20:01 +08:00

41 KiB

Raw Blame History

PC 接口对接规划（Apifox 85 接口版）

状态：当前范围已确认
日期：2026-07-25 当前阶段：桌面版 Apifox 的 PC 目录为 85 条，已逐条在 PC 详情复核并与客户端映射比对。后续仅在该目录出现新增或变更时，按 PC 详情重新核验；不据旧记录猜测施工。交接入口：交接文档.md

1. 已确认的基线

Apifox 的 PC 目录是 PC 前端接口的唯一正式契约源。

当前 Apifox PC 共 85 个操作：

分组	数量
认证登录	12
验证中心	3
文件上传	3
家谱	1
行政区划	4
家族圈	14
字辈谱	6
世系人物	12
内容文章	1
相册	2
视频	1
贺礼邀约	4
祭祀	2
族务记录	16
消息通知	4
合计	85

仓库中的旧 OpenAPI 文件不再作为新增功能依据。Apifox 客户端中实时的 PC 目录是最终验收源；导出文件最多作为本地自动测试快照，不能替代在 Apifox 中逐项核对。
APP 接口不允许在 PC 页面中直接复用。PC 缺少的能力应先补入 Apifox 的 PC 目录，再开发页面。
当前不根据 APP 或后端公开 OpenAPI 扩大范围；没有进入 Apifox PC 目录的接口，不视为 PC 已确认接口。
后端以后新增 PC 接口时，再按新增后的 Apifox PC 契约启动下一轮规划。

2. 当前最重要的结论

现有 85 个接口仍不能覆盖整个 PC 管理端闭环，主要问题不是前端页面，而是接口目录不完整：

没有“我的家谱、家谱详情、创建/加入家谱、家谱成员”接口，PC 无法自行取得真实 genealogyId。
内容文章只有删除接口。
相册只有删除相册、删除照片接口。
视频只有删除接口。
祭祀只有删除祭祀、删除献礼接口。
功德记录只有删除接口。
世系关系只有新增父母、配偶、兄弟姐妹、子女，没有解除关系接口。
字辈谱没有删除接口。

因此对接分成三类：

**当前可以形成可用流程：**认证、验证、文件上传、区划、家族圈、字辈谱、世系人物，以及成长记录、亲友往来、备忘录的新增；三类列表仅能按未展开 DTO 原样展示。其中家谱内接口必须先由 PC 运行入口提供真实 genealogyId。
**当前只做契约映射、不开放页面操作：**文章、相册、视频、祭祀和功德录目前只有删除接口，不能在没有真实列表和详情数据时单独启用删除。
**后端补充 PC 接口后再规划：**家谱上下文、成员，以及上述资源缺少的读写操作、世系关系解除和字辈删除/停用。

2.1 当前范围规则

当前只分析和对接 Apifox PC 中已经存在的 85 个操作。
不读取 APP 接口补 PC 缺口，不把 /genealogy/app 改前缀后用于 PC。
后端公开文档中存在、但 Apifox PC 当前没有的接口，不进入本轮对接；也不以导出文件缺失为由跳过 Apifox 中已有的接口。
PC 当前缺少的业务接口只登记为后端待办，相关页面继续显示待开发状态。
后端新增接口后，必须先进入 Apifox PC 并补齐 DTO，再进入前端对接规划。

3. 公共契约规则

3.1 接口所有权

Apifox PC 目录拥有 method、path、请求 DTO、响应 DTO、枚举和权限说明。
utils/ApiClient.js 只负责实现 Apifox 已定义的业务方法，不允许页面自行拼接接口路径。
页面脚本只消费 ApiClient 方法，不直接调用 Axios。
新契约确认后，旧字段兼容读取、旧路径和临时 fallback 必须一起删除，不能长期维护两套契约。

3.2 家谱上下文

所有家谱内业务必须使用真实 genealogyId：

当前 85 个接口仍没有“我的家谱”入口；新增的家谱配额接口也不能提供真实 genealogyId，本轮不从 APP 获取。
当前家谱业务页面只接受 PC 运行入口通过 URL 传入的真实 genealogyId。
profile-common.js 作为 PC 页面家谱上下文的唯一 owner，负责读取、校验和传播 genealogyId。
ApiClient 负责把 genealogyId 放入路径。

当前 GET /genealogy/pc/genealogies/quota 已映射为 genealogyQuota()；它只返回创建/加入家谱的已用数量、上限、剩余和 canCreate/canJoin，不能作为家谱列表、详情、创建或加入接口，也不能生成或替代真实 genealogyId。 5. 页面缺少 genealogyId 时，统一先跳转 profile-families.html；该入口页只读取配额并说明 PC 尚不能选择家谱，阻止业务请求且不使用示例编号。

个人中心、内容发布和家谱内导航已统一指向该入口页；后端补充 PC 家谱入口接口后，再由入口页实现“我的家谱 → 选择家谱 → 进入业务页面”的完整导航闭环。

3.3 请求头与登录状态

所有 PC 请求统一携带 clientid。
登录后接口统一携带 Authorization: Bearer <token>。
tenantId、clientId 只在 Apifox DTO 明确要求时进入请求体，页面不得自行添加。
401：清除本地登录态并跳转登录页。
403：保留登录态，展示无权限页或无权限状态。

Apifox 必须为每个操作明确标记“公开”或“需要登录”，不能只依赖接口描述文字。

Apifox 还必须正式声明 Bearer security scheme、Authorization 和 clientid，否则自动生成文档、Mock 和测试时无法还原真实请求。

3.4 响应与分页

普通响应统一为：

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

分页响应统一为：

{
  "code": 200,
  "msg": "操作成功",
  "rows": [],
  "total": 0
}

分页参数应明确展开为 pageNum、pageSize、orderByColumn、isAsc，不把整个 pageQuery 声明成一个含义不清的 query object。

除 200 外，每组接口至少定义适用的 400、401、403、404、409、422 和 429 响应，不能把所有失败都写成 401。

3.5 ID、日期和枚举

genealogyId、personId、feedId、commentId、ossId 等 ID 在浏览器端统一按字符串处理，避免 JavaScript int64 精度丢失。
Apifox 当前需要统一文件上传响应和业务写入 DTO 中 ossId 的类型；不能一处为 string、另一处为 integer。
纯日期使用 YYYY-MM-DD。
具体时刻使用带时区的 ISO 8601。
性别、状态、角色、可见性、祭祀类型等必须在 Apifox 中给出固定枚举及中文含义。

3.6 权限

至少区分：

访客
普通家谱成员
内容编辑者
家谱管理员
家谱创建者/所有者
平台管理员

列表和详情 DTO 应返回 canEdit、canDelete、canManage 等能力字段。前端据此显示操作，后端仍必须独立鉴权。

同一个 PC DTO 不等于所有角色都能看到所有字段。手机号、联系方式、通知目标等敏感字段要按权限裁剪；需要时拆成摘要 DTO 和管理员详情 DTO。

前端只使用 Apifox PC 当前声明的 Schema，不从 APP Schema 推导字段。

3.7 文件生命周期

图片、小文件：

单文件上传。
获得 ossId。
保存业务对象。
绑定文件业务引用。

视频、大文件：

初始化分片任务。
上传所有分片。
服务端合并。
保存业务对象。
绑定文件业务引用。

替换或删除业务对象后解除旧文件引用。上传成功但业务保存失败时，也要提供清理策略。

4. 已完成施工接口与当前迁移

4.1 认证登录（当前目录 12）

接口	使用页面	用途
`POST /genealogy/pc/auth/register`	`register.html`	用户注册
`POST /genealogy/pc/auth/login`	`login.html`	密码登录
`POST /genealogy/pc/auth/login/sms`	`login.html`	短信登录
`POST /genealogy/pc/auth/sms/{operationCode}/code`	短信登录、注册、找回密码、换绑手机号、注销账号	按认证动作发送短信验证码
`GET /genealogy/pc/auth/profile`	`profile.html`、`profile-data.html`、`profile-security.html`	获取当前用户资料/已绑定手机号
`PUT /genealogy/pc/auth/profile`	`profile-data.html`	修改个人资料
`PUT /genealogy/pc/auth/password`	`profile-security.html`	修改密码
`PUT /genealogy/pc/auth/password/reset`	`forgot-password.html`	找回密码
`PUT /genealogy/pc/auth/phone`	`profile-security.html`	换绑手机号
`POST /genealogy/pc/auth/account/deactivate`	`profile-security.html`	注销账号
`DELETE /genealogy/pc/auth/logout`	所有登录后页面	退出登录

状态：当前 PC 认证登录目录 12 条已逐条复核：第一轮已接入密码登录、短信登录、注册、找回密码、换绑手机号、注销和退出；本轮已把短信发送迁移到当前 PC 的 operationCode 路径。密码登录也先按 password-login 查询验证策略，策略要求时完成 TAC 后提交返回的 validToken。ApiClient 只补 DTO 明确要求的 grantType、tenantId，clientid 仅由请求头统一注入，body 不得传 clientId。目录内两条短信发送定义为相同路径和契约。资料响应未给出字段 Schema，页面只读取 PC 页面已使用的明确字段，不增加 APP 字段猜测。

已在 Apifox 直接核验的认证约束：

发送短信验证码使用路径 operationCode：sms-login、register、forgot-password、phone-change、account-deactivate。
发送短信码请求体为 grantType、tenantId、phone、validToken；validToken 来自验证中心且只能单次消费。不得传 sceneCode 或 body clientId。
换绑手机号请求体为 phone、smsCode；注销账号请求体为 smsCode。二者不附带 tenantId，clientid 仅通过请求头传递。
密码登录、注册与找回密码使用 grantType: "password"；短信登录与发送短信码使用 grantType: "sms"；所有密码字段均为 32 位 MD5。密码登录的 validToken 由 password-login 验证策略决定，有策略要求时随本次登录提交。上述认证 DTO 都禁止 body clientId。

第一批页面与接口顺序：

页面	页面流程	对接接口
`login.html`	密码登录	`POST /genealogy/pc/auth/login`
`login.html`	获取短信码 → 短信登录	`POST /genealogy/pc/auth/sms/sms-login/code` → `POST /genealogy/pc/auth/login/sms`
`register.html`	获取短信码 → 注册	`POST /genealogy/pc/auth/sms/register/code` → `POST /genealogy/pc/auth/register`
`forgot-password.html`	获取短信码 → 重设密码	`POST /genealogy/pc/auth/sms/forgot-password/code` → `PUT /genealogy/pc/auth/password/reset`
`profile-security.html`	修改密码	`PUT /genealogy/pc/auth/password`
`profile-security.html`	获取短信码 → 换绑手机号	`POST /genealogy/pc/auth/sms/phone-change/code` → `PUT /genealogy/pc/auth/phone`
`profile-security.html`	读取绑定手机号 → 获取短信码 → 注销	`GET /genealogy/pc/auth/profile` → `POST /genealogy/pc/auth/sms/account-deactivate/code` → `POST /genealogy/pc/auth/account/deactivate`
所有登录后页面	退出登录	`DELETE /genealogy/pc/auth/logout`

4.2 验证中心（当前目录 3）

接口	使用位置	用途
`GET /genealogy/pc/auth/verification/{operationCode}/require`	密码登录及发送短信登录、注册、找回、换绑、注销短信前	判断当前认证动作是否需要验证
`POST /genealogy/pc/auth/verification/{operationCode}/challenge`	同上	获取滑块或图形验证挑战
`POST /genealogy/pc/auth/verification/{operationCode}/verify`	同上	校验挑战并换取 `validToken`

已在 Apifox 直接核验的验证码约束：

operationCode 只允许 password-login、sms-login、register、forgot-password、phone-change、account-deactivate。服务端按它解析激活场景，前端不得传 sceneCode。
require query 为必填 tenantId 和可选 subject；challenge body 为必填 tenantId、subject；verify 增加必填 challengeId，可提交 providerCode、captchaType、payload。clientid 只从请求头读取，query/body 不得传 clientId。
validToken 与租户、PC 客户端、认证动作、手机号主体、挑战和请求 IP 绑定。它只用于触发它的当前认证动作：发送短信码时随发送请求提交，密码登录被策略要求时随本次登录提交。

规划：

新流程统一使用 /genealogy/pc/auth/verification/{operationCode}/* 三个接口；页面通过 ApiClient 的业务方法和 URL helper 驱动 TAC，不拼路径。
validToken 不长期存储或写日志；发送短信码或密码登录完成后立即从表单清除。页面只会在验证中心对该认证动作明确要求时，将本次返回的值混入对应请求 DTO。

4.3 文件上传（当前目录 3）

下表是 2026-07-24 的 6 条历史映射。当前桌面版目录只显示 3 条，且三条详情已复核；表中未列的旧单文件上传、文件引用路径已从 ApiClient 删除。

接口	使用位置	用途
`POST /genealogy/pc/files/upload`	头像、文章封面、相册照片、祭祀封面、记录附件	单文件上传
`POST /genealogy/pc/files/resumable/init`	视频、大文件	初始化分片任务
`POST /genealogy/pc/files/resumable/chunk`	视频、大文件	上传单个分片
`POST /genealogy/pc/files/resumable/complete`	视频、大文件	合并分片并返回文件
`POST /genealogy/pc/files/reference`	所有业务保存成功后	绑定业务引用
`DELETE /genealogy/pc/files/reference`	替换或删除业务文件后	解除业务引用

状态：当前三条均为分片初始化、上传分片、完成分片。初始化要求 fileName、fileSize、fileMd5、chunkSize、totalChunks，可附 contentType、bizType、usageScene；分片为 multipart 的 uploadId、chunkIndex、chunkMd5、file；完成要求 uploadId、fileMd5、fileSize。所有文件先初始化，普通小文件可根据 instant=true 直接使用 OSS 信息，但初始化响应 Schema 未展开，页面不猜测 uploadId/ossId/instant，头像上传保持阻止。

已核验的分片/引用约束：

初始化必填 fileName、fileSize、fileMd5、chunkSize、totalChunks，可选 contentType、bizType、usageScene；接口说明规定 instant=true 时直接使用返回的 OSS 信息。当前响应仍是未展开字段的 ObjectResult，因此不开放续传页面流程。
分片上传 multipart 必填 uploadId、chunkIndex、chunkMd5、file；完成上传必填 uploadId、fileMd5、fileSize。
绑定引用必填 bizType、bizTable、bizId、bizField，可选 ossId 或逗号分隔的 ossIds、bizName、usageScene、usageName；解除引用只必填 bizTable、bizId、bizField。
具体业务的 bizType、bizTable、bizField 目前没有由对应业务接口声明，不在页面中猜测创建或解除引用规则。

4.4 行政区划（4）

接口	使用页面	用途
`GET /genealogy/region/children`	个人资料、创建/编辑家谱	获取下级区划
`GET /genealogy/region/path/{regionCode}`	同上	区划编码回显
`GET /genealogy/region/search`	同上	关键词搜索地区
`GET /genealogy/region/{regionCode}`	同上	获取地区详情

状态：四条路径和请求参数已直接核验；个人资料已使用，创建家谱页面待家谱接口补齐后复用同一个区划组件。children 的 parentCode 可选（不传查省级），search 必填 keyword、可选 level 和 limit，路径/详情使用必填 regionCode。当前 Apifox 的地区响应仍是未展开属性的通用对象/数组，页面已有的 regionCode、regionName、regionLevel 消费需在联调时以真实响应再确认，不能把导出快照当 Schema。

个人资料页当前流程：

页面	页面流程	对接接口
`profile.html`	读取当前资料、显示昵称/手机/生日/地区	`GET /genealogy/pc/auth/profile` → `GET /genealogy/region/path/{regionCode}`
`profile-data.html`	回填并保存昵称、性别、生日和头像 OSS ID	`GET /genealogy/pc/auth/profile` → `POST /genealogy/pc/files/upload` → `PUT /genealogy/pc/auth/profile`
`profile-data.html`	回填、搜索、选择并保存现居地区	`GET /genealogy/region/children` / `path` / `search` / `{regionCode}` → `PUT /genealogy/pc/auth/profile`

注意：当前严格使用 Apifox PC 声明的 /genealogy/region/*，页面和 ApiClient 不再维护其他区划路径。

4.5 家族圈（14）

接口	使用页面	用途
`GET /genealogy/pc/genealogies/{genealogyId}/feeds`	`profile-feed.html`	非分页动态列表
`GET .../feeds/page`	`profile-feed.html`	动态分页
`POST .../feeds`	`profile-feed-edit.html`	发布动态
`GET .../feeds/{feedId}`	编辑页、动态详情页	动态详情
`PUT .../feeds/{feedId}`	`profile-feed-edit.html`	修改动态
`DELETE .../feeds/{feedId}`	列表、详情	删除动态
`POST .../feeds/{feedId}/likes`	列表、详情	点赞
`DELETE .../feeds/{feedId}/likes`	列表、详情	取消点赞
`GET .../feeds/{feedId}/comments`	动态详情	评论列表
`GET .../feeds/{feedId}/comments/page`	动态详情	评论分页
`POST .../feeds/{feedId}/comments`	动态详情	评论或回复
`DELETE .../feeds/{feedId}/comments/{commentId}`	动态详情	删除评论
`GET .../comments/{commentId}/replies`	动态详情	直接回复列表
`GET .../comments/{commentId}/replies/page`	动态详情	直接回复分页

状态：14 个操作已在本轮 Apifox PC 详情中逐条复核，现有 ApiClient 路径、分页 query 和页面调用均一致。profile-feed.html 已接入动态分页、点赞、一级评论、发表回复和按需展开直接回复；评论及回复 ID 在路径中按字符串传递。

已核验的评论约束：

发表评论请求体只有必填 commentContent（最多 1000 字）和可选 parentCommentId；不传或传 null 表示一级评论，不能发送旧字段 content 或未声明的 replyUserId。
一级评论接口只返回正常展示的一级评论；直接回复使用 GET .../comments/{commentId}/replies，分页使用 GET .../comments/{commentId}/replies/page。两类分页均为 pageNum、pageSize。
评论响应字段为 commentContent、commentId、parentCommentId、appUserNickName、replyCount、commentLevel、userDeleted 等；作者删除后 commentContent 为 null 且 userDeleted 为 1，页面显示占位而非把响应视为异常。

页面规划：

profile-feed.html 只负责动态分页和轻量操作。
新增动态详情页，负责完整正文、评论、回复、通知跳转和分享深链。
评论 DTO 必须返回稳定的 commentId、parentCommentId、replyCount、发布人和权限字段。

4.6 字辈谱（6）

接口	使用页面	用途
`GET .../generation-poems`	家谱主页、世系展示	查询正常字辈谱
`GET .../generation-poems/management`	`profile-generation.html`	查询字辈维护列表
`POST .../generation-poems`	`profile-generation.html`	新增字辈
`PUT .../generation-poems/{poemId}`	`profile-generation.html`	修改字辈
`POST .../generation-poems/batch/preview`	`profile-generation.html`	批量文本预览
`POST .../generation-poems/batch/save`	`profile-generation.html`	批量保存

状态：6 个操作均已在 Apifox PC 详情中核验并完成客户端路径映射；profile-generation.html 已接入管理列表、新增、修改、停用/恢复、批量预览和批量保存。管理列表仅内容编辑者可访问，403 时页面明确显示无权限并禁用写操作；页面缺少真实 genealogyId 时不发请求，也不使用示例编号。

规划：

页面只提供新增、修改和批量导入。
如果产品要求物理删除，先在 Apifox 增加删除接口；当前修改接口的 status 仅按其已声明的正常/停用语义使用，不作为删除替代。
批量预览必须展示解析错误、重复代次、原/新状态和将被覆盖的记录，用户确认后才能保存；前端按 Apifox 限制校验总文本不超过 26000 字符、单个字辈不超过 50 字符、一次最多 500 代。
字辈新增、修改、状态切换、批量预览和批量保存执行期间锁定写入口，避免重复提交；批量输入示例必须使用 Apifox 已声明的分隔符，连续文本视为一个字辈。

4.7 世系人物（12）

接口	使用页面	用途
`GET .../lineage/persons`	`profile-tree.html`	成员总览
`GET .../lineage/persons/page`	`profile-tree.html`	人物分页与关键词搜索
`GET .../lineage/persons/options`	关系选择、成长记录	人物下拉选项
`GET .../lineage/tree`	`profile-tree.html`	世系树
`POST .../lineage/persons`	`profile-tree.html`	新增人物
`GET .../lineage/persons/{personId}`	树内详情、人物详情	人物详情
`PUT .../lineage/persons/{personId}`	人物编辑	修改人物
`DELETE .../lineage/persons/{personId}`	人物详情	逻辑停用人物
`POST .../persons/{personId}/children`	关系维护	添加子女
`POST .../persons/{personId}/parents`	关系维护	添加父母
`POST .../persons/{personId}/siblings`	关系维护	添加兄弟姐妹
`POST .../persons/{personId}/spouses`	关系维护	添加配偶

状态：12 个操作均已在 Apifox PC 详情中核验并完成客户端路径映射；profile-tree.html 已接入成员总览、树、人物分页搜索与翻页、人物选项、详情、新增、修改、逻辑停用，以及新增父母、配偶、兄弟姐妹、子女。写入和停用请求执行期间会锁定操作入口，页面缺少真实 genealogyId 时不发请求。

已核验的关键约束：

人物 DTO 使用 name、generation、biography，不是旧页面字段 personName、generationNo、introduction。
DELETE .../persons/{personId} 的语义是逻辑停用，不物理删除；人物存在正常子女时后端会拒绝停用。
四个关系接口都接收完整的 LineagePersonBody 来新建关系人物，并非把两个已有 personId 绑定在一起；当前没有解除关系接口。
LineagePersonTreeView 以 spouses、children 递归返回关系树；页面避免将不安全的数值型 int64 ID 用于后续写请求。

规划：

profile-tree.html 负责树、搜索、人物详情、快捷新增和关系人物新增。
人物详情可先使用抽屉；消息和分享需要深链时再补独立详情页。
Apifox 需补充稳定的关系 ID 与解除关系接口。
删除人物前必须返回影响范围，禁止前端猜测是否级联删除子女或关系。
GenealogyMember 是账号和权限成员，LineagePerson 是谱系人物，两者不能合并。

4.8 内容文章（1）

现有接口：

DELETE /genealogy/pc/genealogies/{genealogyId}/articles/{articleId}

使用位置：profile-article.html 的删除操作。

当前不能启用真实文章管理，因为缺少：

文章列表/分页
文章详情
新增文章
修改文章
文章分类
发布、下线和公开可见性
官网公开文章详情

状态：删除操作已核验并映射为 ApiClient.deleteArticle(genealogyId, articleId)。两个路径参数均为必填 int64，登录和 clientid 必填，响应是 VoidResult；没有列表、详情或稳定 articleId 来源，页面不开放删除。

规划：接口补齐前，profile-article.html、profile-article-edit.html 和 article-detail.html 保持设计预览，不单独接入删除接口。

4.9 相册（2）

现有接口：

DELETE /genealogy/pc/genealogies/{genealogyId}/albums/{albumId}
DELETE /genealogy/pc/genealogies/{genealogyId}/albums/{albumId}/photos/{photoId}

使用位置：profile-album.html 的删除相册、删除照片操作。

当前缺少相册列表、详情、新增、修改，以及照片列表、新增、修改和文件引用。接口补齐前不启用删除按钮。

状态：两个删除操作已核验并映射为 deleteAlbum(genealogyId, albumId) 与 deleteAlbumPhoto(genealogyId, albumId, photoId)。所有路径 ID 是必填 int64，登录和 clientid 必填，响应是 VoidResult；删除相册会由后端逻辑删除相册及照片，并释放封面和照片文件引用。没有列表/详情或稳定 ID 来源，页面不开放删除。

4.10 视频（1）

现有接口：

DELETE /genealogy/pc/genealogies/{genealogyId}/videos/{videoId}

使用位置：profile-video.html 的删除操作。

当前缺少视频列表、详情、新增、修改、发布状态、公开播放详情以及文件引用。本轮只映射删除契约；后端补齐 PC 读写接口后，再结合分片上传实施完整视频流程。

状态：删除操作已核验并映射为 deleteVideo(genealogyId, videoId)。两个路径参数是必填 int64，登录和 clientid 必填，响应是 VoidResult；后端逻辑删除视频并释放视频和封面文件引用。没有列表/详情或稳定 ID 来源，页面不开放删除。

4.11 祭祀/典礼（2）

现有接口：

DELETE /genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId}
DELETE /genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId}/gifts/{giftId}

使用位置：profile-gift.html 的删除活动、删除献礼操作。

当前缺少活动列表、详情、新增、修改，以及献礼列表和新增。接口补齐前不启用删除。

状态：两个删除操作已核验并映射为 deleteCeremony(genealogyId, ceremonyId) 与 deleteCeremonyGift(genealogyId, ceremonyId, giftId)。所有路径 ID 是必填 int64，登录和 clientid 必填，响应是 VoidResult；删除祭祀活动会由后端逻辑删除活动及祭品，并释放活动封面文件引用。没有列表/详情或稳定 ID 来源，页面不开放删除。

命名需先拍板：

如果只处理祖先祭祀，DTO 和页面只保留祭祀类型。
如果还处理婚礼、生日、升学等活动，Apifox 目录应改为“典礼/贺礼”，避免接口名称和产品含义不一致。

4.12 贺礼邀约（4）

PUT /genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId}/invitees
GET /genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId}/invitations
PUT /genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId}/invitations/me
GET /genealogy/pc/genealogies/ceremony-invitations/mine

状态：四条已逐条核验并映射为 replaceCeremonyInvitees、ceremonyInvitations、respondCeremonyInvitation、myCeremonyInvitations。替换受邀人只接受必填 inviteeUserIds（空数组取消全部待响应邀请）；当前用户响应只接受 inviteStatus: ACCEPTED|DECLINED。前三条需要真实 genealogyId 和 ceremonyId，最后一条只查询当前用户。当前仍没有活动列表、创建、详情或献礼接口，profile-gift.html / profile-gift-edit.html 不开启操作。

4.13 消息通知（4）

GET  /genealogy/pc/notifications?readStatus=0|1
GET  /genealogy/pc/notifications/unread-count
POST /genealogy/pc/notifications/{notificationId}/read
POST /genealogy/pc/notifications/read-all

状态：四条已逐条核验并映射为 notifications、unreadNotificationCount、markNotificationRead、markAllNotificationsRead。列表的元素 DTO 在当前 PC 详情未展开，不能假设通知标题、正文、时间或 notificationId 的响应字段。profile-messages.html 因此只安全展示原始记录，并开放无歧义的未读数、刷新和全部已读；单条已读继续等待列表元素 Schema。

4.14 族务记录（16）

成长记录（5）

GET    .../growth-records
POST   .../growth-records
GET    .../growth-records/{recordId}
PUT    .../growth-records/{recordId}
DELETE .../growth-records/{recordId}

使用页面：profile-growth.html、profile-growth-edit.html。

用途：列表、新增、详情、编辑、删除，可关联世系人物和附件。

状态：5 个操作均已在 Apifox PC 详情中逐条核验，ApiClient 已映射为 growthRecords、createGrowthRecord、growthRecordDetail、updateGrowthRecord、deleteGrowthRecord。全部需要登录，使用必填 clientid 请求头；genealogyId 和 recordId 都是 int64 路径参数。

已核验的请求/响应约束：

新增和修改使用 GrowthRecordBody：recordTitle 必填；lineagePersonId、recordType、recordContent、recordDate、remindTime、mediaOssIds、sortOrder、status 可选。mediaOssIds 为英文逗号分隔的正整数 OSS ID。
列表响应是 ListResult，但元素 DTO 未在 Apifox 展开；详情、新增和修改是元素 DTO 未展开的 ObjectResult，删除是 VoidResult。因此不能假设响应含有 recordId、标题、权限或文件引用字段。
profile-growth.html 已请求列表并安全地原样展示数组元素；profile-growth-edit.html 已开放新增和写入防重。因为没有可安全使用的响应 ID 或详情字段，详情、编辑和删除入口保持关闭，等待 Apifox 补齐响应 DTO。

亲友往来（5）

GET    .../relative-records
POST   .../relative-records
GET    .../relative-records/{relativeId}
PUT    .../relative-records/{relativeId}
DELETE .../relative-records/{relativeId}

当前没有独立页面。现有 profile-memo.html 同时写了“人情往来”和“备忘提醒”，会导致两个资源边界混乱。

状态：5 个操作已在 Apifox PC 详情中逐条核验，ApiClient 已映射为 relativeRecords、createRelativeRecord、relativeRecordDetail、updateRelativeRecord、deleteRelativeRecord；全部需要登录和必填 clientid 请求头。RelativeRecordBody 的 relativeName 必填，relationName、eventName、eventTime、giftAmount、recordContent、mediaOssIds、sortOrder、status 可选。列表/详情元素 DTO 未展开，故新增 profile-relative.html / profile-relative-edit.html 仅开放原始列表展示和新增，不猜测 relativeId 后开放详情、编辑或删除。

规划：将“人亲簿/亲友往来”和“备忘录”拆成两个 Tab 或两组页面：

亲友往来：亲友、关系、事项、时间、礼金、说明。
备忘录：待办、提醒时间、完成状态、附件。

备忘录（5）

GET    .../memos
POST   .../memos
GET    .../memos/{memoId}
PUT    .../memos/{memoId}
DELETE .../memos/{memoId}

使用页面：profile-memo.html、profile-memo-edit.html。

用途：家族事务、纪念事项、待办提醒和完成状态。

状态：5 个操作已在 Apifox PC 详情中逐条核验，ApiClient 已映射为 memos、createMemo、memoDetail、updateMemo、deleteMemo；全部需要登录、必填 clientid 请求头，genealogyId 和 memoId 都是 int64 路径参数。新增和修改使用已核验的备忘录请求体：memoTitle 必填，memoContent、remindTime、completed、mediaOssIds、sortOrder、status 可选；completed 是 string，mediaOssIds 是英文逗号分隔的正整数 OSS ID。列表响应是元素 DTO 未展开的 ListResult，详情/新增/修改是元素 DTO 未展开的 ObjectResult，删除是 VoidResult，因此 profile-memo.html / profile-memo-edit.html 仅开放原始列表展示和新增，不猜测 memoId 后开放详情、编辑或删除。

功德记录（1）

DELETE .../merit-records/{meritId}

使用位置：profile-merit.html 的删除操作。

当前缺少列表、新增、详情和修改。接口补齐前，profile-merit.html 与 profile-merit-edit.html 保持设计预览。

状态：该删除操作已在 Apifox PC 详情中核验，ApiClient.deleteMeritRecord(genealogyId, meritId) 映射 DELETE /genealogy/pc/genealogies/{genealogyId}/merit-records/{meritId}；genealogyId、meritId 是必填 int64 路径参数，登录和 clientid 必填，响应为 VoidResult。没有真实列表、详情或稳定 meritId 来源，页面不开放删除。

5. 后端后续补充清单（当前不对接）

本节只登记当前 PC 85 个接口之外的业务缺口，不借用 APP 路径、参数或 DTO。后端把新接口正式加入 Apifox PC 后，再更新接口数量和页面对接计划。

后续优先级 1：家谱上下文与成员

这是形成完整 PC 导航闭环的前置能力：

我的家谱列表
家谱下拉选项
公开家谱搜索
家谱详情/概览
创建、修改家谱
申请加入、我的申请、撤销申请
待审核申请、审核申请
家谱成员列表/选项
修改成员角色
移除成员
退出家谱
转让家谱
邀请码/邀请链接的生成、校验和失效

后续优先级 2：当前只有删除操作的模块

文章：列表、详情、新增、修改、分类、发布状态。
相册：相册 CRUD、照片列表/新增/修改、文件引用。
视频：列表、详情、新增、修改、发布状态、文件引用。
祭祀/典礼：活动 CRUD、献礼列表/新增。
功德录：列表、详情、新增、修改。

后续优先级 3：已有主体但缺少的操作

世系关系解除。
字辈删除或停用。
家族圈评论回复 DTO 和权限字段。
删除人物、文章、相册、视频、祭祀等操作的引用清理规则。
官网公开内容的无登录只读接口。

6. 页面与接口实施顺序

阶段 0：锁定当前 PC 契约

目标：

直接在 Apifox 客户端中核对当前 PC 目录。
锁定 15 个目录、85 个操作及各目录数量，作为当前唯一对接清单。
为每个操作在 Apifox 中确认 method、path、请求 DTO、响应 DTO、权限和错误码；可选导出仅用于生成本地契约测试快照。
排除所有未进入 Apifox PC 目录的接口，不引用 APP 或其他公开文档补充本轮范围。
统一 token、ID、ossId、分页、日期和枚举。

验收：

Apifox PC 操作数等于 85，目录数量与第 1 节一致。
第 4 节中的每个接口都能在 Apifox 客户端中找到，且没有 APP 或其他目录的接口混入当前清单。
同一接口只有一套 path 和 DTO。
当前计划不再引用 APP 路径或 APP DTO。

阶段 1：已接模块回归与补齐

范围：

认证登录 12 个。
验证中心 3 个。
行政区划 4 个。
文件上传 3 个。
家族圈 14 个。

执行重点：

先核对现有 ApiClient 与当前 PC 契约，保留已正确对接的部分。
补齐文件分片、文件引用，以及家族圈评论回复列表和分页等当前 PC 已有但页面尚未完整使用的能力。
统一 401、403、业务错误、空状态和重复提交处理。

当前施工进度：

已完成认证、验证码与账号安全流程，包含登录、短信登录、注册、找回密码、换绑、注销和退出；本轮已按当前 PC 契约将验证码与短信发送迁移至 operationCode 路径并移除 sceneCode/body clientId。密码登录已接入 password-login 的验证策略和 TAC validToken 提交。
已完成个人资料读取与保存、行政区划三级联动/搜索/回显；资料和区划请求统一携带登录态，ossId 在浏览器端保持字符串。头像上传等待当前 PC 分片初始化响应 Schema 补齐后再开放回填。
当前仅保留文件分片初始化、分片和完成三条客户端契约；旧单文件上传、文件引用路径已删除。待后端补齐初始化响应 Schema 后，再开通头像上传闭环。
历史 79 条映射不能代替当前 85 条复核。本轮已完成当前 85/85 条的逐项 PC 详情复核：验证中心 3 条、认证登录 12 条、文件上传 3 条、家谱配额、家族圈 14 条、贺礼邀约、族务记录 16 条、消息通知、行政区划 4 条、字辈谱 6 条、世系人物 12 条和文章/相册/视频/祭祀 6 条。成长记录、亲友往来和备忘录的响应 DTO 仍待后端补齐，文章、相册、视频、祭祀和功德记录均只有删除孤岛接口，页面保持关闭。
已去除个人中心中的示例家谱卡片；所有无上下文的家谱业务入口先进入 profile-families.html，实际调用 PC 配额接口并在缺少真实 genealogyId 时保持阻止。

验收：

登录、验证码、区划和上传流程只请求当前 PC 路径。
家族圈列表、详情、点赞、评论和回复使用同一套 DTO 与计数字段。
文件上传完成后按业务保存结果创建引用，删除业务数据时按后端规则解除引用。

阶段 2：家谱内完整资源

范围与顺序：

字辈谱 6 个。
世系人物 12 个。
成长记录 5 个（已完成契约映射、列表/新增页面；响应 DTO 缺口使详情/编辑/删除保持关闭）。
亲友往来 5 个（已完成契约映射、列表/新增页面；响应 DTO 缺口使详情/编辑/删除保持关闭）。
备忘录 5 个（已完成契约映射、列表/新增页面；响应 DTO 缺口使详情/编辑/删除保持关闭）。

执行前提：

页面必须从 PC 的真实入口参数或运行时上下文取得 genealogyId。
当前 PC 尚无家谱入口接口；没有真实 genealogyId 时只展示缺少上下文状态，不发请求、不写死 ID，也不调用 APP。
只实现当前接口支持的操作；世系关系解除、字辈删除等缺口等待后端补充 PC 接口。

验收：

所有请求均携带同一个真实 genealogyId，切换上下文后不串数据。
列表、新增、详情、修改和删除严格按当前各资源的实际接口能力开放。
世系树、人物详情和记录关联统一使用当前 PC 世系人物 DTO。
无权限用户看不到写入口，后端 403 能正确呈现。

阶段 3：当前只有删除能力的模块

范围：

内容文章 1 个（已完成删除契约映射；缺少列表/详情，不开放页面删除）。
相册与照片 2 个（已完成删除契约映射；缺少列表/详情，不开放页面删除）。
视频 1 个（已完成删除契约映射；缺少列表/详情，不开放页面删除）。
祭祀/典礼与献礼 2 个（已完成删除契约映射；缺少列表/详情，不开放页面删除）。
功德记录 1 个（已完成删除契约映射；缺少列表/详情，不开放页面删除）。

处理方式：

先完成删除接口的 ApiClient 契约映射和接口测试。
因当前 PC 缺少列表、详情、新增或修改接口，页面继续保持预览状态，不开放孤立的删除按钮。
后端补齐同模块 PC 接口后，再按完整资源流程启用页面。

验收：

7 个删除操作的 method、path、路径参数和权限定义均与 Apifox PC 一致。
当前页面不会因静态演示数据触发真实删除。
未补齐的能力不会通过 APP 接口、猜测路径或模拟成功结果实现。

阶段 4：接收后端新增 PC 接口

每次后端新增或调整 PC 接口后：

先确认接口已正式进入 Apifox PC 目录。
更新基线数量、第 4 节用途映射和第 5 节缺口。
再安排相应页面、ApiClient 方法、契约测试和联调。
不因为 APP 已存在同类能力而提前实现。

7. 联调与测试要求

每个接口组按相同顺序验收：

直接在 Apifox PC 目录确认 method、path、DTO、枚举和权限。
给 ApiClient 增加业务方法。
增加契约测试，验证 method、path、query 和 body。
接页面加载、空状态、错误状态和成功状态。
验证 401、403、404、业务校验失败和重复提交。
验证写入后重新读取的数据与页面一致。
删除操作验证关联数据和文件引用处理。

禁止以下做法：

页面直接写 Axios 请求。
猜测字段名或同时兼容多个字段。
使用 APP 路径补 PC 缺口。
写死 genealogyId。
把静态示例数据当成接口成功结果。
只有删除接口时先开放删除按钮。

8. 后续业务待确认项（不阻塞当前 85）

以下问题只影响后端后续新增 PC 接口，不改变本轮范围：

“祭祀”究竟只指祖先祭祀，还是通用典礼/贺礼。
亲友往来是否从现有备忘录页面拆成独立 Tab，建议拆分。
字辈是否允许物理删除；建议优先停用。
删除世系人物是否允许级联删除关系；建议默认禁止并由接口返回影响范围。
feedback 只用于意见反馈，还是要承担客服工单；若需要状态、回复和详情，应建立独立 Ticket 契约。
资料提醒是否只是通知的一种类型；若是，NotificationDTO 应提供稳定的通知类型和目标深链。

41 KiB Raw Blame History Unescape Escape

PC 接口对接规划（Apifox 85 接口版）

1. 已确认的基线

2. 当前最重要的结论

2.1 当前范围规则

3. 公共契约规则

3.1 接口所有权

3.2 家谱上下文

3.3 请求头与登录状态

3.4 响应与分页

3.5 ID、日期和枚举

3.6 权限

3.7 文件生命周期

4. 已完成施工接口与当前迁移

4.1 认证登录（当前目录 12）

4.2 验证中心（当前目录 3）

4.3 文件上传（当前目录 3）

4.4 行政区划（4）

4.5 家族圈（14）

4.6 字辈谱（6）

4.7 世系人物（12）

4.8 内容文章（1）

4.9 相册（2）

4.10 视频（1）

4.11 祭祀/典礼（2）

4.12 贺礼邀约（4）

4.13 消息通知（4）

4.14 族务记录（16）

成长记录（5）

亲友往来（5）

备忘录（5）

功德记录（1）

5. 后端后续补充清单（当前不对接）

后续优先级 1：家谱上下文与成员

后续优先级 2：当前只有删除操作的模块

后续优先级 3：已有主体但缺少的操作

6. 页面与接口实施顺序

阶段 0：锁定当前 PC 契约

阶段 1：已接模块回归与补齐

阶段 2：家谱内完整资源

阶段 3：当前只有删除能力的模块

阶段 4：接收后端新增 PC 接口

7. 联调与测试要求

8. 后续业务待确认项（不阻塞当前 85）

41 KiB

Raw Blame History