@microi.net/cli 4.6.4 → 4.6.8

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

@@ -1,165 +1,165 @@
----
-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`，避免把客户逻辑打进主前端。
-
-## 固定审计字段
-
-- `Id`、`CreateTime`、`UpdateTime`、`UserId`、`UserName`、`IsDeleted` 是 DIY 表的正常固定字段。物理列存在时必须有对应 `diy_field` 元数据，不能长期出现在“异常字段修复”列表；`diy_table.DisplayDefaultField` 只控制设计器默认是否显示这些字段，不等于删除元数据。
-- 统一通过平台修复接口或 MCP `microi_repair_audit_fields` 补齐/恢复元数据。修复必须按 `OsClient` 使用共享租约锁，可重复执行，只处理已存在的固定物理列，不借机执行 DDL，并在成功后清理字段缓存。
-- 表格里的创建人、创建时间、修改时间等审计列应与普通字段共用列头高级搜索、权限和格式化逻辑。
-
-## 验收
-
-- 物理列与 `diy_field` 一致，字段缓存已刷新。
-- 新增、编辑、查看、列表、搜索、导入/导出至少覆盖适用场景。
-- 选项显示 Label、保存 Key，回显和筛选一致。
-- 子表新增/编辑/删除与父表外键正确，不能跨父记录串数据。
-- PC 与移动端字段顺序、Tabs、整行控件无截断。
-- 前端校验只改善体验；绕过前端直接 HTTP 提交时后端事件仍能阻止非法数据。
+---
+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`，避免把客户逻辑打进主前端。
+
+## 固定审计字段
+
+- `Id`、`CreateTime`、`UpdateTime`、`UserId`、`UserName`、`IsDeleted` 是 DIY 表的正常固定字段。物理列存在时必须有对应 `diy_field` 元数据，不能长期出现在“异常字段修复”列表；`diy_table.DisplayDefaultField` 只控制设计器默认是否显示这些字段，不等于删除元数据。
+- 统一通过平台修复接口或 MCP `microi_repair_audit_fields` 补齐/恢复元数据。修复必须按 `OsClient` 使用共享租约锁，可重复执行，只处理已存在的固定物理列，不借机执行 DDL，并在成功后清理字段缓存。
+- 表格里的创建人、创建时间、修改时间等审计列应与普通字段共用列头高级搜索、权限和格式化逻辑。
+
+## 验收
+
+- 物理列与 `diy_field` 一致，字段缓存已刷新。
+- 新增、编辑、查看、列表、搜索、导入/导出至少覆盖适用场景。
+- 选项显示 Label、保存 Key，回显和筛选一致。
+- 子表新增/编辑/删除与父表外键正确，不能跨父记录串数据。
+- PC 与移动端字段顺序、Tabs、整行控件无截断。
+- 前端校验只改善体验；绕过前端直接 HTTP 提交时后端事件仍能阻止非法数据。

package/dist/microi.skills/microi-microservice/SKILL.md

@@ -92,6 +92,30 @@ AppKey 稳定且只含安全字符。`microi.routes.json` 是页面事实源，
 Token 只通过宿主上下文传递，不硬编码、不放 URL、不写日志。子应用回传成功/取消/
 错误事件，宿主负责提示、关闭和刷新。
 
+菜单型微服务通过 `window.microApp.getData().hostCapabilities` 发现主框架能力，禁止直接操作
+父页面 DOM、Pinia 或 Vue Router。能力协议固定为 `microi.host.v1`，请求使用：
+
+```js
+window.microApp.dispatch({
+  type: 'micro-app:host-action',
+  action: 'closeTab',
+  requestId: 'optional-id',
+  data: {}
+});
+```
+
+AI 生成菜单微服务时，应优先封装一个 `callMicroiHost(action, data)`，先检查
+`hostCapabilities.actions`，再 dispatch。当前标准动作是：`closeTab`、`navigate`、
+`replaceTab`、`back`、`forward`、`reloadTab`、`setTabTitle`、`showMessage`。
+`navigate/replaceTab` 只传以 `/` 开头的站内 path 或 `{name,params,query,hash}`；禁止传
+外部 URL、登录页、访问密钥页或内部 redirect。目标仍要存在于当前用户动态路由并经过路由守卫，
+宿主桥接不授予菜单或数据权限。业务保存成功后才能关闭/跳转，不能把尽力返回的
+`micro-app:host-action-result` 当作业务持久化确认。
+
+`closeTab` 与 TagsView 当前页签关闭语义一致，固定页签和最后一个页签拒绝关闭；顶部 Tab
+右键刷新与 `reloadTab` 都应重载当前微服务。`OpenAppDialog` 页面不使用 Tab 动作，继续发送
+`app-dialog:success/cancel/error` 关闭弹窗并回传结果。
+
 `sys_microiservice_page` 是友好路由的页面事实源，`sys_menu` 只负责导航和角色权限。
 无需出现在导航中的按钮页/详情页应在页面元数据设置 `InternalOnly=true`，不创建伪隐藏菜单。