@microi.net/cli 5.5.9 → 5.6.0

package/skills/v8-menu-buttons/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: v8-menu-buttons
-description: Microi 菜单按钮与 Tab V8 指南。用于配置 sys_menu MoreBtns、FormBtns、BatchSelectMoreBtns、PageTabs、PageBtns、ExportMoreBtns、显隐代码和行操作。
+description: Microi 菜单按钮与 Tab V8 指南。用于配置 sys_menu MoreBtns、FormBtns、BatchSelectMoreBtns、PageTabs、PageBtns、ExportMoreBtns、显隐代码和行操作。
 ---
 
 > **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
@@ -22,7 +22,7 @@ description: Microi 菜单按钮与 Tab V8 指南。用于配置 sys_menu MoreBt
 | `MoreBtns` | 列表每行尾的"…更多"操作 | `Id, Name, V8Code`，建议 `ShowRow:true` |
 | `FormBtns` | 表单右上角 / 移动端 FAB | `Id, Name, V8Code` |
 | `BatchSelectMoreBtns` | 列表勾选多行后顶部出现 | `Id, Name, V8Code`，按钮里用 `V8.TableRowSelected` 取选中行 |
-| `PageTabs` | 列表页模块 Hero 下方的页签切换 | `Id, Name`，当前模块筛选用 `V8Code`；跨模块切换用 `TargetSysMenuId` |
+| `PageTabs` | 列表页模块 Hero 下方的页签切换 | `Id, Name`，当前模块筛选用 `V8Code`；跨模块切换用 `TargetSysMenuId` |
 | `ExportMoreBtns` | 列表"导出"下拉的扩展 | `Id, Name, V8Code` |
 | `PageBtns` | 页面级顶部按钮 | `Id, Name, V8Code` |
 
