完成10%

2026-07-24 18:11:16 +08:00
parent 8716a68fdb
commit 8870136d1b
33 changed files with 3853 additions and 336 deletions
@@ -0,0 +1,647 @@
+# 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` 应提供稳定的通知类型和目标深链。