@microi.net/cli 5.5.8 → 5.6.0

package/skills/microi-db-schema/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: microi-db-schema
-description: Microi 吾码数据库结构与字典指南。用于通过实时 MCP Schema 或当前租户快照检查 Microi 平台表，梳理 diy_table/diy_field/sys_menu 关系，定位 V8 事件存储字段，生成安全的系统表 V8 FormEngine 查询，或分析工作流、SaaS、权限、菜单、接口引擎、数据源和系统配置结构。
+description: Microi 吾码数据库结构与字典指南。用于通过实时 MCP Schema 或当前租户快照检查 Microi 平台表，梳理 diy_table/diy_field/sys_menu 关系，定位 V8 事件存储字段，生成安全的系统表 V8 FormEngine 查询，或分析工作流、SaaS、权限、菜单、接口引擎、数据源和系统配置结构。
 ---
 
 > **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
@@ -11,9 +11,9 @@ description: Microi 吾码数据库结构与字典指南。用于通过实时 MC
 
 ## 快速流程
 
-1. 优先调用 `microi_get_db_schema` 获取当前服务器的实时表结构；无法连接时才读取当前引擎所属 OsClient 目录的 `.microi-db-schema.md`，并明确说明快照可能过期。`references/schema.md` 只用于理解通用关系，不是任何租户的权威字段清单。
+1. 优先调用 `microi_get_db_schema` 获取当前服务器的实时表结构；无法连接时才读取当前引擎所属 OsClient 目录的 `.microi-db-schema.md`，并明确说明快照可能过期。`references/schema.md` 只用于理解通用关系，不是任何租户的权威字段清单。
 2. 编写感知结构的 V8 代码时，优先使用带 `_Where` 的 `V8.FormEngine`。只有联表、聚合或 FormEngine 无法表达的场景才使用 `V8.Db.FromSql`，并且必须参数化动态值。
-3. 实时 MCP Schema 是字段事实源；本地 `.microi-db-schema.md` 仅作离线快照。不要假设普通用户拥有某个仓库专属数据库文件。DIY 表还带有固定系统字段（`Id`、`CreateTime`、`UpdateTime`、`UserId`、`UserName`、`IsDeleted`）。
+3. 实时 MCP Schema 是字段事实源；本地 `.microi-db-schema.md` 仅作离线快照。不要假设普通用户拥有某个仓库专属数据库文件。DIY 表还带有固定系统字段（`Id`、`CreateTime`、`UpdateTime`、`UserId`、`UserName`、`IsDeleted`）。
 
 ## 核心模型
 
@@ -113,9 +113,9 @@ AI 或 MCP 生成低代码系统时，必须默认遵守此规则。发现已有
   并把真实外键放在子表。不得创建主表 `XxxId` 后用 `JoinForm` 冒充子表。
 - `JoinForm` 仅用于主表保存一个目标 Id 并嵌入一条独立目标记录；目标表不能与当前表相同。
   关系基数不明确时，MCP 写入前必须询问，不能把 `JoinForm` 当安全默认值。
-- 子表外键必须建立与物理租户隔离方式一致的回查索引：物理表存在 `OsClient` 时通常为
-  `(OsClient, ParentId)`，独立租户物理表没有 `OsClient` 时为 `(ParentId)`。结构或索引读取失败
-  必须拒绝关系配置，不能为了通过校验新增不存在业务语义的 `OsClient` 列。子表还要有绑定同一子表的隐藏菜单，
+- 子表外键必须建立与物理租户隔离方式一致的回查索引：物理表存在 `OsClient` 时通常为
+  `(OsClient, ParentId)`，独立租户物理表没有 `OsClient` 时为 `(ParentId)`。结构或索引读取失败
+  必须拒绝关系配置，不能为了通过校验新增不存在业务语义的 `OsClient` 列。子表还要有绑定同一子表的隐藏菜单，
   `Display=0`、`AppDisplay=0`、`HasChild=0`。
 - Manifest/蓝图审查时，只要发现 1:N 关系对应 `JoinForm`、缺少子表外键、缺少隐藏子菜单
   或缺少回查索引，就必须判定计划不合格，停止写入。

package/skills/microi-db-schema/references/core-tables.md

@@ -153,11 +153,11 @@ Use this reference when exact field names are needed for core platform configura
 | `SelectFields` | 查询列 | `mediumtext` | `JsonTable` | 指定select哪些列，不指定则是select * |
 | `SortFieldIds` | 可排序字段 | `mediumtext` | `MultipleSelect` | 可排序字段 |
 | `DelCodeShowV8` | [删除]按钮显示条件 | `mediumtext` | `CodeEditor` | [删除]按钮显示条件 |
-| `DiyConfig` | 已废弃 | `mediumtext` | `CodeEditor` | 仅兼容历史数据，禁止写入新配置 |
-| `EnableViewSchema` | 启用跨端视图 | `int` | `Switch` | 1 表示启用 `ViewSchema` |
-| `ViewSchemaVersion` | 视图协议版本 | `varchar(25)` | `Text` | 当前协议语义版本 |
-| `ViewConfigVersion` | 视图配置版本 | `int` | `NumberText` | 每次发布配置时递增 |
-| `ViewSchema` | 模块展示设计器 | `mediumtext` | `DevComponent` | 可视化配置 List/Card，保存 Detail/Edit/List/Card 的版本化 JSON |
+| `DiyConfig` | 已废弃 | `mediumtext` | `CodeEditor` | 仅兼容历史数据，禁止写入新配置 |
+| `EnableViewSchema` | 启用跨端视图 | `int` | `Switch` | 1 表示启用 `ViewSchema` |
+| `ViewSchemaVersion` | 视图协议版本 | `varchar(25)` | `Text` | 当前协议语义版本 |
+| `ViewConfigVersion` | 视图配置版本 | `int` | `NumberText` | 每次发布配置时递增 |
+| `ViewSchema` | 模块展示设计器 | `mediumtext` | `DevComponent` | 可视化配置 List/Card，保存 Detail/Edit/List/Card 的版本化 JSON |
 | `Url` | Url地址 | `varchar(500)` | `Text` | Url地址 |
 | `IconClass` | 图标 | `varchar(500)` | `FontAwesome` | 图标 |
 | `EditCodeShowV8` | [编辑]按钮显示条件 | `mediumtext` | `CodeEditor` | [编辑]按钮显示条件 |
