@microi.net/cli 5.2.4 → 5.2.6

package/skills/microi-microservice/SKILL.md

@@ -160,7 +160,8 @@ window.microApp.dispatch({
 
 AI 生成菜单微服务时，应优先封装一个 `callMicroiHost(action, data)`，先检查
 `hostCapabilities.actions`，再 dispatch。当前标准动作是：`closeTab`、`navigate`、
-`replaceTab`、`back`、`forward`、`reloadTab`、`setTabTitle`、`showMessage`。
+`replaceTab`、`back`、`forward`、`reloadTab`、`setTabTitle`、`showMessage`、`setGlobalOverlay`。
+`setGlobalOverlay` 只负责平台级遮罩、宿主滚动锁和必要时提升微应用层级，不替代子应用自己的 Dialog、焦点管理和权限。平台级详情/确认弹层打开时传 `visible/blur/lockScroll/mask/promote`，关闭、路由离开、错误和 `onBeforeUnmount` 都必须发送 `visible:false, lockScroll:false, promote:false`；多个弹层用本地计数或统一 computed 保证最后一个关闭后才撤销。
 `navigate/replaceTab` 只传以 `/` 开头的站内 path 或 `{name,params,query,hash}`；禁止传
 外部 URL、登录页、访问密钥页或内部 redirect。目标仍要存在于当前用户动态路由并经过路由守卫，
 宿主桥接不授予菜单或数据权限。业务保存成功后才能关闭/跳转，不能把尽力返回的

package/skills/microi-sso/SKILL.md

@@ -77,6 +77,8 @@ C# 只保留：
 - 高熵一次性 code/ticket、重放保护和 DiyToken 签发；
 - 仅允许精确 Managed Key 调用的 `CreateFederatedUser`、`CreateSsoLoginTicket`、`CompleteSsoLogin`、`RotateSsoClientSecret` 原子。
 
+协议网关的标准路由是 `/api/Sso/Begin`、`/api/Sso/CompleteAuthorization`、`/api/Sso/CompleteLogin`、`/api/Sso/LegacyCapabilities` 和 `/api/Sso/RotateClientSecret`（统一前缀 `/api/Sso/`）。这些路由只处理重定向、协议报文、签名/票据和可信原子；连接投影、身份解析、登录完成与密钥轮换的业务编排仍由上面的 Managed 接口引擎承担。
+
 新增 SSO 需求先判断是否只需修改上述接口引擎。只有缺少不可伪造、不可泄露的底层原子时才增加 V8 方法；增加后同时更新应用 `RequiredPlatformCapabilities`、后端文档、测试与最低版本。
 
 详细用户文档：`microi.doc/docs/doc/more/sso.md`。

package/skills/module-engine/SKILL.md

@@ -112,10 +112,22 @@ Iframe 不把长期 Token、密码或连接串放 URL。第三方单点登录使
 - 查询接口替换、导入/导出替换和跨表动作属于复杂逻辑时，使用接口引擎。
 - 前端按钮只做确认、收集少量参数、调用接口和刷新；事务与最终校验在后端。
 - 预计超过 2 分钟、500 条、1000 个扇出或 100 次外部调用时使用真实后台任务。
-- 不复制官网旧“Redis 文本进度 + 长事务循环”导入示例作为新实现；必须有稳定
-  幂等键、业务任务状态、真实 Current/Total、失败恢复和必要的 checkpoint 分片。
-
-## 跨端 ViewSchema
+- 不复制官网旧“Redis 文本进度 + 长事务循环”导入示例作为新实现；必须有稳定
+  幂等键、业务任务状态、真实 Current/Total、失败恢复和必要的 checkpoint 分片。
+
+### 菜单启动查询与字段元数据兼容
+
+- 菜单树是登录后的启动控制面。读取 `sys_menu` 时，不能把浏览器传入的
+  `_SelectFields` 直接交给依赖 `diy_field` 的通用查询投影：旧库、空库或升级后缓存
+  未同步时，物理列仍存在但元数据可能不完整，查询结果会退化成只含固定字段 `Id`。
+- 服务端应先在已完成登录、租户与角色菜单范围校验的可信边界读取物理菜单行，再在内存中
+  按请求字段投影；构建树所需的 `Id/ParentId/Sort` 必须保留。可信标记不得由浏览器 JSON
+  绑定，不能借此绕过菜单、角色或数据权限。
+- 底层菜单查询失败必须原样返回失败，禁止把失败结果转换成 `Code=1` 的空菜单。回归测试至少
+  覆盖“不向表单引擎下传显式投影”“字段名大小写兼容”“投影仍保留树字段”“未指定字段时
+  保留物理行”。
+
+## 跨端 ViewSchema
 
 顶层 PC 数据列表默认使用紧凑的新模块标题样式；即使未启用自定义表单视图，也不能退回无标题的旧外观。无指标头部固定 `44px`、含指标头部固定 `62px`，连同间距总纵向占用约 `50px / 68px`。子表、关联表、嵌入表不重复显示，移动端由固定导航栏承载标题。`Scene=List/Card` 的个性化标题、指标、复合列和卡片配置存在时必须直接生效；`EnableViewSchema` 只控制 Detail/Edit 自定义表单视图。
 

package/skills/performance-testing/SKILL.md

@@ -115,6 +115,18 @@ POST /api/formengine/DelFormData
 - “有界 Channel + 无界 ConcurrentQueue 溢出区”仍然是无界队列，禁止作为保护方案。主队列和内存重试区都必须有硬容量；两者满时要同步写持久化 spool/WAL 形成回压，并断言 `EmergencySpooled` 可观测、`Dropped=0`。
 - 进程被强制结束、宿主机掉电等场景若要求绝对零丢失，必须采用外部持久消息队列或同步 WAL；内存 Channel 加异步 spool 只能保证 Mongo 故障和正常停机，不得宣称覆盖尚未落盘的强杀窗口。
 
+## 网络流量可观测性与写入性能（强制）
+
+查询动作、AI/MCP 调用、权限与数据解释边界统一读取 `../system-observability/SKILL.md`；本节只定义热路径和压测门禁。
+
+API 网络监控必须同时展示“网卡/容器网络命名空间计数”和“可归因 HTTP 请求体、响应体计数”，并明确两者不能直接画等号。Docker NetIO 还可能包含 TLS/HTTP 头、重传、数据库、Redis、MongoDB、对象存储、外部 HTTP 与容器内部通信；界面必须展示未归因差值、采样范围、节点、窗口和数据边界，禁止把差值伪装成某个帐号或接口的精确流量。
+
+- 请求热路径只做原子计数和有硬上限的分钟桶聚合；端点、IP、帐号、租户、内容类型等维度必须限制基数和保留 TOP N，禁止逐请求同步写 MySQL/MongoDB、同步序列化完整请求或创建无界队列。
+- 高频普通明细只驻留短窗口内存；大文件、可疑、错误或慢请求等有诊断价值的样本进入现有有界日志队列并异步批量写 MongoDB。Mongo 故障、队列满和停机语义继续遵守本 Skill 的 spool/WAL 规则。
+- 长期趋势写 MySQL 固定时间桶汇总（默认 5 分钟），按 `BucketStart + Node + DimensionType + DimensionKeyHash` 形成确定性幂等键，批量 upsert；查询必须命中“时间桶+维度+总字节”等索引，页面默认分页 15 条，不得扫描 Mongo 明细生成每次总览。
+- 禁止持久化 QueryString、Cookie、Token、Authorization、请求正文或响应正文。文件只记录经过清洗且有长度上限的文件名/扩展名/数量/字节；IP 必须标注是可信代理解析后的客户端 IP 还是直接连接 IP。
+- 验收至少覆盖：并发计数无负数、维度基数有界、敏感值不落盘、固定时间桶幂等重放、Mongo 故障不阻塞请求、匿名/登录用户区分、上传/下载字节、网卡重置/回绕、低流量和大流量样本、服务重启后的历史查询，以及开启监控前后 P95/P99、CPU、分配率和内存差异。
+
 ### 多节点与滚动重启压测
 
 - 至少启动两个 API/Worker 实例连接同一 Redis、业务数据库和 MongoDB，通过同一负载均衡入口并发施压；禁止用单进程内开两个对象冒充分布式验收。

package/skills/system-observability/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: system-observability
+description: Microi 系统日志/监控查询、诊断与治理规范。用于通过界面、MCP 或接口引擎分析系统日志、Trace、热点接口、CPU/内存、网络流量归因、安全事件、IP 封禁、应用日志及可观测性性能边界。
+---
+
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
+
+# Microi 系统日志/监控
+
+本 Skill 用于读取、解释、扩展和验收 Microi 的统一【系统日志/监控】能力。它不授权查看其它租户、绕过菜单/平台管理员权限，或把当前节点样本扩写成全局结论。
+
+## 先选入口
+
+| 目标 | 推荐入口 |
+|---|---|
+| 人工排查、看趋势、打开日志详情 | 平台菜单【系统日志/监控】 |
+| AI 查询、自动诊断、验收 | MCP `microi_query_system_observability` |
+| AI 封禁或解封 IP | MCP `microi_manage_system_observability` |
+| 应用页面读取 | Managed 接口引擎 `mci-system-observability-query` |
+| 应用页面治理 | Managed 接口引擎 `mci-system-observability-action` |
+| 扩展宿主、进程、Mongo 或安全底层原子能力 | `V8.Method.GetSystemObservability` / `V8.Method.ManageSystemObservability` |
+
+AI 第一次使用时先查询 `action=Capabilities`，再按返回的动作、权限和边界选择查询。不要用通用 `microi_run_engine` 代替专用工具；专用工具已经限制动作、参数、分页、确认和审计。
+
+## 查询动作
+
+`microi_query_system_observability` 支持：
+
+| action | 用途 | 关键参数 |
+|---|---|---|
+| `Capabilities` | 能力目录与真实边界 | 无 |
+| `Snapshot` | 请求、进程、主机、Docker、队列、诊断和实时网络 | `windowMinutes=1..15`、`top`、`includeHost`、`includeDocker` |
+| `Logs` | 日志列表和完整详情数据 | `keyword/type/category/source/level/searchMonth/pageIndex/pageSize` |
+| `LogTypes` | 日志类型与数量 | `keyword/searchMonth` |
+| `LogStats` | 总数、错误、警告、慢 SQL、慢执行、异常 | `keyword/searchMonth` |
+| `Signal` | 时间窗内的诊断信号 | `windowSeconds=60..86400` 与日志过滤项 |
+| `Trace` | W3C Trace 时间线 | 32 位十六进制 `traceId` |
+| `ApiRank` | 热点接口、耗时占比、平均/P95、异常率 | `top/apiEngineKey/name` |
+| `AppLogs` | 当前 API 进程日志尾部 | `lines=20..1000` |
+| `PlatformStats` | 表、菜单、接口引擎、租户、用户和排行 | 无 |
+| `SecurityData` | 访问、攻击或封锁记录 | `kind=Access|Attack|Block`、分页 |
+| `TrafficHistory` | MySQL 固定时间桶流量历史 | `dimensionType`、`hours=1..168`、分页 |
+
+示例：
+
+```json
+{
+  "action": "TrafficHistory",
+  "dimensionType": "Endpoint",
+  "hours": 24,
+  "pageIndex": 1,
+  "pageSize": 15
+}
+```
+
+所有列表默认按 15 条开始；扩大分页前先增加过滤条件。日志和安全数据每页最多 200 条，Trace 与流量历史最多 500 条。不得循环拉取无时间边界的全量日志。
+
+## 安全治理动作
+
+`microi_manage_system_observability` 只允许 `BlockIp` 和 `UnblockIp`。第一次不带确认调用只返回 dry-run，不产生写入；确认值必须精确为：
+
+```text
+BlockIp:<ip>
+UnblockIp:<ip>
+```
+
+封禁前必须核对反向代理、容器网桥、健康检查、办公出口和 NAT。可信后端会再次验证平台管理员身份、IP 格式、本机/未指定/组播限制、租户范围，并写审计日志。不能通过参数指定其它租户，也不能把批量 IP、CIDR、任意表写入或旧菜单删除塞进这个工具。
+
+## 数据解释边界
+
+1. `Snapshot`、活动请求、最近请求、进程与应用日志是当前 API 节点视角。多节点结论需要逐节点或接入统一遥测平台。
+2. 热点接口的“耗时占比”是窗口总请求耗时贡献，用于定位相关性；它不是逐请求 CPU 核采样，也不等于该接口独占同等 CPU。
+3. HTTP 可归因流量只统计经过 API 中间件的请求体和响应体。网卡、容器 NetIO 还包含 TLS/HTTP 头、重传、数据库、Redis、MongoDB、MQ、对象存储、外部 HTTP、健康检查和同机其它进程。
+4. “未归因流量”只能作为排查线索，不能强行归属给某个帐号、IP 或接口。
+5. IP 必须注明是可信代理解析后的客户端地址还是直接连接地址；代理链未配置正确前不要据此处罚用户。
+
+## 隐私与权限
+
+- 只允许平台可观测性管理员读取敏感运行数据或治理 IP；通常要求 `Level >= 9999`，最终以可信后端判定为准。
+- 不采集或持久化请求正文、响应正文、QueryString、Cookie、Authorization、Token、密码、Secret 或 API Key。
+- 文件流量只记录清洗后的文件名/扩展名/数量/字节，不记录文件内容。
+- 日志详情由可信后端递归脱敏；AI 回答仍要避免复述连接串、内部路径、个人信息或可用于登录的材料。
+- 对外分享截图前检查帐号、IP、Trace、内部域名、物理路径和业务数据；需要时使用测试数据重新截图。
+
+## 高性能存储规范
+
+- 请求热路径只做原子计数和有硬上限的分钟桶聚合；端点、IP、帐号、租户、内容类型限制基数并保留 TOP N。
+- 普通高频明细只保留短窗口内存；错误、慢请求、大文件和可疑传输进入有界队列，异步批量写 MongoDB。
+- 长期趋势使用 MySQL 固定时间桶和确定性幂等键批量 upsert；页面不能每次扫描 Mongo 明细重新聚合总览。
+- 队列必须有硬容量、故障 spool/WAL、停机排空和幂等重放；禁止无界 `ConcurrentQueue` 或逐请求同步写 Mongo/MySQL。
+- Redis 适合短时热点结果、租约和限流；缓存 Key 包含租户、动作和过滤摘要，写入或治理后主动失效，并保留短 TTL 防止永久陈旧。
+
+需要压测或修改热路径时同时读取 `../performance-testing/SKILL.md`；排查 V8/日志写法时读取 `../v8-debugging/SKILL.md`。
+
+## AI 诊断顺序
+
+1. 先查 `Capabilities`，确认当前版本和边界。
+2. 查 `Snapshot`，记录节点、窗口、请求率、活动请求、CPU/内存、队列、HTTP 流量与未归因残差。
+3. 查 `ApiRank` 和 `TrafficHistory` 的 Endpoint/IP/User/Tenant/ContentType 维度，区分“计算慢”与“传输大”。
+4. 按异常接口或 TraceId 查 `Logs`、`Signal`、`Trace`；先处理时间线中的首个根因。
+5. 对慢 SQL 核对执行计划、索引、返回字段、分页、排序/Join 和锁等待；不要先盲目加 Redis。
+6. 对高频只读结果评估短 TTL Redis，并明确更新/删除时的失效路径；对写接口先批量化 I/O、缩小事务和消除逐行远程调用。
+7. 对匿名上传、大响应、重复轮询或攻击信号先核对业务合法性，再限流、对象存储直传/CDN、Range、压缩或封禁。
+8. 优化后用相同窗口与负载复测 P50/P95/P99、RPS、错误率、CPU、内存、分配率和网络字节，不能只凭单次页面刷新下结论。
+
+## 扩展与商城交付
+
+- 普通查询和汇总优先在 `mci-system-observability-query` 接口引擎编排。
+- 只有接口引擎缺少宿主进程、Docker、Mongo 聚合、安全运行态等可复用底层能力时，才扩展最小 V8 原子方法；Controller 不承载业务编排。
+- 官方引擎使用应用包 `ResourcePolicies.ApiEngines=Managed`，客户扩展使用新 Key 或 `CreateIfMissing`，不要覆盖客户已修改的本地代码。
+- 应用包必须包含表、字段、索引/DDL、接口引擎、微服务全部源码、构建产物、菜单和版本日志；安装后回读固定版本快照并在真实页面验收。
+- 后端框架和商城应用是两条升级链：只升级其中一条不能证明功能完整。目标端应先升级兼容框架，再安装/更新最新【系统日志/监控】应用。
+
+## 最低验收
+
+- 系统日志位于首个 Tab；统计、筛选、15 条默认分页、搜索、详情、Trace 时间线均可用。
+- 日志详情使用平台级 `Teleport to="body"` 遮罩整个系统框架；标题/副标题最多两行，异常标红并提供原因与解决方案。
+- 七个 Tab 均跟随主题；动画只使用 transform/opacity 等低成本属性，页面隐藏或 `prefers-reduced-motion` 时暂停。
+- MCP 能发现两个专用工具；`Capabilities`、日志/流量分页、Trace 缺参拦截、IP dry-run、错误确认和成功审计均有自动测试。
+- 对请求热路径做开关前后压测，确认观测开启后 P95/P99、CPU、内存和分配率没有不可接受回退；故障 Mongo 不得阻塞业务请求。
+- 多节点、网卡重置/回绕、服务重启、匿名/登录、大上传/下载、敏感字段脱敏、时间桶幂等和缓存失效均有验证证据。

package/skills/ui-design/SKILL.md

@@ -75,12 +75,15 @@ description: Microi UI 设计系统指南。用于设计 PC Vue、Element Plus
 - 导航栏必须和首屏背景属于同一视觉语境：深色英雄区使用深色玻璃或透明暗底导航，浅色内容页才使用浅色导航；导航文字、Logo、搜索框和下拉入口必须截图检查对比度。
 - 主按钮/胶囊按钮必须使用 `inline-flex` 或等价布局垂直居中，明确 `align-items:center`、`justify-content:center`、稳定高度和 `line-height:1`；不能只靠 padding 让文字“看起来差不多”。
 - 按钮、标签、Tab、空态行动按钮、登录/授权入口等只要文字语义是居中呈现，就必须同时做到上下居中和左右居中；截图或视觉断言发现文字偏上、偏下、偏左、偏右都算未完成。
-- 所有弹窗/对话框默认必须上下左右居中；PC 端应支持通过标题栏拖动，拖动后仍保持在可视区域内；移动端如改为底部抽屉或全屏弹层必须有明确业务理由。弹窗不得贴在左上角、底部或被遮罩/导航/输入框遮挡，截图验收必须覆盖默认居中态和至少一次拖动后的可用状态。
+- 所有弹窗/对话框默认必须上下左右居中；PC 端应支持通过标题栏拖动，拖动后仍保持在可视区域内；移动端如改为底部抽屉或全屏弹层必须有明确业务理由。弹窗不得贴在左上角、底部或被遮罩/导航/输入框遮挡，截图验收必须覆盖默认居中态和至少一次拖动后的可用状态。
+- 菜单微服务中的“平台级详情/确认弹窗”必须通过宿主 `setGlobalOverlay` 能力让遮罩覆盖 Logo、侧栏、顶部页签和内容区，并锁定宿主滚动；子应用自身弹层仍保持可访问焦点、Esc 关闭和 body 滚动恢复。关闭、路由离开、异常及卸载都必须幂等撤销宿主遮罩，禁止只在 iframe/微应用内容矩形内铺一层假全屏遮罩。
 - 禁止在任何交付界面中直接调用浏览器原生 `window.alert`、`window.confirm`、`window.prompt` 或其无前缀别名。简单提示优先使用吾码平台 `Tips`/`DiyCommon.Tips`，确认操作使用 `V8.ConfirmTips`、Element Plus `ElMessageBox`，独立微服务则使用符合本规范的可访问确认弹层；原生浏览器对话框会阻塞线程、无法主题化，也无法满足吾码视觉与自动化标准。
 - Toast、错误反馈、提交结果和二次确认必须脱离业务滚动容器：优先 teleport/append 到 `body`，使用 `position:fixed`、明确遮罩和高于宿主弹窗的层级，并在当前可视区域上下左右居中。用户把长弹窗滚到任意位置后仍必须立刻看到完整提示；禁止把反馈放在内容顶部、滚动层内部或仅靠 `top: 0` 伪装固定。
 - 确认框必须说明“即将执行什么、作用范围、当前任务状态、确认与取消动作”。只有真实检测到正在执行/排队任务时才能写“已有任务”；没有检测到时应明确“提交后新建任务”，并把并发到来时的排队策略作为条件说明，不能用固定模板误导用户。
 - 同一类 UI 在两个及以上页面出现时，必须优先封装为 `Mci*` 或项目级 `mci-*` 组件，通过 props/slots/events 配置标题、说明、图标、按钮、路由、状态和少量变体；不要复制两份卡片、空态、登录提示、按钮组、筛选栏或底部操作栏。
-- 卡片背景必须服务页面氛围：暗色科技背景上的展示卡、价格卡、聊天卡不应突然变成大面积灰白卡；浅色卡片只在整体页面转为浅色内容区时使用，并且要有过渡带或区块背景承接。
+- 卡片背景必须服务页面氛围：暗色科技背景上的展示卡、价格卡、聊天卡不应突然变成大面积灰白卡；浅色卡片只在整体页面转为浅色内容区时使用，并且要有过渡带或区块背景承接。
+- 日志、告警、监控和审计表格的主标题与副标题默认各最多两行，使用 CSS line clamp 与原文 Tooltip/title 保留完整可读性；异常行、异常值和风险标签必须使用主题兼容的红色语义，并在悬停/聚焦时同时说明“可能原因、排查顺序、解决方案”，不能只显示红色数字。
+- 驾驶舱/数据大屏风格必须跟随当前主题令牌并保持紧凑信息密度。持续动效仅允许少量低振幅 `transform`、`opacity`、`background-position`，页面隐藏、微服务 `afterhidden` 或低性能模式时暂停；必须实现 `prefers-reduced-motion` 静态降级，长表格启用虚拟化或 `content-visibility`，禁止每个单元格独立定时器、持续阴影/模糊重绘和高频全量图表重算。
 
 ---
 

package/skills/v8-debugging/SKILL.md

@@ -9,7 +9,7 @@ description: Microi V8 调试与日志指南。用于排查接口引擎、V8 事
 
 你正在为 Microi 吾码平台编写 V8 引擎代码，需要在开发/测试/生产环境进行排错。本指南提供调试模式、异常捕获、系统日志、调试输出的标准做法。
 
-MongoDB 运行日志通过 `microi_query_mongodb_logs` 只读查询；必须限制租户、时间窗、页大小和返回字段，不在结果或回答中输出 Token、连接串、Secret 或完整敏感请求体。
+系统级排查优先读取 `../system-observability/SKILL.md` 并通过 `microi_query_system_observability` 查询统一日志、统计、详情、Trace、热点接口和运行数据；`microi_query_mongodb_logs` 仅保留给只需要旧 Mongo 日志列表的兼容场景。两者都必须限制租户、时间窗、页大小和返回字段，不在结果或回答中输出 Token、连接串、Secret 或完整敏感请求体。
 
 ## 三种输出通道
 

package/skills/v8-export-import/SKILL.md

@@ -150,8 +150,8 @@ return {
 | `NumberFormat/HeaderStyle/Style` | 数字格式与列级样式 |
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-export-import-003 sha256=75977093346f025e91041b36bdb7887e2cacee854800c1f43e407e8fc037a166 -->
-## 解析上传的 Excel（导入）
+<!-- microi-progressive:chunk id=v8-export-import-003 sha256=51a6c3e7a44ca35dc17b5536545ac7a1d47a8915045283841d304a04c04cd219 -->
+## 解析上传的 Excel / CSV（导入）
 
 ```javascript
 // 接口引擎接收 V8.FilesByteBase64
@@ -171,16 +171,24 @@ var dataList = parsed.Data;  // [{ 列标题: 值, ... }, ...]
 return { Code: 1, Data: dataList, DataCount: dataList.length };
 ```
 
-`ExcelToList` 的增强参数为 `HeaderStartRow/HeaderEndRow/DataStartRow/DataEndRow/Columns/MaxDataRows/MaxColumns`。除 `SheetIndex` 和 `Columns[].ColumnIndex` 从 `0` 开始外，行号都从 `1` 开始；传增强范围后每行带 `_ExcelRow`。参数全省略时继续兼容“首行表头、第二行开始数据”。
+`ExcelToList` 的增强参数为 `FileType/FileName/Encoding/Delimiter/HeaderStartRow/HeaderEndRow/DataStartRow/DataEndRow/Columns/MaxDataRows/MaxColumns`。CSV 传 `FileType:'csv'` 或 `.csv` 文件名，编码和分隔符通常省略，由服务端自动识别 UTF-8/GBK 与逗号、制表符、分号、竖线；结果通过 `DataAppend.Encoding/Delimiter` 回传实际识别值。除 `SheetIndex` 和 `Columns[].ColumnIndex` 从 `0` 开始外，行号都从 `1` 开始；传增强范围后每行带 `_ExcelRow`。参数全省略时继续兼容“首行表头、第二行开始数据”。
 
 ### 固定版式模板与后台自定义导入
 
-通用【导入】和 `V8.OpenImportDialog` 共用智能导入弹层：默认宽度 `80%`，选择文件后自动识别工作表、单行/多级合并表头、首条与末条数据行和字段映射；先按每页 `15` 条预览，用户确认后才写入。低可信度时必须允许用户人工指定表头/数据起止行和逐列映射。模板顶部图片、标题、说明文字以及 A 列为空的数据行都不能破坏识别。
+通用【导入】和 `V8.OpenImportDialog` 共用智能导入弹层：默认宽度 `80%`，支持 `.xls/.xlsx/.csv`，选择文件后自动识别工作表、单行/多级合并表头、首条与末条数据行和字段映射；先按每页 `15` 条预览，用户确认后才写入。数据预览必须独立保留全部源列、源行，不能因为零字段匹配而显示空白；未匹配列头以红色和悬停原因标记。低可信度时必须允许用户人工指定表头/数据起止行和逐列映射。模板顶部图片、标题、说明文字以及 A 列为空的数据行都不能破坏识别。
+
+【列映射】后的【原始工作簿】页签必须不依赖解析可信度，直接显示完整工作簿/CSV，包括所有工作表、合并表头、图片、说明、样式和原始数据；该视图只用于核对，不能绕过目标字段映射和服务端校验。
+
+`.xlsx` 原始预览必须兼容 OpenPyXL 等生成器使用等价 DrawingML 默认命名空间的锚定图片。只允许在内存中的预览副本规范化 `xdr` 命名空间和关系目标；正式上传、接口引擎和服务端复核始终使用未经改写的原始文件。
 
 - 页面 V8 可只声明 `ApiEngineKey`；`Workbook.Cells/Columns/HeaderStartRow/HeaderEndRow/DataStartRow/DataEndRow/KeyField` 均为模板提示或固定约束，不传时自动识别。不得拼上传 DOM、传完整工作簿 Base64 或自行轮询。
-- `V8.OpenImportDialog` 后台接口引擎从 `V8.Param._ImportRowsJson` 和 `_ImportMetaJson` 取值；必须重做模板、权限、字段、唯一性和状态校验。
-- 菜单【导入接口替换】仍接收原始文件 `V8.FilesByteBase64`，并新增 `_ImportMetaJson`。接口引擎必须把元数据里的 `SheetIndex/HeaderStartRow/HeaderEndRow/DataStartRow/DataEndRow/Columns` 传给 `V8.Office.ExcelToList`，由服务端按同一范围重读原文件，不能只信任浏览器预览，也不能固定读取第一行。
-- 先校验全部行再写入；接口引擎返回 `Code != 1` 时依靠平台事务整体回滚，禁止手动 Commit/Rollback。
+- 弹层必须让用户在 `RollbackAll`（默认，任一错误整批回滚）和 `ContinueOnError`（逐行提交/跳过错误行）之间明确选择；未传时保持旧版 `RollbackAll`。最终值同时写入 `_ImportErrorPolicy` 与 `_ImportMetaJson.ErrorPolicy`，不能由服务端静默改成另一策略。
+- 当前表的唯一配置必须在上传前可读展示：每个 `Unique=1 + Config.Unique.Type=Alone` 字段各自是一条规则，全部 `Type=All` 字段共同组成一条组合规则；无唯一规则时明确警告“只能新增，重复导入可能产生重复数据”。
+- 标准导入的服务端必须从权威 `diy_field` 重新计算唯一规则，不能信任前端快照。任一完整规则命中同一 Id 则按 Id 修改，均未命中则新增；不同规则命中不同 Id、或一条规则命中多条脏数据时按行报冲突，禁止任意选记录或按宽泛条件更新多行。
+- `V8.OpenImportDialog` 后台接口引擎从 `V8.Param._ImportRowsJson`、`_ImportMetaJson`、`_ImportErrorPolicy` 和 `_ImportUniqueRulesJson` 取值；必须重做模板、权限、字段、唯一性和状态校验。v2.2 元数据中的 `UniqueRules` 只用于说明和诊断。
+- 菜单【导入接口替换】仍接收原始文件 `V8.FilesByteBase64`，并接收上述策略/规则元数据。接口引擎必须把元数据里的 `FileType/SheetIndex/HeaderStartRow/HeaderEndRow/DataStartRow/DataEndRow/Columns` 传给 `V8.Office.ExcelToList`，由服务端按同一范围重读原文件；CSV 应省略固定 `Encoding/Delimiter` 让服务端独立识别，再用 `DataAppend` 与元数据交叉复核。不能只信任浏览器预览，也不能固定读取第一行。
+- `RollbackAll` 在首个行错误时返回 `Code != 1`，依靠平台事务整体回滚；`ContinueOnError` 捕获并记录行错误、继续下一行，最后返回 `Code=1` 提交成功行。两种模式都禁止手动 Commit/Rollback；若底层异常使事务不可继续，必须先做整批预校验或使用平台允许的独立幂等行操作。
+- 结果与进度必须分别统计 `Added/Updated/Failed/Errors`；整批回滚后成功、新增、修改数必须归零，不能把已回滚行计作成功。
 - 用 `V8.Method.UpdateBackgroundTask({Current,Total,Msg,Log})` 上报真实校验/写入工作量；未知总量保持不确定进度，不伪造百分比。
 - 业务幂等键使用后台任务 Id 或明确的导入操作 Id；重试前回读批次，避免重复写入。