@microi.net/cli 4.6.2

package/dist/microi.skills/microi-form-engine/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: microi-form-engine
+description: Microi 表单引擎设计与控件配置指南。用于创建或修改 diy_table、diy_field、表单组件、字段属性、选项/SQL/数据源引擎数据源、子表、关联表单、定制组件、表单布局和字段事件。
+---
+
+# Microi 表单引擎设计
+
+表单引擎同时驱动数据模型、表单、列表、模块、接口配置和工作流配置。处理“新增字段”
+不能只做物理 `ALTER TABLE`：必须让 `diy_table`、`diy_field`、物理列、组件
+Config/Data、菜单查询列与缓存保持一致。
+
+平台创建 DIY 表时会自动加入 `DiyCommon.FixedDiyField` 定义的 Id、创建/更新时间、
+创建人、租户等固定字段。业务 Manifest 不重复声明这些字段；读取 `db.json` 时也不能
+因为 `_Fields` 只列出可配置字段，就误判物理表缺少固定字段。
+
+## 必读参考
+
+- 控件完整目录、推荐物理类型和选择规则：`references/component-catalog.md`
+- 数据源、字段属性、事件与定制组件：`references/data-source-events.md`
+- 表单分组与宽度：`../microi-form-layout/SKILL.md`
+- 后端表单事件：`../v8-table-event/SKILL.md`
+- 前端字段事件：`../v8-frontend-events/SKILL.md`
+
+## 标准工作流
+
+1. 先通过 `microi_get_db_schema` 读取目标租户的真实表、字段和菜单。
+2. 从当前源码
+   `Microi.Client/src/views/form-engine/diy-field-component/diy-component-list.json`
+   核对控件名；官网页面可能含历史控件。
+3. 新表用 `microi_create_table`；字段用 `microi_add_field`，不得直接写
+   `diy_field` 或执行临时 DDL。
+4. 选项控件同时设置 `data/config`；关联控件明确保存字段和显示字段。
+5. 字段多时设置 `diy_table.Tabs` 与字段 `Tab`；只有整行控件设置
+   `FormWidth=24`，普通字段省略。
+6. 绑定菜单后补齐/允许平台推断列表列、搜索列、隐藏列、排序列、移动端列和默认排序。
+7. 回读 `diy_field`、刷新 schema 缓存，再在真实新增/编辑/查看表单中验收。
+
+## 物理类型底线
+
+MCP 建模只使用：
+
+- `varchar(N)`
+- `mediumtext` / `longtext`
+- `int` / `bigint`
+- `decimal(18,N)`
+
+日期时间用 `varchar(25)` 保存 `yyyy-MM-dd HH:mm:ss`，组件用 `DateTime`；
+开关用 `int`。不得生成 `datetime/date/timestamp/float/double/boolean/bool/string/text/nvarchar`。
+前端设计器 JSON 中的历史默认类型不能覆盖服务器建模规则。
+
+## 选项字段
+
+`Select`、`MultipleSelect`、`Radio`、`Checkbox` 没有数据源时会显示空选项：
+
+```text
+1|启用,0|禁用
+```
+
+推荐保存稳定 Key、显示可翻译 Label。修改 `Data/Config/KeyValue` 后必须
+`microi_get_field_list` 回读，并执行 `microi_refresh_schema_cache`。
+
+## `JoinForm` 与 `TableChild` 硬性判定
+
+这两个控件都能在表单内显示另一张表，但数据关系和运行组件完全不同，生成表/字段前
+必须先确定基数，不得因为名称里出现“关联”就默认使用 `JoinForm`。
+
+| 判断项 | `JoinForm`（关联表单） | `TableChild`（子表） |
+|---|---|---|
+| 关系 | 当前记录关联**一个**独立目标记录，通常为 N:1 或 1:1 | 一条主表记录拥有 0..N 条明细，标准 1:N |
+| 关系存储 | 主表字段保存目标记录 `Id` | **子表物理外键**保存主表 `Id`/指定主键值 |
+| 界面 | 嵌入一张 `diy-form`，只展示/编辑一条目标记录 | 嵌入一张 `diy-table`，提供明细列表、分页及行级增删改 |
+| 核心配置 | `Config.JoinForm.{TableId,TableName,JoinFieldName,FormMode,Id,_SearchEqual}` | `Config` 根节点的子表/菜单/外键 Id，加 `Config.TableChild` 运行选项 |
+| 目标限制 | 目标表必须与当前表不同；相同则组件拒绝渲染 | 子表应是独立明细表，并通过外键限定到当前父记录 |
+
+### 决策规则（强制）
+
+- 需求出现“子表、明细、清单、条目、行项目、多个、若干条、记录列表”，且没有明确说明
+  “只关联一条已有记录”时，默认建模为 `TableChild`。
+- 只要一条父记录可能有 0..N 条目标记录，或需要在父表单内列表、分页、新增、编辑、删除
+  多行，就必须用 `TableChild`。
+- 只有主表保存一个目标记录 Id、并需要把该独立记录的完整表单嵌入当前表单时，才用
+  `JoinForm`。选择一条记录但无需嵌入完整表单时，优先 `OpenTable`/`Select`。
+- 语义仍不明确时必须在任何 MCP 写入前询问基数；禁止静默退化为 `JoinForm`。
+- 禁止把“明细”设计为主表 `XxxId + JoinForm`；禁止让 `JoinForm.TableId/TableName`
+  指向当前表；禁止把 1:N 外键放在主表。
+- MCP 的组件枚举、Manifest 结构检查或 `dryRun` 即使通过，也不代表关系基数正确；AI 必须
+  单独执行本节语义门禁。
+
+示例：
+
+- “订单包含多个商品明细” → `order_detail.OrderId` + `TableChild`。
+- “访客单包含多件携带物品” → `fk_carry_item.VisitId` + `TableChild`，不能用
+  `GuestId + JoinForm`，也不能把 `JoinForm` 指回 `fk_carry_item` 自己。
+- “工单关联一个客户，并在工单内展开客户档案” → 主表 `CustomerId` + `JoinForm`。
+
+### MCP 创建 `TableChild` 的两阶段流程
+
+1. 创建主表和独立子表；在子表创建真实外键（如 `VisitId varchar(50)`）。
+2. 在子表为回查创建租户组合索引（通常 `(OsClient, VisitId)`），索引写入 Manifest
+   `tables[].indexes`，并以 `microi_get_table_indexes` 回读。
+3. 为子表创建绑定其 `diyTableId` 的隐藏 CRUD 菜单：`Display=0`、`AppDisplay=0`、
+   `HasChild=0`。
+4. 回读真实的子表 `diy_table.Id`、子菜单 `sys_menu.Id` 与子表外键名后，再在主表
+   新增/更新 `Component=TableChild`、`FormWidth=24` 的配置字段。工具还不能在一次
+   Manifest 中解析这些新建 Id 时，必须分两阶段执行；禁止编造 Id 或改用 `JoinForm`。
+5. `TableChild` 控件字段通常只是表单配置位，关系事实存放在子表外键。至少保存：
+
+```json
+{
+  "TableChildTableId": "<子表 diy_table.Id>",
+  "TableChildSysMenuId": "<子表 sys_menu.Id>",
+  "TableChildSysMenuName": "携带物品明细",
+  "TableChildFkFieldName": "VisitId",
+  "TableChild": {
+    "PrimaryTableFieldName": "Id",
+    "Data": [],
+    "SearchAppend": {},
+    "ImportAutoFillFk": true,
+    "FieldRelations": [],
+    "LastTableId": "",
+    "LastSysMenuId": "",
+    "LastSysMenuName": "",
+    "DisablePagination": false,
+    "NoneDefaultHeight": false
+  }
+}
+```
+
+`FieldRelations` 使用紧凑格式 `[["父表字段","子表字段",true?], ...]`。全部关系用于新增回写和导入回填；第三位 `true` 仅标记参与导入反查父表的关系。后端兼容旧三项配置，新版前端会合并去重并在字段下次保存时清除旧键。
+
+`OpenTable` 用于弹出列表选择数据，固定授权范围用 `V8.OpenTableSetWhere`；`JoinTable`
+用于展示关联集合，不能用前端拼接代替数据权限。
+
+### 子表验收与复盘
+
+- 回读主表字段、子表字段、隐藏子菜单和索引，确认配置中的表 Id、菜单 Id、外键名均真实存在。
+- 用父记录 A 新增/编辑/删除多条子记录；打开父记录 B，确认 A 的数据不可见且不可越权操作。
+- 新增主表尚无真实 Id 时，不得产生孤儿子记录；保存后重新打开仍能正确回显。
+- 若曾误选组件，复盘必须记录：触发用语、误判基数、正确关系、应增加的生成前断言；通用结论
+  回写本节，不能只修一张业务表。
+
+## 自定义组件边界
+
+优先使用现有 44 类标准控件。只有标准控件无法表达交互、且该交互会长期复用时，
+才使用 `DevComponent`：
+
+- Vue 组件路径必须稳定并纳入 `Microi.Client` 源码/构建。
+- 支持 Add/Edit/View、只读、必填、清空、校验、移动端和暗色主题。
+- 不在组件内绕过 FormEngine 权限直接访问任意表。
+- 复杂但租户独有的页面优先使用 MicroService + `V8.OpenAppDialog`，避免把客户逻辑打进主前端。
+
+## 验收
+
+- 物理列与 `diy_field` 一致，字段缓存已刷新。
+- 新增、编辑、查看、列表、搜索、导入/导出至少覆盖适用场景。
+- 选项显示 Label、保存 Key，回显和筛选一致。
+- 子表新增/编辑/删除与父表外键正确，不能跨父记录串数据。
+- PC 与移动端字段顺序、Tabs、整行控件无截断。
+- 前端校验只改善体验；绕过前端直接 HTTP 提交时后端事件仍能阻止非法数据。

