@agile-team/mach-report 2.8.4 → 2.9.1

package/dist/server.d.ts

@@ -1,3 +1,19 @@
+declare interface AggregateDefinition {
+    /** Output column; valueField defaults to this field. */
+    field: string;
+    op: AggregateOperation;
+    valueField?: string;
+    weightField?: string;
+    numeric?: "number" | "decimal";
+    digits?: number;
+}
+
+declare type AggregateOperation = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
+
+export declare function checkJobIdentity(scope: string, id: string): void;
+
+export declare function cloneJob<T>(value: T): T;
+
 /**
  * 列值格式化（声明式、JSON 可序列化）。
  * 在 paginate 的 cellText 出口统一消费：格式化发生在进 RenderPlan 之前，
@@ -47,6 +63,22 @@ declare interface ComponentStyle {
     rotateDeg?: number;
 }
 
+declare interface ComputedField extends ExpressionOptions {
+    field: string;
+    expression: ReportExpression | string;
+    /** Scope controls aggregate inputs; row expressions may reference the current row in any scope. */
+    scope?: "row" | "group" | "dataset";
+    groupBy?: readonly string[];
+    /** String adapter expressions cannot be inspected; declare dependencies explicitly. */
+    dependsOn?: readonly string[];
+}
+
+/** Reference store for tests; use a database CAS or the single-process durable Node adapter in production. */
+export declare function createMemoryReportJobStore(): ReportJobStore;
+
+/** Durable at-least-once dispatch; export/artifact handlers must be idempotent by scope+taskId. */
+export declare function createReportJobService(options: ReportJobServiceOptions): ReportJobService;
+
 /** 无 Vue、无 HTTP 框架的可选服务端外观；PDF/Excel 仅在对应 export 调用时加载。 */
 export declare function createReportRuntime(options: ReportRuntimeOptions): ReportRuntime;
 
@@ -70,6 +102,22 @@ declare interface DatasetValidationOptions {
     maxIssues?: number;
 }
 
