jiapu/docs/交接文档.md

PC 接口对接交接文档

更新：2026-07-25 历史交接记录：本文的 79/85 条接口数量已过期，不再作为 AI 施工依据。当前接口基线、字段分类、阻断项和执行顺序统一以 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 接口：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 和相关测试，并报告改动、验证和剩余阻塞。