@@ -30,7 +30,7 @@ description: Microi 菜单按钮与 Tab V8 指南。用于配置 sys_menu MoreBt
 
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=v8-menu-buttons-001 sha256=baf0987fff87b6a144361f9aa19598d30c9e747867bd170de4ccd40447df9377 -->
-## 3. 模式 A：弹窗收集参数 → 调接口引擎（最常用）
+## 3. 模式 A：弹窗收集参数 → 调接口引擎（最常用）
 
 ```js
 V8.OpenAnyForm({
@@ -58,9 +58,9 @@ V8.OpenAnyForm({
 
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=v8-menu-buttons-002 sha256=f1e1bc64623a26a6c06bccd3e7da3f7e3b16e76b85d2fb398efe2c74407fba04 -->
-## 4. 模式 B：直接确认 + 接口调用
-
-`ConfirmTips` 使用 HTML 模式渲染内容，只传固定文案或经过 HTML 转义的简单文本；不要拼接用户输入、接口消息或数据库富文本。
+## 4. 模式 B：直接确认 + 接口调用
+
+`ConfirmTips` 使用 HTML 模式渲染内容，只传固定文案或经过 HTML 转义的简单文本；不要拼接用户输入、接口消息或数据库富文本。
 
 ```js
 V8.ConfirmTips('确认领取该任务？', function () {
@@ -72,105 +72,105 @@ V8.ConfirmTips('确认领取该任务？', function () {
     else V8.Tips(r.Msg || '失败', false);
     V8.RefreshTable({ _PageIndex: 1 });
   });
-});
-```
-
+});
+```
+
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=v8-menu-buttons-003 sha256=d04e7a71ffe8baa47c2430077d0fd0bb44dffc62c7e7ce2bca9d02b220ae24f5 -->
-## 4.1 模式 B2：在线微服务定制页（OpenAppDialog）
-
-当弹窗包含复杂布局、多步骤交互、实时校验或后续需要 AI 在线维护时，优先把页面实现为在线微服务，按钮 V8 代码只负责打开页面、传入上下文和接收结果。不要把长篇 HTML/CSS 写进 `V8Code`。
-
-```js
-V8.OpenAppDialog({
-  AppKey: 'order_batch_processor',
-  RoutePath: '/execute',
-  Title: '批量处理订单',
-  TitleIcon: 'fas fa-layer-group',
-  Width: 'min(960px, calc(100vw - 32px))',
-  OpenType: 'Dialog',
-  Data: {
-    ids: (V8.TableRowSelected || []).map(function (row) { return row.Id; }),
-    source: 'order-list'
-  },
-  OnSuccess: function (data) {
-    V8.Tips(data.message || '处理成功', true);
-    V8.RefreshTable({ _PageIndex: -1 });
-  },
-  OnCancel: function () {},
-  OnError: function (error) {
-    V8.Tips(error.message || '应用执行失败', false);
-  }
-});
-```
-
-参数规则：
-
-| 参数 | 必传 | 默认值 | 用法 |
-|------|------|--------|------|
-| `AppKey` | 是 | - | `sys_microiservice.MsKey`，目标微服务必须已经编译发布。 |
-| `RoutePath` | 否 | `/` | 子应用内部路由；`MicroRoute` 是兼容别名，优先取 `RoutePath`。 |
-| `Version` | 否 | 当前 `BuildVersion` | 固定加载某个发布版本；通常省略以使用当前版本。 |
-| `Title` | 否 | `应用` | Dialog/Drawer 标题。 |
-| `TitleIcon` | 否 | `fas fa-window-maximize` | 标题图标 class。 |
-| `Width` | 否 | `min(920px, calc(100vw - 32px))` | CSS 宽度值，推荐带移动端安全边距。 |
-| `OpenType` | 否 | `Dialog` | `Dialog` 或 `Drawer`。 |
-| `Data` | 否 | `{}` | 业务参数，子应用从 `window.microApp.getData().dialogData` 获取；只放普通可序列化数据。 |
-| `OnSuccess(data)` | 否 | - | 子应用成功回调，回调后自动关闭。 |
-| `OnCancel(data)` | 否 | - | 子应用取消回调，回调后自动关闭。 |
-| `OnError(error)` | 否 | - | 加载或执行错误回调，不自动关闭。 |
-
-宿主还会自动传入 `apiBase`、`osClient`、`token`、`appKey`、`version`、`microRoute`、`dialog:true`。子应用返回协议：
-
-```js
-window.microApp.dispatch({ type: 'app-dialog:success', data: { message: '已提交' } });
-window.microApp.dispatch({ type: 'app-dialog:cancel', data: {} });
-window.microApp.dispatch({ type: 'app-dialog:error', data: { message: '校验失败' } });
-```
-
-- `success` / `cancel` 会自动关闭，`error` 保持页面打开。
-- 禁止把回调函数放进 `Data`；回调必须使用 `OnSuccess` / `OnCancel` / `OnError`。
-- 不要把 Token 拼接到 URL；使用宿主自动下发的 `token`。
-- `OpenAppDialog` 加载在线微服务；`OpenDialog` 加载 Microi.Client 内已注册的 Vue 组件，两者不要混用。
-
-### 4.2 业务面板复用通用弹窗宿主
-
-某个模块是否出现入口、入口名称、排序、图标和显隐规则属于 `sys_menu.MoreBtns` 配置，禁止在 `diy-table.vue`、卡片模板或通用 mixin 中按菜单 Id、Url、表名直接渲染业务按钮。主前端已有 Vue 面板时先全局注册组件，再用 `V8.OpenDialog`；独立发布、跨应用升级的页面用 `V8.OpenAppDialog`。禁止为单个业务面板扩展 `V8.Open<业务名>` 包装方法。
-
-系统账号的访问密钥入口示例：
-
-```js
-// V8CodeShow
-var currentUser = V8.CurrentUser || {};
-var currentUserId = String(currentUser.Id || "").toLowerCase();
-var targetUserId = String((V8.Form && V8.Form.Id) || "").toLowerCase();
-V8.Result = typeof V8.OpenDialog === "function"
-  && currentUser._AccessKeySession !== true
-  && !!targetUserId
-  && (currentUser._IsAdmin === true
-    || Number(currentUser.Level || 0) >= 9999
-    || currentUserId === targetUserId);
-```
-
-```js
-// V8Code
-var user = V8.Form || {};
-V8.OpenDialog({
-  ComponentName: "UserAccessKeyPanel",
-  Title: "访问密钥 - " + (user.Name || user.Account || ""),
-  TitleIcon: "fas fa-key",
-  Width: "min(980px, calc(100vw - 32px))",
-  OpenType: "Dialog",
-  DataAppend: { User: user }
-});
-```
-
-按钮应设置稳定 `Id`、`ShowRow:true`、`Icon:"fas fa-key"`。前端显隐只改善体验，创建、查询、吊销等接口仍必须在服务端重新校验普通登录会话以及本人/平台管理员权限。
-
-复杂策略编辑器（例如角色 AI 数据权限）应把行按钮持久化到菜单 `MoreBtns`，按钮只通过
-`V8.OpenDialog({ ComponentName, DataAppend })` 打开已注册的 Vue 组件。验收需同时回读菜单按钮 JSON、
-确认组件进入生产构建，并在真实列表行打开弹层；只保留旧定制页面里的按钮不算低代码菜单已迁移。
-
+## 4.1 模式 B2：在线微服务定制页（OpenAppDialog）
+
+当弹窗包含复杂布局、多步骤交互、实时校验或后续需要 AI 在线维护时，优先把页面实现为在线微服务，按钮 V8 代码只负责打开页面、传入上下文和接收结果。不要把长篇 HTML/CSS 写进 `V8Code`。
+
+```js
+V8.OpenAppDialog({
+  AppKey: 'order_batch_processor',
+  RoutePath: '/execute',
+  Title: '批量处理订单',
+  TitleIcon: 'fas fa-layer-group',
+  Width: 'min(960px, calc(100vw - 32px))',
+  OpenType: 'Dialog',
+  Data: {
+    ids: (V8.TableRowSelected || []).map(function (row) { return row.Id; }),
+    source: 'order-list'
+  },
+  OnSuccess: function (data) {
+    V8.Tips(data.message || '处理成功', true);
+    V8.RefreshTable({ _PageIndex: -1 });
+  },
+  OnCancel: function () {},
+  OnError: function (error) {
+    V8.Tips(error.message || '应用执行失败', false);
+  }
+});
+```
+
+参数规则：
+
+| 参数 | 必传 | 默认值 | 用法 |
+|------|------|--------|------|
+| `AppKey` | 是 | - | `sys_microiservice.MsKey`，目标微服务必须已经编译发布。 |
+| `RoutePath` | 否 | `/` | 子应用内部路由；`MicroRoute` 是兼容别名，优先取 `RoutePath`。 |
+| `Version` | 否 | 当前 `BuildVersion` | 固定加载某个发布版本；通常省略以使用当前版本。 |
+| `Title` | 否 | `应用` | Dialog/Drawer 标题。 |
+| `TitleIcon` | 否 | `fas fa-window-maximize` | 标题图标 class。 |
+| `Width` | 否 | `min(920px, calc(100vw - 32px))` | CSS 宽度值，推荐带移动端安全边距。 |
+| `OpenType` | 否 | `Dialog` | `Dialog` 或 `Drawer`。 |
+| `Data` | 否 | `{}` | 业务参数，子应用从 `window.microApp.getData().dialogData` 获取；只放普通可序列化数据。 |
+| `OnSuccess(data)` | 否 | - | 子应用成功回调，回调后自动关闭。 |
+| `OnCancel(data)` | 否 | - | 子应用取消回调，回调后自动关闭。 |
+| `OnError(error)` | 否 | - | 加载或执行错误回调，不自动关闭。 |
+
+宿主还会自动传入 `apiBase`、`osClient`、`token`、`appKey`、`version`、`microRoute`、`dialog:true`。子应用返回协议：
+
+```js
+window.microApp.dispatch({ type: 'app-dialog:success', data: { message: '已提交' } });
+window.microApp.dispatch({ type: 'app-dialog:cancel', data: {} });
+window.microApp.dispatch({ type: 'app-dialog:error', data: { message: '校验失败' } });
+```
+
+- `success` / `cancel` 会自动关闭，`error` 保持页面打开。
+- 禁止把回调函数放进 `Data`；回调必须使用 `OnSuccess` / `OnCancel` / `OnError`。
+- 不要把 Token 拼接到 URL；使用宿主自动下发的 `token`。
+- `OpenAppDialog` 加载在线微服务；`OpenDialog` 加载 Microi.Client 内已注册的 Vue 组件，两者不要混用。
+
+### 4.2 业务面板复用通用弹窗宿主
+
+某个模块是否出现入口、入口名称、排序、图标和显隐规则属于 `sys_menu.MoreBtns` 配置，禁止在 `diy-table.vue`、卡片模板或通用 mixin 中按菜单 Id、Url、表名直接渲染业务按钮。主前端已有 Vue 面板时先全局注册组件，再用 `V8.OpenDialog`；独立发布、跨应用升级的页面用 `V8.OpenAppDialog`。禁止为单个业务面板扩展 `V8.Open<业务名>` 包装方法。
+
+系统账号的访问密钥入口示例：
+
+```js
+// V8CodeShow
+var currentUser = V8.CurrentUser || {};
+var currentUserId = String(currentUser.Id || "").toLowerCase();
+var targetUserId = String((V8.Form && V8.Form.Id) || "").toLowerCase();
+V8.Result = typeof V8.OpenDialog === "function"
+  && currentUser._AccessKeySession !== true
+  && !!targetUserId
+  && (currentUser._IsAdmin === true
+    || Number(currentUser.Level || 0) >= 9999
+    || currentUserId === targetUserId);
+```
+
+```js
+// V8Code
+var user = V8.Form || {};
+V8.OpenDialog({
+  ComponentName: "UserAccessKeyPanel",
+  Title: "访问密钥 - " + (user.Name || user.Account || ""),
+  TitleIcon: "fas fa-key",
+  Width: "min(980px, calc(100vw - 32px))",
+  OpenType: "Dialog",
+  DataAppend: { User: user }
+});
+```
+
+按钮应设置稳定 `Id`、`ShowRow:true`、`Icon:"fas fa-key"`。前端显隐只改善体验，创建、查询、吊销等接口仍必须在服务端重新校验普通登录会话以及本人/平台管理员权限。
+
+复杂策略编辑器（例如角色 AI 数据权限）应把行按钮持久化到菜单 `MoreBtns`，按钮只通过
+`V8.OpenDialog({ ComponentName, DataAppend })` 打开已注册的 Vue 组件。验收需同时回读菜单按钮 JSON、
+确认组件进入生产构建，并在真实列表行打开弹层；只保留旧定制页面里的按钮不算低代码菜单已迁移。
+
 <!-- /microi-progressive:chunk -->
 ## 详细参考路由（渐进披露）
 

