# @happyvertical/smrt-reports 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/smrt-reports/

版本：0\.62\.1
npm 元数据更新时间：2026-11-17T07:54:52.048Z
中文译文更新时间：2026-11-17T09:39:47.948Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/smrt-reports
原文对照：https://npmcn.com/package/%40happyvertical/smrt-reports/?lang=original
项目主页：https://github.com/happyvertical/smrt#readme
源码仓库：https://github.com/happyvertical/smrt

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.5 MB，161 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：svelte ^5\.57\.0
- 首次发布：2026-06-26T14:59:15.903Z
- 最新版本发布：2026-11-17T07:54:51.727Z
- 近 30 天下载量：21624（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：337（近 12 个月 337 个）

## 中文简介

SMRT实际汇总报告模型

## 安装

```sh
npm install @happyvertical/smrt-reports
```

也可以使用：`pnpm add @happyvertical/smrt-reports`、`yarn add @happyvertical/smrt-reports`、`bun add @happyvertical/smrt-reports`

## README

# @happyvertical/smrt-reports (原始内容存档于2019-09-28)

S-m-r-t的实事求是的汇总报告。 将报告定义为装饰类, 将其编译为可移植的聚合查询,并刷新其普通 s-m-r-t 表格 手动,在列表中,在源变化后,或TTL过期后.

运行时刷新检查其表格(仅存在,不列或 指数),如果没有,则明显失败;它没有创建报告或系统 图表。 在正常的可显示驱动迁移中包含报告模式 令人兴奋.

## 安装

```bash
pnpm add @happyvertical/smrt-reports
```

## 定义报告

```ts
import { SmrtObject, smrt } from '@happyvertical/smrt-core';
import {
  groupBy,
  month,
  report,
  SmrtReport,
  SmrtReportCollection,
  sum,
} from '@happyvertical/smrt-reports';

@smrt()
class Invoice extends SmrtObject {
  customerId = '';
  issuedAt = new Date();
  subtotal = 0.0;
  status = '';
}

@report({
  source: Invoice,
  where: { status: 'paid' },
  refresh: { manual: true },
})
@smrt()
class MonthlyRevenue extends SmrtReport {
  @groupBy('customerId') customerId = '';
  @month('issuedAt') issuedMonth = new Date();
  @sum('subtotal') revenue = 0.0;
}

class MonthlyRevenueCollection extends SmrtReportCollection<MonthlyRevenue> {
  static readonly _itemClass = MonthlyRevenue;
}

const reports = await MonthlyRevenueCollection.create({ db: 'app.db' });
await reports.refresh();
const rows = await reports.list({ orderBy: 'issued_month DESC' });
```

## 装饰者

| 装饰 | 含义 |
| --- | --- |
| `@report({ source, ... })` | 声明来源并刷新政策 |
| `@groupBy(column?)` | 按源列、 合并列分组( E)`'wo.title'`),或 `{ expr }` |
| `@minute()` 结束 `@year()` | 装入源时间戳 |
| `@sum()`, (中文(简体) ), `@avg()`, (中文(简体) ), `@min()`, (中文(简体) ), `@max()` | 汇总一个来源或加入的列,或一行 `{ expr }`,可选 `{ filter }`编 |
| `@count()` | 数行或不同的值,可选 `{ filter }`编 |
| `@aggregate()` | 定义自定义支持的集合形状 |

每个非系统报告字段必须是组合键,时间桶,或聚合. 元数据存储在字段 `_meta.__report` 合同扫描仪 运行时间编译保持对齐 .

## 组合、行表达式和过滤措施

报告可以读取相关的模型,从每行计算一个值,然后计数 只有条件所在的行。 每个编译到 SQL 聚合 API 中 `@happyvertical/sql`; 这里没有建为 SQL 文本 .

