@agile-team/mach-report 2.21.0 → 2.22.0

package/dist/designer.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});require("vue");const E=require("./designer-CDqok4S5.cjs");exports.COLUMN_VISUAL_MESSAGES=E.COLUMN_VISUAL_MESSAGES;exports.ChartBindingInspector=E.ChartBindingInspector;exports.ColumnVisualEditor=E.ColumnVisualEditor;exports.DESIGNER_GUIDE_MESSAGES=E.DESIGNER_GUIDE_MESSAGES;exports.EXCEL_BINDING_MESSAGES=E.EXCEL_BINDING_MESSAGES;exports.ExcelBindingWizard=E.ExcelBindingWizard;exports.LABEL_STUDIO_MESSAGES=E.LABEL_STUDIO_MESSAGES;exports.PARAM_EDITOR_MESSAGES=E.PARAM_EDITOR_MESSAGES;exports.ParamEditor=E.ParamEditor;exports.REPORT_BATCH_MESSAGES=E.REPORT_BATCH_MESSAGES;exports.RULE_EDITOR_MESSAGES=E.DEFAULT_RULE_EDITOR_MESSAGES;exports.ReportBatchPanel=E.ReportBatchPanel;exports.ReportLabelStudio=E.ReportLabelStudio;exports.ReportTemplateEditor=E.ReportTemplateEditor;exports.ReportTemplateLibrary=E.ReportTemplateLibrary;exports.RuleEditor=E.RuleEditor;exports.TEMPLATE_EDITOR_MESSAGES=E.TEMPLATE_EDITOR_MESSAGES;exports.TEMPLATE_LIBRARY_MESSAGES=E.TEMPLATE_LIBRARY_MESSAGES;exports.TEMPLATE_PRODUCT_MESSAGES=E.TEMPLATE_PRODUCT_MESSAGES;exports.TEMPLATE_RECOVERY_MESSAGES=E.TEMPLATE_RECOVERY_MESSAGES;exports.TEMPLATE_REVIEW_MESSAGES=E.TEMPLATE_REVIEW_MESSAGES;exports.TemplateOutlinePanel=E.TemplateOutlinePanel;exports.TemplateReusePanel=E.TemplateReusePanel;exports.TemplateReviewPanel=E.TemplateReviewPanel;exports.createTemplateDraftStorage=E.createTemplateDraftStorage;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});require("vue");const E=require("./designer-BWQVpJeN.cjs");exports.COLUMN_VISUAL_MESSAGES=E.COLUMN_VISUAL_MESSAGES;exports.ChartBindingInspector=E.ChartBindingInspector;exports.ColumnVisualEditor=E.ColumnVisualEditor;exports.DESIGNER_GUIDE_MESSAGES=E.DESIGNER_GUIDE_MESSAGES;exports.EXCEL_BINDING_MESSAGES=E.EXCEL_BINDING_MESSAGES;exports.ExcelBindingWizard=E.ExcelBindingWizard;exports.LABEL_STUDIO_MESSAGES=E.LABEL_STUDIO_MESSAGES;exports.PARAM_EDITOR_MESSAGES=E.PARAM_EDITOR_MESSAGES;exports.ParamEditor=E.ParamEditor;exports.REPORT_BATCH_MESSAGES=E.REPORT_BATCH_MESSAGES;exports.RULE_EDITOR_MESSAGES=E.DEFAULT_RULE_EDITOR_MESSAGES;exports.ReportBatchPanel=E.ReportBatchPanel;exports.ReportLabelStudio=E.ReportLabelStudio;exports.ReportTemplateEditor=E.ReportTemplateEditor;exports.ReportTemplateLibrary=E.ReportTemplateLibrary;exports.RuleEditor=E.RuleEditor;exports.TEMPLATE_EDITOR_MESSAGES=E.TEMPLATE_EDITOR_MESSAGES;exports.TEMPLATE_LIBRARY_MESSAGES=E.TEMPLATE_LIBRARY_MESSAGES;exports.TEMPLATE_PRODUCT_MESSAGES=E.TEMPLATE_PRODUCT_MESSAGES;exports.TEMPLATE_RECOVERY_MESSAGES=E.TEMPLATE_RECOVERY_MESSAGES;exports.TEMPLATE_REVIEW_MESSAGES=E.TEMPLATE_REVIEW_MESSAGES;exports.TemplateOutlinePanel=E.TemplateOutlinePanel;exports.TemplateReusePanel=E.TemplateReusePanel;exports.TemplateReviewPanel=E.TemplateReviewPanel;exports.createTemplateDraftStorage=E.createTemplateDraftStorage;exports.useTemplateWorkbench=E.useTemplateWorkbench;

