jiapuapp/docs/APP-136接口功能归属与重复关系-2026-07-26.md

APP 136 接口功能归属与重复关系

更新时间：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 或枚举，前端继续把该字段标为阻塞，而不从导出占位结构猜测。