@microi.net/cli 5.7.8 → 5.8.0

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

@@ -1,10 +1,10 @@
----
-name: microi-form-engine
-description: Microi 表单引擎设计与控件配置指南。用于创建或修改 diy_table、diy_field、表单组件、字段属性、选项/SQL/数据源引擎数据源、子表、关联表单、定制组件、表单布局和字段事件。
----
-
-> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
-
+---
+name: microi-form-engine
+description: Microi 表单引擎设计与控件配置指南。用于创建或修改 diy_table、diy_field、表单组件、字段属性、选项/SQL/数据源引擎数据源、子表、关联表单、定制组件、表单布局和字段事件。
+---
+
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
+
 # Microi 表单引擎设计
 
 ## 表单设计器生成 Vue 3 代码
@@ -12,23 +12,23 @@ description: Microi 表单引擎设计与控件配置指南。用于创建或修
 保留现有 `Diy` 动态渲染；需要每表独立页面时，在保存设计后使用【生成 Vue 3 代码】。生成器产生 `src/pages/Form_表名.vue`，源码归当前租户 `microi-generated-forms` 微服务私有项目，AI 应用工作台可继续编辑。Vite 构建并发布运行产物后，模块菜单用 `CodeForm`，同时绑定原 `DiyTableId` 与对应微服务路由。生成页经前端 V8 SDK 传 `_SysMenuId` 调用 FormEngine，权限及后端事件继续由服务端校验。
 
 生成器遇到复杂控件、动态数据源、前端 V8 事件/模板或人工修改过的目标源码会停止并显示原因；不要静默删字段或覆盖定制代码。设计器再次变更后重新生成草稿，在源码工作台审阅和合并，再构建发布。源码保存不等于微服务已构建、菜单已切换或目标租户已安装。
-
-表单引擎同时驱动数据模型、表单、列表、模块、接口配置和工作流配置。处理“新增字段”
-不能只做物理 `ALTER TABLE`：必须让 `diy_table`、`diy_field`、物理列、组件
-Config/Data、菜单查询列与缓存保持一致。
-
-平台创建 DIY 表时会自动加入 `DiyCommon.FixedDiyField` 定义的 Id、创建/更新时间、
-创建人、租户等固定字段。业务 Manifest 不重复声明这些字段；读取实时 Schema 或离线快照时也不能
-因为 `_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`
-
+
+表单引擎同时驱动数据模型、表单、列表、模块、接口配置和工作流配置。处理“新增字段”
+不能只做物理 `ALTER TABLE`：必须让 `diy_table`、`diy_field`、物理列、组件
+Config/Data、菜单查询列与缓存保持一致。
+
+平台创建 DIY 表时会自动加入 `DiyCommon.FixedDiyField` 定义的 Id、创建/更新时间、
+创建人、租户等固定字段。业务 Manifest 不重复声明这些字段；读取实时 Schema 或离线快照时也不能
+因为 `_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`
+
 ## 标准工作流
 
 ### 物理字段允许为空（强制）
@@ -36,18 +36,18 @@ Config/Data、菜单查询列与缓存保持一致。
 除作为主键的 `Id` 外，通过 MCP、表单设计器、FormEngine、V8 或应用包新增、修改的普通字段，数据库列一律允许 `NULL`。`NotEmpty` 等业务必填要求只作用于表单/服务端校验，不能生成 `NOT NULL`。默认值和是否允许为空是两项独立属性；兼容旧列时只放宽可空约束，保留类型、有效默认值、字符集、排序规则、注释、索引和历史数据，不以补零/空串替代结构修复。
 
 MySQL 的 `ALTER COLUMN DROP DEFAULT` 会让可空列也在省略字段时报 1364；移除普通标量列的旧默认值应使用 `SET DEFAULT NULL`。`IS_NULLABLE=YES` 和 `COLUMN_DEFAULT=NULL` 不足以证明可省略字段，需要通过 `SELECT DEFAULT(列) FROM 表 LIMIT 0` 验证。TEXT/BLOB 的缺失默认标志应保留完整列定义执行 `MODIFY COLUMN` 修复，不能对它们使用 `ALTER COLUMN SET DEFAULT NULL`。
