---
name: report-engine
description: Microi 报表引擎设计与验收规范。用于 Rpt_Report 虚拟表格、数据源、报表字段、查询/增删改接口替换、统计聚合、导出、行级权限和界面引擎图表。
---

> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。

# 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}` 的统计接口引擎，不在前端下载明细再聚合。统计接口设置时间范围、维度和最大点数，返回空数据时保持稳定结构。

## 验收清单

- [ ] 指标口径、时区和小数精度明确
- [ ] 当前租户与行级范围在数据库查询中生效
- [ ] 虚拟字段与物理字段没有混用
- [ ] 写操作走事务接口引擎并校验并发版本
- [ ] 分页、聚合、导出均有资源上限
- [ ] 缓存按租户和权限隔离
- [ ] 普通角色、无权限角色、跨租户负向测试通过