package/dist/designer.d.cts

@@ -1,6 +1,8 @@
 import { ComponentOptionsMixin } from 'vue';
 import { ComputedRef } from 'vue';
 import { DefineComponent } from 'vue';
+import { Ref } from 'vue';
+import { ShallowRef } from 'vue';
 declare type __VLS_Props = {
     modelValue?: ColumnVisual_2;
     fields?: ReadonlyArray<{
@@ -1040,6 +1042,10 @@ export declare interface LabelStudioBrand {
 export declare interface LabelStudioController {
     readonly busy?: boolean;
     readonly pendingLocalChanges?: boolean;
+    readonly mode: "preview" | "design";
+    readonly canPrint: boolean;
+    preview(): Promise<boolean>;
+    print(): Promise<void>;
     guardChanges(): Promise<boolean>;
     prepare(): Promise<ReportTemplateDocument | undefined>;
 }
@@ -1058,6 +1064,8 @@ export declare interface LabelStudioOptions extends LabelStudioLayout {
     schema: DatasetContract;
     title?: string;
     identityField?: string;
+    /** Optional business provenance retained by generated label templates for safe reuse. */
+    dataContract?: ReportTemplate["dataContract"];
     modelValue?: ReportTemplateDocument;
     preview?: TemplateEditorOptions["preview"];
     save?: TemplateEditorOptions["save"];
@@ -1440,6 +1448,7 @@ declare interface MachReportDefaults {
     toolbar?: MachReportToolbarOptions;
     interaction?: ReportInteractionOptions;
     preferences?: ReportPreferencesOptions;
+    refresh?: ReportRefreshOptions;
     /** Protect local input and drafts before replacing a report. Default true. */
     guardChanges?: boolean;
     beforeDiscard?: ReportBeforeDiscard;
@@ -1478,6 +1487,7 @@ declare type MachReportLogger = Pick<Console, "warn" | "info">;
  */
 /** 工具栏与状态文案（默认简体中文；出海场景覆写） */
 declare interface MachReportMessages extends Partial<ReportCalculationMessages>, Partial<ReportDataReviewMessages>, ReportPrintMessages, ReportParamOptionsMessages {
+    previousSnapshot?: string;
     reviewTools?: string;
     validationTitle?: string;
     validationError?: string;
@@ -1664,6 +1674,7 @@ declare interface MachReportMessages extends Partial<ReportCalculationMessages>,
  */
 /** 工具栏与状态文案（默认简体中文；出海场景覆写） */
 declare interface MachReportMessages_2 extends Partial<ReportCalculationMessages_2>, Partial<ReportDataReviewMessages_2>, ReportPrintMessages_2, ReportParamOptionsMessages_2 {
+    previousSnapshot?: string;
     reviewTools?: string;
     validationTitle?: string;
     validationError?: string;
@@ -1865,6 +1876,8 @@ declare interface MachReportTheme {
     btnActiveBg: string;
 }
 declare interface MachReportToolbarOptions {
+    /** Reasons explain host restrictions without granting capabilities. */
+    unavailableReasons?: Partial<Record<ReportPreviewTool, string>>;
     search?: boolean;
     thumbnails?: boolean;
     zoom?: boolean;
@@ -3212,6 +3225,7 @@ declare type ReportExpressionOperation_2 = "add" | "subtract" | "multiply" | "di
 declare type ReportExpressionOperation_3 = "add" | "subtract" | "multiply" | "divide" | "coalesce" | "if" | "round" | "abs" | "concat" | "trim" | "upper" | "lower" | "dateYear" | "dateMonth" | "dateDay";
 declare type ReportFieldAggregation = "sum" | "avg" | "min" | "max" | "count" | "none";
 declare type ReportFieldAggregation_2 = "sum" | "avg" | "min" | "max" | "count" | "none";
+declare type ReportFieldAggregation_3 = "sum" | "avg" | "min" | "max" | "count" | "none";
 declare interface ReportFieldCalculation {
     /** Business-owned explanation, never executable JavaScript or an inferred business formula. */
     description: string;
@@ -3222,6 +3236,11 @@ declare interface ReportFieldCalculation_2 {
     description: string;
     dependsOn: readonly string[];
 }
+declare interface ReportFieldCalculation_3 {
+    /** Business-owned explanation, never executable JavaScript or an inferred business formula. */
+    description: string;
+    dependsOn: readonly string[];
+}
 declare interface ReportFieldContract extends ReportFieldSemantics {
     field: string;
     label?: string;
@@ -3250,6 +3269,20 @@ declare interface ReportFieldContract_2 extends ReportFieldSemantics_2 {
     semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
     unit?: string;
 }
+declare interface ReportFieldContract_3 extends ReportFieldSemantics_3 {
+    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 ReportFieldSemantics {
     description?: string;
     /** Explicit meaning of null/missing; does not convert blanks into zero. */
@@ -3270,6 +3303,16 @@ declare interface ReportFieldSemantics_2 {
     format?: ColumnFormat_2;
     calculation?: ReportFieldCalculation_2;
 }
+declare interface ReportFieldSemantics_3 {
+    description?: string;
+    /** Explicit meaning of null/missing; does not convert blanks into zero. */
+    missingMeaning?: string;
+    /** Recommended aggregation; none marks non-additive measures such as ratios. No aggregation runs implicitly. */
+    aggregation?: ReportFieldAggregation_3;
+    /** Shared presentation only; raw values and calculation precision remain unchanged. */
+    format?: ColumnFormat_3;
+    calculation?: ReportFieldCalculation_3;
+}
 declare interface ReportFlowBand {
     /** Exact stable component IDs. Static components use nid, lists use id. */
     componentIds: string[];
@@ -3305,6 +3348,10 @@ declare interface ReportInteractionOptions {
 export declare const ReportLabelStudio: DefineComponent<LabelStudioOptions, {
     guardChanges: () => Promise<boolean>;
     prepare: () => Promise<ReportTemplateDocument_3 | undefined>;
+    preview: () => Promise<boolean>;
+    print: () => Promise<void>;
+    mode: "preview" | "design";
+    canPrint: boolean;
     busy: boolean;
     pendingLocalChanges: boolean;
 }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
@@ -3512,8 +3559,8 @@ declare type ReportPredicateScalar = string | number | boolean | null;
 declare type ReportPredicateScalar_2 = string | number | boolean | null;
 declare type ReportPredicateScalar_3 = string | number | boolean | null;
 declare interface ReportPreferencesAdapter {
-    load(key: string): Partial<ReportPreviewPreferences> | null | Promise<Partial<ReportPreviewPreferences> | null>;
-    save(key: string, value: Readonly<Partial<ReportPreviewPreferences>>): void | Promise<void>;
+    load(key: string): ReportStoredPreferences | null | Promise<ReportStoredPreferences | null>;
+    save(key: string, value: Readonly<ReportStoredPreferences>): void | Promise<void>;
     remove?(key: string): void | Promise<void>;
 }
 declare interface ReportPreferencesOptions {
@@ -3573,6 +3620,17 @@ declare interface ReportPrintOptions {
     /** Physical translation only; no scaling or mutation of the report data/plan. */
     calibration?: ReportPrintCalibration;
 }
+/** Explicit refresh policy. The key identifies template/layout revisions outside query parameters. */
+declare interface ReportRefreshOptions {
+    retainPrevious?: boolean;
+    key?: string;
+    /** Host API request preceding the preview reload. Blocks edits and output without discarding drafts. */
+    pending?: boolean;
+    /** The host retained an earlier snapshot after its own query failed or was cancelled. */
+    stale?: boolean;
+    /** Retry the host HTTP query when it owns the stale snapshot. The host updates its own state. */
+    retry?(): void | Promise<void>;
+}
 declare interface ReportRuntimeBudget {
     maxRows?: number;
     maxPages?: number;
@@ -3584,8 +3642,14 @@ declare interface ReportRuntimeBudget {
     maxPreparedBytes?: number;
     maxDurationMs?: number;
 }
+declare interface ReportStoredPreferences extends Partial<ReportPreviewPreferences> {
+    zoomMode?: "fit" | number;
+    wideZoomMode?: "fit" | number;
+}
 declare interface ReportTemplate {
     schemaVersion?: string;
+    /** Optional source identity and stable field meanings for safe stored-template reuse. */
+    dataContract?: ReportTemplateDataContract;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
     params?: ReportParamDef[];
     /** Fixed label pages repeat in record → copy → template-page order. */
@@ -3594,6 +3658,8 @@ declare interface ReportTemplate {
 }
 declare interface ReportTemplate_2 {
     schemaVersion?: string;
+    /** Optional source identity and stable field meanings for safe stored-template reuse. */
+    dataContract?: ReportTemplateDataContract_2;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
     params?: ReportParamDef_2[];
     /** Fixed label pages repeat in record → copy → template-page order. */
@@ -3602,6 +3668,8 @@ declare interface ReportTemplate_2 {
 }
 declare interface ReportTemplate_3 {
     schemaVersion?: string;
+    /** Optional source identity and stable field meanings for safe stored-template reuse. */
+    dataContract?: ReportTemplateDataContract_3;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
     params?: ReportParamDef_3[];
     /** Fixed label pages repeat in record → copy → template-page order. */
@@ -3646,6 +3714,27 @@ declare interface ReportTemplateCatalogQuery {
     limit?: number;
     signal?: AbortSignal;
 }
+declare interface ReportTemplateDataContract {
+    /** Host-owned report/domain identity, without a query date or tenant credentials. */
+    source?: string;
+    datasets: Readonly<Record<string, {
+        fields: readonly ReportTemplateFieldBinding[];
+    }>>;
+}
+declare interface ReportTemplateDataContract_2 {
+    /** Host-owned report/domain identity, without a query date or tenant credentials. */
+    source?: string;
+    datasets: Readonly<Record<string, {
+        fields: readonly ReportTemplateFieldBinding_2[];
+    }>>;
+}
+declare interface ReportTemplateDataContract_3 {
+    /** Host-owned report/domain identity, without a query date or tenant credentials. */
+    source?: string;
+    datasets: Readonly<Record<string, {
+        fields: readonly ReportTemplateFieldBinding_3[];
+    }>>;
+}
 /** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
 declare interface ReportTemplateDocument {
     schemaVersion: "1.0";
@@ -3706,6 +3795,30 @@ export declare const ReportTemplateEditor: DefineComponent<TemplateEditorOptions
     showSave: boolean;
     showModeSwitch: boolean;
 }>;
+/** Stable business meaning is independent of a column's position and editable caption. */
+declare interface ReportTemplateFieldBinding {
+    field: string;
+    label?: string;
+    semanticKey?: string;
+    type?: ReportFieldContract["type"];
+    unit?: string;
+}
+/** Stable business meaning is independent of a column's position and editable caption. */
+declare interface ReportTemplateFieldBinding_2 {
+    field: string;
+    label?: string;
+    semanticKey?: string;
+    type?: ReportFieldContract_2["type"];
+    unit?: string;
+}
+/** Stable business meaning is independent of a column's position and editable caption. */
+declare interface ReportTemplateFieldBinding_3 {
+    field: string;
+    label?: string;
+    semanticKey?: string;
+    type?: ReportFieldContract_3["type"];
+    unit?: string;
+}
 declare interface ReportTemplateFixture {
     name: string;
     datasets: DatasetRows;
@@ -4607,6 +4720,8 @@ export declare interface TemplateEditorOptions extends TemplateEditorConflictOpt
     datasets?: DatasetRows;
     dataSchemas?: Record<string, DatasetContract>;
     bindingDatasets?: ExcelBindingDataset[];
+    /** Adopt the host's declared field meaning only after an explicit Excel binding is accepted. */
+    bindingDataContract?: ReportTemplateDocument["template"]["dataContract"];
     /** Optional independently persisted Excel source and binding recipe. */
     bindingSession?: AnyExcelBindingSession;
     readonly?: boolean;
@@ -4740,6 +4855,18 @@ export declare interface TemplateToolDraft {
     value: string;
 }
 export declare type TemplateTotalsMessages = typeof TOTALS_MESSAGES;
+export declare interface TemplateWorkbenchOptions {
+    blocked?: () => boolean;
+    /** Return guards in the visible-first order, including mounted hidden workspaces. */
+    guards?: () => readonly (() => boolean | Promise<boolean>)[];
+    prepare?: () => ReportTemplateDocument | undefined | Promise<ReportTemplateDocument | undefined>;
+    apply?: (document: ReportTemplateDocument, context: TemplateWorkbenchTaskContext) => boolean | void | Promise<boolean | void>;
+    applied?: (document: ReportTemplateDocument) => void | Promise<void>;
+    onError?: (cause: unknown) => void;
+}
+export declare interface TemplateWorkbenchTaskContext {
+    signal: AbortSignal;
+}
 declare const TOTALS_MESSAGES: {
     title: string;
     field: string;
@@ -4820,12 +4947,28 @@ declare interface TreeTableOptions_3 {
     /** Bounded leaf-to-ancestor aggregate work; default one million. */
     maxAggregationVisits?: number;
 }
+/** Optional task orchestration shared by workbench shells, using their existing editor and manager. */
+export declare function useTemplateWorkbench(options: TemplateWorkbenchOptions): {
+    operating: Ref<boolean>;
+    busy: ComputedRef<boolean>;
+    error: ShallowRef<unknown, unknown>;
+    run: <T>(action: (context: TemplateWorkbenchTaskContext) => T | Promise<T>) => Promise<T | undefined>;
+    guardChanges: () => Promise<boolean>;
+    apply: () => Promise<boolean>;
+    dispose: () => void;
+};
 /** The same declarative formatting used by list columns, before any output backend. */
 declare type ValueFormat = ColumnFormat;
 /** The same declarative formatting used by list columns, before any output backend. */
 declare type ValueFormat_2 = ColumnFormat_2;
 /** The same declarative formatting used by list columns, before any output backend. */
 declare type ValueFormat_3 = ColumnFormat_3;
+/** 可序列化的附加工作表在编码前写入，浏览器与 Worker 共用同一声明。 */
+declare interface XlsxAdditionalSheet {
+    name: string;
+    rows: readonly (readonly (string | number | boolean | null)[])[];
+    columnWidths?: readonly number[];
+}
 declare type XlsxImageOptions = ImageMediaOptions;
 /**
  * RenderPlan → xlsx 导出（B 端第二出口，对齐家族 @agile-team/mach-table-xlsx 路线）：
@@ -4838,6 +4981,8 @@ declare type XlsxImageOptions = ImageMediaOptions;
 declare interface XlsxRenderOptions extends AssetRenderOptions, XlsxImageOptions {
     /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
     sheetName?: (sheetIndex: number) => string;
+    /** 可序列化命名，用于 Worker；未提供的项沿用默认名称。 */
+    sheetNames?: readonly string[];
     /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */
     sheetMode?: "auto" | "pages" | "continuous";
     /** 宽表或连续表默认 raw，其余默认 text；显式配置可覆盖默认值。 */
@@ -4846,6 +4991,8 @@ declare interface XlsxRenderOptions extends AssetRenderOptions, XlsxImageOptions
     maxDataBars?: number;
     /** 连续表默认不限制打印纸型；显式 A3/A4/A5 仅设置打印适配，不改变 Excel 列宽。 */
     paperSize?: "auto" | "a3" | "a4" | "a5";
+    /** 在最终编码前追加说明、审计等标量工作表，可直接交给 Worker。 */
+    additionalSheets?: readonly XlsxAdditionalSheet[];
 }
 export {};
 

package/dist/designer.d.ts

@@ -1,6 +1,8 @@
 import { ComponentOptionsMixin } from 'vue';
 import { ComputedRef } from 'vue';
 import { DefineComponent } from 'vue';
+import { Ref } from 'vue';
+import { ShallowRef } from 'vue';
 declare type __VLS_Props = {
     modelValue?: ColumnVisual_2;
     fields?: ReadonlyArray<{
@@ -1040,6 +1042,10 @@ export declare interface LabelStudioBrand {
 export declare interface LabelStudioController {
     readonly busy?: boolean;
     readonly pendingLocalChanges?: boolean;
+    readonly mode: "preview" | "design";
+    readonly canPrint: boolean;
+    preview(): Promise<boolean>;
+    print(): Promise<void>;
     guardChanges(): Promise<boolean>;
     prepare(): Promise<ReportTemplateDocument | undefined>;
 }
@@ -1058,6 +1064,8 @@ export declare interface LabelStudioOptions extends LabelStudioLayout {
     schema: DatasetContract;
     title?: string;
     identityField?: string;
+    /** Optional business provenance retained by generated label templates for safe reuse. */
+    dataContract?: ReportTemplate["dataContract"];
     modelValue?: ReportTemplateDocument;
     preview?: TemplateEditorOptions["preview"];
     save?: TemplateEditorOptions["save"];
@@ -1440,6 +1448,7 @@ declare interface MachReportDefaults {
     toolbar?: MachReportToolbarOptions;
     interaction?: ReportInteractionOptions;
     preferences?: ReportPreferencesOptions;
+    refresh?: ReportRefreshOptions;
     /** Protect local input and drafts before replacing a report. Default true. */
     guardChanges?: boolean;
     beforeDiscard?: ReportBeforeDiscard;
@@ -1478,6 +1487,7 @@ declare type MachReportLogger = Pick<Console, "warn" | "info">;
  */
 /** 工具栏与状态文案（默认简体中文；出海场景覆写） */
 declare interface MachReportMessages extends Partial<ReportCalculationMessages>, Partial<ReportDataReviewMessages>, ReportPrintMessages, ReportParamOptionsMessages {
+    previousSnapshot?: string;
     reviewTools?: string;
     validationTitle?: string;
     validationError?: string;
@@ -1664,6 +1674,7 @@ declare interface MachReportMessages extends Partial<ReportCalculationMessages>,
  */
 /** 工具栏与状态文案（默认简体中文；出海场景覆写） */
 declare interface MachReportMessages_2 extends Partial<ReportCalculationMessages_2>, Partial<ReportDataReviewMessages_2>, ReportPrintMessages_2, ReportParamOptionsMessages_2 {
+    previousSnapshot?: string;
     reviewTools?: string;
     validationTitle?: string;
     validationError?: string;
@@ -1865,6 +1876,8 @@ declare interface MachReportTheme {
     btnActiveBg: string;
 }
 declare interface MachReportToolbarOptions {
+    /** Reasons explain host restrictions without granting capabilities. */
+    unavailableReasons?: Partial<Record<ReportPreviewTool, string>>;
     search?: boolean;
     thumbnails?: boolean;
     zoom?: boolean;
@@ -3212,6 +3225,7 @@ declare type ReportExpressionOperation_2 = "add" | "subtract" | "multiply" | "di
 declare type ReportExpressionOperation_3 = "add" | "subtract" | "multiply" | "divide" | "coalesce" | "if" | "round" | "abs" | "concat" | "trim" | "upper" | "lower" | "dateYear" | "dateMonth" | "dateDay";
 declare type ReportFieldAggregation = "sum" | "avg" | "min" | "max" | "count" | "none";
 declare type ReportFieldAggregation_2 = "sum" | "avg" | "min" | "max" | "count" | "none";
+declare type ReportFieldAggregation_3 = "sum" | "avg" | "min" | "max" | "count" | "none";
 declare interface ReportFieldCalculation {
     /** Business-owned explanation, never executable JavaScript or an inferred business formula. */
     description: string;
@@ -3222,6 +3236,11 @@ declare interface ReportFieldCalculation_2 {
     description: string;
     dependsOn: readonly string[];
 }
+declare interface ReportFieldCalculation_3 {
+    /** Business-owned explanation, never executable JavaScript or an inferred business formula. */
+    description: string;
+    dependsOn: readonly string[];
+}
 declare interface ReportFieldContract extends ReportFieldSemantics {
     field: string;
     label?: string;
@@ -3250,6 +3269,20 @@ declare interface ReportFieldContract_2 extends ReportFieldSemantics_2 {
     semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
     unit?: string;
 }
+declare interface ReportFieldContract_3 extends ReportFieldSemantics_3 {
+    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 ReportFieldSemantics {
     description?: string;
     /** Explicit meaning of null/missing; does not convert blanks into zero. */
@@ -3270,6 +3303,16 @@ declare interface ReportFieldSemantics_2 {
     format?: ColumnFormat_2;
     calculation?: ReportFieldCalculation_2;
 }
+declare interface ReportFieldSemantics_3 {
+    description?: string;
+    /** Explicit meaning of null/missing; does not convert blanks into zero. */
+    missingMeaning?: string;
+    /** Recommended aggregation; none marks non-additive measures such as ratios. No aggregation runs implicitly. */
+    aggregation?: ReportFieldAggregation_3;
+    /** Shared presentation only; raw values and calculation precision remain unchanged. */
+    format?: ColumnFormat_3;
+    calculation?: ReportFieldCalculation_3;
+}
 declare interface ReportFlowBand {
     /** Exact stable component IDs. Static components use nid, lists use id. */
     componentIds: string[];
@@ -3305,6 +3348,10 @@ declare interface ReportInteractionOptions {
 export declare const ReportLabelStudio: DefineComponent<LabelStudioOptions, {
     guardChanges: () => Promise<boolean>;
     prepare: () => Promise<ReportTemplateDocument_3 | undefined>;
+    preview: () => Promise<boolean>;
+    print: () => Promise<void>;
+    mode: "preview" | "design";
+    canPrint: boolean;
     busy: boolean;
     pendingLocalChanges: boolean;
 }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
@@ -3512,8 +3559,8 @@ declare type ReportPredicateScalar = string | number | boolean | null;
 declare type ReportPredicateScalar_2 = string | number | boolean | null;
 declare type ReportPredicateScalar_3 = string | number | boolean | null;
 declare interface ReportPreferencesAdapter {
-    load(key: string): Partial<ReportPreviewPreferences> | null | Promise<Partial<ReportPreviewPreferences> | null>;
-    save(key: string, value: Readonly<Partial<ReportPreviewPreferences>>): void | Promise<void>;
+    load(key: string): ReportStoredPreferences | null | Promise<ReportStoredPreferences | null>;
+    save(key: string, value: Readonly<ReportStoredPreferences>): void | Promise<void>;
     remove?(key: string): void | Promise<void>;
 }
 declare interface ReportPreferencesOptions {
@@ -3573,6 +3620,17 @@ declare interface ReportPrintOptions {
     /** Physical translation only; no scaling or mutation of the report data/plan. */
     calibration?: ReportPrintCalibration;
 }
+/** Explicit refresh policy. The key identifies template/layout revisions outside query parameters. */
+declare interface ReportRefreshOptions {
+    retainPrevious?: boolean;
+    key?: string;
+    /** Host API request preceding the preview reload. Blocks edits and output without discarding drafts. */
+    pending?: boolean;
+    /** The host retained an earlier snapshot after its own query failed or was cancelled. */
+    stale?: boolean;
+    /** Retry the host HTTP query when it owns the stale snapshot. The host updates its own state. */
+    retry?(): void | Promise<void>;
+}
 declare interface ReportRuntimeBudget {
     maxRows?: number;
     maxPages?: number;
@@ -3584,8 +3642,14 @@ declare interface ReportRuntimeBudget {
     maxPreparedBytes?: number;
     maxDurationMs?: number;
 }
+declare interface ReportStoredPreferences extends Partial<ReportPreviewPreferences> {
+    zoomMode?: "fit" | number;
+    wideZoomMode?: "fit" | number;
+}
 declare interface ReportTemplate {
     schemaVersion?: string;
+    /** Optional source identity and stable field meanings for safe stored-template reuse. */
+    dataContract?: ReportTemplateDataContract;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
     params?: ReportParamDef[];
     /** Fixed label pages repeat in record → copy → template-page order. */
@@ -3594,6 +3658,8 @@ declare interface ReportTemplate {
 }
 declare interface ReportTemplate_2 {
     schemaVersion?: string;
+    /** Optional source identity and stable field meanings for safe stored-template reuse. */
+    dataContract?: ReportTemplateDataContract_2;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
     params?: ReportParamDef_2[];
     /** Fixed label pages repeat in record → copy → template-page order. */
@@ -3602,6 +3668,8 @@ declare interface ReportTemplate_2 {
 }
 declare interface ReportTemplate_3 {
     schemaVersion?: string;
+    /** Optional source identity and stable field meanings for safe stored-template reuse. */
+    dataContract?: ReportTemplateDataContract_3;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
     params?: ReportParamDef_3[];
     /** Fixed label pages repeat in record → copy → template-page order. */
@@ -3646,6 +3714,27 @@ declare interface ReportTemplateCatalogQuery {
     limit?: number;
     signal?: AbortSignal;
 }
+declare interface ReportTemplateDataContract {
+    /** Host-owned report/domain identity, without a query date or tenant credentials. */
+    source?: string;
+    datasets: Readonly<Record<string, {
+        fields: readonly ReportTemplateFieldBinding[];
+    }>>;
+}
+declare interface ReportTemplateDataContract_2 {
+    /** Host-owned report/domain identity, without a query date or tenant credentials. */
+    source?: string;
+    datasets: Readonly<Record<string, {
+        fields: readonly ReportTemplateFieldBinding_2[];
+    }>>;
+}
+declare interface ReportTemplateDataContract_3 {
+    /** Host-owned report/domain identity, without a query date or tenant credentials. */
+    source?: string;
+    datasets: Readonly<Record<string, {
+        fields: readonly ReportTemplateFieldBinding_3[];
+    }>>;
+}
 /** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
 declare interface ReportTemplateDocument {
     schemaVersion: "1.0";
@@ -3706,6 +3795,30 @@ export declare const ReportTemplateEditor: DefineComponent<TemplateEditorOptions
     showSave: boolean;
     showModeSwitch: boolean;
 }>;
+/** Stable business meaning is independent of a column's position and editable caption. */
+declare interface ReportTemplateFieldBinding {
+    field: string;
+    label?: string;
+    semanticKey?: string;
+    type?: ReportFieldContract["type"];
+    unit?: string;
+}
+/** Stable business meaning is independent of a column's position and editable caption. */
+declare interface ReportTemplateFieldBinding_2 {
+    field: string;
+    label?: string;
+    semanticKey?: string;
+    type?: ReportFieldContract_2["type"];
+    unit?: string;
+}
+/** Stable business meaning is independent of a column's position and editable caption. */
+declare interface ReportTemplateFieldBinding_3 {
+    field: string;
+    label?: string;
+    semanticKey?: string;
+    type?: ReportFieldContract_3["type"];
+    unit?: string;
+}
 declare interface ReportTemplateFixture {
     name: string;
     datasets: DatasetRows;
@@ -4607,6 +4720,8 @@ export declare interface TemplateEditorOptions extends TemplateEditorConflictOpt
     datasets?: DatasetRows;
     dataSchemas?: Record<string, DatasetContract>;
     bindingDatasets?: ExcelBindingDataset[];
+    /** Adopt the host's declared field meaning only after an explicit Excel binding is accepted. */
+    bindingDataContract?: ReportTemplateDocument["template"]["dataContract"];
     /** Optional independently persisted Excel source and binding recipe. */
     bindingSession?: AnyExcelBindingSession;
     readonly?: boolean;
@@ -4740,6 +4855,18 @@ export declare interface TemplateToolDraft {
     value: string;
 }
 export declare type TemplateTotalsMessages = typeof TOTALS_MESSAGES;
+export declare interface TemplateWorkbenchOptions {
+    blocked?: () => boolean;
+    /** Return guards in the visible-first order, including mounted hidden workspaces. */
+    guards?: () => readonly (() => boolean | Promise<boolean>)[];
+    prepare?: () => ReportTemplateDocument | undefined | Promise<ReportTemplateDocument | undefined>;
+    apply?: (document: ReportTemplateDocument, context: TemplateWorkbenchTaskContext) => boolean | void | Promise<boolean | void>;
+    applied?: (document: ReportTemplateDocument) => void | Promise<void>;
+    onError?: (cause: unknown) => void;
+}
+export declare interface TemplateWorkbenchTaskContext {
+    signal: AbortSignal;
+}
 declare const TOTALS_MESSAGES: {
     title: string;
     field: string;
@@ -4820,12 +4947,28 @@ declare interface TreeTableOptions_3 {
     /** Bounded leaf-to-ancestor aggregate work; default one million. */
     maxAggregationVisits?: number;
 }
+/** Optional task orchestration shared by workbench shells, using their existing editor and manager. */
+export declare function useTemplateWorkbench(options: TemplateWorkbenchOptions): {
+    operating: Ref<boolean>;
+    busy: ComputedRef<boolean>;
+    error: ShallowRef<unknown, unknown>;
+    run: <T>(action: (context: TemplateWorkbenchTaskContext) => T | Promise<T>) => Promise<T | undefined>;
+    guardChanges: () => Promise<boolean>;
+    apply: () => Promise<boolean>;
+    dispose: () => void;
+};
 /** The same declarative formatting used by list columns, before any output backend. */
 declare type ValueFormat = ColumnFormat;
 /** The same declarative formatting used by list columns, before any output backend. */
 declare type ValueFormat_2 = ColumnFormat_2;
 /** The same declarative formatting used by list columns, before any output backend. */
 declare type ValueFormat_3 = ColumnFormat_3;
+/** 可序列化的附加工作表在编码前写入，浏览器与 Worker 共用同一声明。 */
+declare interface XlsxAdditionalSheet {
+    name: string;
+    rows: readonly (readonly (string | number | boolean | null)[])[];
+    columnWidths?: readonly number[];
+}
 declare type XlsxImageOptions = ImageMediaOptions;
 /**
  * RenderPlan → xlsx 导出（B 端第二出口，对齐家族 @agile-team/mach-table-xlsx 路线）：
@@ -4838,6 +4981,8 @@ declare type XlsxImageOptions = ImageMediaOptions;
 declare interface XlsxRenderOptions extends AssetRenderOptions, XlsxImageOptions {
     /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
     sheetName?: (sheetIndex: number) => string;
+    /** 可序列化命名，用于 Worker；未提供的项沿用默认名称。 */
+    sheetNames?: readonly string[];
     /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */
     sheetMode?: "auto" | "pages" | "continuous";
     /** 宽表或连续表默认 raw，其余默认 text；显式配置可覆盖默认值。 */
@@ -4846,6 +4991,8 @@ declare interface XlsxRenderOptions extends AssetRenderOptions, XlsxImageOptions
     maxDataBars?: number;
     /** 连续表默认不限制打印纸型；显式 A3/A4/A5 仅设置打印适配，不改变 Excel 列宽。 */
     paperSize?: "auto" | "a3" | "a4" | "a5";
+    /** 在最终编码前追加说明、审计等标量工作表，可直接交给 Worker。 */
+    additionalSheets?: readonly XlsxAdditionalSheet[];
 }
 export {};