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

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

## 1. 已确认的基线

1. **Apifox 的 PC 目录是 PC 前端接口的唯一正式契约源。**
2. 当前 Apifox PC 共 85 个操作：

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

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

## 2. 当前最重要的结论

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

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

因此对接分成三类：

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

1. 当前 85 个接口仍没有“我的家谱”入口；新增的家谱配额接口也不能提供真实 `genealogyId`，本轮不从 APP 获取。
2. 当前家谱业务页面只接受 PC 运行入口通过 URL 传入的真实 `genealogyId`。
3. `profile-common.js` 作为 PC 页面家谱上下文的唯一 owner，负责读取、校验和传播 `genealogyId`。
4. `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 响应与分页

普通响应统一为：

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

分页响应统一为：

```json
{
  "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 文件生命周期

图片、小文件：

1. 单文件上传。
2. 获得 `ossId`。
3. 保存业务对象。
4. 绑定文件业务引用。

视频、大文件：

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

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

## 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）

现有接口：

```text
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）

现有接口：

```text
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）

现有接口：

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

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

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

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

### 4.11 祭祀/典礼（2）

现有接口：

```text
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）

```text
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）

```text
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）

```text
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）

```text
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）

```text
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）

```text
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：已接模块回归与补齐

范围：

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

执行重点：

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

当前施工进度：

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

验收：

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

### 阶段 2：家谱内完整资源

范围与顺序：

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

执行前提：

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

验收：

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

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

范围：

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

处理方式：

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

验收：

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

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

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

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

## 7. 联调与测试要求

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

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

禁止以下做法：

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

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

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

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