11 KiB
11 KiB
APP 149 接口页面归属与表单字段审计
更新时间：2026-07-27
一、唯一依据与结论
- 唯一接口源：根目录
家谱.openapi.json；桌面 ApifoxAPP概览同步显示 149 条 operation、88 个数据模型。 - 这 149 条不是 149 个页面。页面、认证/上传底层流程、管理操作、兼容旧接口共同构成目录，不能因为没有对应按钮就假称“未对接”，也不能把内部 ID、验证码或支付参数渲染成普通表单。
- 当前核对结果：已存在页面和 API owner 的资源继续按现有页面操作验证；本次已修复 M02、M07、G08、R07 四个确定的字段控件/适配错误。视频发布已接入 F10；视频和官网内容的读取响应仍没有可安全消费 DTO，因此不能伪造列表或详情卡片。
- 所有真实写入验证只允许在页面中选择、输入、提交并做列表/详情回读；不使用后台请求构造数据。短信、改密、换绑、退出、删除、审核、支付、注销不做测试写操作。
二、149 条按 Apifox 模块归属
| 模块 | 条数 | 页面或唯一 owner | 当前判定 |
|---|---|---|---|
| 验证中心 | 7 | A01/A04/A05，utils/auth-verification.js |
APP 行为验证为认证流程内部参数；旧 /captcha/* 与 /auth/code 是兼容链路，无新页面入口。 |
| 认证登录 | 12 | A01/A04/A05、M01、M02、M04/M05/M10 | 登录、注册、资料读取/更新有页面；敏感账号写操作保留但不测。 |
| 文件上传 | 6 | utils/resumable-image-upload.js、各图片选择页 |
上传初始化、分片、完成、引用绑定/释放是技术流程，ossId 由回执拥有，不是手填字段。 |
| 行政区划 | 8 | G03/G11，appApi.getRegion* |
/genealogy/region/* 是 APP/PC 共享 4 条；/genealogy/app/region/* 为同能力 APP 副本，当前统一用共享 owner，不能双接线。 |
| 家谱 | 13 | G01、G03、G05–G11 | 列表、详情、公开搜索、申请、审核、配额、options 分属不同交互，不能互相替代。 |
| 家谱成员 | 6 | API owner 已有；暂无独立账号成员管理页 | memberId 不等于世系 personId；成员管理/转让/移除不映射到 T 系页面。 |
| 字辈谱 | 6 | G12 | 列表、管理、单条维护、批量预览和批量保存均保留。 |
| 世系人物 | 12 | T01、T03–T08、R01/R02 | 首位成员创建仍须以页面实测为准；未得到真实 personId 前不伪造成员或关系。 |
| 家族圈 | 14 | F01–F03 | 动态、评论、回复、点赞、分页是不同资源动作。删除不测试。 |
| 内容文章 | 9 | F04–F06、M06、M08 | 谱文已有创建/读取；分类列表条目 DTO 未声明，分类 ID 不能手输或猜字段。 |
| 相册 | 7 | F07–F09 | 相册和照片是两级资源；上传回执后写入，删除不测试。 |
| 祭祀 | 8 | R05–R07 | 活动及献礼分别由列表、详情、编辑页拥有。 |
| 族务记录 | 20 | R03/R04、R08、R10、R11 | 亲友、成长、备忘、功德是四类独立资源；人生事件没有单独写资源时不伪造。 |
| 消息通知 | 5 | N01、G01 未读数 | 读取有 owner；标读为状态写，不在本轮测试。 |
| 意见反馈 | 2 | M07 | 已修正为接口枚举 value 提交。 |
| VIP | 3 | M09 | 套餐/订单读取可用；下单属于支付链路，不测试。 |
| 视频 | 5 | F10 | 已接入上传、创建及 API owner 的 CRUD 路径；列表/详情响应未声明 DTO，页面不假造卡片字段。 |
| 贺礼邀约 | 4 | R06 及未来“我的邀请”页 | 受邀人数组必须来自业务用户候选；不能用成员/人物 ID 冒充。 |
| 官网内容 | 2 | M10 的协议/说明未来可用 | 见“阻塞”B05：响应体未声明，不能将当前静态说明误报为已接线。 |
三、表单字段的统一处理规则
| 字段类别 | 页面处理 | 传输规则 |
|---|---|---|
required 文本/多行文本 |
显示必填标识并做空值校验 | 只传去空白后的真实输入。 |
有 enum 的 string |
中文标签的单选/下拉 | 只提交 enum value，绝不提交中文标签。 |
date 或写例 yyyy-MM-dd |
日期选择器 | 提交 yyyy-MM-dd。 |
| 日期时间字符串 | 日期 + 时间选择器 | 只有用户已选择日期时组装 yyyy-MM-dd HH:mm:ss。 |
| 候选 ID | 由 options/list 返回项选择 | 不显示内部 ID 自由输入；没有候选 DTO/接口则隐藏该字段并记录阻塞。 |
*OssId、mediaOssIds |
统一上传控件 | 只使用上传回执；不允许键盘输入。 |
status、completed 等管理/字典字段 |
创建表单默认省略，除非当前页面有明确管理权限且文档给出枚举 | 不把“停用”“完成”猜成前台默认开关。 |
token、clientid、tenantId、grantType、验证码票据、分片 hash |
永不显示 | 由 session、运行时配置、验证或上传 owner 自动生成。 |
四、已有页面的重点 body 字段矩阵
| 页面/接口 | 必填字段 | 可填写字段 | 选择/自动/隐藏字段 | 当前实现结论 |
|---|---|---|---|---|
M02 PUT /auth/profile |
无 | nickName、realName、email |
sex：男 0/女 1/未知 2；birthday：日期；avatar：上传回执 |
已修正性别选择器，适配器拒绝非 0/1/2。 |
M07 POST /feedback |
feedbackContent |
contactInfo |
feedbackType：建议 advice/功能问题 bug/投诉 complaint/其他 other |
已修正为中文显示、枚举 value 提交。 |
| G03/G11 家谱创建/修改 | 创建：genealogyName、surname、regionCode |
堂号、籍贯、地址、简介 | 地区：三级行政区划选择；封面：上传；可见性/加入方式：枚举选择 | 保留页面已有 owner。 |
G08 POST .../join-applies |
无 | 申请人姓名、手机号、关系说明、申请理由 | inviterUserId：只有业务用户候选时才可选；当前隐藏 |
已删除“邀请人编号”手输框；适配器保留字段以供未来真实候选使用。 |
T04/T05 与亲属写入 LineagePersonBody |
name、bindingMode |
姓名、别名、编号、字辈、地点、生平、备注、排序 | 性别 0/1/2、农历 0/1、人物状态 0/1/2、父母为人物 options、头像上传；SELF/NONE 不传 appUserId，SPECIFIED 必须由可信业务用户候选选择 |
页面已有选择器与白名单；首位成员后端业务 code:500 曾阻塞，必须用页面重试和回读确认。 |
| F02 动态 | feedContent |
内容、排序 | 类型固定自动 text；多媒体由上传回执；状态不在普通创建页展示 |
页面显示“文字动态”。 |
| F06 谱文 | articleTitle、articleContent |
摘要、作者、正文、排序 | 封面上传；categoryId 必须分类候选选择 |
分类列表没有条目 DTO，不能猜 id/label，暂不展示分类选择。 |
| F07/F09 相册与照片 | 相册名；照片 ossId |
描述、标题、摄影者、拍摄时间、排序 | OSS 均来自上传；状态默认省略 | 已有创建后回读路径。 |
| R04 亲友往来 | relativeName |
关系、事件、时间、金额、正文、排序 | 多媒体上传；状态默认省略 | 可选字段不被前端强制必填。 |
| R07 礼仪活动 | ceremonyType、ceremonyTitle |
说明、日期时间、地点、详细地址、排序 | 封面上传；经纬度仅地图组件成对回填，当前隐藏；状态默认省略 | 适配器已接收 locationAddress，若未来传坐标会校验经纬度成对。 |
| R08 成长记录 | recordTitle |
类型、正文、日期、提醒、排序 | lineagePersonId 只可选真实人物；媒体上传；状态默认省略 |
无真实人物前保留为空。 |
| R10 备忘 | memoTitle |
正文、提醒、排序 | completed 无 enum，默认省略；媒体上传 |
不伪造完成开关。 |
| R11 功德 | donorName、meritTitle |
正文、金额、时间、排序 | 类型：donation/repair/public/other；状态默认省略 |
现有选择器使用接口 value。 |
| F10 视频 | videoTitle、videoOssId |
视频标题、说明 | 视频文件：上传回执自动填充；封面、时长、排序、状态：创建页隐藏 | 已接入视频选择、分片上传和创建；不允许手填 OSS ID。 |
五、不能直接补成页面的阻塞项
| 编号 | 接口/字段 | 已知请求或返回事实 | 前端处理与需要后端补充 |
|---|---|---|---|
| B01 | 首位成员 POST .../lineage/persons |
页面最小合法 body 曾返回 HTTP 200、envelope code:500、发生未知异常，请联系管理员；没有成功返回 personId |
后端修复后，必须从 T04 页面提交并回读 T01/T03，不能后台造成员。 |
| B02 | LineagePersonBody.bindingMode=SPECIFIED |
appUserId 条件必填，但现有 APP 没有“可信业务用户候选”读取合同 |
保留 NONE/SELF；补业务用户 options DTO 后才开放指定绑定。 |
| B03 | 谱文分类 GET .../article-categories |
operation 有列表路径，但当前导出没有可消费的条目字段模型 | 后端给出分类项的 id、显示名及响应 schema；前端再做选择器。 |
| B04 | 视频 GET/GET detail | VideoBody 请求要求 videoTitle、videoOssId；F10 已可选择视频、上传并创建，当前 200 读取响应仍未声明字段 |
后端补 VideoView/列表 rows 的完整响应 DTO，并确认播放地址与封面读取合同；前端再展示视频列表、详情和播放。 |
| B05 | 官网内容 GET /site/articles、/site/pages/{pageKey} |
当前 200 响应 schema 未声明 | 后端补文章/页面 key、标题、正文、更新时间等 DTO；M10 才能替换静态说明。 |
| B06 | 礼仪坐标 | longitude、latitude 可选且必须成对；没有地图选点或坐标来源 operation |
提供地图/地理编码集成合同，或明确允许何种受控坐标来源；不让用户手输。 |
| B07 | 贺礼邀约 inviteeUserIds |
必填业务用户 ID 数组；成员和世系人物 options 不能证明等同业务用户 | 发布受邀业务用户候选接口与 DTO。 |
| B08 | completed、payType、审核 status |
当前 schema 未给可安全映射的全部 value-label 语义 | 后端补 enum 或字典 options；前端保持隐藏/不测。 |
六、验证记录
- 本轮代码静态/适配器验证通过：
lineage-openapi-contract、feedback-openapi-contract、profile-pages-contract、m07-feedback-submit-contract、g08-g10-application-flow-contract、r-business-flow-contract、form-enum-api-runtime-smoke、oss-id-payload-api-runtime-smoke、compile-audit。 - 这些验证不替代真实写入。下一阶段在浏览器完成接口详情核对后，仅在测试账号的页面内输入、选择、提交和回读；敏感操作继续跳过。