@agile-team/mach-report 2.5.0 → 2.6.1

package/dist/worker.d.ts

@@ -0,0 +1,302 @@
+export declare interface BrowserReportWorker {
+    postMessage(value: unknown, transfer?: Transferable[]): void;
+    terminate(): void;
+    addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+    addEventListener(type: "error" | "messageerror", listener: (event: Event) => void): void;
+    removeEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: "error" | "messageerror", listener: (event: Event) => void): void;
+}
+
+declare type ComponentKind = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
+
+declare interface ComponentStyle {
+    fontSizePx?: number;
+    fontSize?: number;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string;
+    backgroundColor?: string;
+    align?: "left" | "center" | "right" | "justify";
+    verticalAlign?: "top" | "middle" | "bottom";
+    lineColor?: string;
+    borderColor?: string;
+    lineWidthPt?: number;
+    borderTop?: boolean;
+    borderRight?: boolean;
+    borderBottom?: boolean;
+    borderLeft?: boolean;
+    lineHeight?: number;
+    letterSpacing?: number;
+    opacity?: number;
+    rotateDeg?: number;
+}
+
+/** factory 每次返回全新 Worker，例如 () => new Worker(new URL('./worker.ts', import.meta.url), {type:'module'})。 */
+export declare function createBrowserReportExecutor(factory: () => BrowserReportWorker, options?: ReportWorkerOptions): ReportRuntimeExecutor;
+
+declare interface GridCell {
+    text?: string;
+    rawText?: string;
+    /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
+    value?: string | number | boolean | null;
+    /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
+    numberFormat?: string;
+    /** 编辑输入类型；省略时只按原始值推断，数字字符串不会被转换为数值。 */
+    valueType?: "text" | "number" | "boolean";
+    /** 单元格级编辑控制；预览仍需显式开启 editing。 */
+    editable?: boolean;
+    source?: ReportCellSource;
+    /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
+    formula?: string;
+    children?: PlanComponent[];
+    colSpan?: number;
+    rowSpan?: number;
+    style?: ComponentStyle;
+}
+
+declare interface PlanComponent {
+    kind: ComponentKind;
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    nid?: string;
+    rkey?: string;
+    text?: string;
+    rawText?: string;
+    lines?: string[];
+    richParagraphs?: RichParagraph[];
+    imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
+    grid?: PlanGrid;
+    table?: PlanTableFragment;
+    style?: ComponentStyle;
+    meta?: Record<string, unknown>;
+    /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
+    fallbackText?: string;
+}
+
+declare interface PlanGrid {
+    /** 行内允许 null 空位；渲染器按空单元格处理 */
+    cells: (GridCell | null)[][];
+    colWidthsMm?: number[];
+    rowHeightsMm?: number[];
+    gapMm?: number;
+    /** 单元格四边内距；旧静态网格默认 0.5mm，分页列表使用其真实测量内距。 */
+    paddingMm?: number;
+}
+
+declare interface PlanPage {
+    /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
+    layout?: "page" | "wide";
+    pageWidthMm: number;
+    pageHeightMm: number;
+    marginTopMm?: number;
+    marginBottomMm?: number;
+    marginLeftMm?: number;
+    marginRightMm?: number;
+    components: PlanComponent[];
+}
+
+/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
+declare interface PlanTableFragment {
+    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
+    id: string;
+    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
+    rowIndex: number;
+    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
+    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
+    columnKeys: string[];
+    layout?: "page" | "wide";
+    title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
+}
+
+declare interface PreparedReport {
+    plan: RenderPlan;
+    diagnostics: ReportDiagnostic[];
+    stats: ReportRuntimeStats;
+    revisions: Record<string, {
+        revision?: string;
+        sourceToken?: string;
+    }>;
+}
+
+declare interface RenderPlan {
+    schemaVersion: string;
+    pages: PlanPage[];
+}
+
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+declare interface ReportCellSource {
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+
+declare interface ReportDescription {
+    id: string;
+    params: ReportParamDef[];
+    paramsSchema: Record<string, unknown>;
+    datasetsSchema: Record<string, Record<string, unknown>>;
+    /** Provider 的可选远程能力；runtime 自身始终提供 PDF/XLSX 导出。 */
+    capabilities: {
+        save: boolean;
+        export: boolean;
+        templates: boolean;
+    };
+}
+
+declare interface ReportDiagnostic {
+    code: string;
+    message: string;
+    path?: string;
+    severity: "warning" | "error" | "info";
+}
+
+/** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
+declare interface ReportParamDef {
+    /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
+    field: string;
+    /** 显示名（缺省用 field） */
+    label?: string;
+    type?: "text" | "number" | "date" | "select";
+    /** select 选项 */
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    defaultValue?: string;
+    required?: boolean;
+    placeholder?: string;
+    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
+    min?: number | string;
+    max?: number | string;
+    minLength?: number;
+    maxLength?: number;
+}
+
+declare interface ReportParamIssue {
+    code: ReportParamIssueCode;
+    path: string;
+    field: string;
+    message: string;
+}
+
+declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "minimum" | "maximum" | "minLength" | "maxLength";
+
+declare interface ReportParamValidation {
+    ok: boolean;
+    /** 保留历史取数契约的字符串形式；未知参数保留，不能代替接口权限白名单。 */
+    values: Record<string, string>;
+    /** JSON Schema 对应的规范值：number 参数转换为有限数字。 */
+    typedValues: Record<string, string | number>;
+    issues: ReportParamIssue[];
+}
+
+declare interface ReportRuntime {
+    describe(reportIds?: string[]): ReportDescription[];
+    validate(input: Omit<ReportRuntimeInput, "signal">): ReportParamValidation;
+    prepare(input: ReportRuntimeInput): Promise<PreparedReport>;
+    export(input: ReportRuntimeExportInput): Promise<ReportRuntimeExportResult>;
+}
+
+/** 可用 worker_threads/进程/RPC 实现；接收可序列化请求，signal 由桥接层映射为取消消息。 */
+declare interface ReportRuntimeExecutor {
+    prepare(input: Omit<ReportRuntimeInput, "signal">, signal?: AbortSignal): Promise<PreparedReport>;
+    export(input: Omit<ReportRuntimeExportInput, "signal">, signal?: AbortSignal): Promise<ReportRuntimeExportResult>;
+}
+
+declare interface ReportRuntimeExportInput extends ReportRuntimeInput {
+    format: "pdf" | "xlsx";
+    /** PDF 中文需宿主显式提供有授权的字体；不隐式下载字体或资源。 */
+    pdf?: {
+        customFontBytes?: Uint8Array | ArrayBuffer;
+        customFontName?: string;
+        customFontFaces?: {
+            regular: Uint8Array | ArrayBuffer;
+            bold?: Uint8Array | ArrayBuffer;
+            italic?: Uint8Array | ArrayBuffer;
+            boldItalic?: Uint8Array | ArrayBuffer;
+        };
+    };
+    xlsx?: {
+        sheetMode?: "auto" | "pages" | "continuous";
+        valueMode?: "text" | "raw";
+        paperSize?: "auto" | "a3" | "a4" | "a5";
+    };
+}
+
+declare interface ReportRuntimeExportResult extends Omit<PreparedReport, "plan"> {
+    bytes: Uint8Array;
+    format: "pdf" | "xlsx";
+    contentType: string;
+}
+
+declare interface ReportRuntimeInput {
+    reportIds: string[];
+    params?: Record<string, string>;
+    signal?: AbortSignal;
+}
+
+declare interface ReportRuntimeStats {
+    rows: number;
+    pages: number;
+    cells: number;
+    durationMs: number;
+    outputBytes?: number;
+}
+
+export declare class ReportWorkerError extends Error {
+    readonly code?: string;
+    readonly path?: string;
+    readonly issues?: unknown;
+    constructor(error: SerializedReportError);
+}
+
+export declare interface ReportWorkerOptions {
+    timeoutMs?: number;
+}
+
+export declare interface ReportWorkerScope {
+    postMessage(value: unknown, transfer?: Transferable[]): void;
+    addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+}
+
+declare interface RichParagraph {
+    segments: RichSegment[];
+    align?: ComponentStyle["align"];
+    lineHeight?: number;
+    spaceBeforeMm?: number;
+    spaceAfterMm?: number;
+    indentMm?: number;
+}
+
+declare interface RichSegment {
+    kind?: "text" | "field";
+    text?: string;
+    field?: string;
+    style?: ComponentStyle;
+}
+
+declare interface SerializedReportError {
+    name: string;
+    message: string;
+    code?: string;
+    path?: string;
+    issues?: unknown;
+}
+
+/** 在 Worker 入口注册一次 runtime；返回函数可清理监听器，浏览器主线程无需引入 Node。 */
+export declare function serveReportWorker(runtime: ReportRuntime, scope?: ReportWorkerScope): () => void;
+
+export { }

