# 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. 推荐实施顺序

1. 后端先完成 C01、C02：视频可展示播放、世系首位人物可创建，才能闭合两个主要入口。
2. 补 C03、C04、C07：所有候选 ID 都能选择而不是手填。
3. 实施 F11（成员管理）和 F12（申请审核/撤销），先补清晰的权限和确认流程。
4. 实施 F01–F10 的编辑/删除闭环；每一项均先做“当前用户是否有权”的详情回读。
5. 处理 C05、C06、C08 与 R09，完成官网内容、地图、字典和人生事件的新增合同。

## 9. 验证边界

- 本文是接口和代码静态审计，不代表所有写接口已经在生产环境执行。
- 真实写入必须在测试账号、对应页面中操作，再通过列表/详情回读验证；不得用脚本绕过页面构造业务数据。
- 当前视频测试文件为 `C:\Users\Rain\Desktop\9d063f4536624f6b1ccb4d2cb9e9786c.mp4`；已确认存在且为非空 MP4。真实上传需在登录态下从 F10 的系统文件选择器选择它。