@microi.net/cli 4.6.2

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

@@ -0,0 +1,131 @@
+---
+name: module-engine
+description: Microi 模块引擎与 sys_menu 配置指南。用于创建或修改后台菜单、菜单统计角标、模块标题指标、复合列表列、移动端业务卡片、查询列、接口替换、跨端 ViewSchema、动态按钮、PageTabs、树形加表格布局和 MicroService 菜单。
+---
+
+# Microi 模块引擎
+
+模块引擎决定同一张表在某个菜单、角色和终端中“如何查询、展示和操作”。
+配置实体是 `sys_menu`，不是 `sys_module`；表结构与字段仍属于
+`diy_table/diy_field`。
+
+## 必读参考
+
+- 字段、打开方式、查询配置、ViewSchema 和接口替换：
+  `references/module-config.md`
+- 动态按钮 JSON 与后台任务：`../v8-menu-buttons/SKILL.md`
+- 树形+表格：`../microi-left-right-layout/SKILL.md`
+- 表单控件：`../microi-form-engine/SKILL.md`
+- 表单平铺、CollapseGroup 与 Tabs 决策：`../microi-form-layout/SKILL.md`
+- MicroService 菜单：`../microi-microservice/SKILL.md`
+
+## 创建/修改标准流程
+
+1. `microi_get_db_schema` 读取真实 `diy_table`、字段、已有菜单和父菜单。
+2. 绑定表的菜单使用 `microi_create_module`/Manifest，不直接写 `sys_menu`。
+3. 明确 `openType`、父菜单、路由、PC/移动端显隐和角色范围。
+4. 用字段名配置 `listFields/searchFields/sortFields/hiddenFields/mobileFields`；
+   MCP 解析为字段 Id 和 `SelectFields/SearchFieldIds/...`。
+5. 同一次创建配齐业务按钮、FormBtns、PageTabs 和批量按钮。
+6. 写后回读模块，检查字段映射、按钮 JSON、路由和目标页面。
+7. 为管理员/目标角色分配菜单权限，并以真实登录用户验收。
+
+## 绑定表菜单不能只写两个字段
+
+除 `Name` 和 `DiyTableId` 外，至少配置或允许平台推断：
+
+- `TableDiyFieldIds`
+- `SelectFields`
+- `SearchFieldIds`
+- `SortFieldIds`
+- `NotShowFields`
+- `StatisticsFields`
+- `MobileListFields`
+- `CardTitleTagFields`
+- `CardBottomTagFields`
+- `DefaultOrderBy`
+
+普通状态、开关等低基数字段不能机械创建单列索引。只有真实查询、关联、唯一约束
+或扫描需要的索引才进入 Manifest 并通过 MCP 创建、回读。
+
+## 打开方式
+
+| OpenType | 用途 |
+|---|---|
+| `Diy` | 标准表单引擎列表/表单 |
+| `Component` | 主前端已注册 Vue 组件 |
+| `Iframe` | 受控外部页面 |
+| `SecondMenu` | 仅作为父菜单 |
+| `Report` | 虚拟报表 |
+| `MicroService` | 已发布前端微服务页面 |
+
+Iframe 不把长期 Token、密码或连接串放 URL。第三方单点登录使用短期、一次性、
+可撤销的服务端交换票据，限制 redirect/scope，并在落地后清理地址栏。
+
+## 数据与业务逻辑
+
+- 单表 CRUD 已由绑定表菜单提供，不额外创建重复接口引擎。
+- 后端 V8 可用 `V8.ModuleEngine.GetTableData({...})`，通过
+  `ModuleEngineKey` 应用模块的关联表查询配置；标准前端 V8 不挂载
+  `V8.ModuleEngine`。
+- 查询接口替换、导入/导出替换和跨表动作属于复杂逻辑时，使用接口引擎。
+- 前端按钮只做确认、收集少量参数、调用接口和刷新；事务与最终校验在后端。
+- 预计超过 2 分钟、500 条、1000 个扇出或 100 次外部调用时使用真实后台任务。
+- 不复制官网旧“Redis 文本进度 + 长事务循环”导入示例作为新实现；必须有稳定
+  幂等键、业务任务状态、真实 Current/Total、失败恢复和必要的 checkpoint 分片。
+
+## 跨端 ViewSchema
+
+顶层 PC 数据列表默认使用紧凑的新模块标题样式；即使未启用 ViewSchema，也不能退回无标题的旧外观。无指标头部固定 `44px`、含指标头部固定 `58px`，连同间距总纵向占用约 `50px / 64px`。子表、关联表、嵌入表不重复显示，移动端由固定导航栏承载标题。`ViewSchema` 只负责个性化标题、指标、复合列和卡片，不改变 Detail/Edit 的显式启用语义。
+
+PC 列表的固定结构顺序是“模块 Hero（标题/副标题/动态指标）→ PageTabs → 查询与表格”，Hero 必须渲染在页面多 Tab 上方。头部只使用一次性入场和一次性轻量光效，禁止持续循环动画；`prefers-reduced-motion: reduce` 必须关闭动画和过渡。
+
+`ViewSchema` 是模块级视图，不写入已废弃的通用 `DiyConfig`。优先通过 sys_menu“跨端视图”的 `DiyModulePresentationDesigner` 配置；需要角色视图或 Detail/Edit 高级布局时再使用设计器的高级 JSON。启用后仍须：
+
+- 配置 `EnableViewSchema`、语义版本和递增配置版本。
+- 按 Scene、Device、RoleIds、Priority 选择视图。
+- 配置损坏或客户端不支持时回退标准 `sys_menu + diy_table + diy_field`，不能白屏。
+- 小程序只消费声明式动作，不执行 PC 的任意 `V8Code`。
+- 声明式动作中的 ParamMap/VisibleWhen 只允许白名单字段，不使用 `eval`。
+
+### 重要模块的统计与信息层级
+
+- 待办、库存预警、未读、逾期、待收/待付等有行动含义的菜单，主动询问并配置
+  `MenuBadgeEnabled=1` 与 `MenuBadgeApiEngineKey`。接口统一返回
+  `{ Code:1, Data:{ Value: number } }`，并按当前用户权限统计。
+- `Scene=List` 的 `Layout.Hero` 用 `Eyebrow/Title/Description/Metrics` 建立模块标题与
+  指标条。相同 `ApiEngineKey` 的指标必须由一个聚合接口批量返回，使用 `ValuePath`
+  取值；禁止一个指标一次请求。
+- Hero 指标可用 `Source=DataCount` 读取当前筛选总记录数、用 `Source=PageCount` 读取本页
+  已加载记录数；两者复用列表结果，不调用额外接口。字段汇总继续用 `Field`，跨表或复合
+  统计才用 `ApiEngineKey + ValuePath`。
+- `Layout.List.Columns[]` 用 `Field + Lines + TrailingFields` 配置双行/多行列和右侧
+  图标状态；声明支持 `Tone/Color/Icon/ShowLabel/Prefix/Suffix`，引用字段必须进入查询列。
+- `Scene=Card, Device=Mobile` 用 `Layout.Card` 配置 `AvatarTextField/TitleField/TopFields/
+  SubtitleFields/RightFields/Fields/MetaFields/BottomFields`。未配置时继续兼容
+  `MobileListFields/CardTitleTagFields/CardBottomTagFields`。
+- `PageTabs/MoreBtns/PageBtns/BatchSelectMoreBtns/ExportMoreBtns/FormBtns` 需要数量时配置
+  `BadgeEnabled/BadgeApiEngineKey`；一个接口接收当前页 `Ids + ButtonKeys` 并一次返回
+  `Data.Buttons` 与 `Data.Rows`，禁止逐行调用。
+- 能直接用字段表达的信息优先配置复合列/卡片字段；只有确需 HTML 样式或组合逻辑时
+  才使用字段的 `V8TmpEngineTable`，且仍需遵守 DOMPurify 和查询字段范围。
+
+### 表单布局协同
+
+- `<=6` 个核心可见字段优先平铺；`7~29` 个字段按基础、业务、状态、附件等信息域使用
+  `CollapseGroup`；`30+` 个字段，或存在多个大型子表、扫码/代码编辑等强任务域时使用
+  表级 `diy_table.Tabs`。最终还要按有效表单行校正，避免产生只有少量字段的空洞 Tab。
+- 新增 `Tabs/CollapseGroup/Divider/Alert` 等布局节点必须走明确的“仅元数据”专用路径。
+  普通新增字段接口可能同步对业务表执行物理 DDL，不能把向 `diy_field` 新增一行误认为
+  仅保存布局配置；写入后要同时回读元数据并核对业务表结构未新增实体列。
+
+## 验收
+
+- `Display/AppDisplay` 除明确隐藏外为 1，父子菜单层级正确。
+- 路由刷新、直接访问、切换菜单均不 404/白屏。
+- 列表字段、筛选、排序、统计、移动端卡片与预期一致。
+- 权限用户可访问，未授权用户不能靠 URL、`_SysMenuId` 或前端字段绕过。
+- MoreBtns/FormBtns/PageTabs/BatchSelectMoreBtns 显隐、调用和刷新正确；PageTabs 数字角标使用稳定 Tab Id 取 `Data.Buttons`。
+- 菜单角标、模块指标和按钮角标按真实权限返回，零值/超限/接口失败降级正确且无 N+1。
+- PC 复合列和 Mobile Card 引用的附加字段均在查询结果中；长文本、空值、模板值不破版。
+- PC 和移动端分别验证；MicroService 还要验证运行时、页面路由和宿主上下文。

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

