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

# Apifox 写接口字段—表单控件映射

## 口径与来源

- 核对时间：2026-07-27。
- 主源：桌面 Apifox 当前 `APP` 项目中的接口详情；根目录 `家谱.openapi.json` 只用于补全接口路径和没有展示在当前屏幕中的普通字段。
- `必填` 以 Apifox `必需` 标记为准；没有 `必需` 的字段均应允许不填，提交时传空值或省略由当前 API 适配器统一处理。
- `枚举选择` 只能提交下表列出的 value，不能把中文标签提交给后端。
- `候选选择` 只能从对应选项接口选取，页面不得暴露裸露的内部 ID 输入框。
- `上传` 必须先走统一上传，提交上传回执中的 `ossId`；不能让用户手输 OSS ID。
- 所有 `sortOrder` 是整数数字框；所有 `amount/giftAmount` 是金额数字框；示例为 `yyyy-MM-dd HH:mm:ss` 的时间字段用“日期 + 时间”控件拼接后提交。

## 已在 Apifox 字段详情中确认的字典

| 字段/字典 | value → 中文 | 页面控件 |
| --- | --- | --- |
| `sys_user_sex` | `0` 男；`1` 女；`2` 未知 | 单选/下拉选择 |
| `gen_number_yes_no` | `0` 否；`1` 是 | 单选/下拉选择 |
| `gen_lineage_person_status` | `0` 健在；`1` 已故；`2` 未知 | 单选/下拉选择 |
| `sys_normal_disable` | `0` 正常；`1` 停用 | 单选/开关；默认 `0` |
| `gen_genealogy_visibility` | `0` 私密；`1` 公开；`2` 成员可见 | 单选/下拉选择 |
| `gen_genealogy_join_mode` | `0` 关闭加入；`1` 申请审核；`2` 邀请加入 | 单选/下拉选择 |
| `gen_merit_type` | `donation` 捐赠；`repair` 修祠；`public` 公益；`other` 其他 | 单选/下拉选择 |
| 活动邀请响应 | `ACCEPTED` 接受；`DECLINED` 拒绝 | 二选一 |

`completed` 在 Apifox 当前详情中是 `string`，只给出示例 `0`，没有挂字典/允许值；因此不能伪造“完成/未完成”的值表。当前页面应默认省略，待后端给出该字段的字典定义后再开启开关。

## 已有页面：字段到控件映射

### M02 修改用户资料 — `PUT /genealogy/app/auth/profile`

| 字段 | 必填 | Apifox 详情 | 正确控件与提交 |
| --- | --- | --- | --- |
| `nickName` | 否 | string，用户昵称，最多 30 字 | 文本框，最多 30 字 |
| `realName` | 否 | string，真实姓名，最多 30 字 | 文本框，最多 30 字 |
| `avatar` | 否 | int64，头像文件 OSS ID | 图片上传；仅提交可安全表示的数值 OSS ID |
| `sex` | 否 | `sys_user_sex` | 枚举选择 `0/1/2` |
| `birthday` | 否 | date，生日，格式 `yyyy-MM-dd` | 日期选择器 |
| `email` | 否 | email，最多 100 字 | email 文本框 |

### G03/G11 创建、修改家谱 — `GenealogyCreateBody` / `GenealogyUpdateBody`

| 字段 | 创建必填 | 正确控件与提交 |
| --- | --- | --- |
| `genealogyName` | 是 | 文本框 |
| `surname` | 是 | 文本框 |
| `ancestralHall` | 否 | 文本框 |
| `originPlace` | 否 | 文本框 |
| `regionCode` | 是 | 省市区级联候选选择，提交行政区划 code |
| `addressDetail` | 否 | 文本框 |
| `coverOssId` | 否 | 图片上传，提交字符串 OSS ID |
| `intro` | 否 | 多行文本 |
| `visibility` | 否 | 枚举选择：私密 `0` / 公开 `1` / 成员可见 `2` |
| `joinMode` | 否 | 枚举选择：关闭加入 `0` / 申请审核 `1` / 邀请加入 `2` |

### T04/T05 录入、修改世系人物 — `LineagePersonBody`

同一 body 还用于“添加子女、父母、兄弟姐妹、配偶”。`name` 是唯一 body 必填字段；关系路径由 URL 决定，不能把中文关系标签当成接口字段替代。

