rain/jiapu

Files

T

2026-07-24 18:11:32 +08:00

32 KiB

Raw Blame History

PC 接口对接规划（Apifox 79 接口版）

状态：当前范围已确认
日期：2026-07-24
当前阶段：已直接在 Apifox 核验验证码中心、认证登录、文件上传、行政区划、家族圈、字辈谱和世系人物共 57 条接口；施工只以这些 PC 详情为准，其余目录继续逐组核验后再接入。交接入口：交接文档.md

1. 已确认的基线

Apifox 的 PC 目录是 PC 前端接口的唯一正式契约源。

当前 Apifox PC 共 79 个操作：

分组	数量
认证登录	11
验证中心	4
文件上传	6
行政区划	4
家族圈	14
字辈谱	6
世系人物	12
内容文章	1
相册	2
视频	1
祭祀	2
族务记录	16
合计	79

仓库中的旧 OpenAPI 文件不再作为新增功能依据。Apifox 客户端中实时的 PC 目录是最终验收源；导出文件最多作为本地自动测试快照，不能替代在 Apifox 中逐项核对。
APP 接口不允许在 PC 页面中直接复用。PC 缺少的能力应先补入 Apifox 的 PC 目录，再开发页面。
当前不根据 APP 或后端公开 OpenAPI 扩大范围；没有进入 Apifox PC 目录的接口，不视为 PC 已确认接口。
后端以后新增 PC 接口时，再按新增后的 Apifox PC 契约启动下一轮规划。

2. 当前最重要的结论

现有 79 个接口不能覆盖整个 PC 管理端闭环，主要问题不是前端页面，而是接口目录不完整：

没有“我的家谱、家谱详情、创建/加入家谱、家谱成员”接口，PC 无法自行取得真实 genealogyId。
内容文章只有删除接口。
相册只有删除相册、删除照片接口。
视频只有删除接口。
祭祀只有删除祭祀、删除献礼接口。
功德记录只有删除接口。
世系关系只有新增父母、配偶、兄弟姐妹、子女，没有解除关系接口。
字辈谱没有删除接口。

因此对接分成三类：

**当前可以形成可用流程：**认证、验证、文件上传、区划、家族圈、字辈谱、世系人物、成长记录、亲友往来、备忘录；其中家谱内接口必须先由 PC 运行入口提供真实 genealogyId。
**当前只做契约映射、不开放页面操作：**文章、相册、视频、祭祀和功德录目前只有删除接口，不能在没有真实列表和详情数据时单独启用删除。
**后端补充 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：

当前 79 个接口没有“我的家谱”入口，本轮不从 APP 获取 genealogyId。
当前家谱业务页面只接受 PC 运行入口通过 URL 传入的真实 genealogyId。
profile-common.js 作为 PC 页面家谱上下文的唯一 owner，负责读取、校验和传播 genealogyId。
ApiClient 负责把 genealogyId 放入路径。
页面缺少 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 响应与分页

普通响应统一为：

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

分页响应统一为：