package/skills/v8-menu-buttons/references/progressive-01-2-/346/214/211/351/222/256/345/257/271/350/261/241-schema.md

@@ -14,78 +14,78 @@
   "BtnStyle": "primary",      // primary | success | warning | danger | (空)
   "IsVisible": true,          // 是否参与渲染（false 则完全隐藏）
   "ShowRow": true,            // MoreBtns 必填：true 显示在行内，false 收进"更多"
-  "V8CodeShow": "...",        // 显隐表达式 JS：return true/false 或赋值 V8.Result=true/false
-  "V8Code": "...",            // 点击执行的 JS（前端 V8 上下文）
-  "Url": "",                  // 可选：直接跳转 URL（不与 V8Code 同用）
-  "TargetSysMenuId": "",      // 仅 PageTabs：关联另一个 sys_menu.Id，替换路由并完整加载目标模块
-  "RunBackground": false,      // 可选：true 时以后台任务执行接口引擎
-  "BackgroundTask": false,     // 可选：兼容别名
-  "IsBackgroundTask": false,   // 可选：兼容别名
-  "ApiEngineKey": "",          // 可选：后台任务要执行的接口引擎 Key
-  "BadgeEnabled": true,         // 可选：显示统计角标
-  "BadgeApiEngineKey": "button_counts",
-  "BadgeValuePath": "",        // 可选：如 Data.Rows.{RowId}.button-id
-  "BadgeField": "",            // 行按钮读当前行；PageTab/页面按钮读模块 StatisticsFields，不请求接口
-  "BadgeTone": "primary",      // primary/success/warning/danger/info
-  "BadgeMax": 99,
-  "BadgeShowZero": false,
-  "BadgeRefreshSeconds": 60
-}
-```
-
-### 统计角标接口契约
-
-角标适用于附件数、日志数、未处理子记录等“点击按钮后有明确行动”的数量。
-`PageTabs/MoreBtns/PageBtns/BatchSelectMoreBtns/ExportMoreBtns/FormBtns` 都可配置。前端按不同
-`BadgeApiEngineKey` 分组，每个接口仅调用一次，并传入 `Ids`（当前页行 Id）、
-`ButtonKeys`、`SysMenuId/_SysMenuId`、`DiyTableId` 和筛选上下文。
-
-推荐一次返回页面级与逐行结果：
-
-```js
-return {
-  Code: 1,
-  Data: {
-    Buttons: { 'button-id': 12 },
-    Rows: {
-      'row-id-1': { 'button-id': 2 },
-      'row-id-2': { 'button-id': 0 }
-    }
-  }
-};
-```
-
-按钮和 PageTab 必须有稳定 `Id`，否则只能回退用 `Name` 匹配。`Data.Buttons` 同时用于页面按钮和 PageTabs；页签可通过 `BadgeValuePath=Data.Buttons.{TabId}` 显式取值。PageTabs/页面按钮若使用 `BadgeField`，必须同时把该字段加入模块 `StatisticsFields`，读取页面汇总值。不要在按钮 V8、Tab V8、模板引擎或每行
-生命周期里单独查数量；后端应按 `Ids` 批量 `GROUP BY`，并继续应用租户、菜单和数据权限。
-统计失败只隐藏角标，不能阻断按钮本身或 PageTab 切换。
-
-### JsonTable 内嵌选择器的数据源代理
-
-`PageTabs/MoreBtns/PageBtns/BatchSelectMoreBtns/ExportMoreBtns/FormBtns` 都是 `JsonTable` 字段，
-其中的列对象不是独立 `diy_field`。内嵌 `Select/Radio/Checkbox/Autocomplete/Cascader/SelectTree`
-一旦使用 `Sql/DataSource/ApiEngine` 服务端数据源，必须在列的 `Config.DataSourceFieldId` 中填写
-同租户、同表内一个真实且权限等价的 `diy_field.Id`。禁止把内嵌列的 `Key` 或列 `Id` 当成
-字段 Id，否则打开“模块设计-按钮”时会触发“DiyField 数据不存在”，并使同批字段数据加载失败。
-
-远程 SQL 搜索还应同时设置 `DataSourceSqlRemote=true`，使用 `$Keyword$` 参数并限制返回条数；
-应用包回归测试必须逐个校验所有按钮集合的代理字段真实存在、保存字段/显示字段一致。
-
-### PageTabs 关联模块
-
-- 列表页固定顺序为“模块 Hero（标题/副标题/动态指标）→ PageTabs → 查询与表格”；PageTabs 不能渲染到 Hero 上方，也不能重复承担模块标题。
-- `TargetSysMenuId` 为空时，页签仍在当前模块执行 `V8Code` 和重新查询。
-- `TargetSysMenuId` 指向其它模块时，点击会在当前 `diy-table` 实例内加载目标模块自己的表单引擎、字段、查询接口替换、按钮和分页配置；入口路由、面包屑、顶部访问标签和宿主 Hero 不变，URL 只更新 `Tab` 查询参数。
-- 目标模块可以设置 `Display=0、AppDisplay=0` 隐藏左侧菜单，但必须给使用角色分配菜单权限，否则动态路由中找不到目标模块。
-- 一组 PageTabs 只保存在入口模块；隐藏目标模块设置 `ParentId=入口菜单Id、HasChild=0、PageTabs=[]`，不得复制同一套 PageTabs。入口菜单保持 `HasChild=0`，仍然直接打开业务页面。
-- 模块设计器的 PageTabs 必须显示【关联模块】可搜索菜单树，展示模块名称并保存 `TargetSysMenuId`，不能让该协议只能手工改 JSON。
-- 禁止在 `diy-table` 或 mixin 中按模块名、Url、表名写死页签数据源。
-
-### V8CodeShow（显隐控制）—— 支持 `return` 和 `V8.Result`
-
-未配置 `V8CodeShow`，或代码执行后既没有 `return true/false`、也没有设置
-`V8.Result = true/false` 时，显示条件默认按“显示”处理；只有明确
-`return false` 或 `V8.Result = false` 才由显示条件隐藏按钮。角色按钮权限仍是
-独立约束，不应通过省略显示条件绕过。
+  "V8CodeShow": "...",        // 显隐表达式 JS：return true/false 或赋值 V8.Result=true/false
+  "V8Code": "...",            // 点击执行的 JS（前端 V8 上下文）
+  "Url": "",                  // 可选：直接跳转 URL（不与 V8Code 同用）
+  "TargetSysMenuId": "",      // 仅 PageTabs：关联另一个 sys_menu.Id，替换路由并完整加载目标模块
+  "RunBackground": false,      // 可选：true 时以后台任务执行接口引擎
+  "BackgroundTask": false,     // 可选：兼容别名
+  "IsBackgroundTask": false,   // 可选：兼容别名
+  "ApiEngineKey": "",          // 可选：后台任务要执行的接口引擎 Key
+  "BadgeEnabled": true,         // 可选：显示统计角标
+  "BadgeApiEngineKey": "button_counts",
+  "BadgeValuePath": "",        // 可选：如 Data.Rows.{RowId}.button-id
+  "BadgeField": "",            // 行按钮读当前行；PageTab/页面按钮读模块 StatisticsFields，不请求接口
+  "BadgeTone": "primary",      // primary/success/warning/danger/info
+  "BadgeMax": 99,
+  "BadgeShowZero": false,
+  "BadgeRefreshSeconds": 60
+}
+```
+
+### 统计角标接口契约
+
+角标适用于附件数、日志数、未处理子记录等“点击按钮后有明确行动”的数量。
+`PageTabs/MoreBtns/PageBtns/BatchSelectMoreBtns/ExportMoreBtns/FormBtns` 都可配置。前端按不同
+`BadgeApiEngineKey` 分组，每个接口仅调用一次，并传入 `Ids`（当前页行 Id）、
+`ButtonKeys`、`SysMenuId/_SysMenuId`、`DiyTableId` 和筛选上下文。
+
+推荐一次返回页面级与逐行结果：
+
+```js
+return {
+  Code: 1,
+  Data: {
+    Buttons: { 'button-id': 12 },
+    Rows: {
+      'row-id-1': { 'button-id': 2 },
+      'row-id-2': { 'button-id': 0 }
+    }
+  }
+};
+```
+
+按钮和 PageTab 必须有稳定 `Id`，否则只能回退用 `Name` 匹配。`Data.Buttons` 同时用于页面按钮和 PageTabs；页签可通过 `BadgeValuePath=Data.Buttons.{TabId}` 显式取值。PageTabs/页面按钮若使用 `BadgeField`，必须同时把该字段加入模块 `StatisticsFields`，读取页面汇总值。不要在按钮 V8、Tab V8、模板引擎或每行
+生命周期里单独查数量；后端应按 `Ids` 批量 `GROUP BY`，并继续应用租户、菜单和数据权限。
+统计失败只隐藏角标，不能阻断按钮本身或 PageTab 切换。
+
+### JsonTable 内嵌选择器的数据源代理
+
+`PageTabs/MoreBtns/PageBtns/BatchSelectMoreBtns/ExportMoreBtns/FormBtns` 都是 `JsonTable` 字段，
+其中的列对象不是独立 `diy_field`。内嵌 `Select/Radio/Checkbox/Autocomplete/Cascader/SelectTree`
+一旦使用 `Sql/DataSource/ApiEngine` 服务端数据源，必须在列的 `Config.DataSourceFieldId` 中填写
+同租户、同表内一个真实且权限等价的 `diy_field.Id`。禁止把内嵌列的 `Key` 或列 `Id` 当成
+字段 Id，否则打开“模块设计-按钮”时会触发“DiyField 数据不存在”，并使同批字段数据加载失败。
+
+远程 SQL 搜索还应同时设置 `DataSourceSqlRemote=true`，使用 `$Keyword$` 参数并限制返回条数；
+应用包回归测试必须逐个校验所有按钮集合的代理字段真实存在、保存字段/显示字段一致。
+
+### PageTabs 关联模块
+
+- 列表页固定顺序为“模块 Hero（标题/副标题/动态指标）→ PageTabs → 查询与表格”；PageTabs 不能渲染到 Hero 上方，也不能重复承担模块标题。
+- `TargetSysMenuId` 为空时，页签仍在当前模块执行 `V8Code` 和重新查询。
+- `TargetSysMenuId` 指向其它模块时，点击会在当前 `diy-table` 实例内加载目标模块自己的表单引擎、字段、查询接口替换、按钮和分页配置；入口路由、面包屑、顶部访问标签和宿主 Hero 不变，URL 只更新 `Tab` 查询参数。
+- 目标模块可以设置 `Display=0、AppDisplay=0` 隐藏左侧菜单，但必须给使用角色分配菜单权限，否则动态路由中找不到目标模块。
+- 一组 PageTabs 只保存在入口模块；隐藏目标模块设置 `ParentId=入口菜单Id、HasChild=0、PageTabs=[]`，不得复制同一套 PageTabs。入口菜单保持 `HasChild=0`，仍然直接打开业务页面。
+- 模块设计器的 PageTabs 必须显示【关联模块】可搜索菜单树，展示模块名称并保存 `TargetSysMenuId`，不能让该协议只能手工改 JSON。
+- 禁止在 `diy-table` 或 mixin 中按模块名、Url、表名写死页签数据源。
+
+### V8CodeShow（显隐控制）—— 支持 `return` 和 `V8.Result`
+
+未配置 `V8CodeShow`，或代码执行后既没有 `return true/false`、也没有设置
+`V8.Result = true/false` 时，显示条件默认按“显示”处理；只有明确
+`return false` 或 `V8.Result = false` 才由显示条件隐藏按钮。角色按钮权限仍是
+独立约束，不应通过省略显示条件绕过。
 
 推荐写法：直接返回布尔值。
 