package/dist/worker.js

@@ -0,0 +1,133 @@
+import { c as v } from "./validate-S6CgIm5d.js";
+const u = "mach-report-worker/1";
+class R extends Error {
+  constructor(e) {
+    super(e.message), this.name = e.name, this.code = e.code, this.path = e.path, this.issues = e.issues;
+  }
+}
+function m(r) {
+  return !!r && typeof r == "object" && !Array.isArray(r);
+}
+function x(r) {
+  return m(r) ? ["rows", "pages", "cells"].every((e) => typeof r[e] == "number" && Number.isSafeInteger(r[e]) && r[e] >= 0) && typeof r.durationMs == "number" && Number.isFinite(r.durationMs) && r.durationMs >= 0 : !1;
+}
+function M(r) {
+  return Array.isArray(r) && r.every((e) => m(e) && typeof e.code == "string" && typeof e.message == "string" && ["info", "warning", "error"].includes(e.severity));
+}
+function L(r) {
+  return m(r) && Object.values(r).every((e) => m(e) && (e.revision === void 0 || typeof e.revision == "string") && (e.sourceToken === void 0 || typeof e.sourceToken == "string"));
+}
+function A(r, e) {
+  if (!m(r) || !x(r.stats) || !M(r.diagnostics) || !L(r.revisions)) return !1;
+  if (e === "prepare") return v(r.plan).ok;
+  const t = r.format === "pdf" ? "application/pdf" : "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+  return r.bytes instanceof Uint8Array && (r.format === "pdf" || r.format === "xlsx") && r.contentType === t;
+}
+function T(r) {
+  if (!r || typeof r != "object") return { message: String(r) };
+  const e = {};
+  for (const t of ["code", "path", "field", "message"]) {
+    const o = r[t];
+    typeof o == "string" && (e[t] = o);
+  }
+  return e;
+}
+function j(r) {
+  if (!(r instanceof Error)) return { name: "Error", message: String(r) };
+  const e = r;
+  return {
+    name: r.name,
+    message: r.message,
+    ...typeof e.code == "string" ? { code: e.code } : {},
+    ...typeof e.path == "string" ? { path: e.path } : {},
+    ...Array.isArray(e.issues) ? { issues: e.issues.map(T) } : {}
+  };
+}
+function O(r) {
+  if (!r || typeof r != "object") return !1;
+  const e = r;
+  return e.protocol === u && typeof e.id == "string" && (e.operation === "prepare" || e.operation === "export") && !!e.input && typeof e.input == "object";
+}
+async function P(r, e) {
+  try {
+    const t = e.operation === "prepare" ? await r.prepare(e.input) : await r.export(e.input);
+    return { protocol: u, id: e.id, result: t };
+  } catch (t) {
+    return { protocol: u, id: e.id, error: j(t) };
+  }
+}
+function N(r) {
+  const e = r.result;
+  return !e || !("bytes" in e) || !(e.bytes.buffer instanceof ArrayBuffer) ? [] : [e.bytes.buffer];
+}
+let S = 0;
+function w(r) {
+  const e = new Error("报表 Worker 任务已取消");
+  return e.name = "AbortError", Object.defineProperty(e, "cause", { value: r }), e;
+}
+function $(r, e) {
+  if (!r || typeof r != "object") return;
+  const t = r;
+  return t.protocol === u && t.id === e ? t : void 0;
+}
+function z(r, e = {}) {
+  const t = e.timeoutMs ?? 12e4;
+  if (!Number.isFinite(t) || t <= 0 || t > 2147483647) throw new RangeError("Worker timeoutMs 应为正有限数字，且不能超过 2147483647");
+  const o = (s, c, n) => n?.aborted ? Promise.reject(w(n.reason)) : new Promise((p, g) => {
+    let d;
+    try {
+      d = r();
+    } catch (i) {
+      g(i);
+      return;
+    }
+    const l = `mach-report-${Date.now()}-${++S}`;
+    let b = !1, y = () => {
+    }, E;
+    const f = (i, a) => {
+      b || (b = !0, E && clearTimeout(E), y(), n?.removeEventListener("abort", h), Promise.resolve().then(() => d.terminate()).then(
+        () => i === void 0 ? p(a) : g(i),
+        (W) => g(i ?? W)
+      ));
+    }, h = () => f(w(n?.reason)), k = (i) => {
+      const a = $(i, l);
+      a && (a.error && typeof a.error.name == "string" && typeof a.error.message == "string" ? f(new R(a.error)) : A(a.result, s) && (s !== "export" || "format" in a.result && "format" in c && a.result.format === c.format) ? f(void 0, a.result) : f(new Error("报表 Worker 返回无效响应")));
+    };
+    try {
+      if (y = d.subscribe(k, (i) => f(i ?? new Error("报表 Worker 执行失败"))), b) {
+        y();
+        return;
+      }
+      n?.addEventListener("abort", h, { once: !0 }), E = setTimeout(() => f(new R({ name: "ReportRuntimeError", code: "timeout", message: `报表 Worker 执行超过 ${t}ms` })), t), n?.aborted ? h() : d.postMessage({ protocol: u, id: l, operation: s, input: c });
+    } catch (i) {
+      f(i);
+    }
+  });
+  return { prepare: (s, c) => o("prepare", s, c), export: (s, c) => o("export", s, c) };
+}
+function F(r, e = {}) {
+  return z(() => {
+    const t = r();
+    return {
+      postMessage: (o) => t.postMessage(o),
+      terminate: () => t.terminate(),
+      subscribe: (o, s) => {
+        const c = (p) => o(p.data), n = (p) => s(p instanceof ErrorEvent ? new Error(p.message) : new Error("报表 Worker 消息无法解码"));
+        return t.addEventListener("message", c), t.addEventListener("error", n), t.addEventListener("messageerror", n), () => {
+          t.removeEventListener("message", c), t.removeEventListener("error", n), t.removeEventListener("messageerror", n);
+        };
+      }
+    };
+  }, e);
+}
+function I(r, e = globalThis) {
+  const t = (o) => {
+    O(o.data) && P(r, o.data).then((s) => e.postMessage(s, N(s)));
+  };
+  return e.addEventListener("message", t), () => e.removeEventListener("message", t);
+}
+export {
+  R as ReportWorkerError,
+  F as createBrowserReportExecutor,
+  I as serveReportWorker
+};

