11 KiB
11 KiB
APP-150 项目接口覆盖与功能缺口总清单
更新时间：2026-07-28
唯一接口依据：仓库根目录 家谱.openapi.json（149 个 operation）。
1. 阅读方式与结论
“没有接口”“接口已接但没功能”“接口不应有单独页面”是三件不同的事。本清单将其分开记录：
- 后端合同缺口：OpenAPI 没有足够的请求/响应字段，前端不能猜测实现。
- 前端功能缺口：
utils/api.js已有请求 owner，但没有页面入口或用户动作调用它。 - 技术/敏感操作：由登录、上传、会话、确认弹窗等 owner 自动调用；不做独立表单。
当前结论：149 个 operation 均已完成归属；视频发布已接通。项目仍有 9 项后端合同缺口、14 组 API 已有但页面功能未接通的缺口，详见第 3、4 节。
2. 全量模块归属（149 个 operation）
| 模块 | 数量 | 当前 owner | 状态 | 说明 |
|---|---|---|---|---|
| 验证中心 | 7 | A01/A04/A05、auth-verification.js |
已归属 | APP 验证是认证内部流程；/captcha/*、/auth/code 为兼容接口。 |
| 认证登录 | 12 | A01/A04/A05、M01/M02/M04/M05/M10 | 部分功能缺口 | 登录、注册、资料、改密、退出有 owner；换绑/注销见第 4 节。 |
| 文件上传 | 6 | resumable-image-upload.js |
已归属 | 初始化、分片、完成、引用释放均是上传 owner；OSS ID 不可手填。 |
| 行政区划 | 8 | G03/G11、appApi.getRegion* |
已归属 | APP 与共享版本各 4 条，当前只消费一套，不能双接。 |
| 家谱 | 13 | G01/G03/G05–G12 | 部分功能缺口 | 创建、读取、设置、申请流程有 owner；申请审核/撤销需补实际动作。 |
| 家谱成员 | 6 | appApi |
无页面 owner | memberId 是账号成员，不是世系 personId；不能放进 T 系页面。 |
| 字辈谱 | 6 | G12 | 部分功能缺口 | 读取、创建、批量预览/保存有 owner；单条修改/停用需补页面动作。 |
| 世系人物 | 12 | T01、T03–T08、R01/R02 | 后端阻塞 | 页面/API 已有；首位人物创建、指定绑定候选仍受合同阻塞。 |
| 家族圈 | 14 | F01–F03 | 部分功能缺口 | 发布、读取、点赞、评论有 owner；编辑/删除与回复发布尚未形成页面流程。 |
| 内容文章 | 9 | F04–F06、M06/M08 | 部分功能缺口 | 读取/新增有 owner；分类 DTO、编辑/删除动作待补。 |
| 相册 | 7 | F07–F09 | 部分功能缺口 | 创建、读取、上传照片有 owner；相册编辑/删除、照片删除待补。 |
| 祭祀 | 8 | R05–R07 | 部分功能缺口 | 创建、读取、献礼新增有 owner；修改/删除、地图与邀请待补。 |
| 族务记录 | 20 | R03/R04、R08、R10/R11 | 部分功能缺口 | 新增/读取有 owner；多项编辑、删除、媒体入口待补。 |
| 消息通知 | 5 | N01/N02、G01 | 部分功能缺口 | 列表、详情、未读数有 owner；标记已读动作待补。 |
| 意见反馈 | 2 | M07 | 部分功能缺口 | 提交有 owner；“我的反馈”列表无页面。 |
| VIP | 3 | M09 | 部分功能缺口 | 套餐/订单读取有 owner；创建订单未形成受控支付流程。 |
| 视频 | 5 | F10、appApi |
后端合同缺口 | 上传、创建和 CRUD API owner 已接；列表/详情 DTO 缺失。 |
| 贺礼邀约 | 4 | R06、appApi |
后端合同缺口 | API owner 有；缺业务用户候选与“我的邀请”页面。 |
| 官网内容 | 2 | M10 | 后端合同缺口 | 响应无 DTO，不能替换当前静态说明。 |
3. 后端 / OpenAPI 必须补充的合同（不能由前端猜）
| ID | 相关接口/字段 | 现状 | 缺少的合同 | 前端当前处理 | 优先级 |
|---|---|---|---|---|---|
| C01 | GET /genealogies/{genealogyId}/videos、GET .../videos/{videoId} |
只有通用响应，无可消费视频字段 | VideoView：videoId、标题、说明、视频播放 URL、封面 URL、时长、创建时间、状态 |
F10 可上传并创建，不渲染列表/播放器 | P0 |
| C02 | POST /lineage/persons 首位成员 |
页面最小合法请求曾收到业务 code:500 |
后端修复创建逻辑，并返回可回读的 personId |
T04 不伪造首位人物 | P0 |
| C03 | LineagePersonBody.bindingMode=SPECIFIED |
appUserId 条件必填 |
可信业务用户候选接口及 DTO，明确用户 ID 与人物关系 | 仅开放 NONE / SELF |
P1 |
| C04 | GET .../article-categories |
列表 response 未定义条目字段 | 分类 id、显示名、状态、排序 DTO |
F06 隐藏分类选择，不能手输 categoryId |
P1 |
| C05 | GET /site/articles、GET /site/pages/{pageKey} |
response 未定义 | 文章/页面 key、标题、正文、更新时间、链接 DTO | M10 保留静态内容 | P1 |
| C06 | 礼仪 longitude、latitude |
两字段须成对，但无位置来源 | 地图选点或地理编码合同；坐标精度/坐标系说明 | R07 隐藏坐标手输 | P2 |
| C07 | 活动 inviteeUserIds |
需要业务用户 ID 数组 | 可邀请业务用户候选接口、显示名、可邀请条件 DTO | R06 不提交猜测 ID | P1 |
| C08 | completed、payType、部分审核/管理状态 |
字典含义或可用范围不足 | 完整 enum/value-label 与权限规则 | 创建页默认不显示管理开关 | P2 |
| C09 | 家族圈评论回复 | 只有回复列表接口，没有声明创建回复的操作或父评论字段 | 回复创建 endpoint 与请求体（至少评论内容、父评论 ID） | F03 仅展示现有评论，不提供假回复提交 | P1 |
4. API 已有，但页面功能尚未接通
以下项的 appApi 已有对应请求 owner；静态检索未发现页面调用，或页面只展示静态/只读状态。实现前需确认权限与交互，不应直接暴露内部 ID。
| ID | 操作 | 当前缺少的页面功能 | 建议页面/入口 | 前置条件 |
|---|---|---|---|---|
| F01 | PUT/DELETE .../feeds/{feedId} |
编辑、删除本人动态 | F03 动态详情 | 必须仅显示本人有权操作的按钮。 |
| F02 | DELETE .../comments/{commentId} |
删除本人评论/删除占位展示 | F03 评论区 | 有回复时按后端返回的删除占位渲染。 |
| F03 | PUT/DELETE .../articles/{articleId} |
谱文编辑、删除 | F05/F06 | 分类 DTO 到位后，编辑页才开放分类选择。 |
| F04 | PUT/DELETE .../albums/{albumId} |
相册编辑、删除 | F07/F08 | 删除需二次确认并遵循后端权限。 |
| F05 | DELETE .../albums/{albumId}/photos/{photoId} |
删除照片 | F08 | 仅作者/管理者显示。 |
| F06 | PUT/DELETE .../ceremonies/{ceremonyId} |
礼仪编辑、删除 | R06/R07 | 地图字段仍按 C06 处理。 |
| F07 | DELETE .../ceremonies/{ceremonyId}/gifts/{giftId} |
删除献礼 | R06 | 需明确献礼人/管理员权限。 |
| F08 | 成长、备忘、亲友、功德的 PUT/DELETE |
记录编辑、删除 | R08/R10/R04/R11 | 目前新建/读取与编辑动作未闭环。 |
| F09 | PUT .../generation-poems/{poemId} |
修改、停用、恢复单条字辈 | G12 | 需按 status 枚举和管理权限显示。 |
| F10 | 家谱成员 6 条 | 成员列表、成员资料、移除、退出、转让 | 新建“成员管理”页 | 严格使用 memberId，绝不能复用世系人物 UI。 |
| F11 | 加入申请审核、撤销 | 审核/撤销提交动作与结果回读 | G09/G10 | 需确认当前用户角色，敏感写操作必须二次确认。 |
| F12 | 通知标已读、全部已读 | 单条/全部已读行为 | N01/N02 | 标读应静默回写列表，不弹假成功。 |
| F13 | GET /feedback |
“我的反馈”列表 | M07 或新建 M11 | response DTO 足够时展示，不开放删除。 |
| F14 | 换绑、注销、VIP 创建订单 | 安全表单/支付确认链路 | M05/M10/M09 | 短信验证、支付回调、二次确认不可省略。 |
5. 没有可新增接口的页面功能
| 页面 | 原因 | 需要的后端资源 |
|---|---|---|
| R09 人生大事 | OpenAPI 149 条中没有人生事件资源的 CRUD | 人生事件列表、详情、新增、修改、删除；需定义归属人物、事件日期、事件类型、内容、媒体字段。 |
| F10 视频列表/播放 | 已有路径但读取 DTO 不完整，等同不可安全实现 | 见 C01。 |
| “我的活动邀请” | 读取接口有 owner，但没有页面和邀请候选数据 | 邀请页面、C07 候选 DTO；现有 GET .../ceremony-invitations/mine 可作为入口。 |
| 家谱成员管理 | 后端路径完整但无页面信息架构 | 成员管理页面及权限/成员 DTO展示规则。 |
6. 不是“少页面”的接口（保持自动或受控）
| 接口类别 | 正确 owner | 不应暴露的字段/原因 |
|---|---|---|
| 验证挑战、验证校验、短信发送 | auth-verification.js、认证页 |
validToken、challenge、验证码票据由认证流程持有。 |
| 文件初始化、分片、完成、引用 | 上传工具 | uploadId、MD5、chunkIndex、OSS ID 都是上传回执/技术参数。 |
clientid、token、tenantId |
config.js、session |
运行时认证信息，绝不能做表单字段。 |
| 行政区划 APP/共享重复路径 | appApi.getRegion* |
只选择一个 owner，避免同一功能双请求。 |
| 删除、审核、退出、注销、支付 | 现有页面的明确二次确认流程 | 不应为“接口覆盖率”而自动触发真实写操作。 |
7. 表单字段总规则
| 字段类型 | 表单处理 |
|---|---|
OpenAPI required 文本 |
显示必填标识，提交前 trim 校验。 |
enum 字符串 |
使用中文标签的选择器，仅提交 enum value。 |
| 日期/日期时间 | 使用日期或日期+时间选择器；不能自由输入格式。 |
| 候选 ID | 必须由 options/list 选择；缺候选 DTO 时隐藏，不允许手输。 |
*OssId、mediaOssIds |
只从上传回执获取；视频同样适用。 |
status、completed、排序、审核、支付字段 |
默认不出现在普通创建表单；只在明确管理权限和完整字典合同下出现。 |
| 认证、分片、路径 ID | 自动生成/路由携带；不可显示或编辑。 |
8. 推荐实施顺序
- 后端先完成 C01、C02：视频可展示播放、世系首位人物可创建，才能闭合两个主要入口。
- 补 C03、C04、C07：所有候选 ID 都能选择而不是手填。
- 实施 F11（成员管理）和 F12（申请审核/撤销），先补清晰的权限和确认流程。
- 实施 F01–F10 的编辑/删除闭环；每一项均先做“当前用户是否有权”的详情回读。
- 处理 C05、C06、C08 与 R09，完成官网内容、地图、字典和人生事件的新增合同。
9. 验证边界
- 本文是接口和代码静态审计，不代表所有写接口已经在生产环境执行。
- 真实写入必须在测试账号、对应页面中操作，再通过列表/详情回读验证；不得用脚本绕过页面构造业务数据。
- 当前视频测试文件为
C:\Users\Rain\Desktop\9d063f4536624f6b1ccb4d2cb9e9786c.mp4；已确认存在且为非空 MP4。真实上传需在登录态下从 F10 的系统文件选择器选择它。