+declare interface ExpressionOptions {
+    numeric?: "number" | "decimal";
+    digits?: number;
+    nulls?: "propagate" | "error";
+    divisionByZero?: "null" | "error";
+}
+
+declare interface FormulaAdapter {
+    /** Explicit trusted engine; core never evaluates source code/macros/external workbook references. */
+    evaluate(expression: string, context: {
+        row: Readonly<Record<string, unknown>>;
+        rowIndex: number;
+        rows: readonly Record<string, unknown>[];
+    }): unknown;
+}
+
 declare interface GridCell {
     text?: string;
     rawText?: string;
@@ -114,6 +162,9 @@ declare interface ListColumn {
     valueType?: GridCell["valueType"];
     /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
     semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
+    hidden?: boolean;
+    /** Condition hides cell content, preserving its physical layout in preview and exports. */
+    visibleWhen?: StyleRule["when"];
 }
 
 declare interface ListComponent {
@@ -148,15 +199,38 @@ declare interface ListComponent {
     border?: boolean;
     /** 分组小计（组头/组尾小计/组头防孤行） */
     groupBy?: ListGroupBy;
+    /** Ordered outer-to-inner grouping; groupBy remains the single-level shorthand. */
+    groups?: ListGroupBy[];
+    computed?: ComputedField[];
+    /** Dynamic pivot of the current source dataset, with read-only derived identities. */
+    matrix?: MatrixTableOptions;
+    /** Explicit row visibility; hidden rows do not participate in summaries. */
+    rowVisibleWhen?: StyleRule["when"];
+    /** Master/detail relation is keyed by business identity, never by display row index. */
+    detail?: ListDetail;
     /** 末尾总合计行（依赖 groupBy.subtotal 或显式 fields） */
     grandTotal?: ListGrandTotal;
 }
 
+declare interface ListDetail {
+    dataset: string;
+    parentKey: string;
+    foreignKey: string;
+    rowKey?: string;
+    columns: ListColumn[];
+    rowHeightMm?: number;
+    header?: boolean;
+    label?: string;
+    /** Unmatched children fail by default; opt-in ignore is explicit. */
+    unmatched?: "error" | "ignore";
+}
+
 declare type ListGrandTotal = boolean | {
     label?: string;
     style?: ComponentStyle;
     /** 合计列（缺省沿用 groupBy.subtotal） */
     fields?: string[];
+    aggregates?: AggregateDefinition[];
 };
 
 /** 分组小计配置（声明式，见 ListComponent.groupBy） */
@@ -172,8 +246,42 @@ declare interface ListGroupBy {
     subtotalLabel?: string;
     /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
     keepWithNext?: boolean;
+    aggregates?: AggregateDefinition[];
+    /** Repeat this group heading after page breaks within the group. */
+    repeatHeader?: boolean;
+}
+
+declare interface MatrixTableOptions {
+    rowFields: readonly string[];
+    columnFields: readonly string[];
+    measures: readonly (AggregateDefinition & {
+        label?: string;
+    })[];
+    totals?: boolean;
+    rowHeader?: string;
+    columnWidthMm?: number;
+    rowWidthMm?: number;
+    maxRows?: number;
+    maxColumns?: number;
+    maxInputRows?: number;
+    maxCells?: number;
+}
+
+declare interface OutputDiagnostic {
+    code: "missing-image" | "unsupported-component" | "unsupported-image-format" | "unsupported-style" | "rich-text-flattened" | "nested-components-omitted" | "async-image-required" | "image-decode-failed" | "asset-render-failed" | "asset-budget-exceeded";
+    severity: "warning";
+    format: OutputFormat;
+    pageIndex: number;
+    componentIndex: number;
+    /** Nested grid child location as repeating [rowIndex, columnIndex, childIndex] triples. */
+    componentPath?: readonly number[];
+    kind: string;
+    nid?: string;
+    message: string;
 }
 
+declare type OutputFormat = "dom" | "canvas" | "pdf" | "xlsx";
+
 declare interface PaginateOptions {
     /** 每行额外占高（mm），压测专用钩子 */
     mmPerRow?: number;
@@ -181,9 +289,19 @@ declare interface PaginateOptions {
     measurer?: TextMeasurer;
     /** 可选页数上限；在追加超限页前终止，避免先分配全部页面再检查。 */
     maxPages?: number;
+    /** Actual grid cells, including repeated furniture and nested children; checked before each page is appended. */
+    maxCells?: number;
+    signal?: AbortSignal;
+    /** Streaming total-page anchors can skip the bounded counting pass when known. */
+    knownTotalPages?: number;
+    onWarning?: (warning: string) => void;
+    /** Trusted formula adapter is passed at execution time; it is never serialized in templates. */
+    formula?: FormulaAdapter;
 }
 
 declare interface PlanComponent {
+    /** Template page furniture repeats per page and reserves its vertical band. */
+    pageAnchor?: "header" | "footer";
     kind: ComponentKind;
     leftMm: number;
     topMm: number;
@@ -333,6 +451,19 @@ declare interface ReportDiagnostic {
     severity: "warning" | "error" | "info";
 }
 
+declare type ReportExpression = {
+    field: string;
+} | {
+    value: string | number | boolean | null;
+} | {
+    aggregate: AggregateOperation;
+    field?: string;
+    weightField?: string;
+} | {
+    op: "add" | "subtract" | "multiply" | "divide" | "coalesce";
+    args: readonly ReportExpression[];
+};
+
 declare interface ReportFieldContract {
     field: string;
     label?: string;
@@ -348,6 +479,87 @@ declare interface ReportFieldContract {
     unit?: string;
 }
 
+export declare class ReportJobError extends Error {
+    readonly code: "input" | "conflict" | "missing" | "lease" | "closed" | "capacity";
+    constructor(code: "input" | "conflict" | "missing" | "lease" | "closed" | "capacity", message: string);
+}
+
+export declare interface ReportJobExecutionContext {
+    scope: string;
+    taskId: string;
+    signal: AbortSignal;
+    reportProgress(completed: number, total?: number): Promise<void>;
+}
+
+export declare type ReportJobHandler = (payload: ReportJobJson, context: ReportJobExecutionContext) => ReportJobJson | Promise<ReportJobJson>;
+
+export declare type ReportJobJson = null | boolean | number | string | ReportJobJson[] | {
+    [key: string]: ReportJobJson;
+};
+
+export declare interface ReportJobRecord {
+    scope: string;
+    id: string;
+    revision: number;
+    request: ReportJobRequest;
+    status: ReportJobStatus;
+    createdAt: number;
+    updatedAt: number;
+    attempt: number;
+    lease?: {
+        owner: string;
+        expiresAt: number;
+    };
+    cancelRequested?: boolean;
+    progress?: {
+        completed: number;
+        total?: number;
+    };
+    result?: ReportJobJson;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+
+export declare interface ReportJobRequest {
+    kind: string;
+    payload: ReportJobJson;
+}
+
+export declare interface ReportJobService {
+    submit(input: ReportJobRequest & {
+        scope: string;
+        id: string;
+    }): Promise<ReportJobRecord>;
+    get(scope: string, id: string): Promise<ReportJobRecord | undefined>;
+    cancel(scope: string, id: string): Promise<ReportJobRecord>;
+    retry(scope: string, id: string, expectedRevision: number): Promise<ReportJobRecord>;
+    /** Dispatch one queued/expired job. A scheduler controls when to call this method. */
+    runNext(workerId: string): Promise<ReportJobRecord | undefined>;
+    /** Stops new dispatch, signals active handlers and waits until their actual completion. */
+    close(): Promise<void>;
+    readonly active: number;
+}
+
+export declare interface ReportJobServiceOptions {
+    store: ReportJobStore;
+    handlers: Readonly<Record<string, ReportJobHandler>>;
+    concurrency?: number;
+    leaseMs?: number;
+    heartbeatMs?: number;
+    now?: () => number;
+}
+
+export declare type ReportJobStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+
+/** CAS must be atomic across all worker instances; candidate enumeration is advisory only. */
+export declare interface ReportJobStore {
+    read(scope: string, id: string): Promise<ReportJobRecord | undefined>;
+    candidates(now: number, limit: number): Promise<ReportJobRecord[]>;
+    compareAndSwap(scope: string, id: string, expectedRevision: number | null, next: ReportJobRecord): Promise<boolean>;
+}
+
 /** 取数与排版共同使用的请求上下文；取消只影响本次调用。 */
 declare interface ReportLoadContext {
     reportId: string;
@@ -414,6 +626,31 @@ declare interface ReportProviderExportResult {
     diagnostics?: ReportDiagnostic[];
 }
 
+export declare interface ReportPublicationArtifact {
+    fixture: string;
+    format: "pdf" | "xlsx";
+    bytes: number;
+    pages: number;
+    /** Optional host digest. No Node or crypto dependency is pulled into /server. */
+    digest?: string;
+}
+
+export declare interface ReportPublicationOptions extends ReportTemplateReviewOptions {
+    formats?: readonly ("pdf" | "xlsx")[];
+    signal?: AbortSignal;
+    pdf?: ReportRuntimeExportInput["pdf"];
+    xlsx?: ReportRuntimeExportInput["xlsx"];
+    maxOutputBytes?: number;
+    maxDurationMs?: number;
+    /** Explicit fixtures only. Host may archive these bytes; the result retains metadata only. */
+    onArtifact?: (fixture: string, result: ReportRuntimeExportResult) => void | Promise<void>;
+    digest?: (bytes: Uint8Array) => string | Promise<string>;
+}
+
+export declare interface ReportPublicationReview extends ReportTemplateReview {
+    artifacts: ReportPublicationArtifact[];
+}
+
 declare interface ReportQueryResult {
     datasets: DatasetRows;
     revision?: string;
@@ -580,6 +817,22 @@ declare interface ReportTemplate {
     pages: TemplatePage[];
 }
 
+declare interface ReportTemplateChange {
+    kind: "added" | "removed" | "modified" | "moved";
+    category: "metadata" | "structure" | "binding" | "calculation" | "format";
+    path: string;
+    before?: string;
+    after?: string;
+    breaking: boolean;
+}
+
+declare interface ReportTemplateDiff {
+    changes: ReportTemplateChange[];
+    totalChanges: number;
+    truncated: boolean;
+    breakingChanges: number;
+}
+
 /** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
 declare interface ReportTemplateDocument {
     schemaVersion: "1.0";
@@ -591,6 +844,12 @@ declare interface ReportTemplateDocument {
     template: ReportTemplate;
 }
 
+declare interface ReportTemplateFixture {
+    name: string;
+    datasets: DatasetRows;
+    params?: Record<string, string>;
+}
+
 declare type ReportTemplateLoader = (context: ReportLoadContext) => ReportTemplate | Promise<ReportTemplate>;
 
 declare interface ReportTemplateProvider {
@@ -602,8 +861,46 @@ declare interface ReportTemplateProvider {
     }): Promise<ReportTemplateDocument | undefined>;
 }
 
+declare interface ReportTemplateReview {
+    ok: boolean;
+    changes?: ReportTemplateDiff;
+    issues: ReportTemplateReviewIssue[];
+    samples: Array<{
+        name: string;
+        pages: number;
+        rows: number;
+        diagnostics: OutputDiagnostic[];
+    }>;
+}
+
+declare interface ReportTemplateReviewIssue {
+    code: "template" | "compatibility" | "dataset" | "field" | "sample" | "layout" | "output";
+    severity: "error" | "warning";
+    path: string;
+    message: string;
+    fixture?: string;
+    pageIndex?: number;
+    componentIndex?: number;
+    field?: string;
+}
+
+declare interface ReportTemplateReviewOptions {
+    previous?: ReportTemplateDocument;
+    dataSchemas?: Readonly<Record<string, DatasetContract>>;
+    fixtures?: readonly ReportTemplateFixture[];
+    formats?: readonly OutputFormat[];
+    maxPages?: number;
+    maxCells?: number;
+    maxSampleRows?: number;
+    allowBreakingChanges?: boolean;
+    strictOutputs?: boolean;
+}
+
 declare type ReportTemplateSummary = Omit<ReportTemplateDocument, "template">;
 
+/** Publication gate with actual sequential PDF/XLSX encoding, no business query or implicit save. */
+export declare function reviewReportPublication(input: unknown, options?: ReportPublicationOptions): Promise<ReportPublicationReview>;
+
 declare interface RichParagraph {
     segments: RichSegment[];
     align?: ComponentStyle["align"];
@@ -620,12 +917,22 @@ declare interface RichSegment {
     style?: ComponentStyle;
 }
 
+export declare function runnableJob(record: ReportJobRecord, now: number): boolean;
+
+/** Canonical plain JSON rejects getters/scripts and gives stable idempotency without coercion. */
+export declare function serializeJobJson(value: unknown, budget?: {
+    maxNodes?: number;
+    maxCharacters?: number;
+}): string;
+
 /** 条件格式规则求值（声明式，见 ListColumn.rules） */
 declare interface StyleRule {
     when: {
         field: string;
         op: ">" | ">=" | "<" | "<=" | "==" | "!=";
         value: number | string;
+        /** Explicit decimal comparisons retain decimal thresholds as text. */
+        numeric?: "number" | "decimal";
     };
     /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
     style: Record<string, unknown>;
@@ -665,4 +972,8 @@ declare interface TextMeasurer {
     measureMm(text: string, options: TextMeasureOptions): number;
 }
 
+export declare function validateJobRecord(record: ReportJobRecord, scope: string, id: string, expectedRevision: number | null): void;
+
+export declare function validateJobTransition(previous: ReportJobRecord | undefined, next: ReportJobRecord): void;
+
 export { }