@agile-team/mach-report 2.12.0 → 2.14.0

package/dist/worker.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const x=require("./task-events-DQ276fn2.cjs"),A=require("./validate-BJ5HIWY8.cjs"),u="mach-report-worker/1";class l extends Error{constructor(r){super(r.message),this.name=r.name,this.code=r.code,this.path=r.path,this.issues=r.issues,this.diagnostics=r.diagnostics}}function p(e){return!!e&&typeof e=="object"&&!Array.isArray(e)}function L(e){return p(e)?["rows","pages","cells"].every(r=>typeof e[r]=="number"&&Number.isSafeInteger(e[r])&&e[r]>=0)&&typeof e.durationMs=="number"&&Number.isFinite(e.durationMs)&&e.durationMs>=0:!1}function P(e){return Array.isArray(e)&&e.every(r=>p(r)&&typeof r.code=="string"&&typeof r.message=="string"&&["info","warning","error"].includes(r.severity))}function T(e){return p(e)&&Object.values(e).every(r=>p(r)&&(r.revision===void 0||typeof r.revision=="string")&&(r.sourceToken===void 0||typeof r.sourceToken=="string"))}function v(e,r){if(!p(e)||!L(e.stats)||!P(e.diagnostics)||!T(e.revisions))return!1;if(r==="prepare")return A.validateRenderPlan(e.plan).ok;const t=e.format==="pdf"?"application/pdf":"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";return e.bytes instanceof Uint8Array&&(e.format==="pdf"||e.format==="xlsx")&&e.contentType===t}function W(e){if(!e||typeof e!="object")return{message:String(e)};const r={};for(const t of["code","path","field","message"]){const o=e[t];typeof o=="string"&&(r[t]=o)}return r}function j(e){const r=W(e);if(!p(e))return r;for(const t of["format","severity","kind","nid"])typeof e[t]=="string"&&(r[t]=e[t]);for(const t of["pageIndex","componentIndex"])Number.isSafeInteger(e[t])&&e[t]>=0&&(r[t]=e[t]);return Array.isArray(e.componentPath)&&e.componentPath.every(t=>Number.isSafeInteger(t)&&t>=0)&&(r.componentPath=e.componentPath),r}function O(e){if(!(e instanceof Error))return{name:"Error",message:String(e)};const r=e;return{name:e.name,message:e.message,...typeof r.code=="string"?{code:r.code}:{},...typeof r.path=="string"?{path:r.path}:{},...Array.isArray(r.issues)?{issues:r.issues.map(W)}:{},...Array.isArray(r.diagnostics)?{diagnostics:r.diagnostics.map(j)}:{}}}function S(e){if(!e||typeof e!="object")return!1;const r=e;return r.protocol===u&&typeof r.id=="string"&&(r.operation==="prepare"||r.operation==="export")&&!!r.input&&typeof r.input=="object"}async function N(e,r,t){try{const o=r.operation==="prepare"?await e.prepare({...r.input,onEvent:t}):await e.export({...r.input,onEvent:t});return{protocol:u,id:r.id,result:o}}catch(o){return{protocol:u,id:r.id,error:O(o)}}}function z(e){const r=e.result;return!r||!("bytes"in r)||!(r.bytes.buffer instanceof ArrayBuffer)?[]:[r.bytes.buffer]}function _(e,r){if(!p(e)||typeof e.taskId!="string"||!e.taskId||r.taskId!==void 0&&e.taskId!==r.taskId||e.correlationId!==r.correlationId||e.reportId!==void 0&&(typeof e.reportId!="string"||!r.reportIds.includes(e.reportId))||!["query","validate","layout","assets","encode"].includes(e.stage)||!["started","completed","failed"].includes(e.status))return!1;for(const t of["completed","total"])if(e[t]!==void 0&&(typeof e[t]!="number"||!Number.isFinite(e[t])||e[t]<0))return!1;return e.completed===void 0||e.total===void 0||e.completed<=e.total}let q=0;function w(e){const r=new Error("报表 Worker 任务已取消");return r.name="AbortError",Object.defineProperty(r,"cause",{value:e}),r}function B(e,r){if(!e||typeof e!="object")return;const t=e;return t.protocol===u&&t.id===r?t:void 0}function F(e,r={}){const t=r.timeoutMs??12e4;if(!Number.isFinite(t)||t<=0||t>2147483647)throw new RangeError("Worker timeoutMs 应为正有限数字，且不能超过 2147483647");const o=(i,c,n,d)=>n?.aborted?Promise.reject(w(n.reason)):new Promise((I,b)=>{let g;try{g=e()}catch(a){b(a);return}const R=`mach-report-${Date.now()}-${++q}`;let y=!1,E=()=>{},k;const f=(a,s)=>{y||(y=!0,k&&clearTimeout(k),E(),n?.removeEventListener("abort",h),Promise.resolve().then(()=>g.terminate()).then(()=>a===void 0?I(s):b(a),m=>b(a??m)))},h=()=>f(w(n?.reason)),M=a=>{const s=B(a,R);if(!(!s||y)){if("type"in s&&s.type==="event"){const m="event"in s?s.event:void 0;_(m,c)?x.notifyReportTaskEvent(d,m,n):f(new Error("报表 Worker 返回无效阶段事件"));return}s.error&&typeof s.error.name=="string"&&typeof s.error.message=="string"?f(new l(s.error)):v(s.result,i)&&(i!=="export"||"format"in s.result&&"format"in c&&s.result.format===c.format)?f(void 0,s.result):f(new Error("报表 Worker 返回无效响应"))}};try{if(E=g.subscribe(M,a=>f(a??new Error("报表 Worker 执行失败"))),y){E();return}if(n?.addEventListener("abort",h,{once:!0}),k=setTimeout(()=>f(new l({name:"ReportRuntimeError",code:"timeout",message:`报表 Worker 执行超过 ${t}ms`})),t),n?.aborted)h();else{const{onEvent:a,signal:s,...m}=c;g.postMessage({protocol:u,id:R,operation:i,input:m})}}catch(a){f(a)}});return{prepare:(i,c,n)=>o("prepare",i,c,n),export:(i,c,n)=>o("export",i,c,n)}}function $(e,r={}){return F(()=>{const t=e();return{postMessage:o=>t.postMessage(o),terminate:()=>t.terminate(),subscribe:(o,i)=>{const c=d=>o(d.data),n=d=>i(d instanceof ErrorEvent?new Error(d.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)}}}},r)}function D(e,r=globalThis){const t=o=>{S(o.data)&&N(e,o.data,i=>r.postMessage({protocol:u,id:o.data.id,type:"event",event:i})).then(i=>r.postMessage(i,z(i)))};return r.addEventListener("message",t),()=>r.removeEventListener("message",t)}exports.ReportWorkerError=l;exports.createBrowserReportExecutor=$;exports.serveReportWorker=D;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const M=require("./task-events-DQ276fn2.cjs"),P=require("./data-explanation-BktvER5B.cjs"),A=require("./validate-BJ5HIWY8.cjs"),u="mach-report-worker/1";class l extends Error{constructor(r){super(r.message),this.name=r.name,this.code=r.code,this.path=r.path,this.issues=r.issues,this.diagnostics=r.diagnostics}}function p(e){return!!e&&typeof e=="object"&&!Array.isArray(e)}function L(e){return p(e)?["rows","pages","cells"].every(r=>typeof e[r]=="number"&&Number.isSafeInteger(e[r])&&e[r]>=0)&&typeof e.durationMs=="number"&&Number.isFinite(e.durationMs)&&e.durationMs>=0:!1}function T(e){return Array.isArray(e)&&e.every(r=>p(r)&&typeof r.code=="string"&&typeof r.message=="string"&&["info","warning","error"].includes(r.severity)&&P.hasValidDataExplanation(r))}function j(e){return p(e)&&Object.values(e).every(r=>p(r)&&(r.revision===void 0||typeof r.revision=="string")&&(r.sourceToken===void 0||typeof r.sourceToken=="string"))}function O(e){return e===void 0?!0:p(e)&&["heuristic","provided","font-bytes"].includes(e.textMetrics)&&(e.fontFingerprint===void 0||typeof e.fontFingerprint=="string"&&/^[a-f0-9]{64}$/.test(e.fontFingerprint))}function S(e,r){if(!p(e)||!L(e.stats)||!T(e.diagnostics)||!j(e.revisions)||!O(e.layout))return!1;if(r==="prepare")return A.validateRenderPlan(e.plan).ok;const t=e.format==="pdf"?"application/pdf":"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";return e.bytes instanceof Uint8Array&&(e.format==="pdf"||e.format==="xlsx")&&e.contentType===t}function x(e){if(!e||typeof e!="object")return{message:String(e)};const r={};for(const t of["code","path","field","message"]){const o=e[t];typeof o=="string"&&(r[t]=o)}return r}function F(e){const r=x(e);if(!p(e))return r;for(const t of["format","severity","kind","nid"])typeof e[t]=="string"&&(r[t]=e[t]);for(const t of["pageIndex","componentIndex"])Number.isSafeInteger(e[t])&&e[t]>=0&&(r[t]=e[t]);return Array.isArray(e.componentPath)&&e.componentPath.every(t=>Number.isSafeInteger(t)&&t>=0)&&(r.componentPath=e.componentPath),r}function N(e){if(!(e instanceof Error))return{name:"Error",message:String(e)};const r=e;return{name:e.name,message:e.message,...typeof r.code=="string"?{code:r.code}:{},...typeof r.path=="string"?{path:r.path}:{},...Array.isArray(r.issues)?{issues:r.issues.map(x)}:{},...Array.isArray(r.diagnostics)?{diagnostics:r.diagnostics.map(F)}:{}}}function v(e){if(!e||typeof e!="object")return!1;const r=e;return r.protocol===u&&typeof r.id=="string"&&(r.operation==="prepare"||r.operation==="export"||r.operation==="exportPrepared")&&!!r.input&&typeof r.input=="object"}async function z(e,r,t){try{const o=r.operation==="prepare"?await e.prepare({...r.input,onEvent:t}):r.operation==="exportPrepared"?await e.exportPrepared({...r.input,onEvent:t}):await e.export({...r.input,onEvent:t});return{protocol:u,id:r.id,result:o}}catch(o){return{protocol:u,id:r.id,error:N(o)}}}function _(e){const r=e.result;return!r||!("bytes"in r)||!(r.bytes.buffer instanceof ArrayBuffer)?[]:[r.bytes.buffer]}function $(e,r){if(!p(e)||typeof e.taskId!="string"||!e.taskId||r.taskId!==void 0&&e.taskId!==r.taskId||e.correlationId!==r.correlationId||e.reportId!==void 0&&(typeof e.reportId!="string"||!("reportIds"in r&&r.reportIds.includes(e.reportId)))||!["query","validate","layout","assets","encode"].includes(e.stage)||!["started","completed","failed"].includes(e.status))return!1;for(const t of["completed","total"])if(e[t]!==void 0&&(typeof e[t]!="number"||!Number.isFinite(e[t])||e[t]<0))return!1;return e.completed===void 0||e.total===void 0||e.completed<=e.total}let B=0;function w(e){const r=new Error("报表 Worker 任务已取消");return r.name="AbortError",Object.defineProperty(r,"cause",{value:e}),r}function D(e,r){if(!e||typeof e!="object")return;const t=e;return t.protocol===u&&t.id===r?t:void 0}function q(e,r={}){const t=r.timeoutMs??12e4;if(!Number.isFinite(t)||t<=0||t>2147483647)throw new RangeError("Worker timeoutMs 应为正有限数字，且不能超过 2147483647");const o=(s,a,n,d)=>n?.aborted?Promise.reject(w(n.reason)):new Promise((I,b)=>{let g;try{g=e()}catch(c){b(c);return}const R=`mach-report-${Date.now()}-${++B}`;let y=!1,E=()=>{},k;const f=(c,i)=>{y||(y=!0,k&&clearTimeout(k),E(),n?.removeEventListener("abort",h),Promise.resolve().then(()=>g.terminate()).then(()=>c===void 0?I(i):b(c),m=>b(c??m)))},h=()=>f(w(n?.reason)),W=c=>{const i=D(c,R);if(!(!i||y)){if("type"in i&&i.type==="event"){const m="event"in i?i.event:void 0;$(m,a)?M.notifyReportTaskEvent(d,m,n):f(new Error("报表 Worker 返回无效阶段事件"));return}i.error&&typeof i.error.name=="string"&&typeof i.error.message=="string"?f(new l(i.error)):S(i.result,s)&&(s==="prepare"||"format"in i.result&&"format"in a&&i.result.format===a.format)?f(void 0,i.result):f(new Error("报表 Worker 返回无效响应"))}};try{if(E=g.subscribe(W,c=>f(c??new Error("报表 Worker 执行失败"))),y){E();return}if(n?.addEventListener("abort",h,{once:!0}),k=setTimeout(()=>f(new l({name:"ReportRuntimeError",code:"timeout",message:`报表 Worker 执行超过 ${t}ms`})),t),n?.aborted)h();else{const{onEvent:c,signal:i,...m}=a;g.postMessage({protocol:u,id:R,operation:s,input:m})}}catch(c){f(c)}});return{exportPrepared:(s,a,n)=>o("exportPrepared",s,a,n),prepare:(s,a,n)=>o("prepare",s,a,n),export:(s,a,n)=>o("export",s,a,n)}}function C(e,r={}){return q(()=>{const t=e();return{postMessage:o=>t.postMessage(o),terminate:()=>t.terminate(),subscribe:(o,s)=>{const a=d=>o(d.data),n=d=>s(d instanceof ErrorEvent?new Error(d.message):new Error("报表 Worker 消息无法解码"));return t.addEventListener("message",a),t.addEventListener("error",n),t.addEventListener("messageerror",n),()=>{t.removeEventListener("message",a),t.removeEventListener("error",n),t.removeEventListener("messageerror",n)}}}},r)}function K(e,r=globalThis){const t=o=>{v(o.data)&&z(e,o.data,s=>r.postMessage({protocol:u,id:o.data.id,type:"event",event:s})).then(s=>r.postMessage(s,_(s)))};return r.addEventListener("message",t),()=>r.removeEventListener("message",t)}exports.ReportWorkerError=l;exports.createBrowserReportExecutor=C;exports.serveReportWorker=K;