| 字段 | 必填 | Apifox 详情/限制 | 正确控件与提交 |
| --- | --- | --- | --- |
| `bindingMode` | 是 | 身份认领方式：`NONE` / `SELF` / `SPECIFIED` | 固定英文枚举选择：不绑定账号 / 绑定当前账号 / 绑定指定用户；不发送中文值 |
| `appUserId` | 视 `bindingMode` 而定 | `NONE` 不绑定账号且不传；`SELF` 绑定当前登录账号且不传，后端从 Token 获取；`SPECIFIED` 绑定指定业务用户且必须传 | 仅 `SPECIFIED` 由管理员选择可信业务用户候选后提交；当前没有候选接口时禁止该选项保存，绝不手输 ID |
| `personNo` | 否 | 人物编号；不传由服务端生成 | 可选文本框；留空时省略 |
| `name` | 是 | 姓名 | 文本框 + 必填校验 |
| `aliasName` | 否 | 别名或曾用名 | 文本框 |
| `sex` | 否 | `sys_user_sex` | 枚举选择：男 `0` / 女 `1` / 未知 `2` |
| `generation` | 否 | int64，世代序号 | 正整数数字框；首位成员固定为 `1` |
| `generationName` | 否 | 字辈或辈分 | 文本框 |
| `fatherId` | 否 | 父亲人物 ID，必须属于当前家谱 | 从 `/lineage/persons/options` 选择父亲，提交人物 ID |
| `motherId` | 否 | 母亲人物 ID，必须属于当前家谱 | 从 `/lineage/persons/options` 选择母亲，提交人物 ID |
| `avatarOssId` | 否 | string/null，头像文件 OSS ID；说明明确要求统一上传组件取得，不允许手工录入 | 图片上传，提交字符串 OSS ID |
| `birthDate` | 否 | date-time/null（写接口示例为 `yyyy-MM-dd`） | 日期选择；未录入不传 |
| `birthLunar` | 否 | `gen_number_yes_no` | 枚举选择：否 `0` / 是 `1` |
| `birthPlace` | 否 | 出生地 | 文本框 |
| `deathDate` | 否 | date-time/null（写接口示例为 `yyyy-MM-dd`） | 日期选择；未录入不传 |
| `deathLunar` | 否 | `gen_number_yes_no` | 枚举选择：否 `0` / 是 `1` |
| `deathPlace` | 否 | 逝世地 | 文本框 |
| `burialPlace` | 否 | 安葬地 | 文本框 |
| `personStatus` | 否 | `gen_lineage_person_status` | 枚举选择：健在 `0` / 已故 `1` / 未知 `2` |
| `biography` | 否 | 人物简介 | 多行文本 |
| `sortOrder` | 否 | int64，排序值 | 整数数字框 |
| `remark` | 否 | 备注 | 多行文本 |
| `relationName` | 否 | 关系名称 | 新增亲属时由关系选择派生；编辑时可作为文本修订 |

#### 页面实测（2026-07-27）

- 此接口字段标为 `date-time`，但四个写接口示例使用 `yyyy-MM-dd`。页面此前把日期追加为 `yyyy-MM-dd HH:mm:ss`，会在客户端 `normalizeLineagePersonDate` 校验阶段被拒绝，尚未发起请求；现已改为只传日期。
- 后端于 2026-07-27 明确补齐身份认领合同：`NONE`、`SELF` 禁止提交 `appUserId`；`SELF` 由后端从 Token 取当前 APP 用户；仅 `SPECIFIED` 必须提交 `appUserId`。页面默认 `NONE`，不再自动读取或提交 `profile.userId`。
- 同日页面实测 `POST .../children`：请求体为 `bindingMode: "NONE"` 且不存在 `appUserId`，后端仍返回 HTTP 200 / envelope `code:500`、`发生未知异常，请联系管理员`；三世数据未落库，需后端确认新版写接口是否已部署并排查该业务异常。

### F02 家族圈动态 — `FamilyFeedBody`