@@ -356,17 +356,17 @@ Use this reference when exact field names are needed for core platform configura
 
 ### `sys_osclients` - OsClients
 
-字段数：98
-
-| 字段 | 标签 | 类型 | 控件 | 说明 |
-|---|---|---|---|---|
-| `DisableFileUpload` | 关闭文件上传 | `int` | `Switch` | 默认关闭且允许上传；只有 `1/true` 才禁止当前租户交互式上传。旧 `FileUploadEnabled` 仅作未升级节点兼容并在新版表单隐藏。 |
-| `FileUploadMaxFileMB` | 单文件上限MB | `int` | `NumberText` | 租户业务值；留空依次使用环境变量、appsettings、代码默认值，最终受独立 Absolute/HTTP 上限保护。 |
-| `FileUploadMaxRequestMB` | 单次总量上限MB | `int` | `NumberText` | 租户一次上传全部文件的业务合计；留空按回退链取值，最终受独立 Absolute/HTTP 上限保护。 |
-| `FileUploadMaxCount` | 单次文件数上限 | `int` | `NumberText` | 租户业务值；必须为正整数，留空按回退链取值，最终受 AbsoluteMaxFileCount 保护。 |
-| `FileUploadDailyUserQuotaMB` | 账号日额度MB | `int` | `NumberText` | 留空使用平台默认额度；按 UTC 日期、当前租户和账号在共享 Redis 原子统计。 |
-| `FileUploadDailyTenantQuotaMB` | 租户日额度MB | `int` | `NumberText` | 留空使用平台默认额度；按 UTC 日期和当前租户在共享 Redis 原子统计。 |
-| `MqttEnable` | 启用MQTT | `int` | `Switch` | 注意只有主库对应的SaaS引擎这一条数据MQTT配置的【MQTT端口】才有效果，其它租户SaaS引擎中的MQTT配置中【启用MQTT、用户名、密码、接口引擎】有效。 |
+字段数：98
+
+| 字段 | 标签 | 类型 | 控件 | 说明 |
+|---|---|---|---|---|
+| `DisableFileUpload` | 关闭文件上传 | `int` | `Switch` | 默认关闭且允许上传；只有 `1/true` 才禁止当前租户交互式上传。旧 `FileUploadEnabled` 仅作未升级节点兼容并在新版表单隐藏。 |
+| `FileUploadMaxFileMB` | 单文件上限MB | `int` | `NumberText` | 租户业务值；留空依次使用环境变量、appsettings、代码默认值，最终受独立 Absolute/HTTP 上限保护。 |
+| `FileUploadMaxRequestMB` | 单次总量上限MB | `int` | `NumberText` | 租户一次上传全部文件的业务合计；留空按回退链取值，最终受独立 Absolute/HTTP 上限保护。 |
+| `FileUploadMaxCount` | 单次文件数上限 | `int` | `NumberText` | 租户业务值；必须为正整数，留空按回退链取值，最终受 AbsoluteMaxFileCount 保护。 |
+| `FileUploadDailyUserQuotaMB` | 账号日额度MB | `int` | `NumberText` | 留空使用平台默认额度；按 UTC 日期、当前租户和账号在共享 Redis 原子统计。 |
+| `FileUploadDailyTenantQuotaMB` | 租户日额度MB | `int` | `NumberText` | 留空使用平台默认额度；按 UTC 日期和当前租户在共享 Redis 原子统计。 |
+| `MqttEnable` | 启用MQTT | `int` | `Switch` | 注意只有主库对应的SaaS引擎这一条数据MQTT配置的【MQTT端口】才有效果，其它租户SaaS引擎中的MQTT配置中【启用MQTT、用户名、密码、接口引擎】有效。 |
 | `MqttApiEngine` | 接口引擎 | `varchar(100)` | `Select` | 服务器端启动时、客户端连接时/发送消息时/断开连接时均触发。EventName：StartServer、Connected、Disconnected、MessageReceived、StopServer |
 | `MqttPort` | MQTT端口 | `int` | `NumberText` | 默认1883，注意api的编排ports参数必须添加对应的如- "1883:1883"。<br>注意只有主库对应的SaaS引擎这一条数据MQTT配置的【MQTT端口】才有效果，其它租户SaaS引擎中的MQTT配置中【启用MQTT、用户名、密码、接口引擎】有效。 |
 | `MqttAccount` | 用户名 | `varchar(50)` | `Text` | 用户名 |
@@ -406,12 +406,12 @@ Use this reference when exact field names are needed for core platform configura
 | `OsClientType` | OsClientType | `varchar(50)` | `Text` | SaaS引擎软件环境，自定义值，示例：Product（正式环境））、Dev（测试环境）、WZ（外帐） |
 | `TencentAppId` | TencentAppId | `varchar(50)` | `Text` | TencentAppId |
 | `DbVersion` | 数据库版本 | `varchar(50)` | `Text` | 如：12c、11g |
-| `OsClient` | OsClient | `varchar(50)` | `Text` | SaaS引擎Key，自定义值，建议全小写字母。示例：tenant_a、tenant_demo、demo01 |
+| `OsClient` | OsClient | `varchar(50)` | `Text` | SaaS引擎Key，自定义值，建议全小写字母。示例：tenant_a、tenant_demo、demo01 |
 | `AliOssPrivateAccessKeyId` | 阿里云私有桶Key | `varchar(50)` | `Text` | 阿里云私有桶Key |
 | `ClientSecrets` | Token密钥 | `varchar(50)` | `Text` | 废弃字段 |
 | `MQVitrualHost` | VitrualHost | `varchar(50)` | `Text` | VitrualHost |
 | `DbReadConn` | 数据库连接字符串（读） | `varchar(500)` | `Text` | 为空则取DbConn |
