@agile-team/mach-report 2.5.0 → 2.7.0

package/dist/xlsx.d.cts

@@ -53,6 +53,9 @@ declare type AutoFilter = string | {
     	to: string | { row: number; column: number };
 };
 
+/** 将明确声明的 Excel 表区域变成可反复取数的业务模板；不保留样例明细值，不猜接口。 */
+export declare function bindExcelTemplate(imported: ExcelImportResult, bindings: readonly ExcelTableBinding[]): ExcelTemplateBindingResult;
+
 declare interface Border {
     	style: BorderStyle;
     	color: Partial<Color>;
@@ -563,6 +566,10 @@ declare enum ErrorValue {
     	Num = '#NUM!',
 }
 
+export declare type ExcelBindingColumn = string | (Omit<ListColumn, "widthMm" | "header"> & {
+    header?: string;
+});
+
 export declare interface ExcelImportedSheet {
     name: string;
     /** Original, one-based workbook position. */
@@ -591,7 +598,7 @@ export declare interface ExcelImportLimits {
     maxSheets?: number;
 }
 
-export declare interface ExcelImportOptions {
+export declare interface ExcelImportOptions extends OutputTaskOptions {
     /** Sheet names or one-based workbook positions. Default: all visible sheets. */
     sheets?: Array<string | number>;
     /** A1 range for every sheet, or ranges keyed by exact sheet name. */
@@ -738,6 +745,26 @@ declare namespace ExcelJS {
     }
 }
 
+export declare interface ExcelTableBinding {
+    sheet: string;
+    dataset?: string;
+    /** 完整列宽的表头范围，允许多行合并。 */
+    header: string;
+    /** 将整个样例明细区域替换为动态数据；缺省为表头下方全部行。 */
+    detail?: string;
+    columns: readonly ExcelBindingColumn[];
+    rowKey?: string;
+    revisionField?: string;
+    sourceTokenField?: string;
+    groupBy?: ListComponent["groupBy"];
+    grandTotal?: ListComponent["grandTotal"];
+}
+
+export declare interface ExcelTemplateBindingResult {
+    template: ReportTemplate;
+    warnings: string[];
+}
+
 declare interface ExpressionRuleType extends ConditionalFormattingBaseRule {
     	type: 'expression';
     	formulae?: any[];
@@ -866,6 +893,7 @@ declare interface GridCell {
     valueType?: "text" | "number" | "boolean";
     /** 单元格级编辑控制；预览仍需显式开启 editing。 */
     editable?: boolean;
+    source?: ReportCellSource;
     /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
     formula?: string;
     children?: PlanComponent[];
@@ -998,6 +1026,8 @@ declare interface ListColumn {
     editable?: boolean;
     /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
     valueType?: GridCell["valueType"];
+    /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
 }
 
 declare interface ListComponent {
@@ -1011,6 +1041,10 @@ declare interface ListComponent {
     topMm: number;
     widthMm: number;
     dataset: string;
+    /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
+    rowKey?: string;
+    revisionField?: string;
+    sourceTokenField?: string;
     columns: ListColumn[];
     fontSizePt?: number;
     headerBold?: boolean;
@@ -1023,6 +1057,8 @@ declare interface ListComponent {
     /** 表头默认对齐，列配置可覆盖。 */
     headerAlign?: ComponentStyle["align"];
     headerStyle?: ComponentStyle;
+    /** 可选多行合并表头；列宽按列表物理列对齐，供 Excel 业务模板复用。 */
+    headerGrid?: PlanGrid;
     border?: boolean;
     /** 分组小计（组头/组尾小计/组头防孤行） */
     groupBy?: ListGroupBy;
@@ -1075,6 +1111,34 @@ declare interface Media {
     	buffer: Buffer_2;
 }
 
+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 interface OutputDiagnosticOptions extends OutputTaskOptions {
+    /** Structured fidelity diagnostics; rendering never silently invents missing content. */
+    onDiagnostic?: (diagnostic: OutputDiagnostic) => void;
+    /** Reject known unsupported content before creating an incomplete file. Default warn. */
+    fidelity?: "warn" | "strict";
+}
+
+declare type OutputFormat = "dom" | "canvas" | "pdf" | "xlsx";
+
+/** Stage counts are exact completed units; encoding libraries may remain indeterminate. */
+declare interface OutputTaskOptions {
+    signal?: AbortSignal;
+    onProgress?: (completed: number, total: number) => void;
+}
+
 declare interface PageSetup {
     	/**
      	 * Whitespace on the borders of the page. Units are inches.
@@ -1252,6 +1316,8 @@ declare interface PlanComponent {
     lines?: string[];
     richParagraphs?: RichParagraph[];
     imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
     grid?: PlanGrid;
     table?: PlanTableFragment;
     style?: ComponentStyle;
@@ -1293,6 +1359,10 @@ declare interface PlanTableFragment {
     columnKeys: string[];
     layout?: "page" | "wide";
     title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
 }
 
 declare interface Protection {
@@ -1376,6 +1446,15 @@ declare interface RenderPlan {
 
 export declare function renderPlanToXlsx(plan: RenderPlan, options?: XlsxRenderOptions): Promise<XlsxRenderResult>;
 
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+declare interface ReportCellSource {
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 declare interface ReportParamDef {
     /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
@@ -1391,6 +1470,11 @@ declare interface ReportParamDef {
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
+    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
+    min?: number | string;
+    max?: number | string;
+    minLength?: number;
+    maxLength?: number;
 }
 
 declare interface ReportTemplate {
@@ -2502,7 +2586,7 @@ declare interface XlsxReadOptions {
  *   目标是"财务能直接用的对账表"而非复刻版面）
  * - 未支持组件、富文本专有内容与单元格嵌套组件跳过并计入 warnings
  */
-export declare interface XlsxRenderOptions {
+export declare interface XlsxRenderOptions extends OutputDiagnosticOptions {
     /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
     sheetName?: (sheetIndex: number) => string;
     /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */
@@ -2517,6 +2601,7 @@ export declare interface XlsxRenderResult {
     workbook: ExcelJS.Workbook;
     buffer: ExcelJS.Buffer;
     warnings: string[];
+    diagnostics?: OutputDiagnostic[];
 }
 
 declare interface XlsxWriteOptions extends stream.xlsx.WorkbookWriterOptions {

package/dist/xlsx.d.ts

@@ -53,6 +53,9 @@ declare type AutoFilter = string | {
     	to: string | { row: number; column: number };
 };
 
+/** 将明确声明的 Excel 表区域变成可反复取数的业务模板；不保留样例明细值，不猜接口。 */
+export declare function bindExcelTemplate(imported: ExcelImportResult, bindings: readonly ExcelTableBinding[]): ExcelTemplateBindingResult;
+
 declare interface Border {
     	style: BorderStyle;
     	color: Partial<Color>;
@@ -563,6 +566,10 @@ declare enum ErrorValue {
     	Num = '#NUM!',
 }
 
+export declare type ExcelBindingColumn = string | (Omit<ListColumn, "widthMm" | "header"> & {
+    header?: string;
+});
+
 export declare interface ExcelImportedSheet {
     name: string;
     /** Original, one-based workbook position. */
@@ -591,7 +598,7 @@ export declare interface ExcelImportLimits {
     maxSheets?: number;
 }
 
-export declare interface ExcelImportOptions {
+export declare interface ExcelImportOptions extends OutputTaskOptions {
     /** Sheet names or one-based workbook positions. Default: all visible sheets. */
     sheets?: Array<string | number>;
     /** A1 range for every sheet, or ranges keyed by exact sheet name. */
@@ -738,6 +745,26 @@ declare namespace ExcelJS {
     }
 }
 
+export declare interface ExcelTableBinding {
+    sheet: string;
+    dataset?: string;
+    /** 完整列宽的表头范围，允许多行合并。 */
+    header: string;
+    /** 将整个样例明细区域替换为动态数据；缺省为表头下方全部行。 */
+    detail?: string;
+    columns: readonly ExcelBindingColumn[];
+    rowKey?: string;
+    revisionField?: string;
+    sourceTokenField?: string;
+    groupBy?: ListComponent["groupBy"];
+    grandTotal?: ListComponent["grandTotal"];
+}
+
+export declare interface ExcelTemplateBindingResult {
+    template: ReportTemplate;
+    warnings: string[];
+}
+
 declare interface ExpressionRuleType extends ConditionalFormattingBaseRule {
     	type: 'expression';
     	formulae?: any[];
@@ -866,6 +893,7 @@ declare interface GridCell {
     valueType?: "text" | "number" | "boolean";
     /** 单元格级编辑控制；预览仍需显式开启 editing。 */
     editable?: boolean;
+    source?: ReportCellSource;
     /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
     formula?: string;
     children?: PlanComponent[];
@@ -998,6 +1026,8 @@ declare interface ListColumn {
     editable?: boolean;
     /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
     valueType?: GridCell["valueType"];
+    /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
 }
 
 declare interface ListComponent {
@@ -1011,6 +1041,10 @@ declare interface ListComponent {
     topMm: number;
     widthMm: number;
     dataset: string;
+    /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
+    rowKey?: string;
+    revisionField?: string;
+    sourceTokenField?: string;
     columns: ListColumn[];
     fontSizePt?: number;
     headerBold?: boolean;
@@ -1023,6 +1057,8 @@ declare interface ListComponent {
     /** 表头默认对齐，列配置可覆盖。 */
     headerAlign?: ComponentStyle["align"];
     headerStyle?: ComponentStyle;
+    /** 可选多行合并表头；列宽按列表物理列对齐，供 Excel 业务模板复用。 */
+    headerGrid?: PlanGrid;
     border?: boolean;
     /** 分组小计（组头/组尾小计/组头防孤行） */
     groupBy?: ListGroupBy;
@@ -1075,6 +1111,34 @@ declare interface Media {
     	buffer: Buffer_2;
 }
 
+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 interface OutputDiagnosticOptions extends OutputTaskOptions {
+    /** Structured fidelity diagnostics; rendering never silently invents missing content. */
+    onDiagnostic?: (diagnostic: OutputDiagnostic) => void;
+    /** Reject known unsupported content before creating an incomplete file. Default warn. */
+    fidelity?: "warn" | "strict";
+}
+
+declare type OutputFormat = "dom" | "canvas" | "pdf" | "xlsx";
+
+/** Stage counts are exact completed units; encoding libraries may remain indeterminate. */
+declare interface OutputTaskOptions {
+    signal?: AbortSignal;
+    onProgress?: (completed: number, total: number) => void;
+}
+
 declare interface PageSetup {
     	/**
      	 * Whitespace on the borders of the page. Units are inches.
@@ -1252,6 +1316,8 @@ declare interface PlanComponent {
     lines?: string[];
     richParagraphs?: RichParagraph[];
     imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
     grid?: PlanGrid;
     table?: PlanTableFragment;
     style?: ComponentStyle;
@@ -1293,6 +1359,10 @@ declare interface PlanTableFragment {
     columnKeys: string[];
     layout?: "page" | "wide";
     title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
 }
 
 declare interface Protection {
@@ -1376,6 +1446,15 @@ declare interface RenderPlan {
 
 export declare function renderPlanToXlsx(plan: RenderPlan, options?: XlsxRenderOptions): Promise<XlsxRenderResult>;
 
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+declare interface ReportCellSource {
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 declare interface ReportParamDef {
     /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
@@ -1391,6 +1470,11 @@ declare interface ReportParamDef {
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
+    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
+    min?: number | string;
+    max?: number | string;
+    minLength?: number;
+    maxLength?: number;
 }
 
 declare interface ReportTemplate {
@@ -2502,7 +2586,7 @@ declare interface XlsxReadOptions {
  *   目标是"财务能直接用的对账表"而非复刻版面）
  * - 未支持组件、富文本专有内容与单元格嵌套组件跳过并计入 warnings
  */
-export declare interface XlsxRenderOptions {
+export declare interface XlsxRenderOptions extends OutputDiagnosticOptions {
     /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
     sheetName?: (sheetIndex: number) => string;
     /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */
@@ -2517,6 +2601,7 @@ export declare interface XlsxRenderResult {
     workbook: ExcelJS.Workbook;
     buffer: ExcelJS.Buffer;
     warnings: string[];
+    diagnostics?: OutputDiagnostic[];
 }
 
 declare interface XlsxWriteOptions extends stream.xlsx.WorkbookWriterOptions {