package/dist/xlsx/node.d.cts

@@ -0,0 +1,47 @@
+/// <reference types="node" />
+
+import { Writable } from 'node:stream';
+
+/**
+ * Commits each source row directly to ExcelJS WorkbookWriter. No RenderPlan, full row array,
+ * Workbook or Buffer is retained. Styles are column-scoped; shared strings are disabled.
+ * Destination is ended by the writer. An abort/error leaves a partial, unusable XLSX file.
+ */
+export declare function writeRowsToXlsx<Row extends object>(rows: AsyncIterable<Row> | Iterable<Row>, options: XlsxStreamOptions<Row>): Promise<XlsxStreamProgress>;
+
+export declare type XlsxRowValue = string | number | boolean | Date | null | undefined;
+
+export declare interface XlsxStreamColumn<Row> {
+    key: keyof Row & string;
+    header?: string;
+    width?: number;
+    numberFormat?: string;
+    value?: (row: Row, rowIndex: number) => XlsxRowValue;
+}
+
+declare interface XlsxStreamCommonOptions<Row> {
+    columns: readonly XlsxStreamColumn<Row>[];
+    sheetName?: string;
+    signal?: AbortSignal;
+    /** Data rows, excluding the header. Excel's hard limit is always enforced. */
+    maxRows?: number;
+    maxDurationMs?: number;
+    /** Yield/check downstream backpressure after each batch (default 256). */
+    batchSize?: number;
+    onProgress?: (progress: XlsxStreamProgress) => void;
+}
+
+export declare type XlsxStreamOptions<Row> = XlsxStreamCommonOptions<Row> & ({
+    stream: Writable;
+    filename?: never;
+} | {
+    filename: string;
+    stream?: never;
+});
+
+export declare interface XlsxStreamProgress {
+    rowsWritten: number;
+    elapsedMs: number;
+}
+
+export { }

