@microi.net/cli 5.5.9 → 5.6.0

package/skills/microi-left-right-layout/SKILL.md

@@ -1,141 +1,141 @@
----
-name: microi-left-right-layout
-description: Microi 吾码模块引擎“树形+表格/表单”左右结构配置规范。用于通过 MCP、模块引擎或源码配置 `diy_LeftJoinRightView`，把项目、分类、组织等主数据作为左树，并用主外键过滤右侧列表；覆盖字段语义、初始化 V8、移动端自适应、幂等写入和回读验收。
----
-
-> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
-
-# Microi 左右树表配置规范
-
-当需求是“左侧按项目/分类导航，右侧显示该节点的数据列表或表单”时，使用模块组件 `/diy/left-right/LeftTreeJoinRightForm`，配置表为 `diy_LeftJoinRightView`。不要为每个业务菜单复制定制 Vue 页面。
-
-## 适用与禁用场景
-
-- 适用：项目及其成品、用料、请购、提料、锁料、文档，分类及商品，组织及人员。
-- 左侧必须是稳定的主数据；右侧必须能通过明确的主外键过滤。
-- 左右两边没有关联字段、左侧仅是装饰性筛选，或数据量极大却没有分页/搜索方案时，不应直接套用。
-
-## 模块配置
-
-目标 `sys_menu` 必须配置：
-
-```json
-{
-  "ComponentName": "树形+表格",
-  "ComponentPath": "/diy/left-right/LeftTreeJoinRightForm"
-}
-```
-
-同一菜单只能有一条有效的 `diy_LeftJoinRightView` 配置。创建前先按 `GuanlianCD Like 菜单Id` 回读并复用，禁止重复插入。
-
-## `diy_LeftJoinRightView` 字段
-
-| 字段 | 必填 | 含义与写法 |
-| --- | --- | --- |
-| `GuanlianCD` | 是 | 当前右侧业务菜单链，JSON 数组；末级必须是当前 `sys_menu.Id`。 |
-| `ShuxingGLCD` | 是 | 左侧主数据菜单链，JSON 数组；末级对应左表模块。 |
-| `GuanlianBD` | 是 | 左侧主表名，例如 `xiangmuguanli`。 |
-| `FubiaoGLZD` | 是 | 左表参与关联的字段，通常为 `Id`。 |
-| `ZibiaoGLZD` | 右表格必填 | 右表外键，例如 `XiangmuID`、`ProjectId`、`Guid`。必须以实时表结构为准。 |
-| `GuanlianPPLJ` | 右表格必填 | 匹配操作符，普通主外键使用 `=`。 |
-| `ZuobianZSZJ` | 是 | 左侧组件，通常为 `树形控件`。 |
-| `YoubianZSZJ` | 是 | `表格`、`表单` 或 `表单/表格`。 |
-| `ShuxianSZDM` | 是 | 左树显示字段，必须与初始化结果的属性名一致。 |
-| `ChushiHDM` | 是 | 初始化 V8。必须读取 `V8.Form._PageIndex/_PageSize/inputText`，最终返回 `Data` 和 `DataCount`。 |
-| `ZuoyouXSZB` | 否 | 24 栅格比例，例如 `6/18`、`4/20`，中间 `/` 必须保留。 |
-| `ShubiaoT` | 否 | 左树标题，例如 `项目目录`。 |
-| `ShumoHSS` | 否 | 模糊搜索开关。 |
-| `ShuxiaLSS` | 否 | 搜索字段下拉开关。 |
-| `ShusouSAN` | 否 | 搜索按钮开关。 |
-| `ShushuaX` | 否 | 刷新按钮开关。 |
-| `ShudingJXZ` | 否 | 是否允许新增顶级树节点。 |
-| `ShuxinZ`、`ShubianJ`、`ShushanC` | 否 | 树节点新增、编辑、删除开关。只在业务允许时开启。 |
-| `ShujieDDJSJ` | 否 | 节点点击 V8；可读取 `V8.Form`，异步结果写入 `V8.Result`。 |
-| `YincangBSF` | 否 | 节点命中该字段时隐藏右侧区域。 |
-| `TanchuangLX`、`TanchuangDX` | 否 | 树节点维护弹窗类型和尺寸。 |
-| `LanjiaZ`、`LanjiaZDM` | 否 | 懒加载开关和代码；大树优先使用。 |
-| `DefaultExpandLevel` | 否 | 左树默认展开层级。未配置、空值或 `0` 均不展开；`1` 展开一级节点，`2` 再展开二级节点，以此类推。 |
-
-## 初始化 V8 与分页契约
-
-左树按数据表对待，默认每页 20 条，允许 10/20/50/100 条切换。无论当前只有多少数据，都不能用 `_PageSize:500` 一次拉完整主表。搜索时把页码重置为 1，并在服务端按关键字过滤后返回真实总数。
-
-当初始化 V8 使用 `V8.FormEngine.GetTableTree/GetTableDataTree` 时，左侧来源 `diy_table.IsTree` 必须为 `1`，并显式配置真实存在的 `TreeParentField`（通常是 `ParentId`）；否则接口会成功返回 `Code=0`，页面只显示“暂无数据”。应用包必须同时携带这两项表元数据，并在发布前通过真实树接口回读，不能只验收 `diy_LeftJoinRightView` 配置行。
-
-```js
-var form = V8.Form || {};
-var pageIndex = Math.max(1, parseInt(form._PageIndex || 1, 10));
-var pageSize = Math.min(100, Math.max(1, parseInt(form._PageSize || 20, 10)));
-var keyword = String(form.inputText || '').trim();
-var query = {
-    _SelectFields: ['Id', 'Code', 'Name'],
-    _OrderBy: 'CreateTime',
-    _OrderByType: 'DESC',
-    _PageIndex: pageIndex,
-    _PageSize: pageSize
-};
-
-if (keyword) {
-    query._Where = [
-        ['Code', 'Like', keyword],
-        ['OR', 'Name', 'Like', keyword]
-    ];
-}
-
-var result = await V8.FormEngine.GetTableData('xiangmuguanli', query);
-
-if (result.Code !== 1) {
-    V8.Result = result;
-    return;
-}
-
-V8.Result = {
-    Code: 1,
-    Data: (result.Data || []).map(function (item) {
-        return {
-            Id: item.Id,
-            TreeTitle: [item.Code, item.Name].filter(Boolean).join(' '),
-            Code: item.Code,
-            Name: item.Name
-        };
-    }),
-    DataCount: Number(result.DataCount || 0),
-    PageIndex: pageIndex,
-    PageSize: pageSize
-};
-```
-
-对应配置为 `ShuxianSZDM=TreeTitle`、`FubiaoGLZD=Id`。右侧新增时，组件会通过 `ParentDataAppend` 把父节点、父键和 `ZibiaoGLZD` 传给表格；业务字段仍需由表单事件兜底校验。
-
-加载请求期间必须显示明确的“正在加载项目...”状态，不能先渲染“暂无数据”；多次搜索或翻页并发返回时，只应用最后一次请求，防止旧结果覆盖新页。
-
-## MCP 实施顺序
-
-1. 调用实时 Schema/模块查询，确认左右表、菜单 Id、主键、外键和已有配置。
-2. 读取一个已正常运行的左右结构作为基线，只复用结构，不复制租户或业务字段。
-3. 按当前菜单回读 `diy_LeftJoinRightView`；有记录则更新，无记录才新增。
-4. 更新模块 `ComponentName`、`ComponentPath`，随后回读模块和配置行。
-5. 验证“全部”、单节点切换、右表筛选、右侧新增自动关联、刷新和搜索。
-
-## 移动端要求
-
-- `<=767px` 时不在列表上方直接堆放左树。右侧业务列表占满宽度，顶部显示当前项目和“项目目录”按钮。
-- 点击“项目目录”后，从左向右打开全高抽屉；推荐宽度 `88%`，保留一段遮罩用于快速关闭。抽屉必须支持关闭按钮、点击遮罩和 Esc 关闭。
-- 左树在抽屉内独立滚动，搜索、分页和每页条数选择都必须可操作；关闭抽屉后右表筛选状态不得丢失。
-- 右表与页面使用正常纵向滚动，禁止祖先容器 `overflow:hidden` 截断内容。
-- 右侧卡片、表格 Tab、列表卡片在移动端必须使用 `height:auto` 和 `overflow:visible`；底部操作栏不得盖住最后一条数据。
-- 至少验收桌面 1440x900、手机 390x844；在手机上分别滚动左树和整页到末尾。
-
-## 验收清单
-
-- 当前菜单只匹配一条配置，模块路径正确。
-- 使用树接口的左表已启用 `IsTree=1`，`TreeParentField` 与物理父级字段一致。
-- 左树标题无 `undefined`、`{}`、空白重复项。
-- 点击“全部”清空右侧外键条件；点击节点只显示该节点数据。
-- 后端 `_HasChild=true` 表示可展开，Element Plus 的 `isLeaf` 必须映射为独立 `_IsLeaf=!_HasChild`，不得把 `_HasChild` 直接当叶子标记。
-- `DefaultExpandLevel` 未配置时必须保持全部折叠；只展开有子节点且深度不超过配置值的节点，不能把平台默认值改成一级展开。
-- 页面初始已处于“全部”时，再次点击“全部”不得先清空已加载列表；只清除树节点外键条件并避免重复请求。
-- 右侧新增数据自动写入正确外键，切换节点后不会串数据。
-- 普通用户不出现仅管理员可用的“页面配置”。
-- 桌面左树每页默认 20 条，可翻页并切换 10/20/50/100；加载时不出现错误的空状态。
-- 手机初始不显示树，抽屉打开/节点选择自动关闭/遮罩关闭均正常；列表与操作区可滚动到底，无横向挤压和固定高度裁切。
+---
+name: microi-left-right-layout
+description: Microi 吾码模块引擎“树形+表格/表单”左右结构配置规范。用于通过 MCP、模块引擎或源码配置 `diy_LeftJoinRightView`，把项目、分类、组织等主数据作为左树，并用主外键过滤右侧列表；覆盖字段语义、初始化 V8、移动端自适应、幂等写入和回读验收。
+---
+
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
+
+# Microi 左右树表配置规范
+
+当需求是“左侧按项目/分类导航，右侧显示该节点的数据列表或表单”时，使用模块组件 `/diy/left-right/LeftTreeJoinRightForm`，配置表为 `diy_LeftJoinRightView`。不要为每个业务菜单复制定制 Vue 页面。
+
+## 适用与禁用场景
+
+- 适用：项目及其成品、用料、请购、提料、锁料、文档，分类及商品，组织及人员。
+- 左侧必须是稳定的主数据；右侧必须能通过明确的主外键过滤。
+- 左右两边没有关联字段、左侧仅是装饰性筛选，或数据量极大却没有分页/搜索方案时，不应直接套用。
+
+## 模块配置
+
+目标 `sys_menu` 必须配置：
+
+```json
+{
+  "ComponentName": "树形+表格",
+  "ComponentPath": "/diy/left-right/LeftTreeJoinRightForm"
+}
+```
+
+同一菜单只能有一条有效的 `diy_LeftJoinRightView` 配置。创建前先按 `GuanlianCD Like 菜单Id` 回读并复用，禁止重复插入。
+
+## `diy_LeftJoinRightView` 字段
+
+| 字段 | 必填 | 含义与写法 |
+| --- | --- | --- |
+| `GuanlianCD` | 是 | 当前右侧业务菜单链，JSON 数组；末级必须是当前 `sys_menu.Id`。 |
+| `ShuxingGLCD` | 是 | 左侧主数据菜单链，JSON 数组；末级对应左表模块。 |
+| `GuanlianBD` | 是 | 左侧主表名，例如 `xiangmuguanli`。 |
+| `FubiaoGLZD` | 是 | 左表参与关联的字段，通常为 `Id`。 |
+| `ZibiaoGLZD` | 右表格必填 | 右表外键，例如 `XiangmuID`、`ProjectId`、`Guid`。必须以实时表结构为准。 |
+| `GuanlianPPLJ` | 右表格必填 | 匹配操作符，普通主外键使用 `=`。 |
+| `ZuobianZSZJ` | 是 | 左侧组件，通常为 `树形控件`。 |
+| `YoubianZSZJ` | 是 | `表格`、`表单` 或 `表单/表格`。 |
+| `ShuxianSZDM` | 是 | 左树显示字段，必须与初始化结果的属性名一致。 |
+| `ChushiHDM` | 是 | 初始化 V8。必须读取 `V8.Form._PageIndex/_PageSize/inputText`，最终返回 `Data` 和 `DataCount`。 |
+| `ZuoyouXSZB` | 否 | 24 栅格比例，例如 `6/18`、`4/20`，中间 `/` 必须保留。 |
+| `ShubiaoT` | 否 | 左树标题，例如 `项目目录`。 |
+| `ShumoHSS` | 否 | 模糊搜索开关。 |
+| `ShuxiaLSS` | 否 | 搜索字段下拉开关。 |
+| `ShusouSAN` | 否 | 搜索按钮开关。 |
+| `ShushuaX` | 否 | 刷新按钮开关。 |
+| `ShudingJXZ` | 否 | 是否允许新增顶级树节点。 |
+| `ShuxinZ`、`ShubianJ`、`ShushanC` | 否 | 树节点新增、编辑、删除开关。只在业务允许时开启。 |
+| `ShujieDDJSJ` | 否 | 节点点击 V8；可读取 `V8.Form`，异步结果写入 `V8.Result`。 |
+| `YincangBSF` | 否 | 节点命中该字段时隐藏右侧区域。 |
+| `TanchuangLX`、`TanchuangDX` | 否 | 树节点维护弹窗类型和尺寸。 |
+| `LanjiaZ`、`LanjiaZDM` | 否 | 懒加载开关和代码；大树优先使用。 |
+| `DefaultExpandLevel` | 否 | 左树默认展开层级。未配置、空值或 `0` 均不展开；`1` 展开一级节点，`2` 再展开二级节点，以此类推。 |
+
+## 初始化 V8 与分页契约
+
+左树按数据表对待，默认每页 20 条，允许 10/20/50/100 条切换。无论当前只有多少数据，都不能用 `_PageSize:500` 一次拉完整主表。搜索时把页码重置为 1，并在服务端按关键字过滤后返回真实总数。
+
+当初始化 V8 使用 `V8.FormEngine.GetTableTree/GetTableDataTree` 时，左侧来源 `diy_table.IsTree` 必须为 `1`，并显式配置真实存在的 `TreeParentField`（通常是 `ParentId`）；否则接口会成功返回 `Code=0`，页面只显示“暂无数据”。应用包必须同时携带这两项表元数据，并在发布前通过真实树接口回读，不能只验收 `diy_LeftJoinRightView` 配置行。
+
+```js
+var form = V8.Form || {};
+var pageIndex = Math.max(1, parseInt(form._PageIndex || 1, 10));
+var pageSize = Math.min(100, Math.max(1, parseInt(form._PageSize || 20, 10)));
+var keyword = String(form.inputText || '').trim();
+var query = {
+    _SelectFields: ['Id', 'Code', 'Name'],
+    _OrderBy: 'CreateTime',
+    _OrderByType: 'DESC',
+    _PageIndex: pageIndex,
+    _PageSize: pageSize
+};
+
+if (keyword) {
+    query._Where = [
+        ['Code', 'Like', keyword],
+        ['OR', 'Name', 'Like', keyword]
+    ];
+}
+
+var result = await V8.FormEngine.GetTableData('xiangmuguanli', query);
+
+if (result.Code !== 1) {
+    V8.Result = result;
+    return;
+}
+
+V8.Result = {
+    Code: 1,
+    Data: (result.Data || []).map(function (item) {
+        return {
+            Id: item.Id,
+            TreeTitle: [item.Code, item.Name].filter(Boolean).join(' '),
+            Code: item.Code,
+            Name: item.Name
+        };
+    }),
+    DataCount: Number(result.DataCount || 0),
+    PageIndex: pageIndex,
+    PageSize: pageSize
+};
+```
+
+对应配置为 `ShuxianSZDM=TreeTitle`、`FubiaoGLZD=Id`。右侧新增时，组件会通过 `ParentDataAppend` 把父节点、父键和 `ZibiaoGLZD` 传给表格；业务字段仍需由表单事件兜底校验。
+
+加载请求期间必须显示明确的“正在加载项目...”状态，不能先渲染“暂无数据”；多次搜索或翻页并发返回时，只应用最后一次请求，防止旧结果覆盖新页。
+
+## MCP 实施顺序
+
+1. 调用实时 Schema/模块查询，确认左右表、菜单 Id、主键、外键和已有配置。
+2. 读取一个已正常运行的左右结构作为基线，只复用结构，不复制租户或业务字段。
+3. 按当前菜单回读 `diy_LeftJoinRightView`；有记录则更新，无记录才新增。
+4. 更新模块 `ComponentName`、`ComponentPath`，随后回读模块和配置行。
+5. 验证“全部”、单节点切换、右表筛选、右侧新增自动关联、刷新和搜索。
+
+## 移动端要求
+
+- `<=767px` 时不在列表上方直接堆放左树。右侧业务列表占满宽度，顶部显示当前项目和“项目目录”按钮。
+- 点击“项目目录”后，从左向右打开全高抽屉；推荐宽度 `88%`，保留一段遮罩用于快速关闭。抽屉必须支持关闭按钮、点击遮罩和 Esc 关闭。
+- 左树在抽屉内独立滚动，搜索、分页和每页条数选择都必须可操作；关闭抽屉后右表筛选状态不得丢失。
+- 右表与页面使用正常纵向滚动，禁止祖先容器 `overflow:hidden` 截断内容。
+- 右侧卡片、表格 Tab、列表卡片在移动端必须使用 `height:auto` 和 `overflow:visible`；底部操作栏不得盖住最后一条数据。
+- 至少验收桌面 1440x900、手机 390x844；在手机上分别滚动左树和整页到末尾。
+
+## 验收清单
+
+- 当前菜单只匹配一条配置，模块路径正确。
+- 使用树接口的左表已启用 `IsTree=1`，`TreeParentField` 与物理父级字段一致。
+- 左树标题无 `undefined`、`{}`、空白重复项。
+- 点击“全部”清空右侧外键条件；点击节点只显示该节点数据。
+- 后端 `_HasChild=true` 表示可展开，Element Plus 的 `isLeaf` 必须映射为独立 `_IsLeaf=!_HasChild`，不得把 `_HasChild` 直接当叶子标记。
+- `DefaultExpandLevel` 未配置时必须保持全部折叠；只展开有子节点且深度不超过配置值的节点，不能把平台默认值改成一级展开。
+- 页面初始已处于“全部”时，再次点击“全部”不得先清空已加载列表；只清除树节点外键条件并避免重复请求。
+- 右侧新增数据自动写入正确外键，切换节点后不会串数据。
+- 普通用户不出现仅管理员可用的“页面配置”。
+- 桌面左树每页默认 20 条，可翻页并切换 10/20/50/100；加载时不出现错误的空状态。
+- 手机初始不显示树，抽屉打开/节点选择自动关闭/遮罩关闭均正常；列表与操作区可滚动到底，无横向挤压和固定高度裁切。

