jiapu/docs/交接文档.md

PC 接口对接交接文档

更新：2026-07-24
状态：已完成已核验 PC 接口的首轮页面施工；其余 PC 目录尚未核验、尚未接入。

一、必须遵守的范围

1. Apifox 的 PC 目录是唯一正式契约源。
2. 本地 OpenAPI 导出文件可能少接口，只能辅助查找，不能据此决定接口存在、路径或字段。
3. 不使用 APP 接口，也不能把 /app/ 改为 /pc/ 后猜测使用。
4. 继续任何新接口前，必须直接在 Apifox PC 详情核对 method、path、query、body、响应和权限。
5. 家谱业务只能使用真实 ?genealogyId=...；不写死编号、不从 APP 获取。
6. 页面不直接调用 Axios、不自行拼请求路径，统一通过 utils/ApiClient.js。

二、已直接在 Apifox PC 核验并施工的接口

分组	条数	状态
验证中心	4	已核验、已接入
认证登录	11	已核验、已接入
文件上传	6	已核验；仅单文件上传页面闭环开放
行政区划	4	已核验、已接入
家族圈	14	已核验、已接入
字辈谱	6	已核验、已接入
世系人物	12	已核验、已接入
合计	57

完整映射见 PC接口对接规划.md。

已核验关键规则

• 短信接口为 POST /genealogy/pc/auth/sms/code；场景只允许 PC_SMS_LOGIN、PC_REGISTER、PC_FORGOT_PASSWORD、PC_PHONE_CHANGE、PC_ACCOUNT_DEACTIVATE。validToken 来自 /captcha/*，只能单次消费。
• 认证相关均使用 PC 路径；密码为 32 位 MD5。改绑/注销只使用 PC DTO 所需字段，不擅自加 tenantId。
• 单文件上传为 POST /genealogy/pc/files/upload，multipart 仅提交 file；返回 ossId、url、thumbnailUrl、fileName、originalName。
• 家族圈新评论只提交 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。

三、已经落地的页面

账号与资料

• login.html：密码登录、短信登录。
• register.html：短信注册。
• forgot-password.html：短信重置密码。
• profile-security.html：改密码、改绑手机、注销账号。
• profile-data.html / profile.html：资料读取保存、头像单文件上传、行政区划。

家谱业务

• 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 只以安全字符串用于后续请求。

关键代码文件

文件	责任
utils/ApiClient.js	已核验 PC 路径、请求头、DTO
public/js/profile-common.js	genealogyId 读取和链接传播的唯一 owner
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	世系人物

四、当前阻塞和未完成范围

PC 家谱入口缺失

PC 目录没有“我的家谱、家谱详情、创建/加入/选择家谱”接口。前端无法自行得到真实 genealogyId，因此当前正确行为是：缺少 ID 时提示用户从具体家谱进入并且不发请求。不要伪造编号，也不要用 APP 补这个缺口。

尚未核验、尚未施工的 22 条 PC 接口

分组	条数	当前原则
内容文章	1	目前只见删除能力；没有真实列表/详情来源时不开放删除
相册	2	目前只见删除能力；不猜 DTO
视频	1	目前只见删除能力；不猜 DTO
祭祀	2	目前只见删除能力；不猜实体和献礼字段
族务记录	16	尚未逐条核验；先在 Apifox 看完再映射成长记录、亲友往来、备忘录等页面
合计	22

五、通用行为和安全约束

• ApiClient 统一加 clientid；登录后统一加 Authorization: Bearer <token>。
• 401 清 token 跳转 login.html；403 保留登录态并展示无权限状态。
• 浏览器中的 int64 ID 均按字符串保存，避免精度丢失。
• 当前接口没有定义的删除、解绑、关系解除和业务文件引用值，保持禁用/待开发，不能猜测实现。
• 这是脏工作树；不要使用 git reset --hard、git checkout --，也不要删除未跟踪文件。

六、验证结果

最近一次聚焦验证已通过：52/52 测试通过，git diff --check 通过。

已运行的检查包括：

• node --check utils/ApiClient.js
• node --check public/js/profile-common.js
• node --check public/js/generation-pages.js
• node --check public/js/lineage-pages.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/pending-pages.test.js tests/pc-scope.test.js
• git diff --check

本轮未运行无关的完整历史测试集。

七、下一位 GPT 的执行顺序

1. 读本文和 docs/PC接口对接规划.md。
2. 打开 Apifox，只看 PC 目录，从“族务记录”16 条开始逐条核验。
3. 每次只处理一个完整小分组：Apifox 核验 → ApiClient → 对应页面 → 聚焦测试。
4. 只有删除能力、没有真实列表/详情来源的模块，不开放危险操作，只登记后端缺口。
5. 每完成一组，更新本文、PC接口对接规划.md 和相关测试，并报告改动、验证和剩余阻塞。