-
-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`，普通字段省略。`CollapseGroup` 属于整行控件，必须显式保存
-   `FormWidth=24`，且 `Config.CollapseGroup.ShowFieldCount` 默认补为 `true`。
-6. 绑定菜单后补齐/允许平台推断列表列、搜索列、隐藏列、排序列、移动端列和默认排序。
+
+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`，普通字段省略。`CollapseGroup` 属于整行控件，必须显式保存
+   `FormWidth=24`，且 `Config.CollapseGroup.ShowFieldCount` 默认补为 `true`。
+6. 绑定菜单后补齐/允许平台推断列表列、搜索列、隐藏列、排序列、移动端列和默认排序。
 7. 回读 `diy_field`、刷新 schema 缓存，再在真实新增/编辑/查看表单中验收。
 
 ## 原生查询主库策略
@@ -112,164 +112,164 @@ MySQL 的 `ALTER COLUMN DROP DEFAULT` 会让可空列也在省略字段时报 13
 - 图片、文件和富文本上传必须携带 `FormEngineKey + FieldId + SysMenuId`，编辑记录再带
   `FormDataId`，TableChild 再带父子授权上下文。后端不得按用户等级统一覆盖字段的“禁止匿名访问”；
   无法回查字段与动作权限的普通上传才安全降级为私有桶。