| 字段 | 必填 | Apifox 详情 | 正确控件与提交 |
| --- | --- | --- | --- |
| `feedType` | 否 | 动态类型；未传默认 `text` | 当前页面固定传 `text`，不让用户输入代码 |
| `feedContent` | 是 | 动态内容，不允许为空 | 多行文本 + 必填校验 |
| `mediaOssIds` | 否 | 多个文件 OSS ID 用英文逗号分隔 | 多图上传；回执 ID 以 `,` 拼接 |
| `sortOrder` | 否 | int64；未传默认 `0` | 整数数字框 |
| `status` | 否 | `sys_normal_disable` | 正常 `0` / 停用 `1`；创建页默认 `0`，非管理页不暴露停用操作 |

### F06 谱文、F07 相册、F09 相册照片

| body.字段 | 必填 | 正确控件与提交 |
| --- | --- | --- |
| `ArticleBody.categoryId` | 否 | 从“谱文分类”接口候选选择；不手填分类 ID |
| `articleTitle` / `articleSummary` / `authorName` | 标题是 | 分别为文本、多行摘要、文本 |
| `articleContent` | 是 | 富文本/多行内容编辑 |
| `coverOssId` | 否 | 图片上传，字符串 OSS ID |
| `ArticleBody.sortOrder` | 否 | 整数数字框 |
| `ArticleBody.status` | 否 | `sys_normal_disable` 选择，默认 `0` |
| `AlbumBody.albumName` | 是 | 文本框 |
| `albumDesc` | 否 | 多行文本 |
| `coverOssId` | 否 | 图片上传，字符串 OSS ID |
| `AlbumBody.sortOrder` | 否 | 整数数字框 |
| `AlbumBody.status` | 否 | `sys_normal_disable` 选择，默认 `0` |
| `AlbumPhotoBody.ossId` | 是 | 图片上传；提交字符串 OSS ID |
| `photoTitle` / `photoDesc` / `photographer` | 否 | 文本、多行文本、文本 |
| `shootTime` | 否 | 拍摄时间；示例按标准时间字符串 | 日期 + 时间选择 |
| `AlbumPhotoBody.sortOrder` | 否 | 整数数字框 |
| `AlbumPhotoBody.status` | 否 | `sys_normal_disable` 选择，默认 `0` |

### R07 祭祀活动、R04 献礼

| body.字段 | 必填 | 正确控件与提交 |
| --- | --- | --- |
| `CeremonyBody.ceremonyType` | 是 | Apifox 当前为普通 string；文本框，不能自行伪造枚举 |
| `ceremonyTitle` | 是 | 文本框 |
| `ceremonyDesc` | 否 | 多行文本 |
| `ceremonyTime` | 否 | 示例为 `yyyy-MM-dd HH:mm:ss`；日期 + 时间选择 |
| `location` / `locationAddress` | 否 | 地点名称、详细地址文本框；两项都应保留 |
| `longitude` / `latitude` | 否 | decimal 数字框；应由地图选点回填，不能把经纬度当文本 |
| `coverOssId` | 否 | 图片上传，字符串 OSS ID |
| `sortOrder` | 否 | 整数数字框 |
| `status` | 否 | `sys_normal_disable` 选择，默认 `0` |
| `CeremonyGiftBody.giverName` | 否 | 文本框 |
| `giftAmount` | 是 | 金额数字框 |
| `giftMessage` | 否 | 多行文本 |

### R08 成长记录、R09 亲友记录、R10 备忘、R11 功德

