@microi.net/cli 4.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +66 -0
  3. package/dist/mcp-codex-stdio-adapter.js +189 -0
  4. package/dist/mcp-server.js +972 -0
  5. package/dist/mcp-trae-windows-launcher.cmd +21 -0
  6. package/dist/microi-cli-mcp.js +7 -0
  7. package/dist/microi-cli.js +1645 -0
  8. package/dist/microi-skills.meta.json +335 -0
  9. package/dist/microi.skills/.microi-skills-version.json +6 -0
  10. package/dist/microi.skills/README.md +276 -0
  11. package/dist/microi.skills/ai-engine/SKILL.md +140 -0
  12. package/dist/microi.skills/ai-engine/agents/openai.yaml +4 -0
  13. package/dist/microi.skills/app-store/SKILL.md +105 -0
  14. package/dist/microi.skills/app-store/agents/openai.yaml +4 -0
  15. package/dist/microi.skills/business-blueprint/SKILL.md +184 -0
  16. package/dist/microi.skills/datasource-engine/SKILL.md +89 -0
  17. package/dist/microi.skills/datasource-engine/agents/openai.yaml +4 -0
  18. package/dist/microi.skills/dos-orm/SKILL.md +76 -0
  19. package/dist/microi.skills/dos-orm/references/api-reference.md +229 -0
  20. package/dist/microi.skills/job-engine/SKILL.md +141 -0
  21. package/dist/microi.skills/job-engine/agents/openai.yaml +4 -0
  22. package/dist/microi.skills/message-notification/SKILL.md +113 -0
  23. package/dist/microi.skills/message-notification/agents/openai.yaml +6 -0
  24. package/dist/microi.skills/message-notification/references/contracts.md +99 -0
  25. package/dist/microi.skills/microi-ai-app-auth.js +651 -0
  26. package/dist/microi.skills/microi-ai-application/SKILL.md +80 -0
  27. package/dist/microi.skills/microi-ai-application/agents/openai.yaml +4 -0
  28. package/dist/microi.skills/microi-ai-application/references/frontend-baseline.md +164 -0
  29. package/dist/microi.skills/microi-client-frontend/SKILL.md +562 -0
  30. package/dist/microi.skills/microi-datasource-mapping/SKILL.md +108 -0
  31. package/dist/microi.skills/microi-db-schema/SKILL.md +170 -0
  32. package/dist/microi.skills/microi-db-schema/agents/openai.yaml +4 -0
  33. package/dist/microi.skills/microi-db-schema/references/core-tables.md +695 -0
  34. package/dist/microi.skills/microi-db-schema/references/form-component-options.md +256 -0
  35. package/dist/microi.skills/microi-db-schema/references/schema-overview.md +203 -0
  36. package/dist/microi.skills/microi-db-schema/references/schema.md +647 -0
  37. package/dist/microi.skills/microi-db-schema/references/table-catalog.md +1607 -0
  38. package/dist/microi.skills/microi-deployment/SKILL.md +117 -0
  39. package/dist/microi.skills/microi-deployment/references/deployment-matrix.md +94 -0
  40. package/dist/microi.skills/microi-docs-coverage/SKILL.md +91 -0
  41. package/dist/microi.skills/microi-docs-coverage/references/capability-map.md +65 -0
  42. package/dist/microi.skills/microi-docs-coverage/scripts/audit-doc-skill-coverage.mjs +887 -0
  43. package/dist/microi.skills/microi-form-engine/SKILL.md +159 -0
  44. package/dist/microi.skills/microi-form-engine/references/component-catalog.md +116 -0
  45. package/dist/microi.skills/microi-form-engine/references/data-source-events.md +117 -0
  46. package/dist/microi.skills/microi-form-layout/SKILL.md +373 -0
  47. package/dist/microi.skills/microi-frontend-sdk/SKILL.md +304 -0
  48. package/dist/microi.skills/microi-left-right-layout/SKILL.md +132 -0
  49. package/dist/microi.skills/microi-microservice/SKILL.md +115 -0
  50. package/dist/microi.skills/microi-microservice/references/runtime-delivery.md +145 -0
  51. package/dist/microi.skills/microi-mobile-app-quality/SKILL.md +436 -0
  52. package/dist/microi.skills/microi-solution-quotation/SKILL.md +76 -0
  53. package/dist/microi.skills/microi-solution-quotation/agents/openai.yaml +4 -0
  54. package/dist/microi.skills/microi-solution-quotation/scripts/build_solution_quote.py +296 -0
  55. package/dist/microi.skills/microi-system-delivery/SKILL.md +446 -0
  56. package/dist/microi.skills/microi-ui/SKILL.md +321 -0
  57. package/dist/microi.skills/microi-uniapp-frontend/SKILL.md +483 -0
  58. package/dist/microi.skills/microi.v8.js +1758 -0
  59. package/dist/microi.skills/module-engine/SKILL.md +131 -0
  60. package/dist/microi.skills/module-engine/references/module-config.md +174 -0
  61. package/dist/microi.skills/page-engine/SKILL.md +397 -0
  62. package/dist/microi.skills/performance-testing/SKILL.md +207 -0
  63. package/dist/microi.skills/playwright-e2e/SKILL.md +769 -0
  64. package/dist/microi.skills/print-engine/SKILL.md +237 -0
  65. package/dist/microi.skills/production-readonly-audit/SKILL.md +39 -0
  66. package/dist/microi.skills/report-engine/SKILL.md +69 -0
  67. package/dist/microi.skills/report-engine/agents/openai.yaml +4 -0
  68. package/dist/microi.skills/search-engine/SKILL.md +73 -0
  69. package/dist/microi.skills/search-engine/agents/openai.yaml +4 -0
  70. package/dist/microi.skills/spider-engine/SKILL.md +188 -0
  71. package/dist/microi.skills/translate-engine/SKILL.md +91 -0
  72. package/dist/microi.skills/translate-engine/agents/openai.yaml +4 -0
  73. package/dist/microi.skills/ui-design/SKILL.md +1575 -0
  74. package/dist/microi.skills/ui-design/assets/pattern-showcase/app.js +54 -0
  75. package/dist/microi.skills/ui-design/assets/pattern-showcase/index.html +163 -0
  76. package/dist/microi.skills/ui-design/assets/pattern-showcase/styles.css +311 -0
  77. package/dist/microi.skills/ui-design/assets/templates/MCI-DESIGN.md +98 -0
  78. package/dist/microi.skills/ui-design/references/design-pattern-library.md +171 -0
  79. package/dist/microi.skills/ui-design/references/mci-design-contract.md +84 -0
  80. package/dist/microi.skills/ui-design/references/motion-and-media.md +71 -0
  81. package/dist/microi.skills/ui-design/references/product-flow-recipes.md +94 -0
  82. package/dist/microi.skills/uniapp-mall-assets/SKILL.md +105 -0
  83. package/dist/microi.skills/v8-api-config/SKILL.md +272 -0
  84. package/dist/microi.skills/v8-cache-pattern/SKILL.md +286 -0
  85. package/dist/microi.skills/v8-crud-api/SKILL.md +398 -0
  86. package/dist/microi.skills/v8-debugging/SKILL.md +279 -0
  87. package/dist/microi.skills/v8-explorer-tree/SKILL.md +224 -0
  88. package/dist/microi.skills/v8-export-import/SKILL.md +590 -0
  89. package/dist/microi.skills/v8-file-upload/SKILL.md +497 -0
  90. package/dist/microi.skills/v8-formengine-http/SKILL.md +218 -0
  91. package/dist/microi.skills/v8-frontend-events/SKILL.md +349 -0
  92. package/dist/microi.skills/v8-frontend-events/references/bluetooth-print-api.md +107 -0
  93. package/dist/microi.skills/v8-frontend-events/references/bluetooth-print.md +185 -0
  94. package/dist/microi.skills/v8-http-integration/SKILL.md +379 -0
  95. package/dist/microi.skills/v8-image-processing/SKILL.md +187 -0
  96. package/dist/microi.skills/v8-image-processing/agents/openai.yaml +4 -0
  97. package/dist/microi.skills/v8-image-processing/references/api-reference.md +620 -0
  98. package/dist/microi.skills/v8-menu-buttons/SKILL.md +661 -0
  99. package/dist/microi.skills/v8-mongodb/SKILL.md +149 -0
  100. package/dist/microi.skills/v8-mq-mqtt/SKILL.md +227 -0
  101. package/dist/microi.skills/v8-saas-multi-tenant/SKILL.md +193 -0
  102. package/dist/microi.skills/v8-security/SKILL.md +417 -0
  103. package/dist/microi.skills/v8-sql-query/SKILL.md +290 -0
  104. package/dist/microi.skills/v8-table-event/SKILL.md +385 -0
  105. package/dist/microi.skills/v8-template-engine/SKILL.md +165 -0
  106. package/dist/microi.skills/v8-utilities/SKILL.md +79 -0
  107. package/dist/microi.skills/v8-utilities/references/client-api-index.md +136 -0
  108. package/dist/microi.skills/v8-utilities/references/platform-http-routes.md +80 -0
  109. package/dist/microi.skills/v8-utilities/references/server-api-index.md +129 -0
  110. package/dist/microi.skills/v8-workflow/SKILL.md +322 -0
  111. package/dist/microi.skills/workspace-conventions/SKILL.md +479 -0
  112. package/package.json +40 -0