package/dist/worker.d.cts

@@ -181,6 +181,11 @@ declare interface PreparedReport {
         revision?: string;
         sourceToken?: string;
     }>;
+    /** Captured metrics identity; absence on old saved instances remains supported with diagnostics. */
+    layout?: {
+        textMetrics: "heuristic" | "provided" | "font-bytes";
+        fontFingerprint?: string;
+    };
 }
 
 declare interface RenderPlan {
@@ -199,6 +204,14 @@ declare interface ReportCellSource {
     sourceToken?: string;
 }
 
+declare interface ReportDataTarget {
+    datasetId: string;
+    field: string;
+    rowKey?: string | number;
+    /** Use table identity when the same dataset appears in several tables. */
+    tableId?: string;
+}
+
 declare interface ReportDescription {
     id: string;
     params: ReportParamDef[];
@@ -217,6 +230,9 @@ declare interface ReportDiagnostic {
     message: string;
     path?: string;
     severity: "warning" | "error" | "info";
+    /** Optional explanation supplied by the business source, not inferred from blank cells. */
+    valueState?: ReportValueState;
+    target?: ReportDataTarget;
 }
 
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
@@ -259,15 +275,30 @@ declare interface ReportParamValidation {
     issues: ReportParamIssue[];
 }
 
+/** Licensed local font bytes; never downloaded implicitly by the runtime. */
+declare interface ReportPdfFontOptions {
+    customFontBytes?: Uint8Array | ArrayBuffer;
+    customFontName?: string;
+    customFontFaces?: {
+        regular: Uint8Array | ArrayBuffer;
+        bold?: Uint8Array | ArrayBuffer;
+        italic?: Uint8Array | ArrayBuffer;
+        boldItalic?: Uint8Array | ArrayBuffer;
+    };
+}
+
 declare interface ReportRuntime {
     describe(reportIds?: string[]): ReportDescription[];
     validate(input: Omit<ReportRuntimeInput, "signal">): ReportParamValidation;
     prepare(input: ReportRuntimeInput): Promise<PreparedReport>;
     export(input: ReportRuntimeExportInput): Promise<ReportRuntimeExportResult>;
+    exportPrepared(input: ReportRuntimePreparedExportInput): Promise<ReportRuntimeExportResult>;
 }
 
 /** 可用 worker_threads/进程/RPC 实现；接收可序列化请求，signal 由桥接层映射为取消消息。 */
 declare interface ReportRuntimeExecutor {
+    /** Old custom executors may omit this; the runtime explicitly rejects unsupported prepared output. */
+    exportPrepared?(input: Omit<ReportRuntimePreparedExportInput, "signal" | "onEvent">, signal?: AbortSignal, onEvent?: ReportTaskObserver): Promise<ReportRuntimeExportResult>;
     prepare(input: Omit<ReportRuntimeInput, "signal" | "onEvent">, signal?: AbortSignal, onEvent?: ReportTaskObserver): Promise<PreparedReport>;
     export(input: Omit<ReportRuntimeExportInput, "signal" | "onEvent">, signal?: AbortSignal, onEvent?: ReportTaskObserver): Promise<ReportRuntimeExportResult>;
 }
@@ -276,17 +307,6 @@ declare interface ReportRuntimeExportInput extends ReportRuntimeInput {
     format: "pdf" | "xlsx";
     /** strict 在编码前拒绝已识别的输出降级；默认保留诊断并继续。 */
     fidelity?: "warn" | "strict";
-    /** 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";
@@ -304,6 +324,18 @@ declare interface ReportRuntimeInput extends ReportTaskMonitoring {
     reportIds: string[];
     params?: Record<string, string>;
     signal?: AbortSignal;
+    /** Prepare using the same licensed font bytes later supplied to PDF output. */
+    pdf?: ReportPdfFontOptions;
+}
+
+/** Encode an existing plan without querying providers or repaginating. */
+declare interface ReportRuntimePreparedExportInput extends ReportTaskMonitoring {
+    prepared: PreparedReport;
+    format: ReportRuntimeExportInput["format"];
+    fidelity?: ReportRuntimeExportInput["fidelity"];
+    pdf?: ReportPdfFontOptions;
+    xlsx?: ReportRuntimeExportInput["xlsx"];
+    signal?: AbortSignal;
 }
 
 declare interface ReportRuntimeStats {
@@ -333,6 +365,9 @@ declare interface ReportTaskMonitoring {
 
 declare type ReportTaskObserver = (event: ReportTaskEvent) => void;
 
+/** Optional business explanations never replace raw data or schema validation. */
+declare type ReportValueState = "missing-source" | "not-applicable" | "not-calculable";
+
 export declare class ReportWorkerError extends Error {
     readonly code?: string;
     readonly path?: string;

package/dist/worker.d.ts

@@ -181,6 +181,11 @@ declare interface PreparedReport {
         revision?: string;
         sourceToken?: string;
     }>;
+    /** Captured metrics identity; absence on old saved instances remains supported with diagnostics. */
+    layout?: {
+        textMetrics: "heuristic" | "provided" | "font-bytes";
+        fontFingerprint?: string;
+    };
 }
 
 declare interface RenderPlan {
@@ -199,6 +204,14 @@ declare interface ReportCellSource {
     sourceToken?: string;
 }
 
+declare interface ReportDataTarget {
+    datasetId: string;
+    field: string;
+    rowKey?: string | number;
+    /** Use table identity when the same dataset appears in several tables. */
+    tableId?: string;
+}
+
 declare interface ReportDescription {
     id: string;
     params: ReportParamDef[];
@@ -217,6 +230,9 @@ declare interface ReportDiagnostic {
     message: string;
     path?: string;
     severity: "warning" | "error" | "info";
+    /** Optional explanation supplied by the business source, not inferred from blank cells. */
+    valueState?: ReportValueState;
+    target?: ReportDataTarget;
 }
 
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
@@ -259,15 +275,30 @@ declare interface ReportParamValidation {
     issues: ReportParamIssue[];
 }
 
+/** Licensed local font bytes; never downloaded implicitly by the runtime. */
+declare interface ReportPdfFontOptions {
+    customFontBytes?: Uint8Array | ArrayBuffer;
+    customFontName?: string;
+    customFontFaces?: {
+        regular: Uint8Array | ArrayBuffer;
+        bold?: Uint8Array | ArrayBuffer;
+        italic?: Uint8Array | ArrayBuffer;
+        boldItalic?: Uint8Array | ArrayBuffer;
+    };
+}
+
 declare interface ReportRuntime {
     describe(reportIds?: string[]): ReportDescription[];
     validate(input: Omit<ReportRuntimeInput, "signal">): ReportParamValidation;
     prepare(input: ReportRuntimeInput): Promise<PreparedReport>;
     export(input: ReportRuntimeExportInput): Promise<ReportRuntimeExportResult>;
+    exportPrepared(input: ReportRuntimePreparedExportInput): Promise<ReportRuntimeExportResult>;
 }
 
 /** 可用 worker_threads/进程/RPC 实现；接收可序列化请求，signal 由桥接层映射为取消消息。 */
 declare interface ReportRuntimeExecutor {
+    /** Old custom executors may omit this; the runtime explicitly rejects unsupported prepared output. */
+    exportPrepared?(input: Omit<ReportRuntimePreparedExportInput, "signal" | "onEvent">, signal?: AbortSignal, onEvent?: ReportTaskObserver): Promise<ReportRuntimeExportResult>;
     prepare(input: Omit<ReportRuntimeInput, "signal" | "onEvent">, signal?: AbortSignal, onEvent?: ReportTaskObserver): Promise<PreparedReport>;
     export(input: Omit<ReportRuntimeExportInput, "signal" | "onEvent">, signal?: AbortSignal, onEvent?: ReportTaskObserver): Promise<ReportRuntimeExportResult>;
 }
@@ -276,17 +307,6 @@ declare interface ReportRuntimeExportInput extends ReportRuntimeInput {
     format: "pdf" | "xlsx";
     /** strict 在编码前拒绝已识别的输出降级；默认保留诊断并继续。 */
     fidelity?: "warn" | "strict";
-    /** 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";
@@ -304,6 +324,18 @@ declare interface ReportRuntimeInput extends ReportTaskMonitoring {
     reportIds: string[];
     params?: Record<string, string>;
     signal?: AbortSignal;
+    /** Prepare using the same licensed font bytes later supplied to PDF output. */
+    pdf?: ReportPdfFontOptions;
+}
+
+/** Encode an existing plan without querying providers or repaginating. */
+declare interface ReportRuntimePreparedExportInput extends ReportTaskMonitoring {
+    prepared: PreparedReport;
+    format: ReportRuntimeExportInput["format"];
+    fidelity?: ReportRuntimeExportInput["fidelity"];
+    pdf?: ReportPdfFontOptions;
+    xlsx?: ReportRuntimeExportInput["xlsx"];
+    signal?: AbortSignal;
 }
 
 declare interface ReportRuntimeStats {
@@ -333,6 +365,9 @@ declare interface ReportTaskMonitoring {
 
 declare type ReportTaskObserver = (event: ReportTaskEvent) => void;
 
+/** Optional business explanations never replace raw data or schema validation. */
+declare type ReportValueState = "missing-source" | "not-applicable" | "not-calculable";
+
 export declare class ReportWorkerError extends Error {
     readonly code?: string;
     readonly path?: string;

package/dist/worker.js

@@ -1,5 +1,6 @@
-import { n as A } from "./task-events-Dpsvf_t2.js";
-import { c as M } from "./validate-DbgEM1Hh.js";
+import { n as P } from "./task-events-Dpsvf_t2.js";
+import { h as W } from "./data-explanation-C_J6jYNi.js";
+import { v as A } from "./validate-CkQBWCeg.js";
 const u = "mach-report-worker/1";
 class R extends Error {
   constructor(r) {
@@ -12,19 +13,22 @@ function p(e) {
 function L(e) {
   return p(e) ? ["rows", "pages", "cells"].every((r) => typeof e[r] == "number" && Number.isSafeInteger(e[r]) && e[r] >= 0) && typeof e.durationMs == "number" && Number.isFinite(e.durationMs) && e.durationMs >= 0 : !1;
 }
-function P(e) {
-  return Array.isArray(e) && e.every((r) => p(r) && typeof r.code == "string" && typeof r.message == "string" && ["info", "warning", "error"].includes(r.severity));
-}
 function T(e) {
+  return Array.isArray(e) && e.every((r) => p(r) && typeof r.code == "string" && typeof r.message == "string" && ["info", "warning", "error"].includes(r.severity) && W(r));
+}
+function j(e) {
   return p(e) && Object.values(e).every((r) => p(r) && (r.revision === void 0 || typeof r.revision == "string") && (r.sourceToken === void 0 || typeof r.sourceToken == "string"));
 }
-function j(e, r) {
-  if (!p(e) || !L(e.stats) || !P(e.diagnostics) || !T(e.revisions)) return !1;
-  if (r === "prepare") return M(e.plan).ok;
+function O(e) {
+  return e === void 0 ? !0 : p(e) && ["heuristic", "provided", "font-bytes"].includes(e.textMetrics) && (e.fontFingerprint === void 0 || typeof e.fontFingerprint == "string" && /^[a-f0-9]{64}$/.test(e.fontFingerprint));
+}
+function F(e, r) {
+  if (!p(e) || !L(e.stats) || !T(e.diagnostics) || !j(e.revisions) || !O(e.layout)) return !1;
+  if (r === "prepare") return A(e.plan).ok;
   const t = e.format === "pdf" ? "application/pdf" : "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
   return e.bytes instanceof Uint8Array && (e.format === "pdf" || e.format === "xlsx") && e.contentType === t;
 }
-function I(e) {
+function x(e) {
   if (!e || typeof e != "object") return { message: String(e) };
   const r = {};
   for (const t of ["code", "path", "field", "message"]) {
@@ -33,14 +37,14 @@ function I(e) {
   }
   return r;
 }
-function O(e) {
-  const r = I(e);
+function N(e) {
+  const r = x(e);
   if (!p(e)) return r;
   for (const t of ["format", "severity", "kind", "nid"]) typeof e[t] == "string" && (r[t] = e[t]);
   for (const t of ["pageIndex", "componentIndex"]) Number.isSafeInteger(e[t]) && e[t] >= 0 && (r[t] = e[t]);
   return Array.isArray(e.componentPath) && e.componentPath.every((t) => Number.isSafeInteger(t) && t >= 0) && (r.componentPath = e.componentPath), r;
 }
-function N(e) {
+function S(e) {
   if (!(e instanceof Error)) return { name: "Error", message: String(e) };
   const r = e;
   return {
@@ -48,111 +52,111 @@ function N(e) {
     message: e.message,
     ...typeof r.code == "string" ? { code: r.code } : {},
     ...typeof r.path == "string" ? { path: r.path } : {},
-    ...Array.isArray(r.issues) ? { issues: r.issues.map(I) } : {},
-    ...Array.isArray(r.diagnostics) ? { diagnostics: r.diagnostics.map(O) } : {}
+    ...Array.isArray(r.issues) ? { issues: r.issues.map(x) } : {},
+    ...Array.isArray(r.diagnostics) ? { diagnostics: r.diagnostics.map(N) } : {}
   };
 }
-function v(e) {
+function z(e) {
   if (!e || typeof e != "object") return !1;
   const r = e;
-  return r.protocol === u && typeof r.id == "string" && (r.operation === "prepare" || r.operation === "export") && !!r.input && typeof r.input == "object";
+  return r.protocol === u && typeof r.id == "string" && (r.operation === "prepare" || r.operation === "export" || r.operation === "exportPrepared") && !!r.input && typeof r.input == "object";
 }
-async function S(e, r, t) {
+async function _(e, r, t) {
   try {
-    const o = r.operation === "prepare" ? await e.prepare({ ...r.input, onEvent: t }) : await e.export({ ...r.input, onEvent: t });
+    const o = r.operation === "prepare" ? await e.prepare({ ...r.input, onEvent: t }) : r.operation === "exportPrepared" ? await e.exportPrepared({ ...r.input, onEvent: t }) : await e.export({ ...r.input, onEvent: t });
     return { protocol: u, id: r.id, result: o };
   } catch (o) {
-    return { protocol: u, id: r.id, error: N(o) };
+    return { protocol: u, id: r.id, error: S(o) };
   }
 }
-function z(e) {
+function $(e) {
   const r = e.result;
   return !r || !("bytes" in r) || !(r.bytes.buffer instanceof ArrayBuffer) ? [] : [r.bytes.buffer];
 }
-function _(e, r) {
-  if (!p(e) || typeof e.taskId != "string" || !e.taskId || r.taskId !== void 0 && e.taskId !== r.taskId || e.correlationId !== r.correlationId || e.reportId !== void 0 && (typeof e.reportId != "string" || !r.reportIds.includes(e.reportId)) || !["query", "validate", "layout", "assets", "encode"].includes(e.stage) || !["started", "completed", "failed"].includes(e.status)) return !1;
+function D(e, r) {
+  if (!p(e) || typeof e.taskId != "string" || !e.taskId || r.taskId !== void 0 && e.taskId !== r.taskId || e.correlationId !== r.correlationId || e.reportId !== void 0 && (typeof e.reportId != "string" || !("reportIds" in r && r.reportIds.includes(e.reportId))) || !["query", "validate", "layout", "assets", "encode"].includes(e.stage) || !["started", "completed", "failed"].includes(e.status)) return !1;
   for (const t of ["completed", "total"]) if (e[t] !== void 0 && (typeof e[t] != "number" || !Number.isFinite(e[t]) || e[t] < 0)) return !1;
   return e.completed === void 0 || e.total === void 0 || e.completed <= e.total;
 }
-let F = 0;
+let v = 0;
 function w(e) {
   const r = new Error("报表 Worker 任务已取消");
   return r.name = "AbortError", Object.defineProperty(r, "cause", { value: e }), r;
 }
-function $(e, r) {
+function B(e, r) {
   if (!e || typeof e != "object") return;
   const t = e;
   return t.protocol === u && t.id === r ? t : void 0;
 }
-function B(e, r = {}) {
+function C(e, r = {}) {
   const t = r.timeoutMs ?? 12e4;
   if (!Number.isFinite(t) || t <= 0 || t > 2147483647) throw new RangeError("Worker timeoutMs 应为正有限数字，且不能超过 2147483647");
-  const o = (i, c, n, d) => n?.aborted ? Promise.reject(w(n.reason)) : new Promise((W, b) => {
+  const o = (s, a, n, d) => n?.aborted ? Promise.reject(w(n.reason)) : new Promise((I, b) => {
     let g;
     try {
       g = e();
-    } catch (a) {
-      b(a);
+    } catch (c) {
+      b(c);
       return;
     }
-    const l = `mach-report-${Date.now()}-${++F}`;
+    const l = `mach-report-${Date.now()}-${++v}`;
     let y = !1, E = () => {
     }, h;
-    const f = (a, s) => {
+    const f = (c, i) => {
       y || (y = !0, h && clearTimeout(h), E(), n?.removeEventListener("abort", k), Promise.resolve().then(() => g.terminate()).then(
-        () => a === void 0 ? W(s) : b(a),
-        (m) => b(a ?? m)
+        () => c === void 0 ? I(i) : b(c),
+        (m) => b(c ?? m)
       ));
-    }, k = () => f(w(n?.reason)), x = (a) => {
-      const s = $(a, l);
-      if (!(!s || y)) {
-        if ("type" in s && s.type === "event") {
-          const m = "event" in s ? s.event : void 0;
-          _(m, c) ? A(d, m, n) : f(new Error("报表 Worker 返回无效阶段事件"));
+    }, k = () => f(w(n?.reason)), M = (c) => {
+      const i = B(c, l);
+      if (!(!i || y)) {
+        if ("type" in i && i.type === "event") {
+          const m = "event" in i ? i.event : void 0;
+          D(m, a) ? P(d, m, n) : f(new Error("报表 Worker 返回无效阶段事件"));
           return;
         }
-        s.error && typeof s.error.name == "string" && typeof s.error.message == "string" ? f(new R(s.error)) : j(s.result, i) && (i !== "export" || "format" in s.result && "format" in c && s.result.format === c.format) ? f(void 0, s.result) : f(new Error("报表 Worker 返回无效响应"));
+        i.error && typeof i.error.name == "string" && typeof i.error.message == "string" ? f(new R(i.error)) : F(i.result, s) && (s === "prepare" || "format" in i.result && "format" in a && i.result.format === a.format) ? f(void 0, i.result) : f(new Error("报表 Worker 返回无效响应"));
       }
     };
     try {
-      if (E = g.subscribe(x, (a) => f(a ?? new Error("报表 Worker 执行失败"))), y) {
+      if (E = g.subscribe(M, (c) => f(c ?? new Error("报表 Worker 执行失败"))), y) {
         E();
         return;
       }
       if (n?.addEventListener("abort", k, { once: !0 }), h = setTimeout(() => f(new R({ name: "ReportRuntimeError", code: "timeout", message: `报表 Worker 执行超过 ${t}ms` })), t), n?.aborted) k();
       else {
-        const { onEvent: a, signal: s, ...m } = c;
-        g.postMessage({ protocol: u, id: l, operation: i, input: m });
+        const { onEvent: c, signal: i, ...m } = a;
+        g.postMessage({ protocol: u, id: l, operation: s, input: m });
       }
-    } catch (a) {
-      f(a);
+    } catch (c) {
+      f(c);
     }
   });
-  return { prepare: (i, c, n) => o("prepare", i, c, n), export: (i, c, n) => o("export", i, c, n) };
+  return { exportPrepared: (s, a, n) => o("exportPrepared", s, a, n), prepare: (s, a, n) => o("prepare", s, a, n), export: (s, a, n) => o("export", s, a, n) };
 }
-function C(e, r = {}) {
-  return B(() => {
+function G(e, r = {}) {
+  return C(() => {
     const t = e();
     return {
       postMessage: (o) => t.postMessage(o),
       terminate: () => t.terminate(),
-      subscribe: (o, i) => {
-        const c = (d) => o(d.data), n = (d) => i(d instanceof ErrorEvent ? new Error(d.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);
+      subscribe: (o, s) => {
+        const a = (d) => o(d.data), n = (d) => s(d instanceof ErrorEvent ? new Error(d.message) : new Error("报表 Worker 消息无法解码"));
+        return t.addEventListener("message", a), t.addEventListener("error", n), t.addEventListener("messageerror", n), () => {
+          t.removeEventListener("message", a), t.removeEventListener("error", n), t.removeEventListener("messageerror", n);
         };
       }
     };
   }, r);
 }
-function K(e, r = globalThis) {
+function H(e, r = globalThis) {
   const t = (o) => {
-    v(o.data) && S(e, o.data, (i) => r.postMessage({ protocol: u, id: o.data.id, type: "event", event: i })).then((i) => r.postMessage(i, z(i)));
+    z(o.data) && _(e, o.data, (s) => r.postMessage({ protocol: u, id: o.data.id, type: "event", event: s })).then((s) => r.postMessage(s, $(s)));
   };
   return r.addEventListener("message", t), () => r.removeEventListener("message", t);
 }
 export {
   R as ReportWorkerError,
-  C as createBrowserReportExecutor,
-  K as serveReportWorker
+  G as createBrowserReportExecutor,
+  H as serveReportWorker
 };

package/dist/xlsx.js

@@ -1,11 +1,11 @@
 import { a as x, o as z } from "./progress-7OSZbFok.js";
-import { e as P, E as B, m as C } from "./workbook-session-BPb3TMnT.js";
-import { i as ke, a as We, o as Ae } from "./workbook-session-BPb3TMnT.js";
+import { e as P, E as B, m as C } from "./workbook-session-BfK1yHOO.js";
+import { i as ke, a as We, o as Ae } from "./workbook-session-BfK1yHOO.js";
 import { i as $ } from "./render-plan-Ck6koX9L.js";
 import { r as k } from "./grid-geometry-BNptEcMm.js";
 import { e as W, r as N } from "./style-CQ1PK8ZB.js";
 import { r as G } from "./capabilities-CK_7hizc.js";
-import { b as Fe, c as Re, a as Te, d as ze, e as Pe, f as Be, g as Ne, h as Ge, p as Le, i as Oe, v as je, j as De, k as _e, l as He, m as Ke, n as Xe } from "./region-binding-workflow-CcUq8W2Q.js";
+import { b as Fe, c as Re, a as Te, d as ze, e as Pe, f as Be, g as Ne, h as Ge, p as Le, i as Oe, v as je, j as De, k as _e, l as He, m as Ke, n as Xe } from "./region-binding-workflow-DEJbhpCv.js";
 function y(e, t) {
   const r = e ?? t;
   if (!Number.isSafeInteger(r) || r <= 0) throw new Error("Excel 图片字节预算应为正安全整数");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/mach-report",
-  "version": "2.12.0",
+  "version": "2.14.0",
   "description": "独立的 TypeScript 报表引擎：模板分页、DOM/Canvas/PDF/Excel 输出与 Vue 3 预览组件",
   "type": "module",
   "sideEffects": [