现在有的接口对接测试完成

docs/PC接口对接规划.md

@@ -1,20 +1,21 @@
-# PC 接口对接规划（Apifox 79 接口版）
+# PC 接口对接规划（Apifox 85 接口版）
 
 > 状态：当前范围已确认  
-> 日期：2026-07-24  
-> 当前阶段：已直接在 Apifox 核验验证码中心、认证登录、文件上传、行政区划、家族圈、字辈谱和世系人物共 57 条接口；施工只以这些 PC 详情为准，其余目录继续逐组核验后再接入。
+> 日期：2026-07-25
+> 当前阶段：桌面版 Apifox 的 PC 目录为 85 条，已逐条在 PC 详情复核并与客户端映射比对。后续仅在该目录出现新增或变更时，按 PC 详情重新核验；不据旧记录猜测施工。
 > 交接入口：[交接文档.md](交接文档.md)
 
 ## 1. 已确认的基线
 
 1. **Apifox 的 PC 目录是 PC 前端接口的唯一正式契约源。**
-2. 当前 Apifox PC 共 79 个操作：
+2. 当前 Apifox PC 共 85 个操作：
 
    | 分组 | 数量 |
    | --- | ---: |
-   | 认证登录 | 11 |
-   | 验证中心 | 4 |
-   | 文件上传 | 6 |
+   | 认证登录 | 12 |
+   | 验证中心 | 3 |
+   | 文件上传 | 3 |
+   | 家谱 | 1 |
    | 行政区划 | 4 |
    | 家族圈 | 14 |
    | 字辈谱 | 6 |
@@ -22,9 +23,11 @@
    | 内容文章 | 1 |
    | 相册 | 2 |
    | 视频 | 1 |
+   | 贺礼邀约 | 4 |
    | 祭祀 | 2 |
    | 族务记录 | 16 |
-   | **合计** | **79** |
+   | 消息通知 | 4 |
+   | **合计** | **85** |
 
 3. 仓库中的旧 OpenAPI 文件不再作为新增功能依据。Apifox 客户端中实时的 PC 目录是最终验收源；导出文件最多作为本地自动测试快照，不能替代在 Apifox 中逐项核对。
 4. APP 接口不允许在 PC 页面中直接复用。PC 缺少的能力应先补入 Apifox 的 PC 目录，再开发页面。
@@ -33,7 +36,7 @@
 
 ## 2. 当前最重要的结论
 
-现有 79 个接口不能覆盖整个 PC 管理端闭环，主要问题不是前端页面，而是接口目录不完整：
+现有 85 个接口仍不能覆盖整个 PC 管理端闭环，主要问题不是前端页面，而是接口目录不完整：
 
 - 没有“我的家谱、家谱详情、创建/加入家谱、家谱成员”接口，PC 无法自行取得真实 `genealogyId`。
 - 内容文章只有删除接口。
@@ -46,13 +49,13 @@
 
 因此对接分成三类：
 
-1. **当前可以形成可用流程：**认证、验证、文件上传、区划、家族圈、字辈谱、世系人物、成长记录、亲友往来、备忘录；其中家谱内接口必须先由 PC 运行入口提供真实 `genealogyId`。
+1. **当前可以形成可用流程：**认证、验证、文件上传、区划、家族圈、字辈谱、世系人物，以及成长记录、亲友往来、备忘录的新增；三类列表仅能按未展开 DTO 原样展示。其中家谱内接口必须先由 PC 运行入口提供真实 `genealogyId`。
 2. **当前只做契约映射、不开放页面操作：**文章、相册、视频、祭祀和功德录目前只有删除接口，不能在没有真实列表和详情数据时单独启用删除。
 3. **后端补充 PC 接口后再规划：**家谱上下文、成员，以及上述资源缺少的读写操作、世系关系解除和字辈删除/停用。
 
 ### 2.1 当前范围规则
 
