@microi.net/cli 5.2.1 → 5.2.3

package/skills/module-engine/references/module-config.md

@@ -1,204 +1,204 @@
-# 模块引擎配置参考
-
-## 核心归属
-
-| 配置 | 归属 |
-|---|---|
-| 表与字段元数据 | `diy_table`、`diy_field` |
-| 菜单、列表列、按钮、打开方式、ViewSchema | `sys_menu` |
-| 接口替换业务逻辑 | `sys_apiengine` |
-| 左右树配置 | `diy_LeftJoinRightView` |
-| MicroService 运行时/页面 | `sys_microiservice`、`sys_microiservice_page` |
-
-## 查询与显示
-
-| 逻辑配置 | sys_menu 侧含义 |
-|---|---|
-| `TableDiyFieldIds` | 当前模块可用字段全集 |
-| `SelectFields` | 列表查询字段 |
-| `SearchFieldIds` | 可搜索字段 |
-| `SortFieldIds` | 可排序字段 |
-| `NotShowFields` | 查询但不直接显示的字段 |
-| `StatisticsFields` | 汇总字段 |
-| `MobileListFields` | 移动端列表字段 |
-| `CardTitleTagFields` | 卡片标题/标签字段 |
-| `CardBottomTagFields` | 卡片底部字段 |
-| `DefaultOrderBy` | 默认排序 |
-| `MenuBadgeEnabled` | 左侧菜单统计角标开关 |
-| `MenuBadgeApiEngineKey` | 菜单统计接口引擎 Key，返回 `Data.Value` |
-| `MenuBadgeTooltip` | 鼠标移入菜单数字角标时显示的统计口径说明；应写清对象、用户范围及待办/未读/总数等含义 |
-
-默认隐藏 Id、外键、系统字段、布局字段、上传、富文本、地图和子表等重字段。
-默认搜索优先名称、标题、编号、状态、类型、分类、负责人和时间；统计优先金额、
-数量、价格、积分和余额。用户明确配置优先。
-
-每个可见且绑定表的 Diy 模块还必须有 List/Card 展示设计：所有普通列给合理
-`TableWidth`，至少一个 PC 复合列给 `MinWidth`，Hero 有业务标题、副标题和 2~4 个
-真实指标，移动卡片覆盖可用的标题/副标题/顶部/状态/右侧/正文/Meta/底部区域。
-复合列一般只用一个主字段加一个 `Lines` 次要字段，形成紧凑双行；可以配置多个各自双行
-的复合列，但不要在同一列堆两个 `Lines` 形成三行。复合列和卡片区域使用过的字段不得
-继续机械显示为普通列或在多个区域重复。
-
-菜单角标只用于少量待办、未读、逾期、预警等重要入口；PageTabs 与按钮角标按业务价值
-选择。相同页面的一组指标/角标使用一个批量接口，不逐指标、逐按钮、逐行请求。
-配置菜单角标时应同时配置 `MenuBadgeTooltip`；历史菜单缺少该字段时，客户端回退显示菜单名
-和原始数字，不得因提示文案缺失影响角标本身。
-自动默认值只保证旧库和漏配模块不出现空白标题，不替代业务设计；严禁用随机数或静态演示
-数字伪造统计。没有可推断业务指标时只使用真实 `DataCount/PageCount` 兜底。
-
-## 打开方式细节
-
-### Diy
-
-默认 `/diy/diy-table-rowlist`，绑定 `DiyTableId` 后自动具备列表、搜索、新增、
-编辑、删除、导入和导出。
-
-### Component
-
-用于主前端源码已注册的组件。组件路径必须存在并经过目标前端构建验证。
-
-### Iframe
-
-仅允许受控 URL。地址接口引擎可返回动态 URL，但：
-
-- 密钥只在后端使用；
-- 外部 Token 短时缓存并按 `OsClient + 用户 + 目标系统` 隔离；
-- URL 参数使用一次性交换码，不使用当前后台 JWT；
-- 限制跳转域名并防 SSRF/开放重定向。
-
-### SecondMenu
-
-只承载子菜单，不绑定业务表；`HasChild` 与真实子菜单一致。
-
-### Report
-
-使用报表引擎虚拟表。读取 `report-engine/SKILL.md`。
-
-### MicroService
-
-必须同时绑定：
-
-- `MicroServiceId`
-- `MicroServicePageId`
-- `MicroServiceRoutePath`
-- `MicroServiceKey`
-- `ComponentPath=/micro-app/host`
-
-路由优先 `/micro-app/{MsKey}/{RoutePath}`，并兼容历史 Id 路由。
-
-完整系统 Manifest 使用可移植引用：模块写 `openType=MicroService`、`microServiceKey`、`microServiceRoutePath`，不把某个租户的 `MicroServiceId/MicroServicePageId` 固化进发行包。`microi_generate_system` 会在首个写操作前回读运行元数据并补齐两个 Id；解析失败必须停止整次生成。直接调用 `microi_create_module` 时仍须一次提供全部四个绑定字段。
-
-## 跨端 ViewSchema
-
-专用物理字段：
-
-| 字段 | 说明 |
-|---|---|
-| `EnableViewSchema` | 1 启用 Detail/Edit 自定义表单视图；不控制 List/Card |
-| `ViewSchemaVersion` | 可选；为空默认 `1.0` |
-| `ViewConfigVersion` | 可选；为空默认 `1`，后续发布递增并驱动缓存失效 |
-| `ViewSchema` | Detail/Edit/List/Card JSON |
-
-顶层 PC 列表不依赖 `EnableViewSchema` 才采用新样式：平台始终显示紧凑模块标题；ViewSchema 中有效的 List-PC 与 Card-Mobile 配置也不受该开关限制。模块表单中的 `DiyModulePresentationDesigner` 负责可视化编辑这些展示配置，以独立 JSON 编辑 Detail/Edit，并通过高级 JSON 保留角色视图及未知字段。
-
-设计器固定提供“模块标题与统计 / PC 复合列 / 移动端卡片 / 自定义表单 / 高级 JSON”五个
-Tab；开关标签是“启用自定义表单视图”，只影响第四个 Tab 中的 Detail/Edit。
-
-视图项常用字段：`Key`、`Scene`、`Device`、`RoleIds`、`Priority`、`Layout`。
-标准区块包括 `EntityHero`、`MetricStrip`、`ActionGrid`、
-`ResponsiveSection`。声明式动作包括：
-
-`ApiEngine`、`OpenDetail`、`OpenList`、`OpenForm`、`Navigate`、
-`Dial`、`Scan`、`Map`、`Refresh`、`Back`、`Copy`。
-
-`ParamMap` 可使用经过白名单处理的 `$form.Field`、`$user.Field`、
-`$menu.Field`。小程序端不下载/执行任意 V8Code。
-
-### List / Card 展示协议
-
-| 配置路径 | 用途 | 核心字段 |
-|---|---|---|
-| `Layout.Hero` | 模块眉题、标题、说明、统计条 | `Eyebrow/Title/Description/Metrics` |
-| `Hero.Metrics[]` | 内置、字段或接口引擎指标 | `Key/Label/Source/Field/ApiEngineKey/ValuePath/Prefix/Suffix/Icon/Tone/Color/RefreshSeconds` |
-| `Layout.List.Columns[]` | PC 复合列 | `Field/Lines/TrailingFields/RequiredFields/Align/MinWidth` |
-| `Layout.Card` | 移动端业务卡片 | `AvatarTextField/TitleField/TopFields/SubtitleFields/RightFields/Fields/MetaFields/BottomFields` |
-
-字段引用对象支持 `Name/AsName/Label/ShowLabel/Icon/Tone/Color/Prefix/Suffix/
-FontWeight/DisplayStyle`。运行时会把引用字段并入 `_SelectFields`；查询接口替换也必须
-返回这些字段。多字段模板沿用对应 `diy_field.V8TmpEngineTable`，不在 ViewSchema 内保存
-可执行脚本。
-
-PC 复合列的常规高度上限是两行：`Field` 占主行，`Lines` 通常只放 1 项。多个信息组拆成
-多个两行复合列；只有确有层级价值且完成桌面截图验收后，才允许在同一列放第 2 个
-`Lines`。`TrailingFields` 位于右侧，不应被误用成增加纵向信息层级。
-
-Hero 必须在 PageTabs 上方渲染。PC 无指标/含指标头部分别为 `44px / 62px`，连同间距的
-总纵向占用约 `50px / 68px`。有指标时标题说明区占约 25%~30%，指标区弹性占满其余空间，
-两区只用弱化渐变分隔；指标容器不加外框，单指标使用轻量语义色背景和图标色块，禁止
-“外层框 + 指标条框 + 指标卡框”的多层线框。无指标时标题说明自动铺满。每个指标必须
-显式配置 `Icon`，同一 Hero 内使用不同 `Tone` 或 `Color` 与不同图标，不能只靠数字区分。
-只允许一次性入场与一次性轻量光效，禁止持续循环动画；
-`prefers-reduced-motion: reduce` 下关闭动画和过渡。
-
-`Hero.Metrics[].Source` 可直接配置 `DataCount`（当前筛选总记录数）或 `PageCount`（本页
-加载数），两者复用列表结果且不请求接口。字段汇总使用 `Field`。动态指标接口按
-`ApiEngineKey` 分组调用，参数包含 `MetricKeys`、当前模块/表、租户和筛选上下文；同一接口
-应一次返回多个指标。`ValuePath` 例：`Data.UnpaidAmount`。
-
-## 动态按钮位置
-
-| 字段 | 位置 |
-|---|---|
-| `MoreBtns` | 行操作 |
-| `FormBtns` | 表单底部 |
-| `BatchSelectMoreBtns` | 批量勾选后 |
-| `PageTabs` | 页面顶部 Tab，固定在模块 Hero 下方 |
-| `PageBtns` | 页面级 |
-| `ExportMoreBtns` | 导出扩展 |
-
-按钮对象必须有稳定唯一 Id、Sort、Name、显隐逻辑和动作。后台任务按钮还要配置
-ApiEngineKey、Workload、幂等字段、并发 Key、业务状态/任务 Id/进度/ETA 字段。
-
-`PageTabs` 与五类按钮共用统计字段：`BadgeEnabled`、`BadgeApiEngineKey`、`BadgeValuePath`、`BadgeField`、
-`BadgeTone`、`BadgeColor`、`BadgeMax`、`BadgeShowZero`、`BadgeRefreshSeconds`。接口一次接收当前页 `Ids` 与
-`ButtonKeys`，推荐返回：
-
-```json
-{
-  "Code": 1,
-  "Data": {
-    "Buttons": { "button-id": 12 },
-    "Rows": { "row-id": { "button-id": 2 } }
-  }
-}
-```
-
-行按钮的 `BadgeField` 直接读取当前行已有字段；PageTabs/页面按钮的 `BadgeField` 读取模块 `StatisticsFields` 页面汇总值，必须同时配置“统计列”。字段模式不调用接口；其它行统计必须批量聚合，禁止 N+1。
-
-## 接口替换
-
-可替换查询、新增、更新、删除、导入、导入进度和导出接口。替换后仍要保持平台
-返回契约、权限、分页、统计、错误码和租户隔离。
-
-- 查询：返回 `Code/Data/DataCount`，不可丢失菜单权限。
-- 导入：读取文件、校验、分片写入、真实进度、幂等恢复。
-- 导出：大数据使用后台任务/流式文件，不在请求内无界物化。
-- 所有路径变量只能使用平台明确支持的占位符，不拼接 Token。
-
-## PageTabs 两种模式
-
-- 无目标菜单：在当前模块执行 V8，通常 `V8.SearchSet(...)`。
-- 有 `TargetSysMenuId`：在当前 `diy-table` 实例内加载目标模块的菜单、表、字段和列表数据。目标菜单即使隐藏导航，也必须给角色权限。
-
-PageTabs 可以通过 `BadgeApiEngineKey` 显示数字角标。接口按 `ButtonKeys` 一次返回所有 Tab 数量到 `Data.Buttons`，`BadgeValuePath` 可显式指定 `Data.Buttons.{TabId}`；失败只隐藏角标，不能阻断页签切换。
-
-PageTabs 只表达当前模块的数据类别/状态，不能取代模块 Hero，也不能渲染到 Hero 上方。
-
-跨表 Tab 由入口模块统一配置一组 PageTabs，目标菜单只保留各自的模块设计、表绑定和角色权限，不复制 PageTabs。隐藏目标菜单统一设置 `ParentId=入口菜单Id、Display=0、AppDisplay=0、HasChild=0、PageTabs=[]`，入口菜单继续保持 `HasChild=0` 作为可直接点击的业务入口。模块设计器用【关联模块】可搜索菜单树展示名称、保存 `TargetSysMenuId`。切换只更新当前 URL 的 `Tab` 查询参数；路由、面包屑、顶部访问标签和入口模块 Hero 保持稳定，表格上下文在原实例中切换。实现时必须取消旧请求、丢弃迟到响应并在失败时回滚，禁止按菜单名或业务表名写死。
-
-首屏和跨模块切换应为 Hero 标题/统计、PageTabs、工具栏和列表提供与最终几何尺寸一致的主题化骨架屏；根据模块元数据判断是否预留指标区和 PageTabs，并支持 `prefers-reduced-motion: reduce`。
-
-## URL 参数
-
-兼容参数包括 `ShowClassicTop`、`ShowClassicLeft`、`FormDataId`。它们只控制
-界面/默认打开记录，不建立授权；记录仍须通过当前菜单和数据权限校验。
+# 模块引擎配置参考
+
+## 核心归属
+
+| 配置 | 归属 |
+|---|---|
+| 表与字段元数据 | `diy_table`、`diy_field` |
+| 菜单、列表列、按钮、打开方式、ViewSchema | `sys_menu` |
+| 接口替换业务逻辑 | `sys_apiengine` |
+| 左右树配置 | `diy_LeftJoinRightView` |
+| MicroService 运行时/页面 | `sys_microiservice`、`sys_microiservice_page` |
+
+## 查询与显示
+
+| 逻辑配置 | sys_menu 侧含义 |
+|---|---|
+| `TableDiyFieldIds` | 当前模块可用字段全集 |
+| `SelectFields` | 列表查询字段 |
+| `SearchFieldIds` | 可搜索字段 |
+| `SortFieldIds` | 可排序字段 |
+| `NotShowFields` | 查询但不直接显示的字段 |
+| `StatisticsFields` | 汇总字段 |
+| `MobileListFields` | 移动端列表字段 |
+| `CardTitleTagFields` | 卡片标题/标签字段 |
+| `CardBottomTagFields` | 卡片底部字段 |
+| `DefaultOrderBy` | 默认排序 |
+| `MenuBadgeEnabled` | 左侧菜单统计角标开关 |
+| `MenuBadgeApiEngineKey` | 菜单统计接口引擎 Key，返回 `Data.Value` |
+| `MenuBadgeTooltip` | 鼠标移入菜单数字角标时显示的统计口径说明；应写清对象、用户范围及待办/未读/总数等含义 |
+
+默认隐藏 Id、外键、系统字段、布局字段、上传、富文本、地图和子表等重字段。
+默认搜索优先名称、标题、编号、状态、类型、分类、负责人和时间；统计优先金额、
+数量、价格、积分和余额。用户明确配置优先。
+
+每个可见且绑定表的 Diy 模块还必须有 List/Card 展示设计：所有普通列给合理
+`TableWidth`，至少一个 PC 复合列给 `MinWidth`，Hero 有业务标题、副标题和 2~4 个
+真实指标，移动卡片覆盖可用的标题/副标题/顶部/状态/右侧/正文/Meta/底部区域。
+复合列一般只用一个主字段加一个 `Lines` 次要字段，形成紧凑双行；可以配置多个各自双行
+的复合列，但不要在同一列堆两个 `Lines` 形成三行。复合列和卡片区域使用过的字段不得
+继续机械显示为普通列或在多个区域重复。
+
+菜单角标只用于少量待办、未读、逾期、预警等重要入口；PageTabs 与按钮角标按业务价值
+选择。相同页面的一组指标/角标使用一个批量接口，不逐指标、逐按钮、逐行请求。
+配置菜单角标时应同时配置 `MenuBadgeTooltip`；历史菜单缺少该字段时，客户端回退显示菜单名
+和原始数字，不得因提示文案缺失影响角标本身。
+自动默认值只保证旧库和漏配模块不出现空白标题，不替代业务设计；严禁用随机数或静态演示
+数字伪造统计。没有可推断业务指标时只使用真实 `DataCount/PageCount` 兜底。
+
+## 打开方式细节
+
+### Diy
+
+默认 `/diy/diy-table-rowlist`，绑定 `DiyTableId` 后自动具备列表、搜索、新增、
+编辑、删除、导入和导出。
+
+### Component
+
+用于主前端源码已注册的组件。组件路径必须存在并经过目标前端构建验证。
+
+### Iframe
+
+仅允许受控 URL。地址接口引擎可返回动态 URL，但：
+
+- 密钥只在后端使用；
+- 外部 Token 短时缓存并按 `OsClient + 用户 + 目标系统` 隔离；
+- URL 参数使用一次性交换码，不使用当前后台 JWT；
+- 限制跳转域名并防 SSRF/开放重定向。
+
+### SecondMenu
+
+只承载子菜单，不绑定业务表；`HasChild` 与真实子菜单一致。
+
+### Report
+
+使用报表引擎虚拟表。读取 `report-engine/SKILL.md`。
+
+### MicroService
+
+必须同时绑定：
+
+- `MicroServiceId`
+- `MicroServicePageId`
+- `MicroServiceRoutePath`
+- `MicroServiceKey`
+- `ComponentPath=/micro-app/host`
+
+路由优先 `/micro-app/{MsKey}/{RoutePath}`，并兼容历史 Id 路由。
+
+完整系统 Manifest 使用可移植引用：模块写 `openType=MicroService`、`microServiceKey`、`microServiceRoutePath`，不把某个租户的 `MicroServiceId/MicroServicePageId` 固化进发行包。`microi_generate_system` 会在首个写操作前回读运行元数据并补齐两个 Id；解析失败必须停止整次生成。直接调用 `microi_create_module` 时仍须一次提供全部四个绑定字段。
+
+## 跨端 ViewSchema
+
+专用物理字段：
+
+| 字段 | 说明 |
+|---|---|
+| `EnableViewSchema` | 1 启用 Detail/Edit 自定义表单视图；不控制 List/Card |
+| `ViewSchemaVersion` | 可选；为空默认 `1.0` |
+| `ViewConfigVersion` | 可选；为空默认 `1`，后续发布递增并驱动缓存失效 |
+| `ViewSchema` | Detail/Edit/List/Card JSON |
+
+顶层 PC 列表不依赖 `EnableViewSchema` 才采用新样式：平台始终显示紧凑模块标题；ViewSchema 中有效的 List-PC 与 Card-Mobile 配置也不受该开关限制。模块表单中的 `DiyModulePresentationDesigner` 负责可视化编辑这些展示配置，以独立 JSON 编辑 Detail/Edit，并通过高级 JSON 保留角色视图及未知字段。
+
+设计器固定提供“模块标题与统计 / PC 复合列 / 移动端卡片 / 自定义表单 / 高级 JSON”五个
+Tab；开关标签是“启用自定义表单视图”，只影响第四个 Tab 中的 Detail/Edit。
+
+视图项常用字段：`Key`、`Scene`、`Device`、`RoleIds`、`Priority`、`Layout`。
+标准区块包括 `EntityHero`、`MetricStrip`、`ActionGrid`、
+`ResponsiveSection`。声明式动作包括：
+
+`ApiEngine`、`OpenDetail`、`OpenList`、`OpenForm`、`Navigate`、
+`Dial`、`Scan`、`Map`、`Refresh`、`Back`、`Copy`。
+
+`ParamMap` 可使用经过白名单处理的 `$form.Field`、`$user.Field`、
+`$menu.Field`。小程序端不下载/执行任意 V8Code。
+
+### List / Card 展示协议
+
+| 配置路径 | 用途 | 核心字段 |
+|---|---|---|
+| `Layout.Hero` | 模块眉题、标题、说明、统计条 | `Eyebrow/Title/Description/Metrics` |
+| `Hero.Metrics[]` | 内置、字段或接口引擎指标 | `Key/Label/Source/Field/ApiEngineKey/ValuePath/Prefix/Suffix/Icon/Tone/Color/RefreshSeconds` |
+| `Layout.List.Columns[]` | PC 复合列 | `Field/Lines/TrailingFields/RequiredFields/Align/MinWidth` |
+| `Layout.Card` | 移动端业务卡片 | `AvatarTextField/TitleField/TopFields/SubtitleFields/RightFields/Fields/MetaFields/BottomFields` |
+
+字段引用对象支持 `Name/AsName/Label/ShowLabel/Icon/Tone/Color/Prefix/Suffix/
+FontWeight/DisplayStyle`。运行时会把引用字段并入 `_SelectFields`；查询接口替换也必须
+返回这些字段。多字段模板沿用对应 `diy_field.V8TmpEngineTable`，不在 ViewSchema 内保存
+可执行脚本。
+
+PC 复合列的常规高度上限是两行：`Field` 占主行，`Lines` 通常只放 1 项。多个信息组拆成
+多个两行复合列；只有确有层级价值且完成桌面截图验收后，才允许在同一列放第 2 个
+`Lines`。`TrailingFields` 位于右侧，不应被误用成增加纵向信息层级。
+
+Hero 必须在 PageTabs 上方渲染。PC 无指标/含指标头部分别为 `44px / 62px`，连同间距的
+总纵向占用约 `50px / 68px`。有指标时标题说明区占约 25%~30%，指标区弹性占满其余空间，
+两区只用弱化渐变分隔；指标容器不加外框，单指标使用轻量语义色背景和图标色块，禁止
+“外层框 + 指标条框 + 指标卡框”的多层线框。无指标时标题说明自动铺满。每个指标必须
+显式配置 `Icon`，同一 Hero 内使用不同 `Tone` 或 `Color` 与不同图标，不能只靠数字区分。
+只允许一次性入场与一次性轻量光效，禁止持续循环动画；
+`prefers-reduced-motion: reduce` 下关闭动画和过渡。
+
+`Hero.Metrics[].Source` 可直接配置 `DataCount`（当前筛选总记录数）或 `PageCount`（本页
+加载数），两者复用列表结果且不请求接口。字段汇总使用 `Field`。动态指标接口按
+`ApiEngineKey` 分组调用，参数包含 `MetricKeys`、当前模块/表、租户和筛选上下文；同一接口
+应一次返回多个指标。`ValuePath` 例：`Data.UnpaidAmount`。
+
+## 动态按钮位置
+
+| 字段 | 位置 |
+|---|---|
+| `MoreBtns` | 行操作 |
+| `FormBtns` | 表单底部 |
+| `BatchSelectMoreBtns` | 批量勾选后 |
+| `PageTabs` | 页面顶部 Tab，固定在模块 Hero 下方 |
+| `PageBtns` | 页面级 |
+| `ExportMoreBtns` | 导出扩展 |
+
+按钮对象必须有稳定唯一 Id、Sort、Name、显隐逻辑和动作。后台任务按钮还要配置
+ApiEngineKey、Workload、幂等字段、并发 Key、业务状态/任务 Id/进度/ETA 字段。
+
+`PageTabs` 与五类按钮共用统计字段：`BadgeEnabled`、`BadgeApiEngineKey`、`BadgeValuePath`、`BadgeField`、
+`BadgeTone`、`BadgeColor`、`BadgeMax`、`BadgeShowZero`、`BadgeRefreshSeconds`。接口一次接收当前页 `Ids` 与
+`ButtonKeys`，推荐返回：
+
+```json
+{
+  "Code": 1,
+  "Data": {
+    "Buttons": { "button-id": 12 },
+    "Rows": { "row-id": { "button-id": 2 } }
+  }
+}
+```
+
+行按钮的 `BadgeField` 直接读取当前行已有字段；PageTabs/页面按钮的 `BadgeField` 读取模块 `StatisticsFields` 页面汇总值，必须同时配置“统计列”。字段模式不调用接口；其它行统计必须批量聚合，禁止 N+1。
+
+## 接口替换
+
+可替换查询、新增、更新、删除、导入、导入进度和导出接口。替换后仍要保持平台
+返回契约、权限、分页、统计、错误码和租户隔离。
+
+- 查询：返回 `Code/Data/DataCount`，不可丢失菜单权限。
+- 导入：读取文件、校验、分片写入、真实进度、幂等恢复。
+- 导出：大数据使用后台任务/流式文件，不在请求内无界物化。
+- 所有路径变量只能使用平台明确支持的占位符，不拼接 Token。
+
+## PageTabs 两种模式
+
+- 无目标菜单：在当前模块执行 V8，通常 `V8.SearchSet(...)`。
+- 有 `TargetSysMenuId`：在当前 `diy-table` 实例内加载目标模块的菜单、表、字段和列表数据。目标菜单即使隐藏导航，也必须给角色权限。
+
+PageTabs 可以通过 `BadgeApiEngineKey` 显示数字角标。接口按 `ButtonKeys` 一次返回所有 Tab 数量到 `Data.Buttons`，`BadgeValuePath` 可显式指定 `Data.Buttons.{TabId}`；失败只隐藏角标，不能阻断页签切换。
+
+PageTabs 只表达当前模块的数据类别/状态，不能取代模块 Hero，也不能渲染到 Hero 上方。
+
+跨表 Tab 由入口模块统一配置一组 PageTabs，目标菜单只保留各自的模块设计、表绑定和角色权限，不复制 PageTabs。隐藏目标菜单统一设置 `ParentId=入口菜单Id、Display=0、AppDisplay=0、HasChild=0、PageTabs=[]`，入口菜单继续保持 `HasChild=0` 作为可直接点击的业务入口。模块设计器用【关联模块】可搜索菜单树展示名称、保存 `TargetSysMenuId`。切换只更新当前 URL 的 `Tab` 查询参数；路由、面包屑、顶部访问标签和入口模块 Hero 保持稳定，表格上下文在原实例中切换。实现时必须取消旧请求、丢弃迟到响应并在失败时回滚，禁止按菜单名或业务表名写死。
+
+首屏和跨模块切换应为 Hero 标题/统计、PageTabs、工具栏和列表提供与最终几何尺寸一致的主题化骨架屏；根据模块元数据判断是否预留指标区和 PageTabs，并支持 `prefers-reduced-motion: reduce`。
+
+## URL 参数
+
+兼容参数包括 `ShowClassicTop`、`ShowClassicLeft`、`FormDataId`。它们只控制
+界面/默认打开记录，不建立授权；记录仍须通过当前菜单和数据权限校验。