-
-新建表/模块时，除非用户显式指定或表单达到极重阈值（约 36+ 业务字段、2+ 子表或同等
-重型控件密度），默认保存 `diy_table.FormOpenType=Dialog` 与 `FormOpenWidth=80%`。
-Drawer 只服务超长复杂表单，不能作为所有 CRUD 模块的模板默认值。
-   若设计器显示而运行态不显示，先检查 `InFormV8`/字段 V8 是否调用
-   `V8.FieldSet(..., 'Visible', false)`、`hideField` 或传入 `HideFields`，再判断前端源码。
-
-## 表单 Banner（所有新业务表必做）
-
-标准表单 Banner 默认显示，以当前主题色约 50% 混合强度叠加深蓝灰渐变，并适配浅色、
-深色与移动端。视觉应有层次但保持清爽，标题始终维持安全对比度；统计卡片使用半透明背景
-和柔和阴影分层，避免堆叠边框。它属于表单语义，配置
-必须写入 `diy_table` 的 `FormBannerEnabled`、`FormBannerTitleField`、
-`FormBannerSubtitleField`、`FormBannerImageField`、`FormBannerIcon`、
-`FormBannerBackgroundField`、`FormBannerTagFields`、`FormBannerMetrics`，禁止写进
-`sys_menu`、`DiyConfig` 或项目定制组件。
-
-- 标题优先业务自动编号/单号/编码，再选名称或标题；副标题优先客户、项目、公司、分类、
-  日期等可读字段。
-- 左侧图片使用 `ImgUpload`。单图、多图取首图，继续遵循吾码公有/私有文件路径与授权
-  规则；图片为空时必须有语义合适的 Font Awesome 图标回退。
-- 右侧标签优先 `Select/Radio/Switch/Checkbox/SelectTree/Department` 等选项字段，最多
-  选择 3 个有业务意义的状态、类型或等级。显式 `[]` 表示不要自动标签。
-- 自动统计最多 3 项，只选择真实金额、合计、数量、成本、余额、评分、比率、进度等具有
-  明确业务口径的数值字段；必须排除 Id、排序、启用、状态、版本、分页和本页加载量。
-  存在 `TableChild` 时，默认统计必须携带完整父表/父字段/父记录授权上下文，在服务端对全部
-  关联子表数据计算行数或业务数值合计，不能只统计当前页。跨表自定义口径使用 `ApiEngineKey +
-  ValuePath + ParamMap + RefreshSeconds`，相同接口批量返回，禁止 N+1、随机数和固定演示数；
-  没有可靠指标时隐藏统计区。显式 `[]` 表示不要自动统计。
-- 兼容旧模块 Hero 时仅迁移视觉、`Source=Field` 或显式记录作用域指标；列表总数、分类数量和
-  未引用当前 `Form/RecordId` 的全局接口统计不得进入单记录 Banner，缺省时回到当前记录和
-  授权 `TableChild` 的语义统计。
+
+新建表/模块时，除非用户显式指定或表单达到极重阈值（约 36+ 业务字段、2+ 子表或同等
+重型控件密度），默认保存 `diy_table.FormOpenType=Dialog` 与 `FormOpenWidth=80%`。
+Drawer 只服务超长复杂表单，不能作为所有 CRUD 模块的模板默认值。
+   若设计器显示而运行态不显示，先检查 `InFormV8`/字段 V8 是否调用
+   `V8.FieldSet(..., 'Visible', false)`、`hideField` 或传入 `HideFields`，再判断前端源码。
+
+## 表单 Banner（所有新业务表必做）
+
+标准表单 Banner 默认显示，以当前主题色约 50% 混合强度叠加深蓝灰渐变，并适配浅色、
+深色与移动端。视觉应有层次但保持清爽，标题始终维持安全对比度；统计卡片使用半透明背景
+和柔和阴影分层，避免堆叠边框。它属于表单语义，配置
+必须写入 `diy_table` 的 `FormBannerEnabled`、`FormBannerTitleField`、
+`FormBannerSubtitleField`、`FormBannerImageField`、`FormBannerIcon`、
+`FormBannerBackgroundField`、`FormBannerTagFields`、`FormBannerMetrics`，禁止写进
+`sys_menu`、`DiyConfig` 或项目定制组件。
+
+- 标题优先业务自动编号/单号/编码，再选名称或标题；副标题优先客户、项目、公司、分类、
+  日期等可读字段。
+- 左侧图片使用 `ImgUpload`。单图、多图取首图，继续遵循吾码公有/私有文件路径与授权
+  规则；图片为空时必须有语义合适的 Font Awesome 图标回退。
+- 右侧标签优先 `Select/Radio/Switch/Checkbox/SelectTree/Department` 等选项字段，最多
+  选择 3 个有业务意义的状态、类型或等级。显式 `[]` 表示不要自动标签。
+- 自动统计最多 3 项，只选择真实金额、合计、数量、成本、余额、评分、比率、进度等具有
+  明确业务口径的数值字段；必须排除 Id、排序、启用、状态、版本、分页和本页加载量。
+  存在 `TableChild` 时，默认统计必须携带完整父表/父字段/父记录授权上下文，在服务端对全部
+  关联子表数据计算行数或业务数值合计，不能只统计当前页。跨表自定义口径使用 `ApiEngineKey +
+  ValuePath + ParamMap + RefreshSeconds`，相同接口批量返回，禁止 N+1、随机数和固定演示数；
+  没有可靠指标时隐藏统计区。显式 `[]` 表示不要自动统计。
+- 兼容旧模块 Hero 时仅迁移视觉、`Source=Field` 或显式记录作用域指标；列表总数、分类数量和
+  未引用当前 `Form/RecordId` 的全局接口统计不得进入单记录 Banner，缺省时回到当前记录和
+  授权 `TableChild` 的语义统计。
 - 未配置的存量表由运行时按字段类型智能推断，不能因为物理字段为空而隐藏或展示空壳。
   只有 `FormBannerEnabled=0` 才隐藏。
 - 字段绑定须区分省略/`NULL` 与显式空字符串：`titleField/subtitleField/imageField/backgroundField`
   省略或 `NULL` 表示未选择，允许兼容推断；显式 `""` 表示不绑定该字段，不能被推断值或旧别名
   覆盖。取消标题/图片字段后仍保留表单名称/默认图标回退。完整验收须同时使用包含该语义的 MCP
   与平台前端，逐项回读空字符串并验证实际表单；不能只看到写入 `Code=1` 就宣称生效。