-- 当前只分析和对接 Apifox PC 中已经存在的 79 个操作。
+- 当前只分析和对接 Apifox PC 中已经存在的 85 个操作。
 - 不读取 APP 接口补 PC 缺口，不把 `/genealogy/app` 改前缀后用于 PC。
 - 后端公开文档中存在、但 Apifox PC 当前没有的接口，不进入本轮对接；也不以导出文件缺失为由跳过 Apifox 中已有的接口。
 - PC 当前缺少的业务接口只登记为后端待办，相关页面继续显示待开发状态。
@@ -71,13 +74,15 @@
 
 所有家谱内业务必须使用真实 `genealogyId`：
 
-1. 当前 79 个接口没有“我的家谱”入口，本轮不从 APP 获取 `genealogyId`。
+1. 当前 85 个接口仍没有“我的家谱”入口；新增的家谱配额接口也不能提供真实 `genealogyId`，本轮不从 APP 获取。
 2. 当前家谱业务页面只接受 PC 运行入口通过 URL 传入的真实 `genealogyId`。
 3. `profile-common.js` 作为 PC 页面家谱上下文的唯一 owner，负责读取、校验和传播 `genealogyId`。
 4. `ApiClient` 负责把 `genealogyId` 放入路径。
-5. 页面缺少 `genealogyId` 时阻止请求并显示“等待家谱入口接口”，不使用示例编号。
 
-后端补充 PC 家谱入口接口后，再规划“我的家谱 → 选择家谱 → 进入业务页面”的完整导航闭环。
+当前 `GET /genealogy/pc/genealogies/quota` 已映射为 `genealogyQuota()`；它只返回创建/加入家谱的已用数量、上限、剩余和 `canCreate`/`canJoin`，不能作为家谱列表、详情、创建或加入接口，也不能生成或替代真实 `genealogyId`。
+5. 页面缺少 `genealogyId` 时，统一先跳转 `profile-families.html`；该入口页只读取配额并说明 PC 尚不能选择家谱，阻止业务请求且不使用示例编号。
+
+个人中心、内容发布和家谱内导航已统一指向该入口页；后端补充 PC 家谱入口接口后，再由入口页实现“我的家谱 → 选择家谱 → 进入业务页面”的完整导航闭环。
 
 ### 3.3 请求头与登录状态
 
@@ -162,16 +167,16 @@ Apifox 还必须正式声明 Bearer security scheme、`Authorization` 和 `clien
 
 替换或删除业务对象后解除旧文件引用。上传成功但业务保存失败时，也要提供清理策略。
 
-## 4. 79 个接口的页面用途
+## 4. 已完成施工接口与当前迁移
 
-### 4.1 认证登录（11）
+### 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/code` | 短信登录、注册、找回密码、换绑手机号、注销账号 | 发送短信验证码 |
+| `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` | 修改密码 |
@@ -180,51 +185,50 @@ Apifox 还必须正式声明 Bearer security scheme、`Authorization` 和 `clien
 | `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 字段猜测。
+状态：当前 PC 认证登录目录 12 条已逐条复核：第一轮已接入密码登录、短信登录、注册、找回密码、换绑手机号、注销和退出；本轮已把短信发送迁移到当前 PC 的 `operationCode` 路径。密码登录也先按 `password-login` 查询验证策略，策略要求时完成 TAC 后提交返回的 `validToken`。`ApiClient` 只补 DTO 明确要求的 `grantType`、`tenantId`，`clientid` 仅由请求头统一注入，body 不得传 `clientId`。目录内两条短信发送定义为相同路径和契约。资料响应未给出字段 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。
+- 发送短信验证码使用路径 `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/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` |
+| `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/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` |
+| `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 验证中心（4）
+### 4.2 验证中心（当前目录 3）
 
 | 接口 | 使用位置 | 用途 |
 | --- | --- | --- |
-| `GET /captcha/require` | 发送登录、注册、找回、换绑、注销短信前 | 判断当前场景是否需要验证 |
-| `POST /captcha/challenge` | 同上 | 获取滑块或图形验证挑战 |
-| `POST /captcha/verify` | 同上 | 校验挑战并换取 `validToken` |
-| `GET /auth/code` | 仅兼容旧图形验证码 | 旧验证方案 |
+| `GET /genealogy/pc/auth/verification/{operationCode}/require` | 密码登录及发送短信登录、注册、找回、换绑、注销短信前 | 判断当前认证动作是否需要验证 |
+| `POST /genealogy/pc/auth/verification/{operationCode}/challenge` | 同上 | 获取滑块或图形验证挑战 |
+| `POST /genealogy/pc/auth/verification/{operationCode}/verify` | 同上 | 校验挑战并换取 `validToken` |
 
 已在 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 绑定，只能随发送短信码接口单次提交。
+- `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 绑定。它只用于触发它的当前认证动作：发送短信码时随发送请求提交，密码登录被策略要求时随本次登录提交。
 
 规划：
 