package/skills/microi-microservice/SKILL.md

@@ -77,16 +77,16 @@ AppKey 稳定且只含安全字符。`microi.routes.json` 是页面事实源，
 ### 线上目标在本地 Microi.Client 复现（强制）
 
 - 先在一次性隔离 browser context 打开线上友好路由并读取
-  `window.__MICROI_RUNTIME_ENDPOINT__`；旧版回退读取页面全局、同源缓存和域名解析，禁止猜
-  ApiBase/OsClient。
+  `window.__MICROI_RUNTIME_ENDPOINT__`；旧版回退读取页面全局、同源缓存和域名解析，禁止猜
+  ApiBase/OsClient。
 - 在新的独立 context 打开
   `http://localhost:61500/?OsClient=<encoded>&ApiBase=<encoded>#/micro-app/{MsKey}/{RoutePath}`。
   两个 URL 参数是当前页面最高优先级；初始化后回读同一个运行时对象确认命中目标。
 - 同源普通窗口共享 Token、CurrentUser、ApiBase、OsClient。并行不同目标必须一组目标一个
   Playwright `browser.newContext()` 或独立浏览器 Profile；多个无痕窗口不保证彼此隔离。
-- 本地复现、主框架宿主验收、远端运行产物和生产部署分别报告；本地通过不能替代发布后回读。
-- 新租户或历史还原库可能没有 `SysConfig.ApiBase`。微服务安装不得依赖该字段才能写入运行 HTML：按目标 `OsClient` 注入上下文，运行时使用同租户宿主的 `microApp.getData()` 或绑定该租户的 API 稳定入口，保留代理路径；不得沿用发布端上下文、跨租户宿主或把 HDFS/CDN 域名当成 API。独立 Web/UniApp 仍需有效的目标 API 配置。
-- 登录用户的角色等历史字段可能返回数组、JSON 字符串或空值。列表运算前必须归一化类型，并优先使用当前接口给出的结构化字段；验收应使用真实旧格式数据验证页面渲染及导航，不能只断言接口成功或没有 `pageerror`，还应检查 Vue 捕获到的控制台异常。
+- 本地复现、主框架宿主验收、远端运行产物和生产部署分别报告；本地通过不能替代发布后回读。
+- 新租户或历史还原库可能没有 `SysConfig.ApiBase`。微服务安装不得依赖该字段才能写入运行 HTML：按目标 `OsClient` 注入上下文，运行时使用同租户宿主的 `microApp.getData()` 或绑定该租户的 API 稳定入口，保留代理路径；不得沿用发布端上下文、跨租户宿主或把 HDFS/CDN 域名当成 API。独立 Web/UniApp 仍需有效的目标 API 配置。
+- 登录用户的角色等历史字段可能返回数组、JSON 字符串或空值。列表运算前必须归一化类型，并优先使用当前接口给出的结构化字段；验收应使用真实旧格式数据验证页面渲染及导航，不能只断言接口成功或没有 `pageerror`，还应检查 Vue 捕获到的控制台异常。
 
 迁移 Vue2 定制页到独立 Vite 微服务时，不得假设宿主会提供 Tailwind/UnoCSS 等原子类；
 页面依赖的宽高、颜色、间距、响应式和打印/下载样式必须由组件自身的语义 class 明确声明，
