@microi.net/cli 5.9.2 → 5.9.4

package/skills/report-engine/SKILL.md

@@ -1,71 +1,71 @@
----
-name: report-engine
-description: Microi 报表引擎设计与验收规范。用于 Rpt_Report 虚拟表格、数据源、报表字段、查询/增删改接口替换、统计聚合、导出、行级权限和界面引擎图表。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# Microi 报表引擎
-
-## 定位
-
-报表引擎以 `Rpt_Report`、报表字段配置和数据源引擎组成虚拟表格。表格展示使用报表引擎；ECharts 图表和仪表盘使用界面引擎。报表字段是虚拟字段，不能假设存在同名物理表列。
-
-## 建模顺序
-
-1. 明确指标口径、时间粒度、维度、权限和导出上限。
-2. 创建只读数据源（SQL/V8/JSON），使用稳定 `DataSourceKey`。
-3. 创建报表并绑定数据源。
-4. 配置字段 `Name/Label/Component`、查询列、排序、格式和表内编辑。
-5. 如需写操作，为查询/新增/修改/删除分别绑定专用接口引擎。
-6. 菜单只暴露用户需要的报表入口，配置数据范围。
-
-## 权限与 SQL
-
-- 报表数据源必须应用当前租户和服务端用户数据范围。菜单权限不会自动保护任意聚合 SQL。
-- 聚合结果也可能泄露敏感信息；小样本、人员薪资、客户金额等需最小分组阈值或字段脱敏。
-- SQL 动态值参数化，维度/排序/指标使用白名单映射，不接收原始 SQL、列名或 `GROUP BY`。
-- 管理员专用平台表不能作为普通用户报表数据源；只读委托表只有获得真实 `Read` 授权后才能查询，`mic_page/mic_print` 继续按角色权限处理。
-
-## 写入型报表
-
-统计报表通常来自多表。新增、修改、删除必须调用接口引擎，在一个事务中完成校验与写入：
-
-```js
-var result = await V8.ApiEngine.Run('report_adjust_inventory', {
-  RowId: V8.Form.Id,
-  ExpectedVersion: V8.Form.Version,
-  Quantity: Number(V8.Form.Quantity || 0)
-});
-```
-
-接口引擎重新校验角色、记录范围、当前版本和业务状态。前端隐藏按钮、只读字段或报表行数据不能作为授权。
-
-## 性能
-
-- 默认分页，限制最大页数/每页行数/导出行数。
-- 大聚合在数据库建立合适索引或使用预聚合表；不要每次全表扫描。
-- 缓存 Key 包含 `OsClient + ReportId + 权限主体/授权版本 + 查询参数哈希`。
-- 导出走后台任务；生成文件放私有桶并绑定菜单、记录和字段访问上下文。
-
-## MCP 工作流
-
-1. `microi_get_db_schema` 读取 `Rpt_Report`、数据源、字段、菜单和业务表。
-2. `microi_save_data_source` 保存数据源并回读。
-3. 创建/更新报表及字段；复杂写操作先创建接口引擎。
-4. 设置菜单与角色权限。
-5. 用真实普通角色验收列表、筛选、汇总、详情、编辑与导出。
-
-## 图表
-
-界面引擎图表应调用返回稳定 `{Code, Data}` 的统计接口引擎，不在前端下载明细再聚合。统计接口设置时间范围、维度和最大点数，返回空数据时保持稳定结构。
-
-## 验收清单
-
-- [ ] 指标口径、时区和小数精度明确
-- [ ] 当前租户与行级范围在数据库查询中生效
-- [ ] 虚拟字段与物理字段没有混用
-- [ ] 写操作走事务接口引擎并校验并发版本
-- [ ] 分页、聚合、导出均有资源上限
-- [ ] 缓存按租户和权限隔离
-- [ ] 普通角色、无权限角色、跨租户负向测试通过
+---
+name: report-engine
+description: Microi 报表引擎设计与验收规范。用于 Rpt_Report 虚拟表格、数据源、报表字段、查询/增删改接口替换、统计聚合、导出、行级权限和界面引擎图表。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi 报表引擎
+
+## 定位
+
+报表引擎以 `Rpt_Report`、报表字段配置和数据源引擎组成虚拟表格。表格展示使用报表引擎；ECharts 图表和仪表盘使用界面引擎。报表字段是虚拟字段，不能假设存在同名物理表列。
+
+## 建模顺序
+
+1. 明确指标口径、时间粒度、维度、权限和导出上限。
+2. 创建只读数据源（SQL/V8/JSON），使用稳定 `DataSourceKey`。
+3. 创建报表并绑定数据源。
+4. 配置字段 `Name/Label/Component`、查询列、排序、格式和表内编辑。
+5. 如需写操作，为查询/新增/修改/删除分别绑定专用接口引擎。
+6. 菜单只暴露用户需要的报表入口，配置数据范围。
+
+## 权限与 SQL
+
+- 报表数据源必须应用当前租户和服务端用户数据范围。菜单权限不会自动保护任意聚合 SQL。
+- 聚合结果也可能泄露敏感信息；小样本、人员薪资、客户金额等需最小分组阈值或字段脱敏。
+- SQL 动态值参数化，维度/排序/指标使用白名单映射，不接收原始 SQL、列名或 `GROUP BY`。
+- 管理员专用平台表不能作为普通用户报表数据源；只读委托表只有获得真实 `Read` 授权后才能查询，`mic_page/mic_print` 继续按角色权限处理。
+
+## 写入型报表
+
+统计报表通常来自多表。新增、修改、删除必须调用接口引擎，在一个事务中完成校验与写入：
+
+```js
+var result = await V8.ApiEngine.Run('report_adjust_inventory', {
+  RowId: V8.Form.Id,
+  ExpectedVersion: V8.Form.Version,
+  Quantity: Number(V8.Form.Quantity || 0)
+});
+```
+
+接口引擎重新校验角色、记录范围、当前版本和业务状态。前端隐藏按钮、只读字段或报表行数据不能作为授权。
+
+## 性能
+
+- 默认分页，限制最大页数/每页行数/导出行数。
+- 大聚合在数据库建立合适索引或使用预聚合表；不要每次全表扫描。
+- 缓存 Key 包含 `OsClient + ReportId + 权限主体/授权版本 + 查询参数哈希`。
+- 导出走后台任务；生成文件放私有桶并绑定菜单、记录和字段访问上下文。
+
+## MCP 工作流
+
+1. `microi_get_db_schema` 读取 `Rpt_Report`、数据源、字段、菜单和业务表。
+2. `microi_save_data_source` 保存数据源并回读。
+3. 创建/更新报表及字段；复杂写操作先创建接口引擎。
+4. 设置菜单与角色权限。
+5. 用真实普通角色验收列表、筛选、汇总、详情、编辑与导出。
+
+## 图表
+
+界面引擎图表应调用返回稳定 `{Code, Data}` 的统计接口引擎，不在前端下载明细再聚合。统计接口设置时间范围、维度和最大点数，返回空数据时保持稳定结构。
+
+## 验收清单
+
+- [ ] 指标口径、时区和小数精度明确
+- [ ] 当前租户与行级范围在数据库查询中生效
+- [ ] 虚拟字段与物理字段没有混用
+- [ ] 写操作走事务接口引擎并校验并发版本
+- [ ] 分页、聚合、导出均有资源上限
+- [ ] 缓存按租户和权限隔离
+- [ ] 普通角色、无权限角色、跨租户负向测试通过

