@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 用于清新 计划 和租房的不常客.