-- 完整系统 Manifest 使用 `tables[].formBanner`；未提供时 `microi_generate_system` 仍须写入
+- 完整系统 Manifest 使用 `tables[].formBanner`；未提供时 `microi_generate_system` 仍须写入
   类型感知的默认值。逐步创建字段后调用 `microi_configure_form_banner` 并回读验证。
 - `microi_generate_system` 的最终验收与 `microi_validate_system` 必须逐表回读 Banner 语义字段；
   写入返回成功、结构验收 `Code=1` 都不能代替已持久化配置，`Data.Passed=false` 仍视为失败。
   旧库缺少 Banner 物理列时先完成平台正式升级，再配置和重新验收，不直接执行 SQL 补列。
-- 表单设计器验收必须覆盖有/无图片、有/无统计、子表完整聚合、接口失败回退、浅色、深色、
-  PC 和窄屏，并检查文字对比度以及不存在技术字段伪统计。
-
-## 物理类型底线
-
-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 外键放在主表。
-- 完整系统 Manifest 中，`JoinForm` / `TableChild` 字段必须声明 `relation.cardinality`；
-  `microi_plan_system` 与 `microi_generate_system` 会在任何写入前执行本节门禁。直接调用
-  `microi_add_field` / `microi_update_field` 时，后端仍会校验目标表、主/子外键、隐藏菜单
-  和子表索引，不能靠绕过 Manifest 写入未初始化配置。
-
-示例：
-
-- “订单包含多个商品明细” → `order_detail.OrderId` + `TableChild`。
-- “访客单包含多件携带物品” → `fk_carry_item.VisitId` + `TableChild`，不能用
-  `GuestId + JoinForm`，也不能把 `JoinForm` 指回 `fk_carry_item` 自己。
-- “工单关联一个客户，并在工单内展开客户档案” → 主表 `CustomerId` + `JoinForm`。
-
-### MCP 创建 `TableChild` 的两阶段流程
-
-1. 创建主表和独立子表；在子表创建真实外键（如 `VisitId varchar(50)`）。
+- 表单设计器验收必须覆盖有/无图片、有/无统计、子表完整聚合、接口失败回退、浅色、深色、
+  PC 和窄屏，并检查文字对比度以及不存在技术字段伪统计。
+
+## 物理类型底线
+
+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 外键放在主表。
+- 完整系统 Manifest 中，`JoinForm` / `TableChild` 字段必须声明 `relation.cardinality`；
+  `microi_plan_system` 与 `microi_generate_system` 会在任何写入前执行本节门禁。直接调用
+  `microi_add_field` / `microi_update_field` 时，后端仍会校验目标表、主/子外键、隐藏菜单
+  和子表索引，不能靠绕过 Manifest 写入未初始化配置。
+
+示例：
+
+- “订单包含多个商品明细” → `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` 时通常为
    `(OsClient, VisitId)`，独立租户表没有该列时为 `(VisitId)`。索引写入 Manifest
    `tables[].indexes`，并以 `microi_get_table_indexes` 回读；物理字段回读失败时停止配置。
-3. 为子表创建绑定其 `diyTableId` 的隐藏 CRUD 菜单：`Display=0`、`AppDisplay=0`、
-   `HasChild=0`。
-4. 在完整系统 Manifest 的主表字段声明：
-
-   ```json
-   {
-     "name": "Items",
-     "label": "明细",
-     "component": "TableChild",
-     "formWidth": 24,
-     "relation": {
-       "cardinality": "1:N",
-       "targetTable": "Biz_OrderItem",
-       "childForeignKey": "OrderId",
-       "childModule": "订单明细（隐藏）",
-       "primaryTableFieldName": "Id"
-     }
-   }
-   ```
-
-   `microi_generate_system` 会先创建全部表与普通字段，再创建隐藏菜单，最后回读并写入
-   当前租户真实的 `diy_table.Id` / `sys_menu.Id`。禁止在 Manifest 中编造这些 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
-  }
-}
-```
-
+3. 为子表创建绑定其 `diyTableId` 的隐藏 CRUD 菜单：`Display=0`、`AppDisplay=0`、
+   `HasChild=0`。
+4. 在完整系统 Manifest 的主表字段声明：
+
+   ```json
+   {
+     "name": "Items",
+     "label": "明细",
+     "component": "TableChild",
+     "formWidth": 24,
+     "relation": {
+       "cardinality": "1:N",
+       "targetTable": "Biz_OrderItem",
+       "childForeignKey": "OrderId",
+       "childModule": "订单明细（隐藏）",
+       "primaryTableFieldName": "Id"
+     }
+   }
+   ```
+
+   `microi_generate_system` 会先创建全部表与普通字段，再创建隐藏菜单，最后回读并写入
+   当前租户真实的 `diy_table.Id` / `sys_menu.Id`。禁止在 Manifest 中编造这些 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` 仅标记参与导入反查父表的关系。后端兼容旧三项配置，新版前端会合并去重并在字段下次保存时清除旧键。
 
 - `TableChild` 的父关联键为空、`null` 或仅空白时必须失败关闭：不得发起子表列表请求，服务端