@@ -0,0 +1,373 @@
1
+ ---
2
+ name: microi-form-layout
3
+ description: Microi 吾码低代码表单布局分组规范。用于通过 MCP、Manifest、VS Code 插件或 V8 引擎创建/优化 `diy_table` 和 `diy_field` 时,决定使用 `diy_table.Tabs` 表单全局 Tab、字段级 `Tabs` 控件、字段级 `CollapseGroup` 折叠分组,还是直接平铺字段。覆盖"何时分 Tab、何时分折叠分组、有效表单行判断阈值、JSON 配置示例、回读验收与回滚"。
4
+ ---
5
+
6
+ # Microi 表单布局分组规范(Tabs vs CollapseGroup)
7
+
8
+ Microi 吾码低代码提供 **三种** 表单分组能力,但每种都有明确的使用场景。**AI 必须先按本规范评估,再决定如何分组**,禁止盲目创建 Tab。
9
+
10
+ 本 Skill 中的 Tabs、CollapseGroup、Divider 是编辑表单布局。模块级 Detail/Edit/List/Card 跨端视图必须配置在 `sys_menu.ViewSchema` 物理字段中;EntityHero、MetricStrip、ActionGrid、ResponsiveSection 属于独立视图区块,不得伪装成 `diy_field`。三个核心表的 `DiyConfig` 均已废弃,禁止作为新布局或新功能配置入口。
11
+
12
+ 控件事实源:`Microi.Client/src/views/form-engine/diy-field-component/diy-component-list.json` 中 `Sort=1000` 附近的 `Divider`、`CollapseGroup`、`Tabs`、`Alert`、`StaticText`、`Html`、`RichText` 等都属于 Advanced 布局控件。
13
+
14
+ ## 1. 三种分组能力速查
15
+
16
+ | 能力 | 存储位置 | 控件 | 核心作用 | 适用场景 |
17
+ |------|---------|------|---------|---------|
18
+ | **A. diy_table.Tabs(表级 Tab)** | `diy_table.Tabs`(JSON 字符串) | 表单顶部 Tab 条 | 把整张表的字段切到不同 Tab 中,**同屏只能看一个 Tab** | 表单整体很长,单个 Tab 通常占 **≥6 个有效表单行**,且 Tab 之间字段**业务强隔离**(扫码操作 vs 单据信息、主数据 vs 大型子表) |
19
+ | **B. 字段级 Tabs 控件** | `diy_field.Component='Tabs'` + `Config.FieldTabs` | 字段本身就是 Tab 容器 | 多个 Tab 字段组合嵌套,**同屏只能看一个 Tab** | 同一张表内需要二级 Tab,或 Tab 内容互相独立 |
20
+ | **C. 字段级 CollapseGroup(折叠分组)** | `diy_field.Component='CollapseGroup'` + `Config.CollapseGroup` | 字段是折叠面板标题 | **所有分组可在同一页面展开**,用户一屏看到全部标题和分组字段 | 只占 **≤5 个有效表单行** 的小分组(短字段即使有 8~10 个,也常只占 4~5 行) |
21
+ | **D. 不分组(默认平铺)** | 无 | — | 全部字段在第一屏 | 总有效表单行 ≤ 6、没有复杂控件,且没有必须强调的业务分组 |
22
+
23
+ ## 2. 黄金决策流程(AI 必须按此顺序判断)
24
+
25
+ ### 2.1 先算“有效表单行”,禁止只数字段
26
+
27
+ 字段数不能直接代表视觉高度。AI 必须按 `diy_table.Column` 估算每组字段占用的有效表单行:
28
+
29
+ - 普通 Text / Select / NumberText / DateTime 等短控件:占 `1 / Column` 行;双列布局中 8 个短字段约为 4 行。
30
+ - `FormWidth=24` 或 Textarea / RichText / FileUpload / ImgUpload / Map:每个至少占 1 行。
31
+ - TableChild / CodeEditor / DevComponent / 大型 JsonTable:视为独立任务区,不能按普通字段数压缩。
32
+ - 隐藏字段、Id、纯布局控件不计入视觉行数,但必须保留其排序和业务配置。
33
+
34
+ **一级字段数门槛**:`<=6` 个核心可见字段优先平铺;`7~29` 个字段按基础、业务、状态、附件等信息域使用 CollapseGroup;`30+` 个字段优先评估表级 Tabs。字段数只是一级门槛,仍须结合下方“有效表单行”和任务隔离判断。
35
+
36
+ **表级 Tab 的默认准入条件**:除 `30+` 字段外,表单总有效行通常大于 12 行,并且至少两个 Tab 各自达到 6 个有效行;否则优先平铺或 CollapseGroup。多个大型子表,或扫码、代码编辑、运行测试等强任务域,可以直接进入 Tabs 评估;字段达到 8 个不再自动获得独立 Tab 资格。
37
+
38
+ **强任务隔离例外**:扫码/报工/质检操作区、可独立滚动的大型子表、运行测试、代码编辑、工作流事件等即使行数较少,也可以保留 Tab,因为切换代表任务模式而不是装饰性分组。
39
+
40
+ ```
41
+ 开始
42
+
43
+ Q1: 核心可见字段数、子表和强任务域?
44
+ ├─ ≤ 6 字段且无复杂控件 → D. 不分组(默认平铺)
45
+ ├─ 7 ~ 29 字段且无多个大型子表/强任务域 → 按信息域使用 C. CollapseGroup
46
+ └─ ≥ 30 字段,或多个大型子表/强任务域 → 优先评估 A. diy_table.Tabs
47
+
48
+ Q2: 是否至少有两个需要切换的独立业务域?
49
+ ├─ 否 → D. 平铺,或用 CollapseGroup 收起次要字段
50
+ └─ 是
51
+
52
+ Q3: 每个业务域的有效表单行数?
53
+ ├─ 至少两个业务域均 ≥ 6 行 → A. diy_table.Tabs(表级 Tab)
54
+ └─ 存在 ≤ 5 行的小业务域
55
+
56
+ 混合方案:Tab 容纳大业务域(≥6 个有效行)+ CollapseGroup 收起小业务域(≤5 个有效行)
57
+
58
+ 注意:所有 Tab 内的 ≤5 个有效行小业务域,必须用 CollapseGroup 折叠分组
59
+ ```
60
+
61
+ **简明决策表**:
62
+
63
+ | 场景 | 推荐方案 | 禁止做法 |
64
+ |------|---------|---------|
65
+ | 13 字段双列表单 + 3 个小业务域(2/9/2 个字段) | 3 个 CollapseGroup,核心业务组默认展开 | 禁止建立 3 个 Tab;9 个短字段通常只有 4.5 行,仍不足以独占一页 |
66
+ | 13 字段表 + 1 个"MRP 运算"子集(3 字段) | C. CollapseGroup 折叠"MRP 运算"分组,剩余 10 字段平铺 | 禁止用 diy_table.Tabs 拆出"MRP 运算"Tab(用户必须点击切换才能看到 3 个字段) |
67
+ | 35 字段表 + 4 个业务域(10/8/9/8) | A. diy_table.Tabs(4 个 Tab) | 禁止把每个 Tab 内 ≤5 字段的"备注/其他"再开 Tab |
68
+ | 42 字段表 + 5 个业务域(14/13/6/5/4) | A. diy_table.Tabs(5 个 Tab),后两个 Tab 内用 C. CollapseGroup 收次要字段 | 禁止为了 4~5 字段"审核信息"单独建 Tab |
69
+ | 8 字段简单登记表 | D. 不分组 | 禁止任何 Tab/折叠 |
70
+ | 工作流审批表(≤10 字段) | D. 不分组 | 禁止使用 Tab |
71
+
72
+ ## 3. 三种分组的存储与配置
73
+
74
+ ### 3.1 diy_table.Tabs(表级 Tab)
75
+
76
+ 存储:`diy_table.Tabs`(JSON 字符串)+ 每个字段的 `diy_field.Tab`(归属 Tab 名)。
77
+
78
+ ```jsonc
79
+ // diy_table.Tabs JSON 格式
80
+ [
81
+ { "Id": "basic", "Name": "基础信息", "Sort": 10 },
82
+ { "Id": "business","Name": "业务明细", "Sort": 20 },
83
+ { "Id": "attach", "Name": "附件备注", "Sort": 30 }
84
+ ]
85
+ ```
86
+
87
+ 字段归属:在 `diy_field.Tab` 写 `Id`(不是 `Name`)。`Tab` 留空的字段属于"非 Tab 字段"(即 `diy_table.Tabs` 之外的字段),会作为隐藏的剩余字段自动归到最后 Tab。
88
+
89
+ - 字段 `Tab="basic"` → 归属"基础信息"Tab
90
+ - 字段 `Tab=""` 且 `diy_table.Tabs` 存在 → 自动归到最后一个 Tab 的剩余字段
91
+ - 字段 `Tab=""` 且 `diy_table.Tabs` 不存在 → 全部在第一屏平铺
92
+
93
+ **不推荐用法**:把 `diy_table.Tabs` 拆出 3 个 Tab、每个 Tab 内只有 2~3 个字段。这会让用户必须点击 3 次 Tab 才能看完一张表,且首屏只看到 2~3 个字段。
94
+
95
+ ### 3.2 字段级 Tabs 控件(`diy_field.Component='Tabs'`)
96
+
97
+ 存储:`diy_field` 行 + `Config.FieldTabs`(JSON)。
98
+
99
+ ```jsonc
100
+ // diy_field 必要字段
101
+ {
102
+ "Id": "TabsField_Main",
103
+ "Name": "TabsMain",
104
+ "Label": "主分组",
105
+ "Component": "Tabs",
106
+ "Type": "varchar(50)",
107
+ "Sort": 50,
108
+ "Visible": 0, // 通常设为 0,因为 Tabs 本身是布局控件
109
+ "AppVisible": 0,
110
+ "Config": "{\"FieldTabs\":{...}}"
111
+ }
112
+
113
+ // Config.FieldTabs
114
+ {
115
+ "ScopeMode": "FieldCount", // 或 "Manual"
116
+ "TotalFieldCount": 0, // 0 表示直到下一个 Tabs
117
+ "DefaultActiveKey": "tab1",
118
+ "Type": "card", // "" | "card" | "border-card"
119
+ "Position": "top", // top | bottom | left | right
120
+ "Stretch": false,
121
+ "ShowFieldCount": true,
122
+ "CaptureRest": true,
123
+ "Description": "",
124
+ "Theme": "default",
125
+ "Tabs": [
126
+ { "Key": "tab1", "Title": "页签一", "Icon": "fas fa-info-circle", "FieldCount": 6, "Disabled": false }
127
+ ]
128
+ }
129
+ ```
130
+
131
+ **作用范围**:从该 Tabs 字段开始,到下一个 `Component in (Tabs, CollapseGroup, Divider)` 字段为止。
132
+
133
+ ### 3.3 字段级 CollapseGroup 折叠分组(`diy_field.Component='CollapseGroup'`)
134
+
135
+ 存储:`diy_field` 行 + `Config.CollapseGroup`(JSON)。
136
+
137
+ ```jsonc
138
+ // diy_field 必要字段
139
+ {
140
+ "Id": "CollapseGroup_MRP",
141
+ "Name": "MrpGroup",
142
+ "Label": "MRP 运算",
143
+ "Component": "CollapseGroup",
144
+ "Type": "varchar(50)",
145
+ "Sort": 120,
146
+ "Visible": 1,
147
+ "AppVisible": 1,
148
+ "Config": "{\"CollapseGroup\":{...}}"
149
+ }
150
+
151
+ // Config.CollapseGroup
152
+ {
153
+ "DefaultCollapsed": false, // 默认展开;高频访问分组可设 false
154
+ "ScopeMode": "UntilNextGroup", // 直到下一个折叠/Tab/Divider
155
+ "FieldCount": 5, // ScopeMode=FieldCount 时生效
156
+ "Description": "MRP 运算结果与时间",
157
+ "Icon": "fas fa-calculator",
158
+ "Theme": "primary", // default | primary | success | warning | danger
159
+ "ShowFieldCount": true
160
+ }
161
+ ```
162
+
163
+ **作用范围**:从该 CollapseGroup 字段开始,到下一个 `Component in (Tabs, CollapseGroup, Divider)` 字段为止。
164
+
165
+ **与 Tab 的关键区别**:所有 CollapseGroup 标题**始终可见**,分组内字段**默认展开**或**默认收起**,但所有分组的字段**都在同一页面**,可同时展开多个。
166
+
167
+ ### 3.4 控件视觉对比
168
+
169
+ | 视觉表现 | Tabs | CollapseGroup |
170
+ |---------|------|---------------|
171
+ | 首屏可见字段数 | 仅一个 Tab 的字段 | **所有分组的标题 + 展开分组的字段** |
172
+ | 用户切换分组方式 | 必须点击 Tab 头 | 可直接滚动或逐个点击展开 |
173
+ | 同时看到多组 | ❌ | ✅ |
174
+ | 适合"展开后阅读" | ❌(频繁切换会烦) | ✅ |
175
+ | 适合"互斥分组" | ✅ | ❌ |
176
+
177
+ ## 4. AI 生成表单布局的标准动作
178
+
179
+ ### 4.1 必做顺序
180
+
181
+ 1. **先数字段**:调用 `microi_get_field_list` 拉出全部字段,统计**有效字段数**(排除 `Visible=0` 隐藏字段、`Id`、系统字段)。
182
+ 2. **再分业务域**:用 `Sort` 顺序浏览字段,把字段聚类到 2~5 个业务域(基础信息 / 业务明细 / 业主/组织 / 财务 / 附件备注 / 状态 / 时间 / 其他)。
183
+ 3. **算每个域有效表单行**:A. 大于等于 6 行且存在强隔离价值 → Tab;B. 小于等于 5 行 → CollapseGroup;C. 等于 0 → 删除该域。
184
+ 4. **决定顶层方案**:A. 全 Tab / B. Tab+CollapseGroup 混合 / C. 全 CollapseGroup / D. 平铺。
185
+ 5. **写配置**:先写 `diy_table.Tabs`(若有 Tab),再逐字段写 `Tab` 归属;新增 `Component=CollapseGroup/Tabs/Divider/Alert` 等布局节点时,只能使用明确标注为“仅元数据”的布局专用路径,不能使用会同步建业务列的普通新增字段接口。
186
+ 6. **回读验收**:调用 `microi_get_field_list` 回读,确认 `Tab` 字段、`Sort`、`Component`、`Config.FieldTabs` / `Config.CollapseGroup` JSON 正确。
187
+ 7. **V8 完整性校验**:修改前后比较表级六类 V8 事件、字段 `V8Code/KeyupV8Code/Config`;布局迁移不得覆盖业务代码。若代码出现 `HideFormTab/ShowFormTab/ClickFormTab`,必须先适配或跳过该表。
188
+ 8. **清缓存**:`microi_refresh_schema_cache tables=['表名']`,避免前端看到旧配置。
189
+
190
+ ### 4.2 存量表自动审计与安全迁移
191
+
192
+ 当用户要求“检查所有表单设计”时,AI 必须执行自动化盘点,不能只修截图中的一张表:
193
+
194
+ 1. 读取所有 `diy_table.Tabs`,排除只有一个 `none` 默认页签的表。
195
+ 2. 一次性读取候选表的 `diy_field`,按 `Tab + Sort + Component + FormWidth + Visible` 计算每组有效行数。
196
+ 3. 保留扫码、报工、质检操作、大型子表、代码编辑、运行测试等强任务 Tab。
197
+ 4. 将“总有效行 ≤12、每组 ≤5 行、无复杂控件、无 Tab 控制 V8”的表列为高置信迁移候选。
198
+ 5. 修改前记录 `Tabs`、字段 `Tab/Sort/Component/Config/V8Code/KeyupV8Code` 和表级 V8 摘要;修改后逐项回读,业务代码摘要必须一致。
199
+ 6. 迁移为 CollapseGroup 时,只能通过布局专用的“仅元数据”路径新增布局节点,再清空原字段 `Tab` 和表级 `Tabs`;不得重建业务字段,不得改数据源、必填、只读、默认值或 V8。普通新增字段可能触发物理 DDL,严禁把通用 `AddFormData(diy_field)` 或普通字段创建接口当作元数据写入捷径。
200
+ 7. 平台控制面、安全表和存在歧义的业务表只报告,不自动批量迁移。
201
+
202
+ ### 4.3 后端实现备忘
203
+
204
+ 后端表结构(`diy_table`):
205
+ - `Tabs` 字段:JSON 字符串,存表级 Tab 列表。
206
+ - `TabsPosition` 字段:top / bottom / left / right。
207
+ - `TableTabs` / `TableTabsPosition`:表格视图的 Tab,与表单 Tab 独立。
208
+ - `FormArticle` / `TableArticle`:表单/表格的说明文案(不是 Tab)。
209
+
210
+ 后端字段结构(`diy_field`):
211
+ - `Tab` 字段:归属 Tab 名(与 `diy_table.Tabs.Id` 对应)。
212
+ - `Component = Tabs` / `CollapseGroup` / `Divider` / `Alert` 等 Advanced 控件,作为布局节点。
213
+ - `Config` 字段:JSON 字符串,存 `FieldTabs` / `CollapseGroup` 等子配置。
214
+
215
+ V8 事件中可用 `V8.HideFormTab('tabId')` / `V8.ShowFormTab('tabId')` / `V8.ClickFormTab('tabId')` 动态控制 Tab 显隐和默认选中。
216
+
217
+ ## 5. 必填与禁止
218
+
219
+ ### 5.1 必填
220
+
221
+ - 字段数 13~30 的表单,必须有可见的**业务分组**(Tab 或 CollapseGroup 二选一),不能让用户上下滚动 5 屏找字段。
222
+ - 创建 CollapseGroup 分组时,必须设置 `Icon`(如 `fas fa-calculator` / `fas fa-info-circle`),不要默认空白。
223
+ - 任何 Tab / CollapseGroup 都必须有 `Description` 解释分组用途,不要只放一个标题。
224
+ - 修改 `diy_table.Tabs` 或 `diy_field.Tab` / `Config.CollapseGroup` / `Config.FieldTabs` 后,必须调用 `microi_refresh_schema_cache`。
225
+ - Tab 内嵌套 CollapseGroup 时,CollapseGroup 必须设 `DefaultCollapsed=true`(默认收起),避免 Tab 内继续被折叠分组抢首屏空间。
226
+ - 新增布局节点后必须同时回读 `diy_field` 元数据和目标业务表结构,确认没有新增物理业务列;若当前工具不提供仅元数据能力,只报告设计建议,不得绕过后端直接写表。
227
+
228
+ ### 5.2 禁止
229
+
230
+ - ❌ **禁止**为 ≤5 个有效表单行的业务域单独创建 Tab(必须改用 CollapseGroup);8~10 个双列短字段通常仍属于此范围。
231
+ - ❌ **禁止**仅凭 13~30 个原始字段决定平铺或分 Tab;总有效行超过 6 且存在明确业务域时,至少使用 CollapseGroup 分组。
232
+ - ❌ **禁止**为 8~10 字段的简单业务表创建多层 Tab 嵌套(直接用 CollapseGroup 即可)。
233
+ - ❌ **禁止**在用户没有要求时使用 `Tabs` 字段控件(`diy_field.Component='Tabs'`),更优先用 `diy_table.Tabs`。
234
+ - ❌ **禁止**为 `Tabs` / `CollapseGroup` / `Divider` / `Alert` 等布局控件设置 `FormWidth=24`,这些控件天然占整行。
235
+ - ❌ **禁止**只创建 Tab 不写字段的 `Tab` 归属(每个 Tab 必须有至少 1 个非空 `Tab` 的字段)。
236
+ - ❌ **禁止**用 Tabs 控件的 `FieldCount` 跨过 CollapseGroup 或 Divider 计数(不同布局控件的计数是隔离的)。
237
+ - ❌ **禁止**把高频访问的字段(如单据编号、项目名称)放进默认收起的 CollapseGroup。
238
+ - ❌ **禁止**用普通新增字段或通用表单数据写入创建布局节点;这类路径可能对目标业务表执行物理 DDL。
239
+
240
+ ## 6. 验收清单
241
+
242
+ 修改或新建表单布局后,AI 必须按以下顺序验收:
243
+
244
+ 1. **回读字段**:`microi_get_field_list` 检查 `Tab` / `Component` / `Config` 与设计一致。
245
+ 2. **回读表与结构**:`microi_get_table_data _SelectFields=['Id'] _PageSize=1` 验证表可读,并检查实时表结构未因纯布局节点新增物理业务列。
246
+ 3. **清缓存**:`microi_refresh_schema_cache tables=['表名']`。
247
+ 4. **手动打开表单**:通过 Playwright 或 V8 引擎调用,截图第一屏。
248
+ 5. **视觉确认**:
249
+ - 第一屏必须能看到核心业务信息,通常至少 6~10 个短字段或一个完整任务区(而不是 2~3 个字段加大片空白)。
250
+ - Tab 或 CollapseGroup 标题与说明文字清晰可见。
251
+ - 没有任何"只剩 1 个字段的 Tab"。
252
+ 6. **业务闭环**:新建一条测试数据、编辑、查看、删除,验证字段在正确分组中显示。
253
+
254
+ ## 7. 反例参考(必须避免)
255
+
256
+ ### 反例 1:MRP 运算 3 字段单独建 Tab
257
+
258
+ ```
259
+ ❌ 错误:
260
+ diy_table.Tabs = [
261
+ { Id: 'basic', Name: '基础信息' }, // 5 字段
262
+ { Id: 'mrp', Name: 'MRP 运算' }, // 3 字段
263
+ { Id: 'remark', Name: '备注' } // 1 字段
264
+ ]
265
+ // 用户打开表单,第一屏只看到 5 个"基础信息"字段,"MRP 运算"和"备注"被藏在 Tab 里
266
+
267
+ ✅ 正确:
268
+ // 不创建 diy_table.Tabs,把"MRP 运算" 3 字段用 CollapseGroup 收在表单末尾(默认展开)
269
+ // 把"备注"也用 CollapseGroup 或 Divider 收
270
+ // 第一屏用户能看到所有基础信息 + MRP 运算
271
+ ```
272
+
273
+ ### 反例 1.1:项目收款记录拆成 2/9/2 三个 Tab
274
+
275
+ ```
276
+ ❌ 错误:
277
+ 项目(2 个短字段) + 收款(9 个短字段) + 附件备注(2 个整行字段)分别建 Tab。
278
+ 结果是每页只有 1~5 行内容,桌面抽屉出现大面积空白,用户要切换三次才能看完整记录。
279
+
280
+ ✅ 正确:
281
+ 取消表级 Tab,按原顺序建立“项目信息 / 收款信息 / 附件备注”三个 CollapseGroup。
282
+ 核心组默认展开,低频附件备注可默认收起;保留原字段、数据源、必填规则和 V8 代码。
283
+ ```
284
+
285
+ ### 反例 2:13 字段表全平铺
286
+
287
+ ```
288
+ ❌ 错误:
289
+ // 13 字段全部 Tab 留空
290
+ // 用户必须向下滚动 3 屏才能看到所有字段
291
+
292
+ ✅ 正确:
293
+ // 13 字段按业务分两组:8 字段"基础信息" + 5 字段"业务明细"
294
+ // 用 1 个 diy_table.Tabs(基础信息 + 业务明细)
295
+ // 或用 1 个 CollapseGroup 把"业务明细"5 字段收起
296
+ ```
297
+
298
+ ### 反例 3:42 字段表用 6 个 Tab
299
+
300
+ ```
301
+ ❌ 错误:
302
+ // 6 个 Tab:基础(14) + 项目业主(2) + 发货通知(13) + 生产需求(3) + 审核(4) + ERP出库(4) + 其他(2)
303
+ // 用户要点 6 次才能看完,且"项目业主"和"生产需求"这种 2~3 字段的 Tab 完全没必要
304
+
305
+ ✅ 正确:
306
+ // 4 个 Tab:基础(14) + 发货通知+生产需求(16) + 审核+ERP出库(8) + 其他(4)
307
+ // 或 3 个 Tab + 内部嵌套 CollapseGroup
308
+ ```
309
+
310
+ ## 8. 快速参考代码片段
311
+
312
+ ### 8.1 MCP 创建表级 Tab
313
+
314
+ ```js
315
+ // 假设已创建 diy_table,通过 microi_update_table 设置 Tabs
316
+ // 注意:microi_create_table 不直接接收 Tabs JSON,需创建后 microi_update_table 补全
317
+ microi_update_table({
318
+ name: "yutaoliaojieguo",
319
+ // 暂未直接传 Tabs,需要通过 microi_update_table 文档化的方式补全
320
+ })
321
+ ```
322
+
323
+ > 实际写入 `diy_table.Tabs` 优先用 `microi_update_field` 之外的元数据写入方式或 `microi_upsert_engine` 委托接口引擎;后续 MCP 工具可补强 `Tabs` 参数。
324
+
325
+ ### 8.2 MCP 创建字段级 CollapseGroup
326
+
327
+ ```js
328
+ // 1. 创建一个 CollapseGroup 字段
329
+ microi_add_field({
330
+ tableId: "01KTASHWEBE514R1XTB0WVJJRX",
331
+ name: "MrpGroup",
332
+ label: "MRP 运算",
333
+ type: "varchar(50)",
334
+ component: "CollapseGroup",
335
+ sort: 150,
336
+ visible: 1,
337
+ appVisible: 1,
338
+ config: JSON.stringify({
339
+ CollapseGroup: {
340
+ DefaultCollapsed: false,
341
+ ScopeMode: "UntilNextGroup",
342
+ Description: "MRP 运算状态、批次号与时间",
343
+ Icon: "fas fa-calculator",
344
+ Theme: "primary",
345
+ ShowFieldCount: true
346
+ }
347
+ })
348
+ })
349
+
350
+ // 2. 让"MRP 运算"相关字段归属到该 CollapseGroup
351
+ // 范围方式:把 CalcStatus、CalcBatchNo、MrpTime 三个字段的 Sort 排在 150~300 之间,
352
+ // 下一个 CollapseGroup/Tabs/Divider 字段之前的所有字段都属于该分组
353
+ ```
354
+
355
+ ### 8.3 MCP 把字段 Tab 归属到 diy_table.Tabs
356
+
357
+ ```js
358
+ // 创建表级 Tab
359
+ // 1. microi_update_table 设置 diy_table.Tabs 字段(待 MCP 工具补全)
360
+ // 2. 给字段写 Tab 归属
361
+ microi_update_field({
362
+ id: "01KVTWDJ7WXB3Z60HGJ5BPTBJ0",
363
+ tab: "basic" // 归属到 diy_table.Tabs.Id='basic' 的 Tab
364
+ })
365
+ ```
366
+
367
+ ## 9. 与其他 Skill 的关系
368
+
369
+ - 字段创建流程:`v8-table-event/SKILL.md` 写 InFormV8 / SubmitFormV8 等。
370
+ - 外键 Id+Name 双字段:`ui-design/SKILL.md` 中的"外键字段必须使用 Id+Name 双控件设计"。
371
+ - 整行控件规则:`microi-system-delivery/SKILL.md` 中 `FormWidth=24` 的使用条件。
372
+ - 表单设计器与按钮:`v8-menu-buttons/SKILL.md`。
373
+ - V8 事件 Tab 显隐 API:`v8-table-event/SKILL.md` 中 `V8.HideFormTab` / `V8.ShowFormTab` / `V8.ClickFormTab`。