@happyvertical/smrt-reports

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 2.2万

SMRT实际汇总报告模型

中文使用文档
文档目录12 节
  1. 安装
  2. 定义报告
  3. 装饰者
  4. 组合、行表达式和过滤措施
  5. 刷新模式
  6. 公共入境点
  7. 报告适配器
  8. 预定的更新生命周期
  9. 保存视图和快照导出
  10. 运行时间报告
  11. 浏览器组件
  12. 发展

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

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

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

安装

pnpm add @happyvertical/smrt-reports

定义报告

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 文本 .

@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 财务报告和审定财务报表 coalesceA级 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。 。 。 .

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

公共入境点

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

@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

报告适配器

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

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。 。 。 .

浏览器组件

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

发展

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

见 AGENTS.md 用于清新 计划 和租房的不常客.

版本与发布记录

@happyvertical/smrt-reports 共发布 337 个版本,首次发布于 2026/06/26;过去 12 个月发布了 337 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-reports 的常见问题

@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 和提交记录判断。