14 KiB
14 KiB
Apifox 写接口字段—表单控件映射
当前有效的 149 operation 总表、页面 owner 与阻塞项见 APP-149接口页面归属与表单字段审计-2026-07-27.md。本文件保留为字段控件速查表；其中以下修订以根目录最新
家谱.openapi.json为准。
口径与来源
- 核对时间：2026-07-27。
- 主源：桌面 Apifox 当前
APP项目（149 条 operation）及同一时刻导出的根目录家谱.openapi.json；两者的 operation 数量一致。 必填以 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 / envelopecode: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 |
否 | 仅可由地图选点组件成对回填；当前没有地图候选/选点合同，R07 不暴露手输框，也不传这两个字段。API 适配层只接受成对有限数字，供后续真实地图组件使用。 |
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 选填枚举选择：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 必填多选业务用户候选；无候选接口不能用逗号文本代替数组。 |
CeremonyInvitationResponseBody |
inviteStatus 必填二选一：接受 ACCEPTED、拒绝 DECLINED。 |
非页面直接填写的底层接口
认证挑战、验证码、分片上传初始化/完成、文件引用等 body 由登录/上传流程生成，不应渲染为业务表单。grantType、tenantId、challengeId、validToken、文件 hash/分片大小等由对应流程拥有，不能让用户在页面中编辑。
当前改造判定
- 已经可以立即改为选择控件的字段：
sex、出生/逝世农历、personStatus、visibility、joinMode、所有status、meritType、邀请响应。 - 必须改为候选选择的字段：所有家谱/成员/世系人物/分类/套餐/受邀用户的 ID 字段。
- 必须改为上传的字段：所有
*OssId、mediaOssIds、头像、封面、照片、视频文件。 completed、payType、审核status等尚未在当前 Apifox 字段详情给出允许值；在后端未提供字典或候选接口前，不增加猜测性选择项。feedbackType已有四个枚举值，已改为选择控件。