@@ -281,51 +281,51 @@ MCP 建模只使用：
 
 `OpenTable` 用于弹出列表选择数据，固定授权范围用 `V8.OpenTableSetWhere`；`JoinTable`
 用于展示关联集合，不能用前端拼接代替数据权限。
-
-### 子表验收与复盘
-
-- 回读主表字段、子表字段、隐藏子菜单和索引，确认配置中的表 Id、菜单 Id、外键名均真实存在。
-- 用父记录 A 新增/编辑/删除多条子记录；打开父记录 B，确认 A 的数据不可见且不可越权操作。
-- 新增主表尚无真实 Id 时，不得产生孤儿子记录；保存后重新打开仍能正确回显。
-- 若曾误选组件，复盘必须记录：触发用语、误判基数、正确关系、应增加的生成前断言；通用结论
-  回写本节，不能只修一张业务表。
-
-## 自定义组件边界
-
-优先使用现有 44 类标准控件。只有标准控件无法表达交互、且该交互会长期复用时，
-才使用 `DevComponent`：
-
-- 多租户共用且与主框架强耦合的 Vue 组件，路径必须稳定并纳入 `Microi.Client` 源码/构建。
-- 支持 Add/Edit/View、只读、必填、清空、校验、移动端和暗色主题。
-- 不在组件内绕过 FormEngine 权限直接访问任意表。
-- 复杂但租户独有、需要固定嵌入表单的区域，优先使用 `DevComponent` + MicroService 路由；临时打开的复杂页面使用 `V8.OpenAppDialog`，都避免把客户逻辑打进主前端。
-- MicroService 表单嵌入使用 `microi.routes.json` 页面级 `LegacyComponentPaths` 作为稳定别名，字段 `Config.DevComponentPath` 与其匹配。主前端存在同路径 Vue 文件时本地优先；不存在时平台自动加载对应 `sys_microiservice_page.RoutePath`。新别名不得与 `/src/views` 真实文件冲突。
-- 组件宿主下发 `componentMode=true`、可序列化 `componentData` 与 `permissionContext`；子应用用 `dev-component:resize` 同步高度，用 `dev-component:event` 回传 `update:modelValue`、`CallbackFormValueChange`、`FormSet` 或 `ParentFormSet`。不传 Vue 实例、函数、循环引用或 `ParentV8`，不直接操作父页面 DOM。
-- 表单嵌入验收必须覆盖 Add/Edit/View/只读、初始值与回写、自动高度、窄屏、暗色主题，以及当前菜单 `ModuleEngineKey` 下的有权/无权账号。
-- `DevComponent` 配置了非空字段标题时必须正常渲染 Label；只有标题本身为空时才允许隐藏，
-  不能按组件类型全局吞掉业务标题。`el-form--label-top` 下的字段级 `Button` 仍保留与其它
-  控件等高的不可见 Label 占位，使按钮对齐控件区而不是对齐标题行。
-- 字段显式配置 `FormLabelPosition=left/right/top` 时优先于子表、代码编辑器等特殊组件的默认
-  `top` 布局；移动端仍可统一回落到 `top`。验收时必须在真实设计器保存后回读该字段配置。
-- 同一标签行同时显示 `Label` 与 `Description` 时，业务 Label 不允许收缩或省略；说明文字使用
-  剩余宽度并以省略号截断，完整说明通过 Element Plus tooltip 提供。自定义组件内部不得再次
-  输出与宿主字段相同的标题；需要补充的是说明或安全提示。
-- 权限树勾选子菜单时必须补齐全部祖先菜单的 `Read` 权限，祖先不得被动继承子菜单的增删改查；
-  这样既保证路由可见，又避免扩大业务操作权限。
-
+
+### 子表验收与复盘
+
+- 回读主表字段、子表字段、隐藏子菜单和索引，确认配置中的表 Id、菜单 Id、外键名均真实存在。
+- 用父记录 A 新增/编辑/删除多条子记录；打开父记录 B，确认 A 的数据不可见且不可越权操作。
+- 新增主表尚无真实 Id 时，不得产生孤儿子记录；保存后重新打开仍能正确回显。
+- 若曾误选组件，复盘必须记录：触发用语、误判基数、正确关系、应增加的生成前断言；通用结论
+  回写本节，不能只修一张业务表。
+
+## 自定义组件边界
+
+优先使用现有 44 类标准控件。只有标准控件无法表达交互、且该交互会长期复用时，
+才使用 `DevComponent`：
+
+- 多租户共用且与主框架强耦合的 Vue 组件，路径必须稳定并纳入 `Microi.Client` 源码/构建。
+- 支持 Add/Edit/View、只读、必填、清空、校验、移动端和暗色主题。
+- 不在组件内绕过 FormEngine 权限直接访问任意表。
+- 复杂但租户独有、需要固定嵌入表单的区域，优先使用 `DevComponent` + MicroService 路由；临时打开的复杂页面使用 `V8.OpenAppDialog`，都避免把客户逻辑打进主前端。
+- MicroService 表单嵌入使用 `microi.routes.json` 页面级 `LegacyComponentPaths` 作为稳定别名，字段 `Config.DevComponentPath` 与其匹配。主前端存在同路径 Vue 文件时本地优先；不存在时平台自动加载对应 `sys_microiservice_page.RoutePath`。新别名不得与 `/src/views` 真实文件冲突。
+- 组件宿主下发 `componentMode=true`、可序列化 `componentData` 与 `permissionContext`；子应用用 `dev-component:resize` 同步高度，用 `dev-component:event` 回传 `update:modelValue`、`CallbackFormValueChange`、`FormSet` 或 `ParentFormSet`。不传 Vue 实例、函数、循环引用或 `ParentV8`，不直接操作父页面 DOM。
+- 表单嵌入验收必须覆盖 Add/Edit/View/只读、初始值与回写、自动高度、窄屏、暗色主题，以及当前菜单 `ModuleEngineKey` 下的有权/无权账号。
+- `DevComponent` 配置了非空字段标题时必须正常渲染 Label；只有标题本身为空时才允许隐藏，
+  不能按组件类型全局吞掉业务标题。`el-form--label-top` 下的字段级 `Button` 仍保留与其它
+  控件等高的不可见 Label 占位，使按钮对齐控件区而不是对齐标题行。
+- 字段显式配置 `FormLabelPosition=left/right/top` 时优先于子表、代码编辑器等特殊组件的默认
+  `top` 布局；移动端仍可统一回落到 `top`。验收时必须在真实设计器保存后回读该字段配置。
+- 同一标签行同时显示 `Label` 与 `Description` 时，业务 Label 不允许收缩或省略；说明文字使用
+  剩余宽度并以省略号截断，完整说明通过 Element Plus tooltip 提供。自定义组件内部不得再次
+  输出与宿主字段相同的标题；需要补充的是说明或安全提示。
+- 权限树勾选子菜单时必须补齐全部祖先菜单的 `Read` 权限，祖先不得被动继承子菜单的增删改查；
+  这样既保证路由可见，又避免扩大业务操作权限。
+
 ## 固定审计字段
 
 - 核心协议迁移也必须遵守普通物理列允许 NULL。流式发布的 SaaS 开关、协议版本、栅栏、门禁代次和审计字段不能在旧迁移补跑时重新设为 NOT NULL；默认值、状态机、身份校验和完整审计由可信程序保证，只有主键 Id 保持数据库非空约束。
-
-- `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 提交时后端事件仍能阻止非法数据。
+
+- `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 提交时后端事件仍能阻止非法数据。