| body.字段 | 必填 | Apifox 详情/正确控件 |
| --- | --- | --- |
| `GrowthRecordBody.lineagePersonId` | 否 | 世系人物候选选择，提交人物 ID |
| `recordType` | 否 | 当前详情为普通 string，文本框 |
| `recordTitle` | 是 | 文本框 |
| `recordContent` | 否 | 多行文本 |
| `recordDate` / `remindTime` | 否 | 示例均为 `yyyy-MM-dd HH:mm:ss`；日期 + 时间选择 |
| `mediaOssIds` | 否 | 多图上传，逗号分隔 OSS ID |
| `GrowthRecordBody.sortOrder` / `status` | 否 | 整数数字框；`sys_normal_disable` 选择 |
| `MemoBody.memoTitle` | 是 | 文本框 |
| `memoContent` | 否 | 多行文本 |
| `remindTime` | 否 | 示例为 `yyyy-MM-dd HH:mm:ss`；日期 + 时间选择 |
| `completed` | 否 | 当前仅 string 示例 `0`，无字典；默认省略，不能私设枚举 |
| `MemoBody.mediaOssIds` / `sortOrder` / `status` | 否 | 多图上传；整数数字框；`sys_normal_disable` 选择 |
| `RelativeRecordBody.relativeName` | 是 | 文本框 |
| `relationName` / `eventName` | 否 | 文本框 |
| `eventTime` | 否 | 示例为 `yyyy-MM-dd HH:mm:ss`；日期 + 时间选择 |
| `giftAmount` | 否 | 金额数字框 |
| `recordContent` | 否 | 多行文本 |
| `RelativeRecordBody.mediaOssIds` / `sortOrder` / `status` | 否 | 多图上传；整数数字框；`sys_normal_disable` 选择 |
| `MeritRecordBody.donorName` / `meritTitle` | 是 | 文本框 |
| `meritType` | 否 | 枚举选择：捐赠 `donation` / 修祠 `repair` / 公益 `public` / 其他 `other` |
| `meritContent` | 否 | 多行文本 |
| `amount` | 否 | 金额数字框 |
| `meritTime` | 否 | 示例为 `yyyy-MM-dd HH:mm:ss`；日期 + 时间选择 |
| `MeritRecordBody.sortOrder` / `status` | 否 | 整数数字框；`sys_normal_disable` 选择 |

## 其余写接口：同样必须按字段类型建控件

| 接口 body | 字段映射 |
| --- | --- |
| `GenealogyJoinApplyBody` | `applicantName`、`phone`、`relationDesc`、`applyReason` 为文本/多行文本；`inviterUserId` 必须是业务用户候选选择，当前缺候选接口时不暴露裸 ID 输入。 |
| `GenealogyJoinAuditBody` | `status` 是审核结果，必须由 Apifox 的审核状态字典提供选项后才做选择器；`auditRemark` 多行文本。 |
| `GenealogyMemberUpdateBody` | `memberName`、`relationName`、`roleType` 文本；`lineagePersonId` 为世系人物候选选择。 |
| `GenealogyOwnerTransferBody` | `targetMemberId` 必填，家谱成员候选选择。 |
| `GenerationPoemBody` | `generationNo` 必填正整数；`generationText` 必填文本；`description` 多行文本；`sortOrder` 数字；`status` 用 `sys_normal_disable`。 |
| `GenerationPoemBatchBody` | `poemText` 必填多行文本；`disableMissing` 布尔开关。 |
| `FamilyFeedCommentBody` | `parentCommentId` 为评论候选/回复上下文，不能输入 ID；`commentContent` 必填多行文本。 |
| `FeedbackBody` | `feedbackType` 当前详情为 string，待字典明确前为文本；`feedbackContent` 必填多行文本；`contactInfo` 文本。 |
| `VipOrderBody` | `packageId` 必填，VIP 套餐候选选择；`genealogyId` 为当前家谱上下文选择；`payType` 只能使用支付方式字典，不能手填代码。 |
| `VideoBody` | `videoTitle` 必填文本，`videoDesc` 多行文本，`coverOssId`/`videoOssId` 为上传，`durationSeconds`/`sortOrder` 为数字，`status` 为 `sys_normal_disable`。 |
| `CeremonyInviteesBody` | `inviteeUserIds` 必填多选业务用户候选；无候选接口不能用逗号文本代替数组。 |
| `CeremonyInvitationResponseBody` | `inviteStatus` 必填二选一：接受 `ACCEPTED`、拒绝 `DECLINED`。 |

## 非页面直接填写的底层接口

认证挑战、验证码、分片上传初始化/完成、文件引用等 body 由登录/上传流程生成，不应渲染为业务表单。`grantType`、`tenantId`、`challengeId`、`validToken`、文件 hash/分片大小等由对应流程拥有，不能让用户在页面中编辑。

## 当前改造判定

1. 已经可以立即改为选择控件的字段：`sex`、出生/逝世农历、`personStatus`、`visibility`、`joinMode`、所有 `status`、`meritType`、邀请响应。
2. 必须改为候选选择的字段：所有家谱/成员/世系人物/分类/套餐/受邀用户的 ID 字段。
3. 必须改为上传的字段：所有 `*OssId`、`mediaOssIds`、头像、封面、照片、视频文件。
4. `completed`、`feedbackType`、`payType`、审核 `status` 等尚未在当前 Apifox 字段详情给出允许值；在后端未提供字典或候选接口前，不增加猜测性选择项。