@agile-team/mach-report 2.4.1 → 2.6.1

package/dist/server.d.ts

@@ -0,0 +1,643 @@
+/**
+ * 列值格式化（声明式、JSON 可序列化）。
+ * 在 paginate 的 cellText 出口统一消费：格式化发生在进 RenderPlan 之前，
+ * 三后端（DOM/Canvas/PDF）零改动。
+ *
+ * 语义约定（v0.9 固化）：
+ * - number.digits 显式给出 → 精确保留（12.5 + digits:2 → "12.50"）
+ * - number.thousands 默认 false（千分位显式开启）
+ * - date 字符串按"本地时区的日历日"解析（YYYY-MM-DD / YYYY/MM/DD 直取年月日，
+ *   不经 Date 字符串构造——后者按 UTC 零点，负时区环境会少一天）
+ */
+declare type ColumnFormat = {
+    kind: "number";
+    thousands?: boolean;
+    digits?: number;
+} | {
+    kind: "percent";
+    digits?: number;
+} | {
+    kind: "date";
+    pattern?: string;
+};
+
+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;
+}
+
+/** 无 Vue、无 HTTP 框架的可选服务端外观；PDF/Excel 仅在对应 export 调用时加载。 */
+export declare function createReportRuntime(options: ReportRuntimeOptions): ReportRuntime;
+
+/** 有界、无重试的进程内任务队列；取消不会提前归还仍在执行的 CPU 任务并发槽位。 */
+export declare function createReportTaskQueue(options?: {
+    concurrency?: number;
+    maxQueued?: number;
+}): ReportTaskQueue;
+
+declare interface DatasetContract {
+    fields: readonly ReportFieldContract[];
+    rowKey?: string;
+}
+
+declare type DatasetRows = Record<string, Record<string, unknown>[]>;
+
+declare interface DatasetValidationOptions {
+    path?: string;
+    maxRows?: number;
+    maxCells?: number;
+    maxIssues?: number;
+}
+
+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;
+}
+
+/** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
+declare type ListAlignment = NonNullable<ComponentStyle["align"]> | "auto";
+
+declare interface ListColumn {
+    header: string;
+    field: string;
+    widthMm: number;
+    style?: ComponentStyle;
+    /** 内容对齐，优先于 style.align；数值字符串不会自动判为数字。 */
+    align?: ListAlignment;
+    /** 独立的表头对齐，不改变内容对齐。 */
+    headerAlign?: ComponentStyle["align"];
+    /** 独立的表头样式，优先于列表级表头样式。 */
+    headerStyle?: ComponentStyle;
+    /** 值格式化（声明式）：千分位/小数位、百分比、日期 pattern */
+    format?: ColumnFormat;
+    /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
+    rules?: StyleRule[];
+    /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
+    editable?: boolean;
+    /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
+    valueType?: GridCell["valueType"];
+    /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
+}
+
+declare interface ListComponent {
+    kind: "list";
+    id?: string;
+    /** 宽表标记用于连续 Excel；不改变低层列表的列宽和分页算法。 */
+    layout?: "page" | "wide";
+    /** 逻辑表名称，供 Excel Sheet 命名；不额外生成标题组件。 */
+    title?: string;
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    dataset: string;
+    /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
+    rowKey?: string;
+    revisionField?: string;
+    sourceTokenField?: string;
+    columns: ListColumn[];
+    fontSizePt?: number;
+    headerBold?: boolean;
+    rowHeightMm?: number;
+    paddingMm?: number;
+    headerEveryPage?: boolean;
+    headerBackgroundColor?: string;
+    /** 内容默认对齐，列配置可覆盖；低层模板缺省仍为 left。 */
+    align?: ListAlignment;
+    /** 表头默认对齐，列配置可覆盖。 */
+    headerAlign?: ComponentStyle["align"];
+    headerStyle?: ComponentStyle;
+    /** 可选多行合并表头；列宽按列表物理列对齐，供 Excel 业务模板复用。 */
+    headerGrid?: PlanGrid;
+    border?: boolean;
+    /** 分组小计（组头/组尾小计/组头防孤行） */
+    groupBy?: ListGroupBy;
+    /** 末尾总合计行（依赖 groupBy.subtotal 或显式 fields） */
+    grandTotal?: ListGrandTotal;
+}
+
+declare type ListGrandTotal = boolean | {
+    label?: string;
+    style?: ComponentStyle;
+    /** 合计列（缺省沿用 groupBy.subtotal） */
+    fields?: string[];
+};
+
+/** 分组小计配置（声明式，见 ListComponent.groupBy） */
+declare interface ListGroupBy {
+    /** 分组字段（值变化即切组） */
+    field: string;
+    /** 组头文案模板，{value} 占位（默认 "{value}"） */
+    headerTemplate?: string;
+    headerStyle?: ComponentStyle;
+    /** 需要小计的列字段（组尾输出合计行；数值列求和，其余输出首值/留空） */
+    subtotal?: string[];
+    subtotalStyle?: ComponentStyle;
+    subtotalLabel?: string;
+    /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
+    keepWithNext?: boolean;
+}
+
+declare interface PaginateOptions {
+    /** 每行额外占高（mm），压测专用钩子 */
+    mmPerRow?: number;
+    /** 文本测量器（默认启发式；浏览器端可注入 canvas 测量校准） */
+    measurer?: TextMeasurer;
+    /** 可选页数上限；在追加超限页前终止，避免先分配全部页面再检查。 */
+    maxPages?: number;
+}
+
+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;
+    };
+}
+
+export 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 ReportCellAddress {
+    pageIndex: number;
+    componentIndex: number;
+    rowIndex: number;
+    columnIndex: number;
+}
+
+declare interface ReportCellEdit {
+    address: ReportCellAddress;
+    table?: ReportCellTableIdentity;
+    source?: Readonly<ReportCellSource>;
+    previousValue: ReportCellValue;
+    previousText: string;
+    value: ReportCellValue;
+    text: string;
+}
+
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+declare interface ReportCellSource {
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+
+declare interface ReportCellTableIdentity {
+    id: string;
+    /** 逻辑表行索引；跨分页的同一行保持不变。 */
+    rowIndex: number;
+    role: PlanTableFragment["role"];
+    columnKey?: string;
+}
+
+declare type ReportCellValue = string | number | boolean | null;
+
+declare interface ReportDefinition {
+    /** 静态模板或宿主提供的异步模板加载器；动态模板默认每次重新读取，不缓存版本。 */
+    template: ReportTemplate | ReportTemplateLoader;
+    /** 静态数据；load 存在时优先使用 load 的结果。 */
+    datasets?: DatasetRows;
+    load?: (context: ReportLoadContext) => DatasetRows | Promise<DatasetRows>;
+    /** 可选统一适配器；load 存在时仍优先 load，兼容已有定义。 */
+    provider?: ReportProvider;
+    /** 可选业务数据契约；声明的数据集缺失或字段不合法时，在分页前给出结构化错误。 */
+    dataSchema?: Record<string, DatasetContract>;
+    dataValidation?: Pick<DatasetValidationOptions, "maxRows" | "maxCells" | "maxIssues">;
+    /** 覆盖模板参数定义；动态模板应在此声明查询面板元数据，避免查询前先请求模板。 */
+    params?: ReportParamDef[];
+    pagination?: PaginateOptions;
+}
+
+export 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 ReportFieldContract {
+    field: string;
+    label?: string;
+    type: "text" | "number" | "boolean" | "date" | "decimal";
+    required?: boolean;
+    nullable?: boolean;
+    enum?: readonly (string | number | boolean)[];
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
+    unit?: string;
+}
+
+/** 取数与排版共同使用的请求上下文；取消只影响本次调用。 */
+declare interface ReportLoadContext {
+    reportId: string;
+    params: Record<string, string>;
+    signal?: AbortSignal;
+}
+
+/** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
+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[];
+}
+
+/** 查询是唯一基础能力；权限、HTTP、数据库和事务都留在宿主适配器内。 */
+declare interface ReportProvider {
+    query(context: ReportLoadContext): ReportQueryResult | Promise<ReportQueryResult>;
+    save?(input: ReportSaveInput): ReportSaveResult | Promise<ReportSaveResult>;
+    export?(input: ReportProviderExportInput): ReportProviderExportResult | Promise<ReportProviderExportResult>;
+    templates?: ReportTemplateProvider;
+}
+
+declare interface ReportProviderExportInput extends ReportLoadContext {
+    format: "pdf" | "xlsx";
+}
+
+declare interface ReportProviderExportResult {
+    bytes: Uint8Array;
+    contentType: string;
+    fileName?: string;
+    diagnostics?: ReportDiagnostic[];
+}
+
+declare interface ReportQueryResult {
+    datasets: DatasetRows;
+    revision?: string;
+    sourceToken?: string;
+    diagnostics?: ReportDiagnostic[];
+}
+
+declare type ReportRegistry = Record<string, ReportDefinition>;
+
+export declare interface ReportRuntime {
+    describe(reportIds?: string[]): ReportDescription[];
+    validate(input: Omit<ReportRuntimeInput, "signal">): ReportParamValidation;
+    prepare(input: ReportRuntimeInput): Promise<PreparedReport>;
+    export(input: ReportRuntimeExportInput): Promise<ReportRuntimeExportResult>;
+}
+
+export declare interface ReportRuntimeBudget {
+    maxRows?: number;
+    maxPages?: number;
+    maxCells?: number;
+    maxOutputBytes?: number;
+    maxDurationMs?: number;
+}
+
+export declare class ReportRuntimeError extends Error {
+    readonly code: "budget" | "timeout" | "queue-full" | "closed";
+    readonly path?: string | undefined;
+    constructor(code: "budget" | "timeout" | "queue-full" | "closed", message: string, path?: string | undefined);
+}
+
+/** 可用 worker_threads/进程/RPC 实现；接收可序列化请求，signal 由桥接层映射为取消消息。 */
+export declare interface ReportRuntimeExecutor {
+    prepare(input: Omit<ReportRuntimeInput, "signal">, signal?: AbortSignal): Promise<PreparedReport>;
+    export(input: Omit<ReportRuntimeExportInput, "signal">, signal?: AbortSignal): Promise<ReportRuntimeExportResult>;
+}
+
+export 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";
+    };
+}
+
+export declare interface ReportRuntimeExportResult extends Omit<PreparedReport, "plan"> {
+    bytes: Uint8Array;
+    format: "pdf" | "xlsx";
+    contentType: string;
+}
+
+export declare interface ReportRuntimeInput {
+    reportIds: string[];
+    params?: Record<string, string>;
+    signal?: AbortSignal;
+}
+
+export declare interface ReportRuntimeOptions {
+    reports: ReportRegistry;
+    budget?: ReportRuntimeBudget;
+    /** 各定义可覆盖默认分页配置；PDF自带字体时，自动使用字体字节度量以保持排版与输出一致。 */
+    pagination?: PaginateOptions;
+    executor?: ReportRuntimeExecutor;
+}
+
+export declare interface ReportRuntimeStats {
+    rows: number;
+    pages: number;
+    cells: number;
+    durationMs: number;
+    outputBytes?: number;
+}
+
+declare interface ReportSaveInput extends ReportLoadContext {
+    requestId: string;
+    expectedRevision?: string;
+    sourceToken?: string;
+    edits: readonly ReportCellEdit[];
+    action?: "edit" | "undo" | "redo" | "restore";
+}
+
+declare interface ReportSaveResult {
+    revision: string;
+    sourceToken?: string;
+    conflicts?: Array<{
+        editIndex: number;
+        code: string;
+        message: string;
+    }>;
+    diagnostics?: ReportDiagnostic[];
+}
+
+export declare interface ReportTask<T> {
+    readonly id: string;
+    readonly status: ReportTaskStatus;
+    readonly progress: {
+        completed: number;
+        total?: number;
+    } | undefined;
+    result: Promise<T>;
+    cancel(reason?: unknown): void;
+}
+
+export declare interface ReportTaskContext {
+    signal: AbortSignal;
+    reportProgress(completed: number, total?: number): void;
+}
+
+export declare interface ReportTaskQueue {
+    readonly active: number;
+    readonly pending: number;
+    enqueue<T>(run: (context: ReportTaskContext) => T | Promise<T>, options?: {
+        id?: string;
+        signal?: AbortSignal;
+    }): ReportTask<T>;
+    /** 关闭后拒绝新任务并取消排队任务；运行任务按参数发送取消信号。 */
+    close(options?: {
+        cancelRunning?: boolean;
+    }): void;
+}
+
+export declare type ReportTaskStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+
+declare interface ReportTemplate {
+    schemaVersion?: string;
+    /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
+    params?: ReportParamDef[];
+    pages: TemplatePage[];
+}
+
+/** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
+declare interface ReportTemplateDocument {
+    schemaVersion: "1.0";
+    id: string;
+    name: string;
+    /** 宿主的发布版本/乐观锁标识，不由引擎自动递增。 */
+    revision?: string;
+    description?: string;
+    template: ReportTemplate;
+}
+
+declare type ReportTemplateLoader = (context: ReportLoadContext) => ReportTemplate | Promise<ReportTemplate>;
+
+declare interface ReportTemplateProvider {
+    list(context: {
+        signal?: AbortSignal;
+    }): Promise<ReportTemplateSummary[]>;
+    get(id: string, context: {
+        signal?: AbortSignal;
+    }): Promise<ReportTemplateDocument | undefined>;
+}
+
+declare type ReportTemplateSummary = Omit<ReportTemplateDocument, "template">;
+
+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;
+}
+
+/** 条件格式规则求值（声明式，见 ListColumn.rules） */
+declare interface StyleRule {
+    when: {
+        field: string;
+        op: ">" | ">=" | "<" | "<=" | "==" | "!=";
+        value: number | string;
+    };
+    /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
+    style: Record<string, unknown>;
+}
+
+declare type TemplateComponent = PlanComponent | ListComponent;
+
+declare interface TemplatePage {
+    widthMm: number;
+    heightMm: number;
+    /** 宽表保持全列自然宽度，页高只控制内部纵向分段。 */
+    layout?: "page" | "wide";
+    marginTopMm?: number;
+    marginBottomMm?: number;
+    marginLeftMm?: number;
+    marginRightMm?: number;
+    components: TemplateComponent[];
+}
+
+/**
+ * 文本测量与折行（分页/Canvas/PDF 共用的唯一折行真相源）。
+ *
+ * 测量模型可注入（TextMeasurer）：
+ * - 默认 createHeuristicMeasurer()：CJK/拉丁宽度启发式（零依赖、Node 可用）
+ * - 浏览器端可注入 createCanvasMeasurer()（真字体 metrics，消除三端折行差异）
+ */
+declare interface TextMeasureOptions {
+    fontSizePt: number;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    letterSpacingPt?: number;
+}
+
+/** 宽度测量接口：返回文本在给定字号下的宽度（mm）。实现必须无副作用、可缓存。 */
+declare interface TextMeasurer {
+    measureMm(text: string, options: TextMeasureOptions): number;
+}
+
+export { }