@@ -0,0 +1,174 @@
+# 模块引擎配置参考
+
+## 核心归属
+
+| 配置 | 归属 |
+|---|---|
+| 表与字段元数据 | `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` |
+
+默认隐藏 Id、外键、系统字段、布局字段、上传、富文本、地图和子表等重字段。
+默认搜索优先名称、标题、编号、状态、类型、分类、负责人和时间；统计优先金额、
+数量、价格、积分和余额。用户明确配置优先。
+
+## 打开方式细节
+
+### 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 路由。
+
+## 跨端 ViewSchema
+
+专用物理字段：
+
+| 字段 | 说明 |
+|---|---|
+| `EnableViewSchema` | 1 启用 |
+| `ViewSchemaVersion` | 协议语义版本 |
+| `ViewConfigVersion` | 每次发布递增，驱动缓存失效 |
+| `ViewSchema` | Detail/Edit/List/Card JSON |
+
+顶层 PC 列表不依赖 `EnableViewSchema` 才采用新样式：平台始终显示紧凑模块标题。模块表单中的 `DiyModulePresentationDesigner` 负责可视化编辑默认 List-PC 与 Card-Mobile 视图，并保留 Detail/Edit、角色视图及未知 JSON 字段。
+
+视图项常用字段：`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/Tone/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 内保存
+可执行脚本。
+
+Hero 必须在 PageTabs 上方渲染。PC 无指标/含指标头部分别为 `44px / 58px`，连同间距的
+总纵向占用约 `50px / 64px`。只允许一次性入场与一次性轻量光效，禁止持续循环动画；
+`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`：加载目标模块。目标菜单即使隐藏导航，也必须给角色权限。
+
+PageTabs 可以通过 `BadgeApiEngineKey` 显示数字角标。接口按 `ButtonKeys` 一次返回所有 Tab 数量到 `Data.Buttons`，`BadgeValuePath` 可显式指定 `Data.Buttons.{TabId}`；失败只隐藏角标，不能阻断页签切换。
+
+PageTabs 只表达当前模块的数据类别/状态，不能取代模块 Hero，也不能渲染到 Hero 上方。
+
+跨表 Tab 应让每个目标菜单配置同一组 PageTabs，不在前端按菜单名写死。
+
+## URL 参数
+
+兼容参数包括 `ShowClassicTop`、`ShowClassicLeft`、`FormDataId`。它们只控制
+界面/默认打开记录，不建立授权；记录仍须通过当前菜单和数据权限校验。