package/dist/xlsx/node.d.ts

@@ -0,0 +1,47 @@
+/// <reference types="node" />
+
+import { Writable } from 'node:stream';
+
+/**
+ * Commits each source row directly to ExcelJS WorkbookWriter. No RenderPlan, full row array,
+ * Workbook or Buffer is retained. Styles are column-scoped; shared strings are disabled.
+ * Destination is ended by the writer. An abort/error leaves a partial, unusable XLSX file.
+ */
+export declare function writeRowsToXlsx<Row extends object>(rows: AsyncIterable<Row> | Iterable<Row>, options: XlsxStreamOptions<Row>): Promise<XlsxStreamProgress>;
+
+export declare type XlsxRowValue = string | number | boolean | Date | null | undefined;
+
+export declare interface XlsxStreamColumn<Row> {
+    key: keyof Row & string;
+    header?: string;
+    width?: number;
+    numberFormat?: string;
+    value?: (row: Row, rowIndex: number) => XlsxRowValue;
+}
+
+declare interface XlsxStreamCommonOptions<Row> {
+    columns: readonly XlsxStreamColumn<Row>[];
+    sheetName?: string;
+    signal?: AbortSignal;
+    /** Data rows, excluding the header. Excel's hard limit is always enforced. */
+    maxRows?: number;
+    maxDurationMs?: number;
+    /** Yield/check downstream backpressure after each batch (default 256). */
+    batchSize?: number;
+    onProgress?: (progress: XlsxStreamProgress) => void;
+}
+
+export declare type XlsxStreamOptions<Row> = XlsxStreamCommonOptions<Row> & ({
+    stream: Writable;
+    filename?: never;
+} | {
+    filename: string;
+    stream?: never;
+});
+
+export declare interface XlsxStreamProgress {
+    rowsWritten: number;
+    elapsedMs: number;
+}
+
+export { }