85 lines
7.9 KiB
Markdown
85 lines
7.9 KiB
Markdown
# APP 136 接口功能归属与重复关系
|
||
|
||
> 历史快照（2026-07-26，136 条 operation），不再作为当前实施依据。当前根目录导出与桌面 Apifox 均为 149 条 operation，请使用 [APP-149接口页面归属与表单字段审计-2026-07-27.md](APP-149接口页面归属与表单字段审计-2026-07-27.md)。
|
||
|
||
更新时间：2026-07-26
|
||
|
||
## 结论
|
||
|
||
Apifox 当前目录共 136 条：128 条 APP 接口、4 条 APP/PC 共用行政区划接口、4 条旧系统兼容验证接口。
|
||
|
||
“136 条”不等于 136 个独立页面功能。真正功能重复的只有旧兼容验证/发码链路；列表、分页、详情、选项、管理态接口是同一资源在不同交互下的不同合同，不能擅自删掉或混用。
|
||
|
||
字段、必填、枚举、请求/响应 DTO 以桌面 Apifox 为准。根目录 `家谱.openapi.json` 只用于核对目录数量和路径，不用其缺失字段推断前端 DTO。
|
||
|
||
## 一、唯一入口与功能重复
|
||
|
||
| 分类 | 接口 | 当前唯一使用策略 | 结论 |
|
||
| --- | --- | --- | --- |
|
||
| APP 人机验证 | `GET /genealogy/app/auth/verification/{operationCode}/require`、`POST .../challenge`、`POST .../verify` | A01 密码/短信登录、A04 注册、A05 找回密码，通过 `TacVerification` 与 `utils/auth-verification.js` | 当前 APP 唯一验证链路 |
|
||
| 旧验证码兼容 | `GET /captcha/require`、`POST /captcha/challenge`、`POST /captcha/verify`、`GET /auth/code` | 当前 APP 不调用 | 与 APP 人机验证功能重叠，保留 API 目录记录但不能再接回 A01/A04/A05，避免重复验证 |
|
||
| APP 场景发码 | `POST /genealogy/app/auth/sms/{operationCode}/code` | A01/A04/A05；`operationCode` 是 `password-login`、`sms-login`、`register`、`forgot-password` | 当前 APP 唯一发码链路 |
|
||
| 旧短信发码兼容 | `POST /genealogy/app/auth/sms/code` | 仅 `appApi.sendLegacySmsCode` API 层 owner；没有页面入口 | 与上项发码功能重叠。保留兼容方法供后端指定旧调用方，不得在现有认证页重复发短信 |
|
||
| 行政区划（共享） | `GET /genealogy/region/children`、`/path/{regionCode}`、`/search`、`/{regionCode}` | APP 与 PC 共用；当前 G03/G11 使用 children | 不是旧接口、不是重复接口。其余三条在对应 UI 出现“回填路径/搜索/单项校验”交互后接入 |
|
||
|
||
## 二、136 条按功能模块归属
|
||
|
||
| Apifox 模块 | 数量 | 应归属页面/组件 | 备注 |
|
||
| --- | ---: | --- | --- |
|
||
| 验证中心 | 7 | A01、A04、A05、`TacVerification` | 其中 4 条为旧兼容，见上表 |
|
||
| 认证登录 | 12 | A01、A04、A05、M01、M02、M04、M05、M10 | 改密、换绑、注销、退出属于敏感写操作，测试不执行 |
|
||
| 文件上传 | 6 | G03、G11、M02、F02、F06、F07、F09、R04、R07、R08、R10，通过 `resumable-image-upload.js` | 单文件、分片 init/chunk/complete、业务引用绑定/释放各自用途不同 |
|
||
| 行政区划 | 4 | G03 创建家谱、G11 家谱设置 | APP/PC 共用基础查询 |
|
||
| 家谱 | 13 | G01、G03、G05、G06、G08、G09、G10、G11 | 配额、options、详情、审核/撤销等要与具体页面按钮逐项接线，不因已有列表接口视为完成 |
|
||
| 家谱成员 | 6 | 当前没有“家谱成员（账号成员）管理”页面；不要误接到世系人物 T03–T08 | `memberId` 与 `personId` 不是同一 ID。成员管理页/候选 DTO 缺失需单列 |
|
||
| 字辈谱 | 6 | G12 | 正常列表、维护列表、批量预览、批量保存、单条新增/修改是不同操作 |
|
||
| 世系人物 | 12 | T01、T03–T08、R01、R02 | 首位成员创建后端 `code:500` 阻塞；不能伪造 personId |
|
||
| 家族圈 | 14 | F01、F02、F03 | 列表与分页、评论与评论分页、回复与回复分页均非重复；编辑/删除/点赞/回复 UI 需逐项确认 |
|
||
| 内容文章 | 9 | F04、F05、F06、M06、M08 | 谱文分类、帮助详情目前没有已确认页面入口，不能靠列表代替 |
|
||
| 相册 | 7 | F07、F08、F09 | 相册本身与相片记录是两级资源；编辑/删除动作需遵守测试禁止删除边界 |
|
||
| 祭祀 | 8 | R05、R06、R07 | 活动、献礼分别有列表和写入合同 |
|
||
| 族务记录 | 18 | R03、R04、R08、R10、R11 | 成长/备忘/亲友的详情、修改、删除需有明确详情或编辑入口；R09 人生事件没有独立资源合同 |
|
||
| 消息通知 | 4 | N01、G01 未读数 | N02 没有单条详情读取接口；标已读/全部已读不能在未授权测试中触发 |
|
||
| 意见反馈 | 2 | M07 | 列表与提交分别接线 |
|
||
| VIP | 3 | M09 | 套餐、订单列表可读取；创建订单属于支付链路，不执行 |
|
||
| 视频 | 1 | F10 | 仅有删除视频接口，缺少视频列表/详情/上传/播放合同，因此 F10 不能假装可用 |
|
||
| 贺礼邀约 | 4 | R06（活动详情）及“我的活动邀请”入口待产品页面 | 受邀人需要真实 `appUserId`；当前成员/世系 DTO 没有可确认候选来源，不能拿 `memberId` 或 `personId` 猜代 |
|
||
|
||
以上数量相加为 136。
|
||
|
||
## 三、共享行政区划的实测合同
|
||
|
||
桌面 Apifox 已核对：
|
||
|
||
| 接口 | 必填 | 可选 | 当前 API owner | 页面状态 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `GET /genealogy/region/children` | 无 | `parentCode`（不传或 `0` 为省级） | `appApi.getRegionChildren` | G03/G11 已真实读取 |
|
||
| `GET /genealogy/region/path/{regionCode}` | path `regionCode:string` | `clientid` header | `appApi.getRegionPath` | 暂无“按已存地区回填层级路径”控件 |
|
||
| `GET /genealogy/region/search` | query `keyword:string` | `level: 1..5`、`limit:integer`、`clientid` header | `appApi.searchRegions` | 暂无地区关键字搜索控件 |
|
||
| `GET /genealogy/region/{regionCode}` | path `regionCode:string` | `clientid` header | `appApi.getRegion` | 暂无单项详情校验控件 |
|
||
|
||
后三条返回 DTO 在桌面文档当前显示为通用对象/列表对象，API 层只校验 envelope 与最外层数组/对象，不擅自猜测内部字段。等页面要消费具体字段时，先在桌面 Apifox 展开响应模型并补严字段校验。
|
||
|
||
## 四、接线判定标准
|
||
|
||
一条接口只有同时满足以下三项才标记“页面完成”：
|
||
|
||
1. `utils/api.js` 有唯一方法 owner，按桌面 Apifox 的必填/可选参数组装请求；
|
||
2. 明确页面按钮、页面加载或组件行为调用该方法，且参数来源不是猜测 ID；
|
||
3. 用浏览器在测试账号和测试数据上做真实请求验证；写入再做列表或详情回读。
|
||
|
||
仅有 API 方法、或仅页面能打开、或只有导出文件字段，均不算页面完成。
|
||
|
||
## 五、2026-07-26 浏览器复测结论
|
||
|
||
- 从 A01 密码登录进入测试账号后，以真实 `genealogyId`、动态、谱文和相册标识运行 `tests/all-page-route-runtime-smoke.js`，52/52 页面均通过；认证态访问 A01 被守卫重定向到 G01 属于预期行为，测试已明确校验该分支。
|
||
- G01 的“世系图、成员、字辈诗、申请审核”四个快捷入口均通过浏览器页面点击复测，分别到达 T01、G05、G12、G10，未捕获运行时异常。
|
||
- T04 再次经页面输入首位成员姓名并提交。请求仍未获服务端确认，页面显示“保存失败 / 发生未知异常，请联系管理员”；未写入本地成员、未生成假 `personId`。该结果继续受“首位成员创建 code:500”阻塞。
|
||
- 该路由复测只验证真实读取、页面状态和既有测试数据；未执行短信、改密、换绑、退出、删除、审核或支付。
|
||
|
||
## 六、桌面 Apifox 与导出目录核对
|
||
|
||
桌面 Apifox 本地接口树（2026-07-26 16:56 更新）包含根目录 `家谱.openapi.json` 的全部 136 个 `HTTP method + path`；没有只存在于导出而桌面目录不存在的 operation。导出文件可用于路径、方法和数量的完整审计。
|
||
|
||
该核对不扩大为 DTO 字段已完整：页面要消费的 body/response 字段、必填、枚举和示例仍以桌面 Apifox 的接口详情为准。若桌面详情未声明条目 DTO 或枚举，前端继续把该字段标为阻塞，而不从导出占位结构猜测。
|