-- 新流程统一使用 `/captcha/*` 三个接口。
-- `/auth/code` 标记为兼容接口，确定所有场景迁移完成后从 Apifox 和代码一起删除。
-- `validToken` 只用于发送短信验证码的请求；发送完成后立即从表单清除，不写日志、不长期存储，也不混入登录、注册、重置或换绑的业务 DTO。
+- 新流程统一使用 `/genealogy/pc/auth/verification/{operationCode}/*` 三个接口；页面通过 `ApiClient` 的业务方法和 URL helper 驱动 TAC，不拼路径。
+- `validToken` 不长期存储或写日志；发送短信码或密码登录完成后立即从表单清除。页面只会在验证中心对该认证动作明确要求时，将本次返回的值混入对应请求 DTO。
 
-### 4.3 文件上传（6）
+### 4.3 文件上传（当前目录 3）
+
+> 下表是 2026-07-24 的 6 条历史映射。当前桌面版目录只显示 3 条，且三条详情已复核；表中未列的旧单文件上传、文件引用路径已从 `ApiClient` 删除。
 
 | 接口 | 使用位置 | 用途 |
 | --- | --- | --- |
@@ -235,7 +239,7 @@ Apifox 还必须正式声明 Bearer security scheme、`Authorization` 和 `clien
 | `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`；分片为 multipart 的 `uploadId`、`chunkIndex`、`chunkMd5`、`file`；完成要求 `uploadId`、`fileMd5`、`fileSize`。所有文件先初始化，普通小文件可根据 `instant=true` 直接使用 OSS 信息，但初始化响应 Schema 未展开，页面不猜测 `uploadId`/`ossId`/`instant`，头像上传保持阻止。
 
 已核验的分片/引用约束：
 
@@ -284,7 +288,7 @@ Apifox 还必须正式声明 Bearer security scheme、`Authorization` 和 `clien
 | `GET .../comments/{commentId}/replies` | 动态详情 | 直接回复列表 |
 | `GET .../comments/{commentId}/replies/page` | 动态详情 | 直接回复分页 |
 
-状态：14 个操作均已在 Apifox PC 详情中核验并完成客户端路径映射。`profile-feed.html` 已接入动态分页、点赞、一级评论、发表回复和按需展开直接回复；评论及回复 ID 在路径中按字符串传递。
+状态：14 个操作已在本轮 Apifox PC 详情中逐条复核，现有 `ApiClient` 路径、分页 query 和页面调用均一致。`profile-feed.html` 已接入动态分页、点赞、一级评论、发表回复和按需展开直接回复；评论及回复 ID 在路径中按字符串传递。
 
 已核验的评论约束：
 
@@ -372,6 +376,8 @@ DELETE /genealogy/pc/genealogies/{genealogyId}/articles/{articleId}
 - 发布、下线和公开可见性
 - 官网公开文章详情
 
+状态：删除操作已核验并映射为 `ApiClient.deleteArticle(genealogyId, articleId)`。两个路径参数均为必填 int64，登录和 `clientid` 必填，响应是 `VoidResult`；没有列表、详情或稳定 `articleId` 来源，页面不开放删除。
+
 规划：接口补齐前，`profile-article.html`、`profile-article-edit.html` 和 `article-detail.html` 保持设计预览，不单独接入删除接口。
 
 ### 4.9 相册（2）
@@ -387,6 +393,8 @@ DELETE /genealogy/pc/genealogies/{genealogyId}/albums/{albumId}/photos/{photoId}
 
 当前缺少相册列表、详情、新增、修改，以及照片列表、新增、修改和文件引用。接口补齐前不启用删除按钮。
 