package/dist/microi.skills/microi-form-engine/references/component-catalog.md

@@ -0,0 +1,116 @@
+# 表单组件目录
+
+控件名称以
+`Microi.Client/src/views/form-engine/diy-field-component/diy-component-list.json`
+为当前事实源；物理类型以服务器/MCP 允许类型为准。
+
+## 基础输入
+
+| Component | 用途 | 推荐物理类型 |
+|---|---|---|
+| `Text` | 单行文本 | `varchar(200)` |
+| `Guid` | GUID/只读标识 | `varchar(50)` |
+| `Textarea` | 多行文本 | `mediumtext` |
+| `NumberText` | 整数/金额/小数 | `int` 或 `decimal(18,2)` |
+| `DateTime` | 日期时间选择 | `varchar(25)` |
+| `Select` | 下拉单选 | `varchar(50)` |
+| `MultipleSelect` | 下拉多选 | `varchar(500)` 或 `mediumtext` |
+| `Radio` | 单选 | `varchar(50)` |
+| `Checkbox` | 多选 | `varchar(500)` 或 `mediumtext` |
+| `Switch` | 0/1 开关 | `int` |
+| `Rate` | 评分 | `int` |
+| `Progress` | 进度展示/输入 | `int` |
+| `Slider` | 滑块 | `int` 或 `decimal(18,2)` |
+| `ColorPicker` | 颜色 | `varchar(50)` |
+| `AutoNumber` | 自动编号 | `varchar(200)` |
+| `Button` | 表单动作按钮 | 通常 `varchar(50)`，不承载核心业务值 |
+
+## 布局与内容
+
+| Component | 用途 | 规则 |
+|---|---|---|
+| `Divider` | 分割线 | 布局字段，不进入关键查询 |
+| `CollapseGroup` | 局部分组折叠 | 先读 `microi-form-layout` |
+| `Tabs` | 字段级页签布局 | 整体多分区优先 `diy_table.Tabs` |
+| `Alert` | 提示说明 | 不承载业务状态 |
+| `StaticText` | 静态文本 | 不承载业务状态 |
+| `Html` | 可信 HTML 展示 | 必须净化，不拼接不可信内容 |
+| `RichText` | 富文本 | `mediumtext`；输出需净化 |
+| `CodeEditor` | 代码/JSON/SQL 编辑 | `mediumtext`；通常 `FormWidth=24` |
+| `JsonTable` | JSON 表格 | `mediumtext`；定义结构与大小上限 |
+
+## 文件与高级输入
+
+| Component | 用途 | 推荐物理类型 |
+|---|---|---|
+| `ImgUpload` | 图片上传 | `mediumtext` |
+| `FileUpload` | 文件上传 | `mediumtext` |
+| `Autocomplete` | 自动完成 | `varchar(200)` |
+| `TagInput` | 标签集合 | `varchar(500)` 或 `mediumtext` |
+| `Transfer` | 穿梭框多选 | `mediumtext` |
+| `Cascader` | 级联选择 | `varchar(500)` |
+| `Address` | 省市区地址 | `varchar(500)` |
+| `Department` | 部门选择 | `varchar(50)` |
+| `SelectTree` | 树形选择 | `varchar(50)` 或 `varchar(500)` |
+| `TreeCheckbox` | 树形权限多选 | `mediumtext` |
+
+## 关联、地图与扩展
+
+| Component | 用途 | 关键约束 |
+|---|---|---|
+| `OpenTable` | 弹出列表选择 | 配置保存字段、显示字段和固定查询范围 |
+| `JoinTable` | 关联集合展示 | 查询与权限在服务端完成 |
+| `JoinForm` | 嵌入一个独立记录的完整表单 | 主表字段保存一个目标 Id；目标表不能与当前表相同 |
+| `TableChild` | 主表内嵌 0..N 条明细列表 | 独立子表、子表真实外键、隐藏子菜单、回查索引 |
+| `Map` | 点位 | `varchar(200)`/`mediumtext`，明确坐标格式 |
+| `MapArea` | 区域 | `mediumtext`，限制点数/体积 |
+| `Qrcode` | 二维码展示 | `varchar(500)` |
+| `FontAwesome` | 图标选择 | `varchar(200)` |
+| `DevComponent` | 主前端定制 Vue 控件 | 仅用于长期复用且标准控件无法满足的场景 |
+
+### `JoinForm` 不是子表
+
+- `JoinForm` 渲染 `diy-form`，通过 `Config.JoinForm.JoinFieldName` 从当前表单取出一个
+  目标记录 Id（也可用固定 `Id` / `_SearchEqual`），因此表达的是“这一条记录关联哪一条
+  独立记录”。当前表和目标表相同会被组件判为无效并拒绝渲染。
+- `TableChild` 渲染 `diy-table`，通过 `Config.TableChildFkFieldName` 把子表列表限定在
+  当前父记录，并依赖 `TableChildTableId` 与 `TableChildSysMenuId` 完成列表和行级增删改。
+- `TableChild` 控件字段通常不承担关系存储；真正的关系列位于子表，例如
+  `order_detail.OrderId`。不得创建主表 `DetailId` 后用 `JoinForm` 冒充明细。
+- 生成前先问“一个父记录最多有几条目标记录”：答案可能大于 1 就选 `TableChild`；只有
+  明确恰好一个目标 Id 且需要嵌入完整目标表单时才选 `JoinForm`。不确定时先询问，不写入。
+
+## 官网历史名称
+
+中文官网可能仍展示 `PhoneSMS`、`Timeline` 等历史/业务扩展控件。生成新字段前
+必须在当前 `diy-component-list.json`、目标租户 `diy_field.Component` 和实际客户端
+中核对；未出现在当前控件清单的名称不得仅凭旧文档直接生成。
+
+## 常用配置键
+
+这些是 `diy_field.Config` 内的配置路径，不是可调用函数；保存后必须回读
+`Config` 并刷新 Schema 缓存：
+
+| 组件族 | 常用配置路径 |
+|---|---|
+| Textarea | `Textarea.DefaultRows` |
+| TagInput | `TagInput.Placeholder`、`TagInput.Options`、`TagInput.MaxCount` |
+| Transfer | `Transfer.LeftTitle`、`Transfer.RightTitle`、`Transfer.Filterable`、`Transfer.Options` |
+| AutoNumber | `AutoNumber.DataRule`、`AutoNumber.CreateRule`，以及 `AutoNumberFixed`、`AutoNumberLength`、`AutoNumberFields` |
+| Button | `Button.Type`、`Button.Icon`、`Button.Size`、`Button.PreviewCanClick`、`Button.RefreshTableAfterClick`、`Button.Loading`（`V8.FieldSet` 时使用 `Config.Button.Loading`） |
+| Divider / StaticText | `Divider.Icon`、`StaticText.Content` |
+| OpenTable | `OpenTable.BtnName`、`OpenTable.MultipleSelect`、`OpenTable.BeforeOpenV8`、`OpenTable.SubmitV8` |
+| CodeEditor / JsonTable | `CodeEditor.Height`、`JsonTable.Columns`、`JsonTable.Columns[].Config` |
+| JoinForm | `JoinForm.TableId`、`JoinForm.TableName`、`JoinForm.JoinFieldName`、`JoinForm.FormMode`、`JoinForm.Id`、`JoinForm._SearchEqual` |
+| TableChild | Config 根节点的 `TableChildTableId`、`TableChildSysMenuId`、`TableChildFkFieldName`；`TableChild.PrimaryTableFieldName`（默认 `Id`）及分页/导入选项 |
+| ImgUpload | `ImgUpload.Multiple`；导出时会按最大图片数展开列 |
+
+其余选择、树、上传、关联和布局选项以当前字段设计器和
+`microi-db-schema/references/form-component-options.md` 为事实源；不要凭旧截图
+发明配置键。
+
+## 宽度与重字段
+
+- 普通 Text、Select、NumberText、DateTime 默认不写 `FormWidth`。
+- Textarea、RichText、CodeEditor、JsonTable、上传、子表、地图、布局和定制组件通常 `FormWidth=24`。
+- 列表默认隐藏上传、富文本、地图、子表、布局等重字段；按需在详情中加载。

