183 lines
19 KiB
Markdown
183 lines
19 KiB
Markdown
# PC 接口对接交接文档
|
||
|
||
> 更新：2026-07-25
|
||
> 历史交接记录：本文的 79/85 条接口数量已过期，不再作为 AI 施工依据。当前接口基线、字段分类、阻断项和执行顺序统一以 [PC接口对接规划.md](PC接口对接规划.md) 为准；执行前仍须在 Apifox 实时复核并重新导出。
|
||
|
||
## 一、必须遵守的范围
|
||
|
||
1. Apifox 的 **PC 目录**是唯一正式契约源。
|
||
2. 本地 OpenAPI 导出文件可能少接口，只能辅助查找，不能据此决定接口存在、路径或字段。
|
||
3. 不使用 APP 接口，也不能把 `/app/` 改为 `/pc/` 后猜测使用。
|
||
4. 继续任何新接口前，必须直接在 Apifox PC 详情核对 method、path、query、body、响应和权限。
|
||
5. 家谱业务只能使用真实 `?genealogyId=...`；不写死编号、不从 APP 获取。
|
||
6. 页面不直接调用 Axios、不自行拼请求路径，统一通过 `utils/ApiClient.js`。
|
||
|
||
## 二、当前目录与历史施工范围
|
||
|
||
### 当前 PC 目录（2026-07-25）
|
||
|
||
| 分组 | 条数 | 当前处理状态 |
|
||
| --- | ---: | --- |
|
||
| 验证中心 | 3 | 已逐条复核并迁移 |
|
||
| 认证登录 | 12 | 已逐条复核并迁移；其中两条短信发送定义同为当前 `operationCode` 路径 |
|
||
| 文件上传 | 3 | 已逐条复核、`ApiClient` 仅保留分片三条；初始化响应未展开，头像上传保持阻止 |
|
||
| 家谱 | 1 | 已核验并映射配额查询；入口页仅展示配额并阻止进入需 `genealogyId` 的业务页，不能伪造编号 |
|
||
| 家族圈 | 14 | 已逐条复核；动态、点赞、评论、直接回复及两类分页均与当前实现一致 |
|
||
| 行政区划 | 4 | 已逐条复核；当前 PC 目录下实际路径均为 `/genealogy/region/*`，与 `ApiClient` 一致 |
|
||
| 字辈谱 | 6 | 已逐条复核；正常查询、维护、新增、批量预览/保存和修改/停用/恢复均与当前实现一致 |
|
||
| 世系人物 | 12 | 已逐条复核；人物列表/分页/选项/树、CRUD/停用和四种新增关系均与当前实现一致 |
|
||
| 内容文章 | 1 | 已核验；仅删除，页面继续关闭危险入口 |
|
||
| 相册 | 2 | 已核验；仅删除，页面继续关闭危险入口 |
|
||
| 视频 | 1 | 已核验；仅删除，页面继续关闭危险入口 |
|
||
| 贺礼邀约 | 4 | 已逐条核验并映射；缺少活动列表/创建/详情，页面保持预览 |
|
||
| 祭祀 | 2 | 已核验；仅删除活动/祭品，页面继续关闭危险入口 |
|
||
| 族务记录 | 16 | 已逐条复核；成长记录、亲友往来、备忘录各 5 条与功德删除 1 条均保持当前契约 |
|
||
| 消息通知 | 4 | 已逐条核验并映射；消息页已接入原始列表、未读数和全部已读 |
|
||
| 合计 | 85 | 以桌面版 PC 目录为准 |
|
||
|
||
### 历史 79 条施工清单（2026-07-24，已被当前目录基线替代）
|
||
|
||
| 分组 | 条数 | 状态 |
|
||
| --- | ---: | --- |
|
||
| 验证中心 | 4 | 已核验、已接入 |
|
||
| 认证登录 | 11 | 已核验、已接入 |
|
||
| 文件上传 | 6 | 已核验；仅单文件上传页面闭环开放 |
|
||
| 行政区划 | 4 | 已核验、已接入 |
|
||
| 家族圈 | 14 | 已核验、已接入 |
|
||
| 字辈谱 | 6 | 已核验、已接入 |
|
||
| 世系人物 | 12 | 已核验、已接入 |
|
||
| 族务记录·成长记录 | 5 | 已核验、`ApiClient` 已映射；页面开放列表与新增 |
|
||
| 族务记录·亲友往来 | 5 | 已核验、`ApiClient` 已映射；页面开放列表与新增 |
|
||
| 族务记录·备忘录 | 5 | 已核验、`ApiClient` 已映射；页面开放列表与新增 |
|
||
| 族务记录·功德记录 | 1 | 已核验、`ApiClient` 已映射；缺少真实列表/详情，页面不开放删除 |
|
||
| 内容文章 | 1 | 已核验、`ApiClient` 已映射；缺少真实列表/详情，页面不开放删除 |
|
||
| 相册 | 2 | 已核验、`ApiClient` 已映射；缺少真实列表/详情，页面不开放删除 |
|
||
| 视频 | 1 | 已核验、`ApiClient` 已映射；缺少真实列表/详情，页面不开放删除 |
|
||
| 祭祀 | 2 | 已核验、`ApiClient` 已映射；缺少真实列表/详情，页面不开放删除 |
|
||
| 合计 | 79 | |
|
||
|
||
完整映射见 [PC接口对接规划.md](PC接口对接规划.md)。
|
||
|
||
### 已核验关键规则
|
||
|
||
- 验证中心现为三条 PC 接口：`GET /genealogy/pc/auth/verification/{operationCode}/require`、`POST .../{operationCode}/challenge`、`POST .../{operationCode}/verify`。`operationCode` 仅允许 `password-login`、`sms-login`、`register`、`forgot-password`、`phone-change`、`account-deactivate`；前端不得提交旧 `sceneCode`。
|
||
- `require` 的 query 为必填 `tenantId` 和可选 `subject`；challenge 的 body 为必填 `tenantId`、`subject`；verify 的 body 在此基础上增加 `challengeId`，可附 `providerCode`、`captchaType`、`payload`。三条都由请求头传 `clientid`，不得在 query/body 传 `clientId`。
|
||
- 短信发送为 `POST /genealogy/pc/auth/sms/{operationCode}/code`，支持除 `password-login` 外的五个短信动作。body 使用 `grantType: "sms"`、`tenantId`、`phone` 和策略开启时的 `validToken`；`clientid` 只走请求头。
|
||
- 当前认证登录的上述已核验接口一律要求 `clientid` 请求头，且 body 明确禁止 `clientId`。注册/密码登录/找回密码的 body 为 `grantType: "password"`、`tenantId` 加业务字段；密码登录在验证中心策略要求时还提交本次验证取得的 `validToken`；短信登录为 `grantType: "sms"`、`tenantId`、`phone`、`smsCode`；换绑为 `phone`、`smsCode`；注销为 `smsCode`。
|
||
- 族务记录当前 16 条由成长记录、亲友往来、备忘录三套完整 CRUD（各 5 条）和 `DELETE .../merit-records/{meritId}` 组成。三套 CRUD 都要求 `genealogyId`，详情/修改/删除还要求各自记录 ID；列表元素与新增/详情响应 DTO 仍未展开，页面只展示原始记录并保持无稳定 ID 的编辑、详情、删除入口关闭。
|
||
- 行政区划四条当前路径为 `GET /genealogy/region/children`（可选 `parentCode`）、`GET /genealogy/region/path/{regionCode}`、`GET /genealogy/region/search`（必填 `keyword`，可选 `level`、`limit`）、`GET /genealogy/region/{regionCode}`；均已与 `ApiClient` 核对一致。
|
||
- 字辈谱 6 条当前路径分别为 `GET .../generation-poems`、`GET .../generation-poems/management`、`POST .../generation-poems`、`POST .../generation-poems/batch/preview`、`POST .../generation-poems/batch/save`、`PUT .../generation-poems/{poemId}`；实现仍只使用其明确 DTO 字段。
|
||
- 世系人物 12 条当前包含 `persons` 列表/新增、`persons/page`、`persons/options`、`tree`、人物详情/修改/停用，以及 `children`、`parents`、`siblings`、`spouses` 四种以完整 `LineagePersonBody` 新建关系人物的接口；`genealogyId` 和 `personId` 均保持真实入口传入。
|
||
- 内容文章、相册、视频和祭祀当前 6 条均为删除孤岛：`DELETE .../articles/{articleId}`、`.../albums/{albumId}`、`.../albums/{albumId}/photos/{photoId}`、`.../videos/{videoId}`、`.../ceremonies/{ceremonyId}`、`.../ceremonies/{ceremonyId}/gifts/{giftId}`。它们已映射但无当前 PC 列表/详情来源，不能开放页面删除。
|
||
- 文件上传现仅有 `POST /genealogy/pc/files/resumable/init`、`POST .../chunk`、`POST .../complete`。所有文件统一先初始化；普通小文件可按初始化响应的 `instant=true` 直接取 OSS 信息，但该响应的字段 Schema 尚未展开，页面不得猜测 `uploadId`、`ossId` 或 `instant`，头像上传继续阻止。
|
||
- 家谱当前只提供 `GET /genealogy/pc/genealogies/quota`，返回创建/加入的已用数量、上限、剩余额度以及 `canCreate`/`canJoin`。它不返回家谱对象或 `genealogyId`；只映射为 `genealogyQuota`，不据此开放家谱业务页面。
|
||
- 贺礼邀约四条为替换受邀人、查询活动邀请名单、当前用户接受/拒绝、查询我的邀请。受邀人 body 只允许 `inviteeUserIds`，当前用户响应 body 只允许 `inviteStatus: ACCEPTED|DECLINED`。缺少活动列表/创建/详情，`profile-gift*.html` 继续为明确的待开发预览。
|
||
- 消息通知为列表（可选 `readStatus: 0|1`）、未读数量、单条已读和全部已读。列表元素 DTO 未展开，`profile-messages.html` 只安全展示服务端原始记录，不猜测标题、内容、时间或单条 `notificationId`；未读数和全部已读已开放。
|
||
- 认证相关均使用 PC 路径；密码为 32 位 MD5。改绑/注销只使用 PC DTO 所需字段，不擅自加 `tenantId`。
|
||
- 家族圈 14 条当前路径为动态列表/分页/详情/增改删、点赞/取消点赞、一级评论列表/分页/发表/删除和直接回复列表/分页；均要求真实 `genealogyId`，现有 `ApiClient` 与页面调用已逐项比对一致。新评论只提交必填 `commentContent` 和可选 `parentCommentId`，不能发旧字段 `content`、`replyUserId`。
|
||
- 字辈管理列表使用 `GET .../generation-poems/management`；批量操作使用 `poemText` 和可选 `disableMissing`。单项最多 50 字符、一次最多 500 代、总长最多 26000。
|
||
- 世系分页 query：`pageNum`、`pageSize`、`keyword`、`generation`、`personStatus`；`keyword` 只查姓名、别名、人物编号。
|
||
- 世系写入字段是 `name`、`generation`、`biography`，不是旧字段 `personName`、`generationNo`、`introduction`；`sortOrder`、`relationName` 是可选字段。
|
||
- `DELETE .../lineage/persons/{personId}` 是逻辑停用，不是物理删除；有正常子女时后端会拒绝。
|
||
- 新增父母/配偶/兄弟姐妹/子女四个关系接口均接收完整 `LineagePersonBody` 来新建关系人物，并非绑定两个已有 ID。
|
||
- 已末次回到 Apifox 复核：世系分页 query、创建人物 body、`POST .../lineage/persons/{personId}/spouses` 和 `relationName`。
|
||
- 成长记录 5 条均为登录接口，路径固定为 `/genealogy/pc/genealogies/{genealogyId}/growth-records` 及 `/{recordId}`；`genealogyId`、`recordId` 均是必填 int64 路径参数，`clientid` 为必填请求头。
|
||
- 成长记录的 `GrowthRecordBody` 只有 `recordTitle` 必填；可选字段为 `lineagePersonId`、`recordType`、`recordContent`、`recordDate`、`remindTime`、`mediaOssIds`、`sortOrder`、`status`。`mediaOssIds` 只接受英文逗号分隔的正整数 OSS ID。
|
||
- 成长记录列表响应是未展开元素 DTO 的 `ListResult`，详情/新增/修改为未展开元素 DTO 的 `ObjectResult`，删除为 `VoidResult`。不能据此猜测 `recordId`、标题或权限字段；页面仅作原始列表展示和新增，不开放编辑、详情或删除入口。
|
||
- 亲友往来 5 条均为登录接口，路径固定为 `/genealogy/pc/genealogies/{genealogyId}/relative-records` 及 `/{relativeId}`；`RelativeRecordBody` 只有 `relativeName` 必填，可选 `relationName`、`eventName`、`eventTime`、`giftAmount`、`recordContent`、`mediaOssIds`、`sortOrder`、`status`。列表/详情元素 DTO 同样未展开，页面不开放编辑、详情或删除入口。
|
||
- 备忘录 5 条均为登录接口，路径固定为 `/genealogy/pc/genealogies/{genealogyId}/memos` 及 `/{memoId}`；`genealogyId`、`memoId` 均是必填 int64 路径参数，`clientid` 为必填请求头。备忘录请求体只有 `memoTitle` 必填，可选 `memoContent`、`remindTime`、`completed`、`mediaOssIds`、`sortOrder`、`status`；`completed` 在 Apifox 中是 string，不能擅自改成布尔值。列表/详情元素 DTO 未展开，页面仅作原始列表展示和新增。
|
||
- 功德记录在 PC 目录中当前只存在 `DELETE /genealogy/pc/genealogies/{genealogyId}/merit-records/{meritId}`；两个路径参数均为必填 int64，登录和 `clientid` 必填，响应为 `VoidResult`。`deleteMeritRecord` 已映射，但页面没有真实列表、详情或稳定 `meritId` 来源，必须保持删除入口关闭。
|
||
- 其余 6 个删除孤岛接口也已核验并映射：`deleteArticle`、`deleteAlbum`、`deleteAlbumPhoto`、`deleteVideo`、`deleteCeremony`、`deleteCeremonyGift`。它们都要求登录、`clientid` 和 int64 路径 ID，响应均为 `VoidResult`；相册、视频与祭祀删除会由后端释放相应文件引用。由于没有 PC 列表/详情和稳定 ID 来源，所有相关页面继续保持预览，不能触发删除。
|
||
|
||
## 三、已经落地的页面
|
||
|
||
### 账号与资料
|
||
|
||
- `login.html`：密码登录、短信登录。
|
||
- `register.html`：短信注册。
|
||
- `forgot-password.html`：短信重置密码。
|
||
- `profile-security.html`：改密码、改绑手机、注销账号。
|
||
- `profile-data.html` / `profile.html`：资料读取保存、行政区划；头像上传等待当前 PC 分片初始化响应 Schema 补齐。
|
||
|
||
### 家谱业务
|
||
|
||
- `profile-feed.html` / `profile-feed-edit.html`：家族圈列表、详情、发布/修改、点赞、评论、回复。
|
||
- `profile-generation.html` + `public/js/generation-pages.js`：字辈管理列表、新增、编辑、停用/恢复、批量预览/保存。所有写操作有防重复提交锁；批量示例要求用空格或支持的标点分隔。
|
||
- `profile-tree.html` + `public/js/lineage-pages.js`：成员总览、世系树、分页搜索/翻页、下拉选择、详情、新增/编辑、逻辑停用、父母/配偶/兄弟姐妹/子女新增。所有写操作有防重复提交锁；响应 int64 ID 只以安全字符串用于后续请求。
|
||
- `profile-growth.html` / `profile-growth-edit.html` + `public/js/growth-pages.js`：成长记录列表和新增；写入仅使用 `GrowthRecordBody`，并有防重复提交锁。列表/详情元素 DTO 尚未展开，编辑、详情和删除保持关闭。
|
||
- `profile-relative.html` / `profile-relative-edit.html` + `public/js/relative-pages.js`：亲友往来列表和新增；写入仅使用 `RelativeRecordBody`，并有防重复提交锁。列表/详情元素 DTO 尚未展开，编辑、详情和删除保持关闭。
|
||
- `profile-memo.html` / `profile-memo-edit.html` + `public/js/memo-pages.js`：备忘录列表和新增；写入仅使用已核验的备忘录请求体字段，并有防重复提交锁。列表/详情元素 DTO 尚未展开，编辑、详情和删除保持关闭。
|
||
|
||
### 关键代码文件
|
||
|
||
| 文件 | 责任 |
|
||
| --- | --- |
|
||
| `utils/ApiClient.js` | 已核验 PC 路径、请求头、DTO |
|
||
| `public/js/profile-common.js` | `genealogyId` 读取和链接传播的唯一 owner |
|
||
| `public/js/genealogy-entry-pages.js` | 无真实家谱上下文时的统一入口页；仅查询 PC 配额并阻止业务跳转 |
|
||
| `public/js/auth-pages.js`、`captcha-pages.js`、`security-pages.js` | 登录、注册、验证码、账号安全 |
|
||
| `public/js/profile-pages.js`、`region-pages.js`、`upload-pages.js` | 资料、区划、头像 |
|
||
| `public/js/feed-pages.js` | 家族圈 |
|
||
| `public/js/generation-pages.js` | 字辈谱 |
|
||
| `public/js/lineage-pages.js` | 世系人物 |
|
||
| `public/js/growth-pages.js` | 成长记录 |
|
||
| `public/js/relative-pages.js` | 亲友往来 |
|
||
| `public/js/memo-pages.js` | 备忘录 |
|
||
|
||
## 四、当前阻塞和未完成范围
|
||
|
||
### PC 家谱入口缺失
|
||
|
||
PC 目录没有“我的家谱、家谱详情、创建/加入/选择家谱”接口。前端无法自行得到真实 `genealogyId`，因此当前正确行为是：个人中心和内容入口先统一进入 `profile-families.html`，该页只读取 `genealogyQuota()` 并明确说明当前不能选择家谱；缺少 ID 时阻止业务请求。静态家谱卡片已移除，不要伪造编号，也不要用 APP 补这个缺口。
|
||
|
||
### 已核验但仍缺业务闭环的页面范围
|
||
|
||
| 分组 | 已核验条数 | 当前原则 |
|
||
| --- | ---: | --- |
|
||
| 内容文章 | 1 | 仅删除；没有真实列表/详情来源时不开放删除 |
|
||
| 相册 | 2 | 仅删除；不猜 DTO 或文件引用来源 |
|
||
| 视频 | 1 | 仅删除；不猜 DTO 或文件引用来源 |
|
||
| 祭祀 | 2 | 仅删除；不猜实体和献礼字段 |
|
||
| 功德记录 | 1 | 仅删除；不猜实体和 `meritId` 来源 |
|
||
|
||
## 五、通用行为和安全约束
|
||
|
||
- `ApiClient` 统一加 `clientid`；登录后统一加 `Authorization: Bearer <token>`。
|
||
- 401 清 token 跳转 `login.html`；403 保留登录态并展示无权限状态。
|
||
- 浏览器中的 int64 ID 均按字符串保存，避免精度丢失。
|
||
- 当前接口没有定义的删除、解绑、关系解除和业务文件引用值，保持禁用/待开发，不能猜测实现。
|
||
- 这是脏工作树；不要使用 `git reset --hard`、`git checkout --`，也不要删除未跟踪文件。
|
||
|
||
## 六、验证结果
|
||
|
||
本轮已直接完成当前 PC 目录 85/85 条的详情复核，并逐项比对 `ApiClient`、对应页面和契约测试；历史 79 条记录不作为本轮验收依据。完整测试结果以本轮末次运行记录为准。
|
||
|
||
已运行的检查包括：
|
||
|
||
- `node --check utils/ApiClient.js`
|
||
- `node --check public/js/profile-common.js`
|
||
- `node --check public/js/genealogy-entry-pages.js`
|
||
- `node --check public/js/generation-pages.js`
|
||
- `node --check public/js/lineage-pages.js`
|
||
- `node --check public/js/growth-pages.js`
|
||
- `node --check public/js/memo-pages.js`
|
||
- `node --check public/js/captcha-pages.js`
|
||
- `node --check public/js/auth-pages.js`
|
||
- `node --check public/js/security-pages.js`
|
||
- `node --test tests/api-client-contract.test.js tests/captcha-pages-contract.test.js tests/auth-pages.test.js tests/security-upload-scope.test.js tests/profile-pages.test.js`
|
||
- `node --test tests/auth-pages.test.js tests/api-client-contract.test.js tests/profile-pages.test.js tests/security-upload-scope.test.js tests/feed-pages.test.js tests/generation-pages.test.js tests/lineage-pages.test.js tests/growth-pages.test.js tests/relative-pages.test.js tests/memo-pages.test.js tests/pending-pages.test.js tests/pc-scope.test.js`
|
||
- `npm.cmd test`（91/91 通过）
|
||
- `git diff --check`
|
||
|
||
本地运行态检查已使用 Chrome DevTools 逐页打开 `profile-feed*`、成长记录、亲友往来、备忘录、消息、资料、字辈和世系页面：12 个静态页面均返回 200；无登录态时需鉴权的页面转到登录且没有发送业务请求，三类族务编辑页缺少真实 `genealogyId` 时保持阻止且不发请求。已使用测试账号完成密码登录的真实滑块验证与登录；资料页实际修改昵称后已恢复原值，页面两次均显示保存成功；消息页实际完成列表和未读数读取，服务端返回空列表。个人中心到家谱入口页的真实点击已验证，入口页仅调用配额接口且在缺少真实 `genealogyId` 时不进入家族业务。当前仍没有 PC 家谱列表/详情返回的真实家谱上下文，因此未对需 `genealogyId` 的写接口发送提交。
|
||
|
||
当前完整测试集已运行并通过。
|
||
|
||
## 七、下一位 GPT 的执行顺序
|
||
|
||
1. 读本文和 `docs/PC接口对接规划.md`。
|
||
2. 先检查桌面版 Apifox PC 目录是否新增或变更；只逐条复核受影响接口，不要借用 APP 接口或猜 DTO。
|
||
3. 每次只处理一个完整小分组：Apifox 核验 → `ApiClient` → 对应页面 → 聚焦测试；家谱配额接口不是入口，继续不写死 `genealogyId`。
|
||
4. 只有删除能力、没有真实列表/详情来源的模块，不开放危险操作，只登记后端缺口。
|
||
5. 每完成一组，更新本文、`PC接口对接规划.md` 和相关测试，并报告改动、验证和剩余阻塞。
|