package/skills/search-engine/SKILL.md

@@ -1,75 +1,75 @@
----
-name: search-engine
-description: Microi 搜索引擎索引、同步、查询与安全规范。用于 Elasticsearch 表索引、增量同步、字段映射、SearchAfter 分页、租户与菜单数据范围、重建和多节点验收。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# Microi SearchEngine
-
-## 能力与事实源
-
-搜索引擎提供建索引/全量同步、单文档新增修改删除、字段映射、查询和 `SearchAfter` 深分页。数据库仍是业务事实源，搜索索引是可重建的读模型，不能直接作为权限、余额、库存或审批状态事实。
-
-## 租户隔离
-
-- 索引名必须包含规范化 `OsClient` 和表标识，禁止不同租户共用无过滤索引。
-- V8/HTTP 调用的 `OsClient` 必须由 Token/服务端上下文确定，不能信任 Query/Body。
-- 搜索服务连接、用户名和密码只从服务端 SaaS 配置读取，不进入前端 `SysConfig`、V8 返回或日志。
-
-## 索引流程
-
-1. 读取 `diy_table/diy_field` 确定可搜索字段、类型和分词需求。
-2. 先扩展索引映射，再开始双写/增量同步。
-3. 全量回填使用稳定游标或主键分页，记录 checkpoint。
-4. 对账数据库数量、抽样字段和删除记录。
-5. 切换读流量后保留旧索引回滚窗口。
-
-可用的服务端方法包括 `AsyncIndex`、`AsyncTableDataToIndex`、`AddDocument`、`UpdateDocument`、`DeleteDocument`、`AddField`、`GetSearchResponse`。
-
-## 查询安全
-
-- 用户关键词作为值参数，不允许决定索引名、任意字段、脚本或原始 DSL。
-- 排序字段从白名单映射；限制 `PageSize`、高亮长度和聚合桶数量。
-- 普通用户的菜单 `SqlWhere`/行级范围不会天然出现在 Elasticsearch 查询中。必须将服务端计算出的允许记录范围同步为可过滤字段，或先取得授权 Id 集合再查询；不能搜索后再在前端过滤。
-- 敏感字段不入索引，或使用独立受控索引；日志只记录 trace id、耗时和计数。
-
-## 同步可靠性
-
-数据库写成功、索引写失败时使用 outbox 事件，`EventId` 全局唯一。消费端按事件 Id 幂等；删除使用 tombstone。索引更新失败不能回滚已经提交的业务事务，应告警并重试。
-
-全量重建和增量消费可能在多个节点同时运行，需分布式租约与 checkpoint 条件更新；本机静态标志不能作为“正在重建”的事实。
-
-## 查询示例
-
-```csharp
-var result = await search.GetSearchResponse(new MicroiSearchEngineParam
-{
-    OsClient = osClient,
-    TableName = "Diy_Product",
-    Keyword = keyword,
-    PageSize = Math.Min(pageSize, 100),
-    Sorts = new List<MicroiSearchEngineSortModel>
-    {
-        new MicroiSearchEngineSortModel { Field = "UpdateTime", Order = "desc" }
-    }
-});
-```
-
-字段名与排序必须在进入此对象前经过服务端白名单。
-
-## MCP/交付流程
-
-- 先用 `microi_get_db_schema` 和菜单元数据确认字段与权限。
-- 搜索配置写入后回读实际索引名、字段映射和租户连接。
-- 用管理员、普通有权限用户、无权限用户和另一个租户验收。
-- 覆盖全量重建中断、重复事件、删除、滚动升级、搜索服务短暂故障。
-
-## 验收清单
-
-- [ ] 索引按租户隔离，跨租户搜索为零
-- [ ] 菜单/行级范围在查询前生效
-- [ ] 字段、排序、分页、聚合均有白名单和上限
-- [ ] 数据库与索引可对账、可重建
-- [ ] outbox 重试幂等，无永久漏同步
-- [ ] 密钥和敏感字段不进入前端/日志/索引
+---
+name: search-engine
+description: Microi 搜索引擎索引、同步、查询与安全规范。用于 Elasticsearch 表索引、增量同步、字段映射、SearchAfter 分页、租户与菜单数据范围、重建和多节点验收。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi SearchEngine
+
+## 能力与事实源
+
+搜索引擎提供建索引/全量同步、单文档新增修改删除、字段映射、查询和 `SearchAfter` 深分页。数据库仍是业务事实源，搜索索引是可重建的读模型，不能直接作为权限、余额、库存或审批状态事实。
+
+## 租户隔离
+
+- 索引名必须包含规范化 `OsClient` 和表标识，禁止不同租户共用无过滤索引。
+- V8/HTTP 调用的 `OsClient` 必须由 Token/服务端上下文确定，不能信任 Query/Body。
+- 搜索服务连接、用户名和密码只从服务端 SaaS 配置读取，不进入前端 `SysConfig`、V8 返回或日志。
+
+## 索引流程
+
+1. 读取 `diy_table/diy_field` 确定可搜索字段、类型和分词需求。
+2. 先扩展索引映射，再开始双写/增量同步。
+3. 全量回填使用稳定游标或主键分页，记录 checkpoint。
+4. 对账数据库数量、抽样字段和删除记录。
+5. 切换读流量后保留旧索引回滚窗口。
+
+可用的服务端方法包括 `AsyncIndex`、`AsyncTableDataToIndex`、`AddDocument`、`UpdateDocument`、`DeleteDocument`、`AddField`、`GetSearchResponse`。
+
+## 查询安全
+
+- 用户关键词作为值参数，不允许决定索引名、任意字段、脚本或原始 DSL。
+- 排序字段从白名单映射；限制 `PageSize`、高亮长度和聚合桶数量。
+- 普通用户的菜单 `SqlWhere`/行级范围不会天然出现在 Elasticsearch 查询中。必须将服务端计算出的允许记录范围同步为可过滤字段，或先取得授权 Id 集合再查询；不能搜索后再在前端过滤。
+- 敏感字段不入索引，或使用独立受控索引；日志只记录 trace id、耗时和计数。
+
+## 同步可靠性
+
+数据库写成功、索引写失败时使用 outbox 事件，`EventId` 全局唯一。消费端按事件 Id 幂等；删除使用 tombstone。索引更新失败不能回滚已经提交的业务事务，应告警并重试。
+
+全量重建和增量消费可能在多个节点同时运行，需分布式租约与 checkpoint 条件更新；本机静态标志不能作为“正在重建”的事实。
+
+## 查询示例
+
+```csharp
+var result = await search.GetSearchResponse(new MicroiSearchEngineParam
+{
+    OsClient = osClient,
+    TableName = "Diy_Product",
+    Keyword = keyword,
+    PageSize = Math.Min(pageSize, 100),
+    Sorts = new List<MicroiSearchEngineSortModel>
+    {
+        new MicroiSearchEngineSortModel { Field = "UpdateTime", Order = "desc" }
+    }
+});
+```
+
+字段名与排序必须在进入此对象前经过服务端白名单。
+
+## MCP/交付流程
+
+- 先用 `microi_get_db_schema` 和菜单元数据确认字段与权限。
+- 搜索配置写入后回读实际索引名、字段映射和租户连接。
+- 用管理员、普通有权限用户、无权限用户和另一个租户验收。
+- 覆盖全量重建中断、重复事件、删除、滚动升级、搜索服务短暂故障。
+
+## 验收清单
+
+- [ ] 索引按租户隔离，跨租户搜索为零
+- [ ] 菜单/行级范围在查询前生效
+- [ ] 字段、排序、分页、聚合均有白名单和上限
+- [ ] 数据库与索引可对账、可重建
+- [ ] outbox 重试幂等，无永久漏同步
+- [ ] 密钥和敏感字段不进入前端/日志/索引