+状态：两个删除操作已核验并映射为 `deleteAlbum(genealogyId, albumId)` 与 `deleteAlbumPhoto(genealogyId, albumId, photoId)`。所有路径 ID 是必填 int64，登录和 `clientid` 必填，响应是 `VoidResult`；删除相册会由后端逻辑删除相册及照片，并释放封面和照片文件引用。没有列表/详情或稳定 ID 来源，页面不开放删除。
+
 ### 4.10 视频（1）
 
 现有接口：
@@ -399,6 +407,8 @@ DELETE /genealogy/pc/genealogies/{genealogyId}/videos/{videoId}
 
 当前缺少视频列表、详情、新增、修改、发布状态、公开播放详情以及文件引用。本轮只映射删除契约；后端补齐 PC 读写接口后，再结合分片上传实施完整视频流程。
 
+状态：删除操作已核验并映射为 `deleteVideo(genealogyId, videoId)`。两个路径参数是必填 int64，登录和 `clientid` 必填，响应是 `VoidResult`；后端逻辑删除视频并释放视频和封面文件引用。没有列表/详情或稳定 ID 来源，页面不开放删除。
+
 ### 4.11 祭祀/典礼（2）
 
 现有接口：
@@ -412,12 +422,36 @@ DELETE /genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId}/gifts/{gi
 
 当前缺少活动列表、详情、新增、修改，以及献礼列表和新增。接口补齐前不启用删除。
 
+状态：两个删除操作已核验并映射为 `deleteCeremony(genealogyId, ceremonyId)` 与 `deleteCeremonyGift(genealogyId, ceremonyId, giftId)`。所有路径 ID 是必填 int64，登录和 `clientid` 必填，响应是 `VoidResult`；删除祭祀活动会由后端逻辑删除活动及祭品，并释放活动封面文件引用。没有列表/详情或稳定 ID 来源，页面不开放删除。
+
 命名需先拍板：
 
 - 如果只处理祖先祭祀，DTO 和页面只保留祭祀类型。
 - 如果还处理婚礼、生日、升学等活动，Apifox 目录应改为“典礼/贺礼”，避免接口名称和产品含义不一致。
 
-### 4.12 族务记录（16）
+### 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）
 
@@ -433,6 +467,14 @@ DELETE .../growth-records/{recordId}
 
 用途：列表、新增、详情、编辑、删除，可关联世系人物和附件。
 
+状态：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
@@ -445,6 +487,8 @@ 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 或两组页面：
 
 - 亲友往来：亲友、关系、事项、时间、礼金、说明。
@@ -464,6 +508,8 @@ DELETE .../memos/{memoId}
 
 用途：家族事务、纪念事项、待办提醒和完成状态。
 
+状态：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
@@ -474,9 +520,11 @@ DELETE .../merit-records/{meritId}
 
 当前缺少列表、新增、详情和修改。接口补齐前，`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 79 个接口之外的业务缺口，不借用 APP 路径、参数或 DTO。后端把新接口正式加入 Apifox PC 后，再更新接口数量和页面对接计划。
+本节只登记当前 PC 85 个接口之外的业务缺口，不借用 APP 路径、参数或 DTO。后端把新接口正式加入 Apifox PC 后，再更新接口数量和页面对接计划。
 
 ### 后续优先级 1：家谱上下文与成员
 
@@ -519,14 +567,14 @@ DELETE .../merit-records/{meritId}
 目标：
 
 - 直接在 Apifox 客户端中核对当前 PC 目录。
-- 锁定 12 个目录、79 个操作及各目录数量，作为本轮唯一对接清单。
+- 锁定 15 个目录、85 个操作及各目录数量，作为当前唯一对接清单。
 - 为每个操作在 Apifox 中确认 method、path、请求 DTO、响应 DTO、权限和错误码；可选导出仅用于生成本地契约测试快照。
 - 排除所有未进入 Apifox PC 目录的接口，不引用 APP 或其他公开文档补充本轮范围。
 - 统一 token、ID、`ossId`、分页、日期和枚举。
 
 验收：
 
-- Apifox PC 操作数等于 79，目录数量与第 1 节一致。
+- Apifox PC 操作数等于 85，目录数量与第 1 节一致。
 - 第 4 节中的每个接口都能在 Apifox 客户端中找到，且没有 APP 或其他目录的接口混入当前清单。
 - 同一接口只有一套 path 和 DTO。
 - 当前计划不再引用 APP 路径或 APP DTO。
@@ -535,10 +583,10 @@ DELETE .../merit-records/{meritId}
 
 范围：
 
-1. 认证登录 11 个。
-2. 验证中心 4 个。
+1. 认证登录 12 个。
+2. 验证中心 3 个。
 3. 行政区划 4 个。
-4. 文件上传 6 个。
+4. 文件上传 3 个。
 5. 家族圈 14 个。
 
 执行重点：
@@ -549,10 +597,11 @@ DELETE .../merit-records/{meritId}
 
 当前施工进度：
 
-1. 已完成认证、验证码与账号安全流程，包含登录、短信登录、注册、找回密码、换绑、注销和退出。
-2. 已完成个人资料读取与保存、头像单文件上传回填、行政区划三级联动/搜索/回显；资料和区划请求统一携带登录态，`ossId` 在浏览器端保持字符串。
-3. 已完成文件分片初始化、分片、完成、绑定和解绑的客户端契约映射；待后端补齐初始化响应和各业务引用值后，再开通页面上传闭环。
-4. 已完成家族圈回复、字辈谱和世系人物的 Apifox 核验与首轮页面施工；下一步直接核验族务记录的完整路径、DTO 与响应字段，再决定成长记录、亲友往来、备忘录页面能否开放。
+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` 时保持阻止。
 
 验收：
 
@@ -566,9 +615,9 @@ DELETE .../merit-records/{meritId}
 
 1. 字辈谱 6 个。
 2. 世系人物 12 个。
-3. 成长记录 5 个。
-4. 亲友往来 5 个。
-5. 备忘录 5 个。
+3. 成长记录 5 个（已完成契约映射、列表/新增页面；响应 DTO 缺口使详情/编辑/删除保持关闭）。
+4. 亲友往来 5 个（已完成契约映射、列表/新增页面；响应 DTO 缺口使详情/编辑/删除保持关闭）。
+5. 备忘录 5 个（已完成契约映射、列表/新增页面；响应 DTO 缺口使详情/编辑/删除保持关闭）。
 
 执行前提：
 
@@ -587,11 +636,11 @@ DELETE .../merit-records/{meritId}
 
 范围：
 
-1. 内容文章 1 个。
-2. 相册与照片 2 个。
-3. 视频 1 个。
-4. 祭祀/典礼与献礼 2 个。
-5. 功德记录 1 个。
+1. 内容文章 1 个（已完成删除契约映射；缺少列表/详情，不开放页面删除）。
+2. 相册与照片 2 个（已完成删除契约映射；缺少列表/详情，不开放页面删除）。
+3. 视频 1 个（已完成删除契约映射；缺少列表/详情，不开放页面删除）。
+4. 祭祀/典礼与献礼 2 个（已完成删除契约映射；缺少列表/详情，不开放页面删除）。
+5. 功德记录 1 个（已完成删除契约映射；缺少列表/详情，不开放页面删除）。
 
 处理方式：
 
@@ -607,7 +656,7 @@ DELETE .../merit-records/{meritId}
 
 ### 阶段 4：接收后端新增 PC 接口
 
-本阶段不属于当前 79 个接口的对接范围。后端每次新增 PC 接口后：
+每次后端新增或调整 PC 接口后：
 
 1. 先确认接口已正式进入 Apifox PC 目录。
 2. 更新基线数量、第 4 节用途映射和第 5 节缺口。
@@ -635,7 +684,7 @@ DELETE .../merit-records/{meritId}
 - 把静态示例数据当成接口成功结果。
 - 只有删除接口时先开放删除按钮。
 
-## 8. 后续业务待确认项（不阻塞当前 79）
+## 8. 后续业务待确认项（不阻塞当前 85）
 
 以下问题只影响后端后续新增 PC 接口，不改变本轮范围：