@@ -266,16 +266,16 @@ window.addEventListener('appstate-change', (event) => {
 吾码宿主独立预览时的回退值。不得直接写死 `min-height: 100vh`、`calc(100vh - 100px)` 等
 只适配浏览器视口或某个主站布局的高度，否则嵌入 TagsView、弹窗或移动端时会被裁剪或产生双滚动。
 
-菜单型微服务必须只有一个纵向滚动所有者：宿主外层隐藏溢出，`<micro-app>` 边界提供默认
-`overflow-y:auto` 兜底。普通长页面保持自然高度即可；子应用若需要 sticky 工具栏、虚拟列表等
-内部滚动，则自己的滚动容器必须具有基于 `--micro-app-available-height` 的确定高度和
-`overflow-y:auto`。真实子滚动容器会把内容约束在边界内，框架兜底条自动不出现；只给自动高度
-根节点写 `overflow:auto` 不算自滚动容器。验收需分别覆盖框架兜底和子应用自滚动，断言任一时刻
-只有一个 `scrollHeight > clientHeight` 的纵向滚动所有者。
-
-相机扫描、收银称台、扫码、签到等高频工具页必须另设“一屏操作”断点：在宿主下发的可用高度内同时显示输入/取景、主操作、处理状态、核心结果和业务要求的最近记录入口，完成主流程不得依赖页面纵向滚动；竖屏优先上下紧凑分区，短横屏切换左右或多列分区。历史明细可在自己的卡片内滚动，但不能隐藏错误、当前结果、暂停/继续/恢复等关键动作。桌面应占满宿主可用宽度，通过有界预览容器和 `object-fit` 防止上传竖图把页面撑高。真实浏览器验收至少覆盖一个常见手机竖屏和一个短横屏，并断言根容器不溢出、取景区/结果区/关键历史入口同时在视口内、平台底部菜单与安全区不遮挡按钮；桌面断点必须回归，不能为移动端压缩破坏 PC 布局。
-
-摄像头微服务必须把媒体异步生命周期当作竞态处理：每次打开、关闭和卸载都递增操作令牌或取消版本；`getUserMedia`、设置 `srcObject`、`video.play()` 每个异步边界返回后都要验证令牌仍有效。关闭时先同步切换 UI 状态并使旧操作失效，再停止全部轨道和清空 `srcObject`，防止旧 Promise 把已关闭状态反写为开启。条件渲染或点击后会移动的关闭按钮可在 `pointerdown` 捕获阶段完成停止，再短时去重后续 `click`。自动识别可以按画面指纹去重，但用户点击主识别按钮必须能强制处理当前帧；同一页面不要再放置语义重复且易被宿主底栏遮挡的第二个“再次识别当前画面”。
+菜单型微服务必须只有一个纵向滚动所有者：宿主外层隐藏溢出，`<micro-app>` 边界提供默认
+`overflow-y:auto` 兜底。普通长页面保持自然高度即可；子应用若需要 sticky 工具栏、虚拟列表等
+内部滚动，则自己的滚动容器必须具有基于 `--micro-app-available-height` 的确定高度和
+`overflow-y:auto`。真实子滚动容器会把内容约束在边界内，框架兜底条自动不出现；只给自动高度
+根节点写 `overflow:auto` 不算自滚动容器。验收需分别覆盖框架兜底和子应用自滚动，断言任一时刻
+只有一个 `scrollHeight > clientHeight` 的纵向滚动所有者。
+
+相机扫描、收银称台、扫码、签到等高频工具页必须另设“一屏操作”断点：在宿主下发的可用高度内同时显示输入/取景、主操作、处理状态、核心结果和业务要求的最近记录入口，完成主流程不得依赖页面纵向滚动；竖屏优先上下紧凑分区，短横屏切换左右或多列分区。历史明细可在自己的卡片内滚动，但不能隐藏错误、当前结果、暂停/继续/恢复等关键动作。桌面应占满宿主可用宽度，通过有界预览容器和 `object-fit` 防止上传竖图把页面撑高。真实浏览器验收至少覆盖一个常见手机竖屏和一个短横屏，并断言根容器不溢出、取景区/结果区/关键历史入口同时在视口内、平台底部菜单与安全区不遮挡按钮；桌面断点必须回归，不能为移动端压缩破坏 PC 布局。
+
+摄像头微服务必须把媒体异步生命周期当作竞态处理：每次打开、关闭和卸载都递增操作令牌或取消版本；`getUserMedia`、设置 `srcObject`、`video.play()` 每个异步边界返回后都要验证令牌仍有效。关闭时先同步切换 UI 状态并使旧操作失效，再停止全部轨道和清空 `srcObject`，防止旧 Promise 把已关闭状态反写为开启。条件渲染或点击后会移动的关闭按钮可在 `pointerdown` 捕获阶段完成停止，再短时去重后续 `click`。自动识别可以按画面指纹去重，但用户点击主识别按钮必须能强制处理当前帧；同一页面不要再放置语义重复且易被宿主底栏遮挡的第二个“再次识别当前画面”。
 
 加载/协议/运行时异常只由宿主兜底显示；子应用业务错误标记 `handled=true` 后宿主不得重复提示。
 加载失败页至少显示 AppKey、PageKey、路由、版本、入口、HTTP 状态、发布状态、资产来源、挂载状态和安全原因码，并提供重试、返回与复制诊断。