package/dist/microi.skills/microi-form-engine/references/data-source-events.md

@@ -0,0 +1,117 @@
+# 字段数据源、属性与事件
+
+## 数据源类型
+
+| 类型 | 适用场景 | 配置要点 |
+|---|---|---|
+| `Data` | 显示值和保存值相同的固定数组 | 适合少量稳定枚举 |
+| `KeyValue` | 保存 Key、显示 Label | 推荐；便于翻译和状态演进 |
+| `Sql` | 基于当前库的受控查询 | 参数化、限制条数、选择明确字段 |
+| `DataSource` | 复用数据源引擎 | 使用稳定 DataSourceId/Key |
+| `ApiEngine` | 复杂权限、跨表或外部数据 | 接口返回稳定的 Label/Value 字段 |
+
+KeyValue 示例：
+
+```text
+draft|草稿,enabled|启用,disabled|禁用
+```
+
+对应核心语义：
+
+```json
+{
+  "DataSource": "KeyValue",
+  "SelectLabel": "Value",
+  "SelectSaveField": "Key"
+}
+```
+
+动态 SQL 示例只选择必要字段并限制返回量：
+
+```json
+{
+  "DataSource": "Sql",
+  "Sql": "select Id,Name from biz_customer where Name like '%$Keyword$%' limit 0,20",
+  "SelectLabel": "Name",
+  "SelectSaveField": "Id",
+  "DataSourceSqlRemote": true
+}
+```
+
+SQL 仍必须经过平台受控数据源；不要把用户文本拼成标识符或任意 SQL。复杂权限、
+跨库或外部服务使用数据源引擎/接口引擎。
+
+## 动态联动
+
+字段值变化时可用前端 V8 更新另一个字段的数据源：
+
+```javascript
+if (V8.LoadMode === 'Design') return;
+
+var result = await V8.FormEngine.GetTableData('biz_contact', {
+  _SelectFields: ['Id', 'Name'],
+  _Where: [['CustomerId', '=', V8.ThisValue]],
+  _PageIndex: 1,
+  _PageSize: 100
+});
+
+V8.FieldSet('ContactId', 'Data', result.Code === 1 ? result.Data : []);
+```
+
+前端联动不能替代后端权限和提交校验。
+
+## 表单生命周期
+
+| 配置 | 运行端 | 用途 |
+|---|---|---|
+| `InFormV8` | 前端 | 默认值、字段显隐、初始化交互 |
+| `SubmitFormV8` | 前端 | 即时校验；HTTP 直调不会触发 |
+| `SubmitBeforeServerV8` | 后端事务内 | 最终校验、加工、阻止提交 |
+| `SubmitAfterServerV8` | 后端事务内 | 同事务联动其它表 |
+| `OutFormV8` | 前端 | 关闭后刷新/跳转 |
+| `DataFilterV8` | 后端 | 每行脱敏/展示加工 |
+
+事件代码、版本和表单属性都必须从当前 `diy_table/diy_field` 回读。后端阻止提交：
+
+```javascript
+if (!V8.Form.Name) return { Code: 0, Msg: '名称不能为空' };
+```
+
+## 字段属性
+
+常用属性包括 `Visible`、`AppVisible`、`Required`、`Readonly`、`Data`、
+`Config`、`FormWidth`、`TableWidth`、`Tab`、角色绑定和前端事件代码。
+
+- 除非明确隐藏，`Visible=1`、`AppVisible=1`。
+- 角色绑定只缩小界面可见性，不能代替服务器数据权限。
+- 修改防抖编辑器/代码字段前必须刷新待保存值，避免最后一次输入未入库。
+- `Data/Config` 修改后回读并刷新 schema 缓存。
+
+## DevComponent 定制组件
+
+定制组件至少处理：
+
+- `value/modelValue` 的输入与变更通知；
+- 当前字段模型、表单模型、表单模式和只读状态；
+- 校验错误、清空、禁用、加载与销毁；
+- Add/Edit/View 回显；
+- PC、移动端和暗色主题；
+- 组件内部请求的 Token/OsClient 传递与错误态。
+
+定制组件需要修改并发布主前端。若只服务单一租户、包含多个字段或复杂页面，
+优先创建 MicroService 页面，通过 `V8.OpenAppDialog` 与宿主交互。
+
+历史 Options API 定制组件可通过宿主 facade 调用数据源引擎：
+
+```javascript
+this.Microi.DataSourceEngine.Run('customer_summary', { Id: customerId }, (result) => {
+  if (this.Microi.CheckResult(result)) {
+    this.summary = result.Data;
+  }
+});
+```
+
+`Microi.DataSourceEngine.Run` 是回调式宿主接口，`Microi.CheckResult` 负责按
+DosResult 约定判断并展示错误。组件卸载后要阻止迟到回调继续写状态；新页面
+优先使用项目现有的组合式 facade，不要假定 `this.Microi` 在任意 Vue 组件中
+都存在。