待测试

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

@@ -1,5 +1,7 @@
 # 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
 
 ## 结论

docs/APP-149接口页面归属与表单字段审计-2026-07-27.md

@@ -0,0 +1,84 @@
+# APP 149 接口页面归属与表单字段审计
+
+更新时间：2026-07-27
+
+## 一、唯一依据与结论
+
+- 唯一接口源：根目录 `家谱.openapi.json`；桌面 Apifox `APP` 概览同步显示 **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`。
+- 这些验证不替代真实写入。下一阶段在浏览器完成接口详情核对后，仅在测试账号的页面内输入、选择、提交和回读；敏感操作继续跳过。

docs/APP-150项目接口覆盖与功能缺口总清单-2026-07-28.md

@@ -0,0 +1,118 @@
+# 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 的系统文件选择器选择它。

docs/Apifox写接口字段—表单控件映射-2026-07-27.md

@@ -1,9 +1,11 @@
 # Apifox 写接口字段—表单控件映射
 
+> 当前有效的 149 operation 总表、页面 owner 与阻塞项见 [APP-149接口页面归属与表单字段审计-2026-07-27.md](APP-149接口页面归属与表单字段审计-2026-07-27.md)。本文件保留为字段控件速查表；其中以下修订以根目录最新 `家谱.openapi.json` 为准。
+
 ## 口径与来源
 
 - 核对时间：2026-07-27。
-- 主源：桌面 Apifox 当前 `APP` 项目中的接口详情；根目录 `家谱.openapi.json` 只用于补全接口路径和没有展示在当前屏幕中的普通字段。
+- 主源：桌面 Apifox 当前 `APP` 项目（149 条 operation）及同一时刻导出的根目录 `家谱.openapi.json`；两者的 operation 数量一致。
 - `必填` 以 Apifox `必需` 标记为准；没有 `必需` 的字段均应允许不填，提交时传空值或省略由当前 API 适配器统一处理。
 - `枚举选择` 只能提交下表列出的 value，不能把中文标签提交给后端。
 - `候选选择` 只能从对应选项接口选取，页面不得暴露裸露的内部 ID 输入框。
@@ -129,7 +131,7 @@
 | `ceremonyDesc` | 否 | 多行文本 |
 | `ceremonyTime` | 否 | 示例为 `yyyy-MM-dd HH:mm:ss`；日期 + 时间选择 |
 | `location` / `locationAddress` | 否 | 地点名称、详细地址文本框；两项都应保留 |
-| `longitude` / `latitude` | 否 | decimal 数字框；应由地图选点回填，不能把经纬度当文本 |
+| `longitude` / `latitude` | 否 | 仅可由地图选点组件成对回填；当前没有地图候选/选点合同，R07 不暴露手输框，也不传这两个字段。API 适配层只接受成对有限数字，供后续真实地图组件使用。 |
 | `coverOssId` | 否 | 图片上传，字符串 OSS ID |
 | `sortOrder` | 否 | 整数数字框 |
 | `status` | 否 | `sys_normal_disable` 选择，默认 `0` |
@@ -177,7 +179,7 @@
 | `GenerationPoemBody` | `generationNo` 必填正整数；`generationText` 必填文本；`description` 多行文本；`sortOrder` 数字；`status` 用 `sys_normal_disable`。 |
 | `GenerationPoemBatchBody` | `poemText` 必填多行文本；`disableMissing` 布尔开关。 |
 | `FamilyFeedCommentBody` | `parentCommentId` 为评论候选/回复上下文，不能输入 ID；`commentContent` 必填多行文本。 |
-| `FeedbackBody` | `feedbackType` 当前详情为 string，待字典明确前为文本；`feedbackContent` 必填多行文本；`contactInfo` 文本。 |
+| `FeedbackBody` | `feedbackType` 选填枚举选择：`advice` 建议、`bug` 功能问题、`complaint` 投诉反馈、`other` 其他；界面显示中文标签，提交 value。`feedbackContent` 必填多行文本；`contactInfo` 文本。 |
 | `VipOrderBody` | `packageId` 必填，VIP 套餐候选选择；`genealogyId` 为当前家谱上下文选择；`payType` 只能使用支付方式字典，不能手填代码。 |
 | `VideoBody` | `videoTitle` 必填文本，`videoDesc` 多行文本，`coverOssId`/`videoOssId` 为上传，`durationSeconds`/`sortOrder` 为数字，`status` 为 `sys_normal_disable`。 |
 | `CeremonyInviteesBody` | `inviteeUserIds` 必填多选业务用户候选；无候选接口不能用逗号文本代替数组。 |
@@ -192,4 +194,4 @@
 1. 已经可以立即改为选择控件的字段：`sex`、出生/逝世农历、`personStatus`、`visibility`、`joinMode`、所有 `status`、`meritType`、邀请响应。
 2. 必须改为候选选择的字段：所有家谱/成员/世系人物/分类/套餐/受邀用户的 ID 字段。
 3. 必须改为上传的字段：所有 `*OssId`、`mediaOssIds`、头像、封面、照片、视频文件。
-4. `completed`、`feedbackType`、`payType`、审核 `status` 等尚未在当前 Apifox 字段详情给出允许值；在后端未提供字典或候选接口前，不增加猜测性选择项。
+4. `completed`、`payType`、审核 `status` 等尚未在当前 Apifox 字段详情给出允许值；在后端未提供字典或候选接口前，不增加猜测性选择项。`feedbackType` 已有四个枚举值，已改为选择控件。