jiapu/docs/PC接口对接规划.md

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

> 状态：当前范围已确认  
> 日期：2026-07-24  
> 当前阶段：已直接在 Apifox 核验验证码中心、认证登录、文件上传、行政区划、家族圈、字辈谱和世系人物共 57 条接口；施工只以这些 PC 详情为准，其余目录继续逐组核验后再接入。
> 交接入口：[交接文档.md](交接文档.md)

## 1. 已确认的基线

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

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

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

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

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

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

因此对接分成三类：

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

### 2.1 当前范围规则

- 当前只分析和对接 Apifox PC 中已经存在的 79 个操作。
- 不读取 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. 当前 79 个接口没有“我的家谱”入口，本轮不从 APP 获取 `genealogyId`。
2. 当前家谱业务页面只接受 PC 运行入口通过 URL 传入的真实 `genealogyId`。
3. `profile-common.js` 作为 PC 页面家谱上下文的唯一 owner，负责读取、校验和传播 `genealogyId`。
4. `ApiClient` 负责把 `genealogyId` 放入路径。
5. 页面缺少 `genealogyId` 时阻止请求并显示“等待家谱入口接口”，不使用示例编号。

后端补充 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. 79 个接口的页面用途

### 4.1 认证登录（11）

| 接口 | 使用页面 | 用途 |
| --- | --- | --- |
| `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/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` | 所有登录后页面 | 退出登录 |

状态：第一轮施工已接入密码登录、短信登录、注册、找回密码、换绑手机号、注销和退出。注册必须先取得短信码；找回密码由 `ApiClient` 统一补齐 `grantType`、`tenantId`、`clientId`。Apifox 的 `LoginVo` 明确允许 `token`、`accessToken`、`tokenValue` 三种响应字段，客户端按该顺序读取第一个非空值；资料响应未给出字段 Schema，页面只读取 PC 页面已使用的明确字段，不增加 APP 字段猜测。

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

- 发送短信验证码只允许 `PC_SMS_LOGIN`、`PC_REGISTER`、`PC_FORGOT_PASSWORD`、`PC_PHONE_CHANGE`、`PC_ACCOUNT_DEACTIVATE` 五个场景。
- 发送短信码请求体为 `clientId`、`grantType`、`tenantId`、`sceneCode`、`phone`、`validToken`；`validToken` 来自验证码中心且只能单次消费。
- 换绑手机号请求体为 `clientId`、`phone`、`smsCode`；注销账号请求体为 `clientId`、`smsCode`。二者不附带 `tenantId`。
- 密码登录与注册使用 `grantType: "password"`；短信登录与发送短信码使用 `grantType: "sms"`；所有密码字段均为 32 位 MD5。

第一批页面与接口顺序：

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

### 4.2 验证中心（4）

| 接口 | 使用位置 | 用途 |
| --- | --- | --- |
| `GET /captcha/require` | 发送登录、注册、找回、换绑、注销短信前 | 判断当前场景是否需要验证 |
| `POST /captcha/challenge` | 同上 | 获取滑块或图形验证挑战 |
| `POST /captcha/verify` | 同上 | 校验挑战并换取 `validToken` |
| `GET /auth/code` | 仅兼容旧图形验证码 | 旧验证方案 |

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

- `GET /captcha/require` 使用 `tenantId`、`clientId`、`sceneCode`、`subject` 查询场景策略。
- `POST /captcha/challenge` 必须携带同一组 `tenantId`、`clientId`、`sceneCode`、`subject`；天爱策略返回行为验证数据，系统图形策略返回 `uuid` 和 `img`。
- `POST /captcha/verify` 除上述字段外还必须携带 `challengeId`，并以 `providerCode`、`captchaType`、`payload` 提交验证结果；成功后取得 `validToken`。
- `validToken` 与租户、PC 客户端、场景、手机号主体、挑战和请求 IP 绑定，只能随发送短信码接口单次提交。

规划：

- 新流程统一使用 `/captcha/*` 三个接口。
- `/auth/code` 标记为兼容接口，确定所有场景迁移完成后从 Apifox 和代码一起删除。
- `validToken` 只用于发送短信验证码的请求；发送完成后立即从表单清除，不写日志、不长期存储，也不混入登录、注册、重置或换绑的业务 DTO。

### 4.3 文件上传（6）

| 接口 | 使用位置 | 用途 |
| --- | --- | --- |
| `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` | 替换或删除业务文件后 | 解除业务引用 |

状态：6 个文件接口已直接在 Apifox 核验，`ApiClient` 的 PC 路径、认证头和请求形状一致。单文件上传只提交 multipart `file`，返回 `data.ossId`、`url`、`thumbnailUrl`、`fileName`、`originalName`；`profile-data.html` 使用它回填 `avatarOssId`，再随 `PUT /genealogy/pc/auth/profile` 保存。

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

- 初始化必填 `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 详情中核验并完成客户端路径映射。`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` 的删除操作。

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

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

规划：接口补齐前，`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` 的删除相册、删除照片操作。

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

### 4.10 视频（1）

现有接口：

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

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

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

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

现有接口：

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

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

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

命名需先拍板：

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

### 4.12 族务记录（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）

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

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

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

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

#### 备忘录（5）

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

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

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

#### 功德记录（1）

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

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

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

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

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

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

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

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

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

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

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

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

## 6. 页面与接口实施顺序

### 阶段 0：锁定当前 PC 契约

目标：

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

验收：

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

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

范围：

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

执行重点：

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

当前施工进度：

1. 已完成认证、验证码与账号安全流程，包含登录、短信登录、注册、找回密码、换绑、注销和退出。
2. 已完成个人资料读取与保存、头像单文件上传回填、行政区划三级联动/搜索/回显；资料和区划请求统一携带登录态，`ossId` 在浏览器端保持字符串。
3. 已完成文件分片初始化、分片、完成、绑定和解绑的客户端契约映射；待后端补齐初始化响应和各业务引用值后，再开通页面上传闭环。
4. 已完成家族圈回复、字辈谱和世系人物的 Apifox 核验与首轮页面施工；下一步直接核验族务记录的完整路径、DTO 与响应字段，再决定成长记录、亲友往来、备忘录页面能否开放。

验收：

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

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

范围与顺序：

1. 字辈谱 6 个。
2. 世系人物 12 个。
3. 成长记录 5 个。
4. 亲友往来 5 个。
5. 备忘录 5 个。

执行前提：

- 页面必须从 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 接口

本阶段不属于当前 79 个接口的对接范围。后端每次新增 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. 后续业务待确认项（不阻塞当前 79）

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

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