-| `CorsAllowOrigins` | 跨域配置 | `mediumtext` | `Textarea` | 主租户此字段为空时默认允许任意来源；填写后按精确来源或通配符收紧，`CorsAllowAnyWhenUnconfigured` 可调整未配置时的兼容行为。示例：http://localhost:2009;https://os.itdos.com;https://*.microi.net。CORS 不是鉴权边界。 |
+| `CorsAllowOrigins` | 跨域配置 | `mediumtext` | `Textarea` | 主租户此字段为空时默认允许任意来源；填写后按精确来源或通配符收紧，`CorsAllowAnyWhenUnconfigured` 可调整未配置时的兼容行为。示例：http://localhost:2009;https://os.itdos.com;https://*.microi.net。CORS 不是鉴权边界。 |
 | `SessionAuthTimeout` | Token过期时间（PC） | `varchar(50)` | `Text` | 单位：分钟，默认20分钟 |
 | `MQUserName` | 用户名 | `varchar(50)` | `Text` | 用户名 |
 | `DomainName` | 域名 | `mediumtext` | `Text` | 多个域名使用英文分号分割，移动端建议使用m-开头。 |

package/skills/microi-db-schema/references/form-component-options.md

@@ -1,256 +1,256 @@
-# Microi 表单组件配置项参考
-
-本参考用于 AI 生成、审查或修复 `diy_field.Config`。事实源仍是 `Microi.Client/src/views/form-engine/diy-field-component/` 与 `diy-component-list.json`；组件源码新增配置时，必须同步更新本文件和官方文档。
-
-## 字段级元数据
-
-| 字段 | 说明 |
-| --- | --- |
-| `Label` / `Name` | 显示名 / 物理字段名。`Name` 使用 PascalCase 或既有表字段名，不写中文。 |
-| `Type` | 物理列类型，只使用平台允许类型：`varchar(N)`、`mediumtext`、`longtext`、`int`、`bigint`、`decimal(18,N)`。日期时间存 `varchar(25)`。 |
-| `Component` | 控件类型，例如 `Text`、`Select`、`TableChild`。 |
-| `NotEmpty` / `Readonly` | 必填、只读。 |
-| `Visible` / `AppVisible` | PC / App 是否显示，默认业务字段为 `1`。 |
-| `TableWidth` / `FormWidth` | 列表宽度 / 表单栅格宽度。普通字段一般不设置 `FormWidth`；上传、富文本、代码、地图、子表等整行控件设 `24`。 |
-| `Data` | 选项类控件静态数据，常用 KeyValue：`key|label,key2|label2`。 |
-| `DefaultValue` / `Placeholder` / `Tab` | 默认值、占位提示、表单 Tab 分组。 |
-| `V8Code` / `KeyupV8Code` / `V8TmpEngineTable` / `V8TmpEngineForm` | 字段前端事件或 V8 模板代码。代码必须格式化，不要写成单行。 |
-
-## 通用 `Config` 根节点
-
-| 配置 | 说明 |
-| --- | --- |
-| `EnableSearch` | 是否作为搜索条件。 |
-| `ParamData` | 组件请求或 V8 使用的附加参数。 |
-| `Sql` | SQL 数据源查询语句。动态值使用平台占位或后端参数化规则，不拼接用户输入。 |
-| `DataSource` | 数据源类型：`Data`、`KeyValue`、`Sql`、`ApiEngine`、`DataSource` 等。 |
-| `DataSourceSqlRemote` / `DataSourceSqlRemoteLoading` | SQL 是否远程搜索 / 加载态。 |
-| `DataSourceId` / `DataSourceApiEngineKey` | 数据源引擎 Id / 接口引擎 Key。 |
-| `SelectLabel` / `SelectSaveField` | 下拉、树、级联等显示字段 / 保存字段。 |
-| `SelectSaveFormat` | 保存格式，常用 `Text` 或 `Json`。 |
-| `V8Code` / `V8CodeBlur` | 值变更、失焦事件代码。 |
-| `TextIcon` / `TextIconPosition` | 输入框图标与位置。 |
-| `TextApend` / `TextApendPosition` | 输入框前后缀文本与位置。 |
-| `TextShowPassword` / `TextAutocomplete` | 密码显示模式 / 浏览器联想。 |
-| `DateTimeType` | 日期控件类型，如 `date`、`datetime`。 |
-| `DevComponentName` / `DevComponentPath` | 自定义组件名称和路径。 |
-| `MapCompany` | 地图服务商，默认 `Baidu`。 |
-
-## 基础输入类
-
-| 组件 | 推荐类型 | 配置项 |
-| --- | --- | --- |
-| `Text` | `varchar(200)` | 使用通用文本配置：`TextShowPassword`、`TextIcon`、`TextApend`、`V8CodeBlur`。 |
-| `Guid` | `varchar(50)` | 通常只读，用于保存业务关联 GUID。 |
-| `Textarea` | `mediumtext` | `Textarea.DefaultRows` 控制默认行数。 |
-| `NumberText` | `int` 或 `decimal(18,N)` | `NumberTextStep`、`NumberTextPrecision`、`NumberTextMath`、`NumberTextBtn`、`NumberTextBtnPosition`。 |
-| `DateTime` | `varchar(25)` | `DateTimeType` 控制日期、日期时间等模式。 |
-| `Switch` | `int` | 存 `1/0`，不要用 `varchar` 或 `boolean`。 |
-| `Rate` / `Progress` / `Slider` | `int` | 评分、进度、滑块值。 |
-| `ColorPicker` | `varchar(50)` | 保存颜色字符串。 |
-
-## 选项和数据源类
-
-| 组件 | 推荐类型 | 配置项 |
-| --- | --- | --- |
-| `Select` | `varchar(50)` | 必须配置 `Data` 或 `Config.DataSource`；常用 `SelectLabel`、`SelectSaveField`、`SelectSaveFormat`。 |
-| `MultipleSelect` | `varchar(500)` 或 `mediumtext` | 同 `Select`，多选值通常保存 JSON 或分隔文本。 |
-| `Radio` | `varchar(50)` | 必须配置选项数据。 |
-| `Checkbox` | `varchar(500)` 或 `mediumtext` | 必须配置选项数据，多值保存 JSON。 |
-| `Autocomplete` | `varchar(200)` | 可配 SQL/API 数据源，允许输入联想。 |
-| `TagInput` | `mediumtext` | `TagInput.Placeholder`、`TagInput.Options`、`TagInput.MaxCount`。 |
-| `Transfer` | `mediumtext` | `Transfer.LeftTitle`、`Transfer.RightTitle`、`Transfer.Filterable`、`Transfer.Options`。 |
-
-## 布局和说明类
-
-| 组件 | 说明 | 配置项 |
-| --- | --- | --- |
-| `Divider` | 分割线，不保存业务值 | `DividerPosition`、`Divider.Icon`。 |
-| `CollapseGroup` | 折叠分组 | `CollapseGroup.DefaultCollapsed`、`ScopeMode`、`FieldCount`、`UntilNextGroup`、`Description`、`Icon`、`Theme`、`ShowFieldCount`。 |
-| `Tabs` | 字段级页签分组 | `FieldTabs.DefaultActiveKey`、`FieldTabs.Tabs[{Key,Label,Icon,Description}]`。 |
-| `Alert` | 表单提示 | `Alert.Title`、`Content`、`Type`、`Effect`、`ShowIcon`。 |
-| `StaticText` | 静态文本展示 | `StaticText.Content`、样式类配置。 |
-| `Html` | HTML 内容 | 保存 HTML 字符串；注意 XSS 风险。 |
-| `Button` | 表单按钮 | `Button.Type`、`Loading`、`Icon`、`Size`、`PreviewCanClick`、`RefreshTableAfterClick`，点击逻辑写格式化 V8。 |
-
-## 富文本、代码、上传
-
-| 组件 | 推荐类型 | 配置项 |
-| --- | --- | --- |
-| `RichText` | `mediumtext` | 富文本内容，图片上传遵循平台上传配置。 |
-| `CodeEditor` | `mediumtext` | `CodeEditor.Height`；`CodeEditor.DisplayMode=Inline/Dialog`，配置项很多或同页多个代码字段时优先 `Dialog`。 |
-| `JsonTable` | `mediumtext` | JSON 表格展示/编辑，保存结构化 JSON；配置必须写在 `Config.JsonTable`。 |
-| `ImgUpload` | `mediumtext` | `ImgUpload.Limit`、`Multiple`、`Tips`、`MaxCount`、`ShowFileList`、`Preview`、`MaxSize`。 |
-| `FileUpload` | `mediumtext` | `FileUpload.Limit`、`Multiple`、`Tips`、`MaxCount`、`ShowFileList`、`MaxSize`。 |
-| `ImgUpload` / `FileUpload` | - | `Upload.BeforeUploadV8`、`GetPrivateFileBeforeServerV8`、`GetPrivateFileAfterServerV8`。 |
-
-### JsonTable 配置
-
-`JsonTable` 的事实源是 `Microi.Client/src/views/form-engine/diy-field-component/diy-jsontable.vue`。AI 生成字段时不要只写 `Component=JsonTable`，必须同步生成 `Config.JsonTable.Columns`，否则前端只能显示空表。
-
-`Config.JsonTable` 根节点：
-
-| 配置 | 说明 |
-| --- | --- |
-| `Columns` | JSON 表格列数组，必填。每一项描述一列的显示、编辑控件和数据源。 |
-| `DataSource` | 批量导入/候选数据源类型：`KeyValue`、`Sql`、`DataSource`、`ApiEngine` 等。 |
-| `Sql` | `DataSource=Sql` 时的 SQL；远程搜索时必须带 `$Keyword$` 条件和 `limit`。 |
-| `DataSourceId` | `DataSource=DataSource` 时的数据源引擎 Key/Id。 |
-| `ApiEngineKey` / `DataSourceApiEngineKey` | `DataSource=ApiEngine` 时的接口引擎 Key；前端保存到 `ApiEngineKey`，列级配置可用 `DataSourceApiEngineKey`。 |
-| `SelectLabel` | 候选数据展示字段。 |
-| `DataSourceSqlRemote` | 是否远程搜索。大数据量必须设为 `true`。 |
-| `KeyValueList` | 静态键值数据，格式为 `[{ "Key": "A", "Value": "选项A" }]`。 |
-
-`Config.JsonTable.Columns[]` 列对象：
-
-| 配置 | 说明 |
-| --- | --- |
-| `Id` | 列唯一 Id，建议使用 Guid/Ulid。 |
-| `Sort` | 列排序。 |
-| `Label` | 列标题，必填。 |
-| `Key` | JSON 行对象中的属性名，必填，使用英文或既有字段名。 |
-| `Component` | 列编辑控件：`Text`、`Number`、`Textarea`、`Password`、`Select`、`MultipleSelect`、`Radio`、`Checkbox`、`Switch`、`Cascader`、`SelectTree`、`DateTime`、`Rate`、`ColorPicker`、`Progress`、`AutoNumber`、`Autocomplete`、`Address`、`Department`、`Map`、`ImgUpload`、`FileUpload`、`RichText`、`CodeEditor`、`Html`、`Fontawesome`、`Qrcode`、`Divider`、`Button`。 |
-| `Width` / `MinWidth` | 固定宽度 / 最小宽度，`MinWidth` 默认可用 `120`。 |
-| `Required` | 是否必填。 |
-| `Visible` | 是否显示，默认 `true`。 |
-| `DefaultValue` | 新增行默认值。 |
-| `Placeholder` | 占位提示。 |
-| `Readonly` | 是否只读。 |
-| `Config` | 列控件配置。选择类列使用 `SelectLabel`、`SelectSaveField`、`SelectSaveFormat`、`EnableSearch`、`DataSource`、`Sql`、`DataSourceId`、`DataSourceApiEngineKey`、`DataSourceSqlRemote`。 |
-| `Data` | 列级普通静态选项。 |
-| `KeyValueList` | 列级键值选项，格式同根节点。 |
-
-示例：
-
-```json
-{
-  "JsonTable": {
-    "Columns": [
-      {
-        "Id": "col-material",
-        "Sort": 1,
-        "Label": "材料名称",
-        "Key": "MaterialName",
-        "Component": "Text",
-        "MinWidth": 160,
-        "Required": true,
-        "Visible": true,
-        "Placeholder": "请输入材料名称"
-      },
-      {
-        "Id": "col-status",
-        "Sort": 2,
-        "Label": "状态",
-        "Key": "Status",
-        "Component": "Select",
-        "MinWidth": 120,
-        "Visible": true,
-        "Config": {
-          "DataSource": "KeyValue",
-          "SelectLabel": "Value",
-          "SelectSaveField": "Key",
-          "SelectSaveFormat": "Text"
-        },
-        "KeyValueList": [
-          { "Key": "draft", "Value": "草稿" },
-          { "Key": "confirmed", "Value": "已确认" }
-        ]
-      }
-    ]
-  }
-}
-```
-
-## 树、级联、组织
-
-| 组件 | 推荐类型 | 配置项 |
-| --- | --- | --- |
-| `Cascader` | `varchar(500)` 或 `mediumtext` | `Cascader.Lazy`、`Filterable`、`Value`、`Label`、`Children`、`ParentField`、`ParentFields`、`Multiple`、`Disabled`、`Leaf`、`EmitPath`。 |
-| `SelectTree` | `varchar(50)` | `SelectTree.Lazy`、`Filterable`、`Value`、`Label`、`Children`、`ParentField`、`ParentFields`、`Multiple`、`Disabled`、`Leaf`。 |
-| `TreeCheckbox` | `mediumtext` | `TreeCheckbox.DataSourceType`、`DataSourceApi`、`ShowSearch`、`ShowIcon`、`DefaultExpandAll`、`NameColumnWidth`、`NameColumnLabel`、`PermissionColumnLabel`。 |
-| `Department` | `varchar(50)` 或 `varchar(500)` | `Department.Multiple`、`Filterable`、`EmitPath`。 |
-| `Address` | `varchar(500)` | 省市区地址选择，通常保存路径或 JSON。 |
-
-## 弹表、关联表、子表
-
-| 组件 | 推荐类型 | 配置项 |
-| --- | --- | --- |
-| `OpenTable` | `varchar(50)` | `OpenTable.BtnName`、`ShowDialog`、`MultipleSelect`、`BeforeOpenV8`、`SubmitV8`、`SearchAppend`。 |
-| `JoinTable` | `varchar(50)` | `JoinTable.TableId`、`ModuleName`、`ModuleId`、`Where`。 |
-| `JoinForm` | `varchar(50)` | `JoinForm.TableId`、`TableName`、`JoinFieldName`、`Id`、`FormMode`、`_SearchEqual`。主表字段保存一个目标记录 Id。 |
-| `TableChild` | 控件字段通常不承担关系存储 | 根节点：`TableChildTableId`、`TableChildSysMenuId`、`TableChildSysMenuName`、`TableChildFkFieldName`、`TableChildRowClickV8`。真实关系列必须建在子表。 |
-| `TableChild` | - | `TableChild.PrimaryTableFieldName`：主表关联字段，默认 `Id`；`DisablePagination`：子表是否禁用分页；`NoneDefaultHeight`：是否不使用默认高度；`Data`、`SearchAppend`、`LastTableId`、`LastSysMenuId`、`LastSysMenuName`。 |
-| `TableChild` | - | `TableChild.ImportAutoFillFk`：导入子表时自动补外键；`FieldRelations[[Parent,Child,ImportMatch?]]`：全部关系用于新增回写和导入回填，第三位 `true` 的关系用于导入反查主表。 |
-
-### `JoinForm` / `TableChild` 选择门禁
-
-| 业务问题 | 正确组件 |
-| --- | --- |
-| 当前记录保存一个目标 Id，并内嵌该独立目标记录的完整表单 | `JoinForm` |
-| 一条父记录拥有 0..N 条明细，需要列表、分页或多行增删改 | `TableChild` |
-| 只需从列表选择一条/多条，不需要内嵌完整目标表单 | `OpenTable` |
-
-- “明细、子表、清单、条目、行项目、多个记录”默认选择 `TableChild`；基数不清楚时先询问。
-- `JoinForm` 渲染单条 `diy-form`，目标 `TableId/TableName` 必须与当前表不同；指回当前表时
-  组件不会初始化。`JoinFieldName` 是**当前主表中保存目标 Id 的字段名**。
-- `TableChild` 渲染 `diy-table`。子表必须有物理外键，控件必须同时拿到真实的子表 Id、
-  子表菜单 Id 和外键字段名；不得猜 Id 或用 `JoinForm` 代替未完成的两阶段配置。
-- 例：订单商品明细应为 `order_detail.OrderId + TableChild`；工单内嵌一个客户档案才是
-  `work_order.CustomerId + JoinForm`。
-
-### JoinForm 示例
-
-```json
-{
-  "JoinForm": {
-    "TableId": "<目标 diy_table.Id>",
-    "TableName": "",
-    "JoinFieldName": "CustomerId",
-    "FormMode": "View",
-    "Id": "",
-    "_SearchEqual": {}
-  }
-}
-```
-
-字段设计器选择 `TableId` 时会清空 `TableName`；动态配置也可以只给目标 `TableName`，
-二者至少提供一个，不要把当前表作为目标表。
-
-### TableChild 完整示例
-
-```json
-{
-  "TableChildTableId": "01KNRCSVFK2W4NCWYBTVH9HGM2",
-  "TableChildSysMenuId": "01KNRM72C6KBG4S8CY341333XJ",
-  "TableChildSysMenuName": "项目成品清单",
-  "TableChildFkFieldName": "Guid",
-  "TableChild": {
-    "PrimaryTableFieldName": "Id",
-    "Data": [],
-    "SearchAppend": {},
-    "ImportAutoFillFk": true,
-    "FieldRelations": [
-      ["Code", "XiangmuBM", true],
-      ["Name", "XiangmuMC"]
-    ],
-    "LastTableId": "",
-    "LastSysMenuId": "",
-    "LastSysMenuName": "",
-    "DisablePagination": false,
-    "NoneDefaultHeight": false
-  }
-}
-```
-
-`FieldRelations` 每项依次为主表字段、子表字段、可选的导入匹配标记。上例只用编号反查主表，名称仅回填。通过主表子表区域、左右树形页面或 `V8.OpenAnyTable` 带主表条件打开子表后导入时，即使 Excel 没有 `XiangmuBM` / `XiangmuMC`，后端也应根据固定主表行回填外键和展示列。旧三项配置仍由前后端兼容读取，并在字段下次保存时合并清理。
-
-## 地图、二维码、图标、自定义
-
-| 组件 | 推荐类型 | 配置项 |
-| --- | --- | --- |
-| `Map` | `varchar(200)` | 地图点位，使用 `MapCompany`。 |
-| `MapArea` | `mediumtext` | 地图区域，多边形或区域 JSON。 |
-| `Qrcode` | `varchar(500)` | 二维码内容或生成源字段。 |
-| `FontAwesome` | `varchar(100)` | 图标类名。 |
-| `DevComponent` | 视组件而定 | `DevComponentName`、`DevComponentPath`。 |
-| `V8TmpEngine` | `mediumtext` | V8 模板引擎承载控件。 |
+# Microi 表单组件配置项参考
+
+本参考用于 AI 生成、审查或修复 `diy_field.Config`。事实源仍是 `Microi.Client/src/views/form-engine/diy-field-component/` 与 `diy-component-list.json`；组件源码新增配置时，必须同步更新本文件和官方文档。
+
+## 字段级元数据
+
+| 字段 | 说明 |
+| --- | --- |
+| `Label` / `Name` | 显示名 / 物理字段名。`Name` 使用 PascalCase 或既有表字段名，不写中文。 |
+| `Type` | 物理列类型，只使用平台允许类型：`varchar(N)`、`mediumtext`、`longtext`、`int`、`bigint`、`decimal(18,N)`。日期时间存 `varchar(25)`。 |
+| `Component` | 控件类型，例如 `Text`、`Select`、`TableChild`。 |
+| `NotEmpty` / `Readonly` | 必填、只读。 |
+| `Visible` / `AppVisible` | PC / App 是否显示，默认业务字段为 `1`。 |
+| `TableWidth` / `FormWidth` | 列表宽度 / 表单栅格宽度。普通字段一般不设置 `FormWidth`；上传、富文本、代码、地图、子表等整行控件设 `24`。 |
+| `Data` | 选项类控件静态数据，常用 KeyValue：`key|label,key2|label2`。 |
+| `DefaultValue` / `Placeholder` / `Tab` | 默认值、占位提示、表单 Tab 分组。 |
+| `V8Code` / `KeyupV8Code` / `V8TmpEngineTable` / `V8TmpEngineForm` | 字段前端事件或 V8 模板代码。代码必须格式化，不要写成单行。 |
+
+## 通用 `Config` 根节点
+
+| 配置 | 说明 |
+| --- | --- |
+| `EnableSearch` | 是否作为搜索条件。 |
+| `ParamData` | 组件请求或 V8 使用的附加参数。 |
+| `Sql` | SQL 数据源查询语句。动态值使用平台占位或后端参数化规则，不拼接用户输入。 |
+| `DataSource` | 数据源类型：`Data`、`KeyValue`、`Sql`、`ApiEngine`、`DataSource` 等。 |
+| `DataSourceSqlRemote` / `DataSourceSqlRemoteLoading` | SQL 是否远程搜索 / 加载态。 |
+| `DataSourceId` / `DataSourceApiEngineKey` | 数据源引擎 Id / 接口引擎 Key。 |
+| `SelectLabel` / `SelectSaveField` | 下拉、树、级联等显示字段 / 保存字段。 |
+| `SelectSaveFormat` | 保存格式，常用 `Text` 或 `Json`。 |
+| `V8Code` / `V8CodeBlur` | 值变更、失焦事件代码。 |
+| `TextIcon` / `TextIconPosition` | 输入框图标与位置。 |
+| `TextApend` / `TextApendPosition` | 输入框前后缀文本与位置。 |
+| `TextShowPassword` / `TextAutocomplete` | 密码显示模式 / 浏览器联想。 |
+| `DateTimeType` | 日期控件类型，如 `date`、`datetime`。 |
+| `DevComponentName` / `DevComponentPath` | 自定义组件名称和路径。 |
+| `MapCompany` | 地图服务商，默认 `Baidu`。 |
+
+## 基础输入类
+
+| 组件 | 推荐类型 | 配置项 |
+| --- | --- | --- |
+| `Text` | `varchar(200)` | 使用通用文本配置：`TextShowPassword`、`TextIcon`、`TextApend`、`V8CodeBlur`。 |
+| `Guid` | `varchar(50)` | 通常只读，用于保存业务关联 GUID。 |
+| `Textarea` | `mediumtext` | `Textarea.DefaultRows` 控制默认行数。 |
+| `NumberText` | `int` 或 `decimal(18,N)` | `NumberTextStep`、`NumberTextPrecision`、`NumberTextMath`、`NumberTextBtn`、`NumberTextBtnPosition`。 |
+| `DateTime` | `varchar(25)` | `DateTimeType` 控制日期、日期时间等模式。 |
+| `Switch` | `int` | 存 `1/0`，不要用 `varchar` 或 `boolean`。 |
+| `Rate` / `Progress` / `Slider` | `int` | 评分、进度、滑块值。 |
+| `ColorPicker` | `varchar(50)` | 保存颜色字符串。 |
+
+## 选项和数据源类
+
+| 组件 | 推荐类型 | 配置项 |
+| --- | --- | --- |
+| `Select` | `varchar(50)` | 必须配置 `Data` 或 `Config.DataSource`；常用 `SelectLabel`、`SelectSaveField`、`SelectSaveFormat`。 |
+| `MultipleSelect` | `varchar(500)` 或 `mediumtext` | 同 `Select`，多选值通常保存 JSON 或分隔文本。 |
+| `Radio` | `varchar(50)` | 必须配置选项数据。 |
+| `Checkbox` | `varchar(500)` 或 `mediumtext` | 必须配置选项数据，多值保存 JSON。 |
+| `Autocomplete` | `varchar(200)` | 可配 SQL/API 数据源，允许输入联想。 |
+| `TagInput` | `mediumtext` | `TagInput.Placeholder`、`TagInput.Options`、`TagInput.MaxCount`。 |
+| `Transfer` | `mediumtext` | `Transfer.LeftTitle`、`Transfer.RightTitle`、`Transfer.Filterable`、`Transfer.Options`。 |
+
+## 布局和说明类
+
+| 组件 | 说明 | 配置项 |
+| --- | --- | --- |
+| `Divider` | 分割线，不保存业务值 | `DividerPosition`、`Divider.Icon`。 |
+| `CollapseGroup` | 折叠分组 | `CollapseGroup.DefaultCollapsed`、`ScopeMode`、`FieldCount`、`UntilNextGroup`、`Description`、`Icon`、`Theme`、`ShowFieldCount`。 |
+| `Tabs` | 字段级页签分组 | `FieldTabs.DefaultActiveKey`、`FieldTabs.Tabs[{Key,Label,Icon,Description}]`。 |
+| `Alert` | 表单提示 | `Alert.Title`、`Content`、`Type`、`Effect`、`ShowIcon`。 |
+| `StaticText` | 静态文本展示 | `StaticText.Content`、样式类配置。 |
+| `Html` | HTML 内容 | 保存 HTML 字符串；注意 XSS 风险。 |
+| `Button` | 表单按钮 | `Button.Type`、`Loading`、`Icon`、`Size`、`PreviewCanClick`、`RefreshTableAfterClick`，点击逻辑写格式化 V8。 |
+
+## 富文本、代码、上传
+
+| 组件 | 推荐类型 | 配置项 |
+| --- | --- | --- |
+| `RichText` | `mediumtext` | 富文本内容，图片上传遵循平台上传配置。 |
+| `CodeEditor` | `mediumtext` | `CodeEditor.Height`；`CodeEditor.DisplayMode=Inline/Dialog`，配置项很多或同页多个代码字段时优先 `Dialog`。 |
+| `JsonTable` | `mediumtext` | JSON 表格展示/编辑，保存结构化 JSON；配置必须写在 `Config.JsonTable`。 |
+| `ImgUpload` | `mediumtext` | `ImgUpload.Limit`、`Multiple`、`Tips`、`MaxCount`、`ShowFileList`、`Preview`、`MaxSize`。 |
+| `FileUpload` | `mediumtext` | `FileUpload.Limit`、`Multiple`、`Tips`、`MaxCount`、`ShowFileList`、`MaxSize`。 |
+| `ImgUpload` / `FileUpload` | - | `Upload.BeforeUploadV8`、`GetPrivateFileBeforeServerV8`、`GetPrivateFileAfterServerV8`。 |
+
+### JsonTable 配置
+
+`JsonTable` 的事实源是 `Microi.Client/src/views/form-engine/diy-field-component/diy-jsontable.vue`。AI 生成字段时不要只写 `Component=JsonTable`，必须同步生成 `Config.JsonTable.Columns`，否则前端只能显示空表。
+
+`Config.JsonTable` 根节点：
+
+| 配置 | 说明 |
+| --- | --- |
+| `Columns` | JSON 表格列数组，必填。每一项描述一列的显示、编辑控件和数据源。 |
+| `DataSource` | 批量导入/候选数据源类型：`KeyValue`、`Sql`、`DataSource`、`ApiEngine` 等。 |
+| `Sql` | `DataSource=Sql` 时的 SQL；远程搜索时必须带 `$Keyword$` 条件和 `limit`。 |
+| `DataSourceId` | `DataSource=DataSource` 时的数据源引擎 Key/Id。 |
+| `ApiEngineKey` / `DataSourceApiEngineKey` | `DataSource=ApiEngine` 时的接口引擎 Key；前端保存到 `ApiEngineKey`，列级配置可用 `DataSourceApiEngineKey`。 |
+| `SelectLabel` | 候选数据展示字段。 |
+| `DataSourceSqlRemote` | 是否远程搜索。大数据量必须设为 `true`。 |
+| `KeyValueList` | 静态键值数据，格式为 `[{ "Key": "A", "Value": "选项A" }]`。 |
+
+`Config.JsonTable.Columns[]` 列对象：
+
+| 配置 | 说明 |
+| --- | --- |
+| `Id` | 列唯一 Id，建议使用 Guid/Ulid。 |
+| `Sort` | 列排序。 |
+| `Label` | 列标题，必填。 |
+| `Key` | JSON 行对象中的属性名，必填，使用英文或既有字段名。 |
+| `Component` | 列编辑控件：`Text`、`Number`、`Textarea`、`Password`、`Select`、`MultipleSelect`、`Radio`、`Checkbox`、`Switch`、`Cascader`、`SelectTree`、`DateTime`、`Rate`、`ColorPicker`、`Progress`、`AutoNumber`、`Autocomplete`、`Address`、`Department`、`Map`、`ImgUpload`、`FileUpload`、`RichText`、`CodeEditor`、`Html`、`Fontawesome`、`Qrcode`、`Divider`、`Button`。 |
+| `Width` / `MinWidth` | 固定宽度 / 最小宽度，`MinWidth` 默认可用 `120`。 |
+| `Required` | 是否必填。 |
+| `Visible` | 是否显示，默认 `true`。 |
+| `DefaultValue` | 新增行默认值。 |
+| `Placeholder` | 占位提示。 |
+| `Readonly` | 是否只读。 |
+| `Config` | 列控件配置。选择类列使用 `SelectLabel`、`SelectSaveField`、`SelectSaveFormat`、`EnableSearch`、`DataSource`、`Sql`、`DataSourceId`、`DataSourceApiEngineKey`、`DataSourceSqlRemote`。 |
+| `Data` | 列级普通静态选项。 |
+| `KeyValueList` | 列级键值选项，格式同根节点。 |
+
+示例：
+
+```json
+{
+  "JsonTable": {
+    "Columns": [
+      {
+        "Id": "col-material",
+        "Sort": 1,
+        "Label": "材料名称",
+        "Key": "MaterialName",
+        "Component": "Text",
+        "MinWidth": 160,
+        "Required": true,
+        "Visible": true,
+        "Placeholder": "请输入材料名称"
+      },
+      {
+        "Id": "col-status",
+        "Sort": 2,
+        "Label": "状态",
+        "Key": "Status",
+        "Component": "Select",
+        "MinWidth": 120,
+        "Visible": true,
+        "Config": {
+          "DataSource": "KeyValue",
+          "SelectLabel": "Value",
+          "SelectSaveField": "Key",
+          "SelectSaveFormat": "Text"
+        },
+        "KeyValueList": [
+          { "Key": "draft", "Value": "草稿" },
+          { "Key": "confirmed", "Value": "已确认" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## 树、级联、组织
+
+| 组件 | 推荐类型 | 配置项 |
+| --- | --- | --- |
+| `Cascader` | `varchar(500)` 或 `mediumtext` | `Cascader.Lazy`、`Filterable`、`Value`、`Label`、`Children`、`ParentField`、`ParentFields`、`Multiple`、`Disabled`、`Leaf`、`EmitPath`。 |
+| `SelectTree` | `varchar(50)` | `SelectTree.Lazy`、`Filterable`、`Value`、`Label`、`Children`、`ParentField`、`ParentFields`、`Multiple`、`Disabled`、`Leaf`。 |
+| `TreeCheckbox` | `mediumtext` | `TreeCheckbox.DataSourceType`、`DataSourceApi`、`ShowSearch`、`ShowIcon`、`DefaultExpandAll`、`NameColumnWidth`、`NameColumnLabel`、`PermissionColumnLabel`。 |
+| `Department` | `varchar(50)` 或 `varchar(500)` | `Department.Multiple`、`Filterable`、`EmitPath`。 |
+| `Address` | `varchar(500)` | 省市区地址选择，通常保存路径或 JSON。 |
+
+## 弹表、关联表、子表
+
+| 组件 | 推荐类型 | 配置项 |
+| --- | --- | --- |
+| `OpenTable` | `varchar(50)` | `OpenTable.BtnName`、`ShowDialog`、`MultipleSelect`、`BeforeOpenV8`、`SubmitV8`、`SearchAppend`。 |
+| `JoinTable` | `varchar(50)` | `JoinTable.TableId`、`ModuleName`、`ModuleId`、`Where`。 |
+| `JoinForm` | `varchar(50)` | `JoinForm.TableId`、`TableName`、`JoinFieldName`、`Id`、`FormMode`、`_SearchEqual`。主表字段保存一个目标记录 Id。 |
+| `TableChild` | 控件字段通常不承担关系存储 | 根节点：`TableChildTableId`、`TableChildSysMenuId`、`TableChildSysMenuName`、`TableChildFkFieldName`、`TableChildRowClickV8`。真实关系列必须建在子表。 |
+| `TableChild` | - | `TableChild.PrimaryTableFieldName`：主表关联字段，默认 `Id`；`DisablePagination`：子表是否禁用分页；`NoneDefaultHeight`：是否不使用默认高度；`Data`、`SearchAppend`、`LastTableId`、`LastSysMenuId`、`LastSysMenuName`。 |
+| `TableChild` | - | `TableChild.ImportAutoFillFk`：导入子表时自动补外键；`FieldRelations[[Parent,Child,ImportMatch?]]`：全部关系用于新增回写和导入回填，第三位 `true` 的关系用于导入反查主表。 |
+
+### `JoinForm` / `TableChild` 选择门禁
+
+| 业务问题 | 正确组件 |
+| --- | --- |
+| 当前记录保存一个目标 Id，并内嵌该独立目标记录的完整表单 | `JoinForm` |
+| 一条父记录拥有 0..N 条明细，需要列表、分页或多行增删改 | `TableChild` |
+| 只需从列表选择一条/多条，不需要内嵌完整目标表单 | `OpenTable` |
+
+- “明细、子表、清单、条目、行项目、多个记录”默认选择 `TableChild`；基数不清楚时先询问。
+- `JoinForm` 渲染单条 `diy-form`，目标 `TableId/TableName` 必须与当前表不同；指回当前表时
+  组件不会初始化。`JoinFieldName` 是**当前主表中保存目标 Id 的字段名**。
+- `TableChild` 渲染 `diy-table`。子表必须有物理外键，控件必须同时拿到真实的子表 Id、
+  子表菜单 Id 和外键字段名；不得猜 Id 或用 `JoinForm` 代替未完成的两阶段配置。
+- 例：订单商品明细应为 `order_detail.OrderId + TableChild`；工单内嵌一个客户档案才是
+  `work_order.CustomerId + JoinForm`。
+
+### JoinForm 示例
+
+```json
+{
+  "JoinForm": {
+    "TableId": "<目标 diy_table.Id>",
+    "TableName": "",
+    "JoinFieldName": "CustomerId",
+    "FormMode": "View",
+    "Id": "",
+    "_SearchEqual": {}
+  }
+}
+```
+
+字段设计器选择 `TableId` 时会清空 `TableName`；动态配置也可以只给目标 `TableName`，
+二者至少提供一个，不要把当前表作为目标表。
+
+### TableChild 完整示例
+
+```json
+{
+  "TableChildTableId": "01KNRCSVFK2W4NCWYBTVH9HGM2",
+  "TableChildSysMenuId": "01KNRM72C6KBG4S8CY341333XJ",
+  "TableChildSysMenuName": "项目成品清单",
+  "TableChildFkFieldName": "Guid",
+  "TableChild": {
+    "PrimaryTableFieldName": "Id",
+    "Data": [],
+    "SearchAppend": {},
+    "ImportAutoFillFk": true,
+    "FieldRelations": [
+      ["Code", "XiangmuBM", true],
+      ["Name", "XiangmuMC"]
+    ],
+    "LastTableId": "",
+    "LastSysMenuId": "",
+    "LastSysMenuName": "",
+    "DisablePagination": false,
+    "NoneDefaultHeight": false
+  }
+}
+```
+
+`FieldRelations` 每项依次为主表字段、子表字段、可选的导入匹配标记。上例只用编号反查主表，名称仅回填。通过主表子表区域、左右树形页面或 `V8.OpenAnyTable` 带主表条件打开子表后导入时，即使 Excel 没有 `XiangmuBM` / `XiangmuMC`，后端也应根据固定主表行回填外键和展示列。旧三项配置仍由前后端兼容读取，并在字段下次保存时合并清理。
+
+## 地图、二维码、图标、自定义
+
+| 组件 | 推荐类型 | 配置项 |
+| --- | --- | --- |
+| `Map` | `varchar(200)` | 地图点位，使用 `MapCompany`。 |
+| `MapArea` | `mediumtext` | 地图区域，多边形或区域 JSON。 |
+| `Qrcode` | `varchar(500)` | 二维码内容或生成源字段。 |
+| `FontAwesome` | `varchar(100)` | 图标类名。 |
+| `DevComponent` | 视组件而定 | `DevComponentName`、`DevComponentPath`。 |
+| `V8TmpEngine` | `mediumtext` | V8 模板引擎承载控件。 |