rain
118 lines
6.9 KiB
Markdown
118 lines
6.9 KiB
Markdown
# 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](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` 和相关测试，并报告改动、验证和剩余阻塞。
|