{
  "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 文件生命周期

图片、小文件：

单文件上传。
获得 ossId。
保存业务对象。
绑定文件业务引用。

视频、大文件：

初始化分片任务。
上传所有分片。
服务端合并。
保存业务对象。
绑定文件业务引用。

替换或删除业务对象后解除旧文件引用。上传成功但业务保存失败时，也要提供清理策略。

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）

现有接口：

DELETE /genealogy/pc/genealogies/{genealogyId}/articles/{articleId}

使用位置：profile-article.html 的删除操作。

当前不能启用真实文章管理，因为缺少：

文章列表/分页
文章详情
新增文章
修改文章
文章分类
发布、下线和公开可见性
官网公开文章详情

规划：接口补齐前，profile-article.html、profile-article-edit.html 和 article-detail.html 保持设计预览，不单独接入删除接口。

4.9 相册（2）

现有接口：

DELETE /genealogy/pc/genealogies/{genealogyId}/albums/{albumId}
DELETE /genealogy/pc/genealogies/{genealogyId}/albums/{albumId}/photos/{photoId}

使用位置：profile-album.html 的删除相册、删除照片操作。

当前缺少相册列表、详情、新增、修改，以及照片列表、新增、修改和文件引用。接口补齐前不启用删除按钮。

4.10 视频（1）

现有接口：

DELETE /genealogy/pc/genealogies/{genealogyId}/videos/{videoId}

使用位置：profile-video.html 的删除操作。

当前缺少视频列表、详情、新增、修改、发布状态、公开播放详情以及文件引用。本轮只映射删除契约；后端补齐 PC 读写接口后，再结合分片上传实施完整视频流程。

4.11 祭祀/典礼（2）

现有接口：

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）

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）

GET    .../relative-records
POST   .../relative-records
GET    .../relative-records/{relativeId}
PUT    .../relative-records/{relativeId}
DELETE .../relative-records/{relativeId}

当前没有独立页面。现有 profile-memo.html 同时写了“人情往来”和“备忘提醒”，会导致两个资源边界混乱。

规划：将“人亲簿/亲友往来”和“备忘录”拆成两个 Tab 或两组页面：

亲友往来：亲友、关系、事项、时间、礼金、说明。
备忘录：待办、提醒时间、完成状态、附件。

备忘录（5）

GET    .../memos
POST   .../memos
GET    .../memos/{memoId}
PUT    .../memos/{memoId}
DELETE .../memos/{memoId}

使用页面：profile-memo.html、profile-memo-edit.html。

用途：家族事务、纪念事项、待办提醒和完成状态。

功德记录（1）

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：已接模块回归与补齐

范围：

认证登录 11 个。
验证中心 4 个。
行政区划 4 个。
文件上传 6 个。
家族圈 14 个。

执行重点：

先核对现有 ApiClient 与当前 PC 契约，保留已正确对接的部分。
补齐文件分片、文件引用，以及家族圈评论回复列表和分页等当前 PC 已有但页面尚未完整使用的能力。
统一 401、403、业务错误、空状态和重复提交处理。

当前施工进度：

已完成认证、验证码与账号安全流程，包含登录、短信登录、注册、找回密码、换绑、注销和退出。
已完成个人资料读取与保存、头像单文件上传回填、行政区划三级联动/搜索/回显；资料和区划请求统一携带登录态，ossId 在浏览器端保持字符串。
已完成文件分片初始化、分片、完成、绑定和解绑的客户端契约映射；待后端补齐初始化响应和各业务引用值后，再开通页面上传闭环。
已完成家族圈回复、字辈谱和世系人物的 Apifox 核验与首轮页面施工；下一步直接核验族务记录的完整路径、DTO 与响应字段，再决定成长记录、亲友往来、备忘录页面能否开放。

验收：

登录、验证码、区划和上传流程只请求当前 PC 路径。
家族圈列表、详情、点赞、评论和回复使用同一套 DTO 与计数字段。
文件上传完成后按业务保存结果创建引用，删除业务数据时按后端规则解除引用。

阶段 2：家谱内完整资源

范围与顺序：

字辈谱 6 个。
世系人物 12 个。
成长记录 5 个。
亲友往来 5 个。
备忘录 5 个。

执行前提：

页面必须从 PC 的真实入口参数或运行时上下文取得 genealogyId。
当前 PC 尚无家谱入口接口；没有真实 genealogyId 时只展示缺少上下文状态，不发请求、不写死 ID，也不调用 APP。
只实现当前接口支持的操作；世系关系解除、字辈删除等缺口等待后端补充 PC 接口。

验收：

所有请求均携带同一个真实 genealogyId，切换上下文后不串数据。
列表、新增、详情、修改和删除严格按当前各资源的实际接口能力开放。
世系树、人物详情和记录关联统一使用当前 PC 世系人物 DTO。
无权限用户看不到写入口，后端 403 能正确呈现。

阶段 3：当前只有删除能力的模块

范围：

内容文章 1 个。
相册与照片 2 个。
视频 1 个。
祭祀/典礼与献礼 2 个。
功德记录 1 个。

处理方式：

先完成删除接口的 ApiClient 契约映射和接口测试。
因当前 PC 缺少列表、详情、新增或修改接口，页面继续保持预览状态，不开放孤立的删除按钮。
后端补齐同模块 PC 接口后，再按完整资源流程启用页面。

验收：

7 个删除操作的 method、path、路径参数和权限定义均与 Apifox PC 一致。
当前页面不会因静态演示数据触发真实删除。
未补齐的能力不会通过 APP 接口、猜测路径或模拟成功结果实现。

阶段 4：接收后端新增 PC 接口

本阶段不属于当前 79 个接口的对接范围。后端每次新增 PC 接口后：

先确认接口已正式进入 Apifox PC 目录。
更新基线数量、第 4 节用途映射和第 5 节缺口。
再安排相应页面、ApiClient 方法、契约测试和联调。
不因为 APP 已存在同类能力而提前实现。

7. 联调与测试要求

每个接口组按相同顺序验收：

直接在 Apifox PC 目录确认 method、path、DTO、枚举和权限。
给 ApiClient 增加业务方法。
增加契约测试，验证 method、path、query 和 body。
接页面加载、空状态、错误状态和成功状态。
验证 401、403、404、业务校验失败和重复提交。
验证写入后重新读取的数据与页面一致。
删除操作验证关联数据和文件引用处理。

禁止以下做法：

页面直接写 Axios 请求。
猜测字段名或同时兼容多个字段。
使用 APP 路径补 PC 缺口。
写死 genealogyId。
把静态示例数据当成接口成功结果。
只有删除接口时先开放删除按钮。

8. 后续业务待确认项（不阻塞当前 79）

以下问题只影响后端后续新增 PC 接口，不改变本轮范围：

“祭祀”究竟只指祖先祭祀，还是通用典礼/贺礼。
亲友往来是否从现有备忘录页面拆成独立 Tab，建议拆分。
字辈是否允许物理删除；建议优先停用。
删除世系人物是否允许级联删除关系；建议默认禁止并由接口返回影响范围。
feedback 只用于意见反馈，还是要承担客服工单；若需要状态、回复和详情，应建立独立 Ticket 契约。
资料提醒是否只是通知的一种类型；若是，NotificationDTO 应提供稳定的通知类型和目标深链。

32 KiB Raw Blame History Unescape Escape

PC 接口对接规划（Apifox 79 接口版）

1. 已确认的基线

2. 当前最重要的结论

2.1 当前范围规则

3. 公共契约规则

3.1 接口所有权

3.2 家谱上下文

3.3 请求头与登录状态

3.4 响应与分页

3.5 ID、日期和枚举

3.6 权限

3.7 文件生命周期

4. 79 个接口的页面用途

4.1 认证登录（11）

4.2 验证中心（4）

4.3 文件上传（6）

4.4 行政区划（4）

4.5 家族圈（14）

4.6 字辈谱（6）

4.7 世系人物（12）

4.8 内容文章（1）

4.9 相册（2）

4.10 视频（1）

4.11 祭祀/典礼（2）

4.12 族务记录（16）

成长记录（5）

亲友往来（5）

备忘录（5）

功德记录（1）

5. 后端后续补充清单（当前不对接）

后续优先级 1：家谱上下文与成员

后续优先级 2：当前只有删除操作的模块

后续优先级 3：已有主体但缺少的操作

6. 页面与接口实施顺序

阶段 0：锁定当前 PC 契约

阶段 1：已接模块回归与补齐

阶段 2：家谱内完整资源

阶段 3：当前只有删除能力的模块

阶段 4：接收后端新增 PC 接口

7. 联调与测试要求

8. 后续业务待确认项（不阻塞当前 79）

32 KiB

Raw Blame History