@@ -113,87 +113,87 @@ if (V8.Form.Status == '待指派' && !V8.Form.AssigneeId) {
 | `V8.TableId` | 当前 diy_table 的 Id |
 | `V8.TableRowSelected` | 批量按钮里勾选的行数组 |
 | `V8.CurrentUser` | 登录用户 |
-| `V8.ClientType` | `PC` / `IOS` / `Android` / `H5` / `WeChat` |
+| `V8.ClientType` | `PC` / `IOS` / `Android` / `H5` / `WeChat` |
 | `V8.Tips(msg, ok?)` | 浮层提示 |
 | `V8.ConfirmTips(msg, cb)` | 确认弹窗 |
 | `V8.RefreshTable({_PageIndex:1})` | 刷新列表 |
-| `V8.SearchSet({Field:value})` | 设置/重置筛选条件（PageTabs 常用）|
-| `V8.OpenAnyForm({...})` | 弹出任意表单（核心：可替换提交事件）|
-| `V8.OpenAppDialog({...})` | 按 AppKey 打开已发布在线微服务定制页 |
-| `V8.FormSubmit({...})` | 提交当前表单 |
-| `V8.FormSet(field, val)` | 普通表单触发目标字段 V8；列表上下文只更新当前行/模板 |
-| `V8.ApiEngine.Run({...})` | 调用接口引擎（业务逻辑必走）|
-| `V8.ApiEngine.RunBackground(...)` | 启动后台任务（用于安装、导入、初始化等长任务）|
-
-### V8Code 格式化强制要求
-- AI、MCP、VS Code 插件或脚本生成 `V8Code` / `V8CodeShow` 时，必须保存为可读的多行 JavaScript，包含换行和缩进；禁止把完整逻辑压成一整行。
-- 写入 `sys_menu.MoreBtns/FormBtns/PageTabs/BatchSelectMoreBtns` 等 JSON 字符串时，也要先按 `.js` 文件格式组织代码，再通过 `JSON.stringify` 或等价方式转义保存。
-- `V8.OpenAnyTable`、`V8.OpenAnyForm`、`V8.ApiEngine.Run`、确认弹窗、回调函数等嵌套结构必须分行，回调内部逻辑至少缩进一级。
-- 只允许极短的单表达式显隐代码写成一行，例如 `V8.Result = true;`；一旦包含 `if`、`return`、`function`、`async`、数组/对象字面量或接口调用，就必须多行格式化。
-
-格式化示例：
-```js
-var projectId = V8.Form && V8.Form.Id ? V8.Form.Id : "";
-if (!projectId) {
-  V8.Tips("缺少项目Id，无法打开关联清单。", false);
-  return;
-}
-
-V8.OpenAnyTable({
-  SysMenuId: "01K...",
-  DialogType: "Drawer",
-  Width: "80vw",
-  MultipleSelect: false,
-  PropsWhere: [
-    ["XiangmuID", "=", projectId]
-  ],
-  SubmitEvent: async function(selectData, callback) {
-    callback({
-      Code: 1,
-      Data: selectData
-    });
-  }
-});
-```
-
----
-
+| `V8.SearchSet({Field:value})` | 设置/重置筛选条件（PageTabs 常用）|
+| `V8.OpenAnyForm({...})` | 弹出任意表单（核心：可替换提交事件）|
+| `V8.OpenAppDialog({...})` | 按 AppKey 打开已发布在线微服务定制页 |
+| `V8.FormSubmit({...})` | 提交当前表单 |
+| `V8.FormSet(field, val)` | 普通表单触发目标字段 V8；列表上下文只更新当前行/模板 |
+| `V8.ApiEngine.Run({...})` | 调用接口引擎（业务逻辑必走）|
+| `V8.ApiEngine.RunBackground(...)` | 启动后台任务（用于安装、导入、初始化等长任务）|
+
+### V8Code 格式化强制要求
+- AI、MCP、VS Code 插件或脚本生成 `V8Code` / `V8CodeShow` 时，必须保存为可读的多行 JavaScript，包含换行和缩进；禁止把完整逻辑压成一整行。
+- 写入 `sys_menu.MoreBtns/FormBtns/PageTabs/BatchSelectMoreBtns` 等 JSON 字符串时，也要先按 `.js` 文件格式组织代码，再通过 `JSON.stringify` 或等价方式转义保存。
+- `V8.OpenAnyTable`、`V8.OpenAnyForm`、`V8.ApiEngine.Run`、确认弹窗、回调函数等嵌套结构必须分行，回调内部逻辑至少缩进一级。
+- 只允许极短的单表达式显隐代码写成一行，例如 `V8.Result = true;`；一旦包含 `if`、`return`、`function`、`async`、数组/对象字面量或接口调用，就必须多行格式化。
+
+格式化示例：
+```js
+var projectId = V8.Form && V8.Form.Id ? V8.Form.Id : "";
+if (!projectId) {
+  V8.Tips("缺少项目Id，无法打开关联清单。", false);
+  return;
+}
+
+V8.OpenAnyTable({
+  SysMenuId: "01K...",
+  DialogType: "Drawer",
+  Width: "80vw",
+  MultipleSelect: false,
+  PropsWhere: [
+    ["XiangmuID", "=", projectId]
+  ],
+  SubmitEvent: async function(selectData, callback) {
+    callback({
+      Code: 1,
+      Data: selectData
+    });
+  }
+});
+```
+
+---
+
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=v8-menu-buttons-005 sha256=1dddbfaac5cd9a350686ff72c47f1cd5ed022bcdc425a7d54b790537df445cd5 -->
-## 5. 模式 C：状态机推进（无需弹窗）
-
-```js
-var next = '';
-switch (V8.Form.Status) {
-  case '待完成': next = '待验收'; break;
-  case '待验收': next = '待评价'; break;
-}
-if (next) {
-  var result = await V8.ApiEngine.Run('order_advance_status', {
-    Id: V8.Form.Id,
-    ExpectedStatus: V8.Form.Status,
-    NextStatus: next
-  });
-  V8.Tips(result.Code == 1 ? '状态已更新' : result.Msg, result.Code == 1);
-  if (result.Code == 1) V8.RefreshTable({ _PageIndex: -1 });
-}
-```
-
-状态机必须由接口引擎校验当前状态、目标状态、权限和并发版本；不要在前端直接更新状态字段。
+## 5. 模式 C：状态机推进（无需弹窗）
+
+```js
+var next = '';
+switch (V8.Form.Status) {
+  case '待完成': next = '待验收'; break;
+  case '待验收': next = '待评价'; break;
+}
+if (next) {
+  var result = await V8.ApiEngine.Run('order_advance_status', {
+    Id: V8.Form.Id,
+    ExpectedStatus: V8.Form.Status,
+    NextStatus: next
+  });
+  V8.Tips(result.Code == 1 ? '状态已更新' : result.Msg, result.Code == 1);
+  if (result.Code == 1) V8.RefreshTable({ _PageIndex: -1 });
+}
+```
+
+状态机必须由接口引擎校验当前状态、目标状态、权限和并发版本；不要在前端直接更新状态字段。
 
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=v8-menu-buttons-006 sha256=86eb74f9e150eb398b010f2cc0a00920669e12f2e6f2729f2443250659e5c0bd -->
 ## 6. 模式 D：批量操作（BatchSelectMoreBtns）
 
 ```js
-var rows = V8.TableRowSelected;
-if (!rows || rows.length == 0) { V8.Tips('请先勾选数据'); return; }
-var ids = rows.map(function (r) { return r.Id; });
-V8.ConfirmTips('确认删除选中的 ' + ids.length + ' 条？', function () {
-  V8.ApiEngine.Run('order_batch_delete', {
-    Ids: ids
-  }, function (r) {
-    if (r.Code == 1) { V8.Tips('删除成功'); V8.RefreshTable({ _PageIndex: 1 }); }
+var rows = V8.TableRowSelected;
+if (!rows || rows.length == 0) { V8.Tips('请先勾选数据'); return; }
+var ids = rows.map(function (r) { return r.Id; });
+V8.ConfirmTips('确认删除选中的 ' + ids.length + ' 条？', function () {
+  V8.ApiEngine.Run('order_batch_delete', {
+    Ids: ids
+  }, function (r) {
+    if (r.Code == 1) { V8.Tips('删除成功'); V8.RefreshTable({ _PageIndex: 1 }); }
     else V8.Tips(r.Msg, false);
   });
 });
@@ -201,7 +201,7 @@ V8.ConfirmTips('确认删除选中的 ' + ids.length + ' 条？', function () {
 
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=v8-menu-buttons-007 sha256=cb0ccac7faf880e55f33a510fdf43b024ace93d5c80618ddd6a40ca3efbcbb1b -->
-## 7. 模式 E：PageTabs 切换筛选
+## 7. 模式 E：PageTabs 切换筛选
 
 ```js
 // PageTab："待办"
@@ -217,6 +217,6 @@ V8.SearchSet({ Status: '' });
 return V8.ClientType != 'PC';
 ```
 
----
-
+---
+
 <!-- /microi-progressive:chunk -->