完成80%

docs/APP表单控件与接口字段审计-2026-07-26.md

@@ -0,0 +1,63 @@
+# APP 表单控件与接口字段审计
+
+更新日期：2026-07-26  
+依据：桌面 Apifox APP 合同、`家谱.openapi.json`、当前页面真实表单代码。
+
+## 判定规则
+
+| 字段性质 | 页面控件 |
+| --- | --- |
+| 自由文本、标题、说明、地点、姓名 | 文本输入或多行输入 |
+| `date`、明确日期 | 日期选择器 |
+| 明确日期时间 | 日期与时间选择器，页面组合后提交标准时间字符串 |
+| 金额、排序 | 数字输入 |
+| 地区、分类、人物、业务用户、成员等资源 ID | 从真实候选列表选择；禁止手填内部 ID |
+| `sex`、`status`、是否农历等字典值 | value-label 选择器；必须有 Apifox enum 或字典 options 来源 |
+| `ossId`、封面、头像、媒体 | 真实上传组件；禁止手填文件 ID |
+
+## 已确认需要调整的表单
+
+| 页面 | 字段 | 当前控件/状态 | 正确控件 | 依赖或阻塞 |
+| --- | --- | --- | --- | --- |
+| T04、T05 | `birthLunar`、`deathLunar` | 文本输入，且提示为“按家谱记载填写” | “是否农历”选择器 | B15：Apifox 只有字典值描述，无 value-label enum |
+| T04、T05 | `sex`、`personStatus` | 页面缺入口 | 字典选择器 | B15 |
+| T04、T05 | `fatherId`、`motherId`、`appUserId` | 页面不能从候选选择 | 人物/业务用户候选选择器 | B06、B09/B13；首位成员不能填父母 |
+| T04、T05 | `avatarOssId` | 页面未接头像上传 | 真实上传组件 | B08：19 位 `ossId` 类型冲突 |
+| M02 | `sex` | 文本输入 | 字典选择器 | B15 |
+| M02 | `provinceCode`、`cityCode`、`districtCode` | 页面缺入口 | 行政区划级联选择器 | B12 的接口 DTO 已可读；需接入页面 |
+| G08 | `inviterUserId` | 数字输入，要求用户手填内部 ID | 真实邀请人候选选择器 | B09：没有业务用户候选/映射，不能手填 |
+| F06 | `categoryId` | 页面缺入口 | 谱文分类选择器 | B11：测试谱分类为空，合同没有条目字段定义 |
+| F02 | `feedType` | 自由文本输入 | 动态类型选择器或固定默认类型 | 合同仅给默认 `text`，没有完整类型 enum；不能让用户随意输入未声明类型 |
+| F09 | `shootTime` | 手工文本时间 | 日期与时间选择器 | 合同字段是拍摄时间；可直接改页面控件 |
+| R04 | `eventTime` | 手工文本时间 | 日期与时间选择器 | 合同字段是事项时间；可直接改页面控件 |
+| R07 | `ceremonyTime` | 手工文本时间 | 日期与时间选择器 | 合同字段是活动时间；可直接改页面控件 |
+| R08 | `recordDate`、`remindTime` | 手工文本时间 | 日期选择器；提醒用日期与时间选择器 | 合同字段分别是记录日期、提醒时间 |
+| R11 | `meritTime` | 手工文本时间 | 日期与时间选择器 | 合同字段是功德时间 |
+
+## 已经正确的控件
+
+| 页面 | 字段 | 当前控件 |
+| --- | --- | --- |
+| G03、G11 | `regionCode` | 行政区划级联选择器 |
+| G03、G11 | `visibility`、`joinMode` | 已封装为访问规则选择 |
+| M02 | `birthday` | 日期选择器 |
+| R10 | `remindTime` | 日期和时间选择器组合 |
+| 所有上传表单 | `coverOssId`、`mediaOssIds`、`ossId` | 真实上传回执，不提供手填文件 ID |
+| R04、R11 | 金额 | 数字输入 |
+| 各编辑页 | `sortOrder` | 数字输入 |
+
+## 不应为了“字段齐全”强行显示的字段
+
+| 字段 | 原因 |
+| --- | --- |
+| 首位成员的 `fatherId`、`motherId`、`relationName` | 与“首位成员/世系起点”语义冲突；不能伪造已有成员 ID |
+| `personNo` | 合同明确不传时服务端生成，不应要求用户填写 |
+| `avatarOssId`、`coverOssId`、`mediaOssIds` | 必须由上传组件产生，不允许文本输入 |
+| `status`、`completed` 等服务端有默认值的可选字段 | 无业务需求和明确字典时不新增裸代码控件 |
+
+## 实施顺序
+
+1. 先把 F09、R04、R07、R08、R11 的明确时间字段改为选择器并进行浏览器真实提交回读。
+2. 再接入 M02 的地区级联选择。
+3. B15、B09、B11、B06/B08 由后端补齐枚举、候选或 ID 合同后，再补世系、性别、分类、邀请人等选择器。
+