富文本内容
"` (HTML 字符串) | `dangerouslySetInnerHTML` | 一般不参与查询过滤 | ### 2.1 选择类字段统一约定 > 所有"选择类"字段（`SelectField` / `RadioField` / `CheckboxField` / `UserSelectField` / `DepartmentSelectField`）共享**同一种结构**： ```ts type Option = { label: string; value: string }; // 单选 / 单值 type SingleSelectValue = Option; // 多选 / 多值 type MultiSelectValue = Option[]; ``` - **单选/多选的判定**取决于字段配置 `multiple: boolean`，而非字段类型本身。 - **多选字段始终为数组**，即使用户只勾选了一项，也是 `[{label, value}]`，**不要降级为对象**。 ### 2.2 字段类型变更 - 字段创建后对应数据库列类型已经固定。`TextField` 是 `TEXT`，`SelectField` / `RadioField` / 附件 / 子表等复杂字段是 `JSONB`。 - 把 `TextField` 改成 `SelectField` 不是纯 UI 改动，而是 `TEXT -> JSONB` 的破坏性存储类型变更。 - 平台会阻断已有列的破坏性类型变更。需要迁移时采用显式 shadow migration：旧列重命名为 `fieldId__legacy_yyyymmdd`，再创建原 `fieldId` 的新类型列。 - 回填必须提供明确转换规则，例如文本 `"待处理"` 转 `{ "label": "待处理", "value": "pending" }`；平台和 AI 都不能自动猜。 - 发布前可用 `openxiangda form schema-plan这是富文本内容
" } ``` --- ## 4. 查询数据示例（与提交一致） 调用 `getFormDataDetail` 等单条查询 API 后，返回的 `formData` 与提交时**完全一致**，无任何字段被翻译或重组： ```json { "id": "rec_2026052900001", "formCode": "expense_apply", "createdAt": "2026-05-29T10:23:11Z", "updatedAt": "2026-05-29T10:23:11Z", "creator": { "label": "张三", "value": "user_001" }, "formData": { "name": "张三", "amount": 1280.50, "applyDate": "2026-05-29", "department": { "label": "研发部", "value": "dept_001" }, "priority": { "label": "高", "value": "high" }, "tags": [ { "label": "紧急", "value": "urgent" }, { "label": "重要", "value": "important" } ], "ccList": [ { "label": "李四", "value": "user_002" }, { "label": "王五", "value": "user_003" } ], "attachments": [ { "name": "合同.pdf", "url": "https://cdn.openxiangda.com/files/contract.pdf", "size": 204800, "type": "application/pdf" } ], "items": [ { "itemName": "笔记本", "itemQty": 2, "itemPrice": 5000 }, { "itemName": "鼠标", "itemQty": 5, "itemPrice": 100 } ] } } ``` > 注意：`formData` 是 API 返回的聚合 JSON 对象（键为字段 code，值为各字段存储值），与提交时的结构**字字相同**。底层实现是按字段建表（简单字段原生类型列 + 复杂字段 json/jsonb 列），而非所有数据存在单一 JSONB 列中。AI Agent 不要假设后端会做字典补全。 --- ## 5. 数据管理列表 API 返回格式 `advancedSearchDataManagement` 是数据列表查询 API，用于分页、筛选、排序。其返回结构如下： ```json { "code": 200, "message": "ok", "data": { "total": 128, "page": 1, "pageSize": 20, "list": [ { "id": "rec_2026052900001", "formCode": "expense_apply", "createdAt": "2026-05-29T10:23:11Z", "updatedAt": "2026-05-29T10:23:11Z", "creator": { "label": "张三", "value": "user_001" }, "formData": { "name": "张三", "amount": 1280.50, "department": { "label": "研发部", "value": "dept_001" }, "priority": { "label": "高", "value": "high" }, "tags": [ { "label": "紧急", "value": "urgent" } ] } }, { "id": "rec_2026052900002", "formCode": "expense_apply", "createdAt": "2026-05-29T11:05:42Z", "updatedAt": "2026-05-29T11:05:42Z", "creator": { "label": "李四", "value": "user_002" }, "formData": { "name": "李四", "amount": 320.00, "department": { "label": "市场部", "value": "dept_002" }, "priority": { "label": "普通", "value": "normal" }, "tags": [] } } ] } } ``` ### 5.1 字段访问示例 ```ts // 渲染列表表格 list.map(row => ({ id: row.id, 申请人: row.formData.name, // 纯字符串 金额: row.formData.amount, // number 部门: row.formData.department?.label ?? '-', // 选择类直接取 label 优先级: row.formData.priority?.label ?? '-', 标签: row.formData.tags?.map(t => t.label).join(', ') ?? '', 创建人: row.creator.label, })); // 构造筛选条件（用 value，不用 label） const filter = { 'formData.priority.value': 'high', 'formData.tags.value': { $in: ['urgent'] }, }; ``` --- ## 6. AI 开发注意事项（关键规则） > 以下规则按重要程度排序。AI Agent 写代码前请逐条核对。 1. **展示选择类字段值时，直接取 `item.label`**，**不要**做 `options.find(o => o.value === item.value)?.label` 这种"翻译"操作——label 已经在字段里了。 2. **操作（查询/过滤/比较）时一律用 `item.value`**：value 是稳定 ID，label 可能因字典调整而失真。 3. **提交表单时必须组装完整 `{label, value}` 结构**：仅传 value 会导致历史展示丢失中文名。 4. **多选字段始终是数组**，即便只有一项也写成 `[{label, value}]`；空值用 `[]`，不要用 `null`。 5. **`UserSelectField` / `DepartmentSelectField` 与普通 `SelectField` 的格式完全一致**，唯一区别是 `value` 语义为 userId / departmentId。 6. **附件 / 图片字段始终是数组**：单文件场景也是 `[{name, url, ...}]`，没有则 `[]`。使用 OSS 自定义上传时，附件项会额外带 `provider: "oss"`、`storageCode`、`publicUrl` 等元信息，但仍以 `url` 作为主访问地址。启用图片压缩时，`thumbUrl` / `previewUrl` / `variants` 是附加访问地址，不要覆盖原图 `url`。 7. **子表单 `SubFormField` 是对象数组**，每个对象代表一行，键为子字段 code。读取时遍历数组，按字段 code 访问；空子表单为 `[]`。 8. **不要尝试"翻译"或"规范化" label/value**：数据库存的就是最终展示格式，前后端皆然。任何二次翻译都是 bug 来源。 9. **流程表单的数据格式与普通表单一致**：`formData` 结构与普通表单一致，流程节点信息走另外的字段，不影响业务字段结构。 10. **日期字段是字符串而非 Date 对象**：`DateField` 用 ISO 日期串 `"YYYY-MM-DD"`，`DateRangeField` 是 `[startISO, endISO]`，序列化时不要 `JSON.stringify(new Date())`。 11. **数字字段是原生 number**，不是字符串；金额建议在前端格式化展示，不要在存储时加货币符号。 12. **富文本是 HTML 字符串**，渲染需用 `dangerouslySetInnerHTML`，并自行处理 XSS 过滤；不要把它当作 markdown。 13. **位置字段 `LocationField` 是对象**，含 `address` / `lng` / `lat`，地图渲染用 `lng`/`lat`，列表显示用 `address`。 14. **空值约定**：未填写的字段在 `formData` 中可能**缺失键**，也可能为 `null`；读取时统一用可选链 `?.` 与默认值兜底。 15. **不要修改返回的 `formData` 引用**：列表场景下若需做格式化展示，请生成新对象，避免污染原始数据。 --- ## 附录：TypeScript 类型定义参考 ```ts // 选项类（含人员/部门） export interface Option { label: string; value: string; } // 附件 export interface AttachmentItem { name: string; url: string; size?: number; type?: string; provider?: 'platform' | 'oss'; storageCode?: string; thumbUrl?: string; previewUrl?: string; variants?: { thumb?: ImageVariant; preview?: ImageVariant; }; } export interface ImageVariant { url: string; objectName?: string; bucketName?: string; width?: number; height?: number; size?: number; contentType?: string; } // 图片 export interface ImageItem { name: string; url: string; thumbUrl?: string; previewUrl?: string; variants?: AttachmentItem['variants']; } // 位置 export interface LocationValue { address: string; lng: number; lat: number; } // 子表单一行（结构由具体子字段决定） export type SubFormRow = Record