```ts
@report({
  source: AttendanceSegment,
  // Many-to-one: AttendanceSegment.workRefId holds a WorkOrder id.
  joins: { wo: { source: WorkOrder, on: 'workRefId' } },
})
class LabourByWorkOrder extends SmrtReport {
  @groupBy() workRefId = '';
  @groupBy('wo.title') workOrder = '';
  @max('wo.estimatedHours') estimatedHours = 0;

  // A row expression: seconds from createdAt to claimedAt, averaged.
  @avg({ expr: { op: 'secondsBetween', later: { col: 'claimedAt' }, earlier: { col: 'createdAt' } } })
  avgResponseSeconds = 0;

  // A filtered count: one number rather than a two-row grouping.
  @count({ filter: { op: 'eq', left: { col: 'halted' }, right: { value: true } } })
  haltedSegments = 0;
}
```

-   **联合** 数到一,按键 `alias: { source, on, to?, type? }`。 。 。 . `on` 是一个 报告来源的字段; `to` 是它指向的相关字段(默认) `id`),并且必须确定每个租户一个相关的行,或者源行重复. `type` 实值 `left` (默认,保留一个相关行已去去的源行)或 `inner`。异名是小写标识符,而不是 `src`引用 字段为 `alias.field` 内 `@groupBy`和桶装器, 表达式和 `where`。 。 。 .
-   **关键类型.** `on` 财务报告和审定财务报表 `to` 可能为同一类(uuid=uuid,文本=文本),, 以示比照,他们的索引将服务于联合体,或文本字段与 uuid 1,例如多态 `workRefId` 指向 uuid 的字符串 `id`。 。 。 . 当一个列是文本,另一个uuid在计划中,加法将两者作为文本比较 在 PostgreSQL 和 DuckDB (否则会拒绝) `text = uuid` 失败 非uuid值),所以非uuuid的文本值仅与无相匹配: NULL在左联,倒入内联. {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}一个uuid比较一下 小写形式,所以大写存储的引用不匹配. SQL 点 以 TEXT 两种格式存储,并比较未显示的。 投影栏无法使用 索引;对于大表格,更喜欢uuid型的引用(`@foreignKey()` 或者说 `@crossPackageRef()`) (中文(简体) ). 同一规则也适用于租户栏目。 其它 类型对数(一个整数相对于一个小数,如:)作比较.
-   **租界是建筑在联想.** 当相关的模型是租户范围 加入同时匹配 `tenant_id` 在两行之间,所以一个指向 另外一个房客的排从不匹配。 租户范围从源头加入,没有 租地被拒绝。 被软删除的相關行从不相匹配.
-   **外地政策遵循数据.** 读取合并字段的报告栏 标记为敏感或 `readPermission`\- 从适配器上扣下 与字段完全一致.
-   **表达式是数据, 以文字写** (显示的扫描仪读取) 装饰者的参数静态化,所以构建者调用会被放弃: `{ col }`, (中文(简体) ), `{ value }`, (中文(简体) ), `add`编号 :`sub`编号 :`mul`编号 :`div`, (中文(简体) ), `secondsBetween`, (中文(简体) ), `eq`编号 :`ne`编号 :`lt`编号 :`lte`编号 : `gt`编号 :`gte`, (中文(简体) ), `and`编号 :`or`编号 :`not`, (中文(简体) ), `isNull`编号 :`isNotNull` 财务报告和审定财务报表 `coalesce`A级 `col` 命名一个模型字段,绝不是 SQL 列. `div` 返回零的 NULL 分卫. `expr` 财务报告和审定财务报表 `filter` 与 `count`, (中文(简体) ), `sum`, (中文(简体) ), `avg`, (中文(简体) ), `min` 财务报告和审定财务报表 `max`。 。 。 .
-   **合并报告仅通过重建刷新 .** 更改为合并行不 移动源的水印,所以宣布 `mode: 'incremental'` 被拒绝 任何需要递增更新的触发器(时间表, `onChange`页:1 以重建方式运行。 列出在 `refresh.onChange` 改为 改变时重建。 租户所在行 `NULL` (全局切片)没有 匹配租户范围相关行, 因为 `NULL = NULL` 在 SQL 中并非如此.
-   **保存视图和快照通知定义更改 .** 列的表达式、过滤器和所读的相加是其描述符的一部分(`semantics`因此,报告定义指纹;更改一个无效的存储视图和导出快照。 不加入报告或表达报告保留现有指纹.
-   **无法通过连接或计算密钥进行挖掘 .** 由合并的一行或 计算值不能被源列绑回源行,所以 `buildReportDrilldownQuery()` 拒绝这类报告.

运行时报告语法仍然关闭:运行时报告没有加入或 表达.

## 刷新模式

-   `rebuild` 替换已实现的结果.
-   `incremental` 在源水标记后重算受影响的组并删除 变成空的组合.
-   TTL 支持的收藏在读取报告时更新.
-   `ReportScheduleRunner` 财务报告和审定财务报表 `registerReportRefreshInterceptor()` 队列 通过 [`smrt-jobs`](https://npmcn.com/package/%40happyvertical/jobs/README.md)。 。 。 .

递增源通常需要水印和软去除柱 `updatedAt` 财务报告和审定财务报表 `deletedAt`明确过滤器 `tenant_id`;普通的收集截取器无法保证一个生集合.

## 公共入境点

该套件暴露了仅需要编译器的消费者所关注的子路径, 装饰器、刷新引擎、调度器、状态模型或聚合兼容性 帮助者 :

```text
@happyvertical/smrt-reports
@happyvertical/smrt-reports/compiler
@happyvertical/smrt-reports/decorators
@happyvertical/smrt-reports/refresh
@happyvertical/smrt-reports/scheduler
@happyvertical/smrt-reports/state
@happyvertical/smrt-reports/aggregate
```

## 报告适配器

该套件还输出一个用于报告表面的运输中性适配器:

```ts
import {
  buildReportAdapterDescriptor,
  buildReportDrilldownQuery,
  queryReportMaterializedRows,
  reportMaterializedRowKey,
  splitReportFilterScopes,
} from '@happyvertical/smrt-reports';

const descriptor = await buildReportAdapterDescriptor(MonthlyRevenue, {
  tenantScope: 'current',
});
const reports = await MonthlyRevenueCollection.create({ db: 'app.db' });
const result = await queryReportMaterializedRows(
  MonthlyRevenue,
  {
    version: 1,
    requestId: 'monthly-revenue-first-page',
    mode: 'rows',
    projection: ['id', 'customer_id', 'revenue'],
    filter: {
      kind: 'all',
      filters: [
        {
          kind: 'condition',
          field: 'customer_id',
          operator: 'eq',
          value: 'customer-42',
        },
        {
          kind: 'condition',
          field: 'revenue',
          operator: 'gte',
          value: 1000,
        },
      ],
    },
    page: { kind: 'offset', offset: 0, limit: 25 },
    sort: [{ field: 'revenue', direction: 'desc' }],
  },
  {
    collection: reports,
    // Preserve the resource identity of the descriptor selected above.
    adapter: { tenantScope: 'current' },
  },
);
const rowKey = reportMaterializedRowKey(result.rows[0]);
const drilldown = await buildReportDrilldownQuery(MonthlyRevenue, result.rows[0]);
```

`ReportAdapterDescriptor` 是确定性JSON 有稳定的资源代码, `id` 作为身份字段, 键入报告栏, 条形 `DataQuerySchema`, (中文(简体) ), 和结构数据表提示。 这些暗示是故意的,不是 `smrt-ui` 依赖性。 消费者可以将描述符映射到自己的演示层. 适配器曝光的只有持续的报告栏和主键:瞬间, 系统,以及非柱形字段没有浮出水面。 敏感/机密领域和 一个字段 `readPermission` 没有委托人被排除在外,所以 描述失败 .

这个 `dataTable.columns` 条目带有中性 `headerPath`, (中文(简体) ), `valueFormat`, (中文(简体) ), 校正 角色 和响应提示 组合田地、时间桶和 总体计量得到确定性的多层次标题;a 消费者可以通过稳定的标识来覆盖任何一列 `buildReportAdapterDescriptor(..., { dataTable: { columns: { ... } } })`。 。 。 . `valueFormat` 仅用于渲染边界的指令:行返回 以 `queryReportMaterializedRows()` 保留其原始JSON安全值 分类、出口和代理 使用 `dataTable.structuralRows` 计算 汇总、小计、汇总或页脚。 每个都有标记 `selection: 'excluded'` 财务报告和审定财务报表 `actions: 'excluded'`,必须传递到消费桌的结构 相行表面而不是其可选择的数据行.

`queryReportMaterializedRows()` 是已实现的已绑定的已读切片 作行相会. 它支持预测、抵消/限制呼叫(默认限制50), 确定性多种类型(与 `id` 作为最后的领带断裂器,打入过滤器,以及 数据库支持的维度方面。 一个描述标记组/时间字段为 `filterScope: 'where'` 和总措施 `filterScope: 'having'`; 使用 `splitReportFilterScopes()` 当构建一个活源查询时。 一个和可能 将两个瞄准镜组合起来,但是一个OR或NOT不能混合它们,因为移动中任何一个 横跨源头 `WHERE`编号 :`HAVING` 边界会改变它的意义.

实事求是的查询结果 列类型。 平分栏中的对象成为 JSON 文本; JSON 列保留 结构值。 只使用日期和无时区时间戳使用 UTC, 匹配 SQLite存储,和时间面桶遵循相同的规则. 字符串过 4096个字符缩短为 `truncated` 警告,除行身份证外: 身份永远不会被重写,并且没有支持的ID会失败验证. 不安全的重击 数值失败,而不是默默地失去精确度.

已实现的收藏执行已规范的,允许列入的上游 参数化了SQL,并将其同样适用于行,总和和方. 这个 绝不接受原始 SQL, 源字段路径, 租户ID, 或主ID . 描述者 `queryExecution` 合同宣布三种交货选择: `visible` 返回已授权表面的行, `silent` 返回相同的边框结果,同时不作可视表面变化, 财务报告和审定财务报表 `background` 代表一个正常的、无权力的任务 `enqueueBackgroundQuery` 主持人。 背景结果只是队列控件,绝不 实现行. 东道主保留经认证的本金、承租人、报告 定义、外地政策、数据库和最终的工作执行 在查询请求或背景任务中提供. 当消费者选择一个描述符时 `ReportAdapterOptions`,通过这些 通过查询的相同选项 `adapter` 选项返回和背景 任务资源 id 与所选描述符保持一致. `buildReportDrilldownQuery()` 只携带该行宣布的组/桶 和现主、租户的固定继承合同 定义和实地政策;经认证的源适配器必须执行 合同之前,它读源记录。 时间桶保持宣示,所以 源适配器保存报告的数据库/时区语义. 都回来了 行必须有一个非空字符串 `id`; 使用该值,从不显示或页面 索引,用于行身份.

当未注入收藏时, 读取已注册的报表收藏 结束 `ObjectRegistry`,允许普通s-m-r-t收集截取器执行 租户过滤. `tenantScoped` 财务报告和审定财务报表 `tenantField` 在描述中是真实的 仅当报告实际用租户元数据注册时; 范围字符串 单靠自己不是当局的界限。 注入的收藏属于应用程序所有 并且必须提供同等的租户边界。 原始总和刷新仍然 需要上述明确的租户上游.

描述者 `refresh` 区域声明模式、触发器、读取行为, 和经授权、审计的 `refresh` 与 `preview` 财务报告和审定财务报表 `apply` 阶段. 适配器本身只保留读取. 打电话 `getReportLifecycle()` 租户安全 当前、 stale、 刷新、 被锁定或未实现的快照 状态;它会编辑锁住所有者、原始错误和租户识别符。 传出 a `lifecycle` 选项到 `queryReportMaterializedRows()` 只有在消费者需要时 上下文;然后将结果区分为当前、 stale 或已读 刷新点. `previewReportRefresh()` 财务报告和审定财务报表 `applyReportRefresh()` 需要一个 应用程序操作器主机, 以授权和审核呼叫者之前 报告- 更新任务已排队。 手动刷新主机也必须返回一个版本, 非机密事项 `executionAuthority` 装订。 每个工人工序登记姓名 主机为 `registerReportRefreshExecutionAuthorityHost()`;任务检查 持续租户具有约束力,解决目前的成员资格和许可问题,以及记录 在刷新前立即允许或拒绝执行审计。 每个队列 路径还收到 `DurableJobPayloadSigner`,每个工人都登记 与 `registerReportRefreshJobIntegritySigner()`。此验证任务 目标、触发器、租户范围、授权参照和整个储存的有效载荷; 签名密钥永远不会持续。 排定和变更的维修工作 保持系统授权工作,不携带启动用户,而是他们的工作 有效载荷使用相同的完整性边界。 只有注册 `SmrtReportCollection` 能够 同步刷新读取的已失效读取,并且只有在其TTL政策是积极且 不是手动的.

### 预定的更新生命周期

声明 `refresh: { schedule: '*/5 * * * *', tenantFanout: 'discover' }` 一份租户范围的报告 以发现不同的非无源租户 计划运行。 在已实现的表格中包含仍然存在的范围,这样 接下来的重建 取消了对租户失去最后源行的陈旧的组合. 发现保存所配置的刷新模式 。 仍需要递增报告 (单位:千美元) `fullRebuildSchedule` 来抓取不推进源的硬删除 水印mark. 备抵附表 `ensureReportRefreshSchedules({ db, reports })`; 没有发现的瞄准镜意味着没有工作, 发现永远不会更新 环球片. 工人使用登记来源/报告租户栏及其供应 维护执行器。 发现不授予数据库权限或扩展 以租户为单位或手工工作。 保留 `tenantFanout: true` 明确 `tenantIds` 当宿主拥有固定租户名单时.

初始化 a `ReportScheduleRunner` 和一个工作 `TaskRunner` 对抗移民 数据库,然后调用 `const unbind = schedules.bindTaskRunner(tasks)` 在此之前 开始他们。 这将终端任务事件连接到调度计数器, 释放 成功或失败后的货币槽。 反复装订是一能; 调用 `unbind()` 关闭。 听着 `runner:error` 以检测失败的计数器 更新。 错误的失败消息使用工作包的编辑政策. 持续有效载荷签署和执行时间授权检查仍在进行 ; 完成会计使用已签名的附表标识.

重复提供时间表插入缺失的身份并保存现有 历史、下一运行时间、运行计数和操作员设置。 一个不同的克龙, 模式,或租户范围确定不同的时间表;明确禁用过时 更改这些设置时的时间表.

### 保存视图和快照导出

`normalizeReportSavedView()` 财务报告和审定财务报表 `restoreReportSavedView()` 提供 可序列视图边界 。 存储主机拥有保存的视图的租户和 拥有者;每次恢复时,必须把所储存的有效载荷通过电流 释相. 重新应用字段、投影、排序、分组和定义 策略,因此一个僵化的视图不能显示一个不再允许的字段. `migrateReportSavedView()` 升级未编辑的原始文本( 或明确 v0) 排版到当前政策验证前的 v1; 不支持的未来版本 明显失败,而不是被猜测.

从已实现的行中创建导出 `createReportExportSnapshot()`,从 应用程序的不可变现- snapshot 主机, 然后调用 `createReportExportRequest()`。该快照修正了条形查询 指纹,普通投影 排序,准确行数, `asOf`, (中文(简体) ), `refreshedAt`和定义指纹。 每一个请求也 包含确定性平面平面读取计划; 渲染器开始于平面零 并按其验证的页面大小推进,直到精确的行数 已经到达。 使用 `createReportExportPageRequest()` 每页; 保留 被冻结的查询语义, 同时只替换可见的 pagination .

每个请求都以行、字节和最后期限为界 前景行限制成为无权限背景交接. 使用 `previewReportExport()` 财务报告和审定财务报表 `applyReportExport()` 申请相同 人类和代理人的操作主机。 东道方授权和审计 已固定 `reports.export` 动作; 含有个人、敏感或秘密内容的出口 栏需要明确确认.

预览,应用,每个工人呼叫 `validateReportExportExecution()`,哪个 要求主机证明不透明绑定仍能准确解决 不可改变的可实现性 定义和外地政策。 如果做不到,操作失败,而不是 用旧的重新标记新行 `asOf`。艺术元数据没有 URL 或 下载符; 在服务前, 拨打 `validateReportExportArtifact()` 改为 拒绝过期、定义漂移和出界进度,然后适用 主机当前的授权和快照验证 .

## 运行时间报告

报告也可以在运行时被定义为数据. `RuntimeReportSpec` 是关闭的, 版本结构(源代码、尺寸、度量、过滤器、有、排序、, 图表提示),没有自由形式的查询文本. `compileRuntimeReportSpec()` 检查一下 针对服务器拥有的源代码允许列表, 字段政策( 敏感和 权限指定字段无法命名 , 呼叫者的许可, 以及租户 ,然后针对与申报报告相同的总体计划. `RuntimeReport` 存储每个租户验证的规格,存储的规格是 每次运行时为运行中的用户重新编译. 结果行不存储 。 一行 , 继续 只能插入,或更改其光谱,通过 `saveRuntimeReport()` 与 spec hash 一个人类确认; 模型层拒绝 所有其他写入。 这个 聊天软件包提供匹配的助手工具,可以提出一个 spec,预览它, 并且只在人确认之后,才得享受。 见 [`agents/runtime-reports.md`](https://npmcn.com/package/%40happyvertical/smrt-reports/agents/runtime-reports.md)。 。 。 .

## 浏览器组件

`@happyvertical/smrt-reports/svelte` 导出已保存的报告和细节屏幕, 一份确认卡,一份报告/计量拾取器,以及一份共享图结果视图. 他们接受主扫描浏览器传输并显示不可用状态 当未提供服务器时。 见 [浏览器集成合同](https://npmcn.com/package/%40happyvertical/smrt-reports/agents/runtime-report-browser.md) 用于路由主机身份和能力道具、确认接线、配方 地面和游乐场预览.

## 发展

```bash
pnpm --filter @happyvertical/smrt-reports test
pnpm --filter @happyvertical/smrt-reports typecheck
pnpm --filter @happyvertical/smrt-reports build
```

见 [`AGENTS.md`](https://npmcn.com/package/%40happyvertical/smrt-reports/AGENTS.md) 用于清新 计划 和租房的不常客.

## 常见问题

### @happyvertical/smrt-reports 是什么？

SMRT实际汇总报告模型

### 如何安装 @happyvertical/smrt-reports？

在项目目录运行 npm install @happyvertical/smrt-reports，或使用 pnpm add / yarn add / bun add。

### @happyvertical/smrt-reports 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @happyvertical/smrt-reports 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @happyvertical/smrt-reports 可以商用吗？

@happyvertical/smrt-reports 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @happyvertical/smrt-reports 的下载量有多少？

根据 npm 官方下载统计，@happyvertical/smrt-reports 在 2026/10/17 – 2026/11/15 这 30 天内被下载 21,624 次，日均约 721 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @happyvertical/smrt-reports 还在维护吗？

最新版本 0\.62\.1 发布于 2026/11/17（今天）；至今共发布 337 个版本，其中过去 12 个月发布了 337 个；首次发布于 2026/06/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

