@gct-paas/excel 0.1.36 → 0.1.37-beta.0

package/dist/src/nocode-base/src/interface/render.d.ts

@@ -1,5 +1,6 @@
 import { FormTypeEnum } from '../constant';
 import { FormTmplBomController } from '../hooks';
+import { RuntimeFieldMetadata } from '../runtime/runtime-field-registry';
 /** 渲染端公共类 */
 export declare const renderUtils: {
     getValue: (modelValue: any, multiple: any) => any;
@@ -68,7 +69,7 @@ export declare const renderUtils: {
     /** 处理字段列表-优先编辑 */
     deduplicateFields: (data: any) => any[];
     /** 根据模板信息集合筛选字段信息集合 */
-    getFieldsByDataCenter: (dataCenter: any, useDynRowHeight: boolean) => Promise<{
+    getFieldsByDataCenter: (dataCenter: any, useDynRowHeight: boolean, sheetId?: string) => Promise<{
         foreignFields: unknown[];
         subModelFields: {
             masterFieldKey: any;
@@ -83,9 +84,11 @@ export declare const renderUtils: {
         tdIdGroups: Map<any, any>;
         useClsReasonDataLink: string[];
         useClsGroupDataLink: string[];
+        fieldLocations: any[];
+        fieldMetadata: RuntimeFieldMetadata;
     }>;
     /** 提前设置值给widget */
-    setRequestInfo2DataCenter: (dataCenter: any, modelKeys: any, platformType: any, isMockReport: any, formType: FormTypeEnum, paramsConfig: any, useSignFields: any, useClsReasonDataLink: any, useClsGroupDataLink: any, tmplBomC: FormTmplBomController, modelQueries: any) => Promise<void>;
+    setRequestInfo2DataCenter: (dataCenters: any, modelKeys: any, platformType: any, isMockReport: any, formType: FormTypeEnum, paramsConfig: any, useSignFields: any, useClsReasonDataLink: any, useClsGroupDataLink: any, tmplBomC: FormTmplBomController, modelQueries: any) => Promise<void>;
     /** 获取默认值集合 */
     getDefaultValueMapByField: ({ defaultValueFields, mainMaterialNo, mainRelatedLotNo, mainProductName, mainRoutingOperation, mainMfgOrderId, mainWarehouseId, mainLotSnId, mainProductQty, mainSterilizationLot, mainSterilizationLotId, defaultUserId, defaultOrgId, operationData, productData, mfgOrderData, sopList, ESOPData, materialNoData, relatedLotNoData, sterilizeLotData, warehouseData, }: {
         defaultValueFields: any;

package/dist/src/nocode-base/src/interface/transform.d.ts

@@ -1,7 +1,7 @@
 import { RenderModeEnum } from '../constant';
 import { ICheckTableConfig } from './front-config';
-import { IPaper } from '../types';
 import { SubTableCoreFactory } from '../core/factory/sub-table-factory';
+import { RuntimeTableRelation } from '../runtime/table-row-identity';
 /** 将源数据转换为子表数据 */
 declare function transformSourceData2SubTable(data: any, dict?: {}, 
 /** 默认值 */
@@ -28,19 +28,18 @@ export declare const transformUtils: {
         subTableInfo: Array<any>;
         /** 渲染模式 */
         viewMode: RenderModeEnum;
-        /** 纸张信息 */
-        paper: any;
-        /** 数据中心 */
-        dataCenter: any;
+        /** 全部 Sheet 共享的表单配置。 */
+        formConfig: Record<string, any>;
+        /** 各 Sheet 数据中心 */
+        dataCenters: Array<Record<string, any>>;
     }) => {
         _DICT: {};
         _OPCT: {};
         _MCTABLE: {};
     };
-    /** 请求参数映射数据 */
+    /** 请求参数映射数据；参数映射是实例级配置，与当前 Sheet 无关。 */
     getParamData: (payload: {
-        /** 纸张信息 */
-        paper: any;
+        formConfig: Record<string, any>;
         /** 参数配置 */
         paramsConfig: any;
         /** 子表信息 */
@@ -59,8 +58,10 @@ export declare const transformUtils: {
      * @returns 待落库的 checkTableConfig；无检验表或未产生快照时返回 undefined
      */
     requestCheckDsData: (payload: {
-        /** 纸张组件（含 checkTable2DList、customDataSource） */
+        /** 当前 Sheet 的纸张和检验表坐标配置。 */
         paper: any;
+        /** 表单级数据源配置。 */
+        formConfig: Record<string, any>;
         /** 当前表单实例 id，用于协议/接口查询 */
         instanceId: string;
         /** 运行时 JSON 副本，扩行时会直接修改 */
@@ -70,10 +71,9 @@ export declare const transformUtils: {
         /** 实例已落库的 frontConfig（JSON 字符串） */
         frontConfig?: string;
     }) => Promise<ICheckTableConfig | undefined>;
-    /** 请求自定义数据源 */
+    /** 请求自定义数据源；整份表单只执行一次。 */
     requestCustomSourceData: (payload: {
-        /** 纸张信息 */
-        paper: any;
+        formConfig: Record<string, any>;
         /** 参数配置 */
         paramsConfig: any;
         /** 表单实例id */
@@ -81,20 +81,18 @@ export declare const transformUtils: {
         /** 子表信息 */
         subTableInfo: Array<any>;
     }) => Promise<any[]>;
-    /** 初始化数据事件 */
+    /** 初始化数据事件；整份多 Sheet 表单只执行一次。 */
     getEventInitDataLoad: (payload: {
-        /** 纸张信息 */
-        paper: any;
+        formConfig: Record<string, any>;
         /** 参数配置 */
         paramsConfig: any;
         /** 渲染模式 */
         viewMode: RenderModeEnum;
         ofCtx: any;
     }) => Promise<any>;
-    /** 设置字段事件 */
-    setEventInstance: (payload: {
-        /** 纸张信息 */
-        paper: any;
+    /** 创建字段事件执行器；注册后由 RuntimeInstanceRecord 持有，全部 Sheet 共用。 */
+    createScriptRunner: (payload: {
+        formConfig: Record<string, any>;
         formState: any;
         /** 渲染模式 */
         viewMode: RenderModeEnum;
@@ -125,7 +123,9 @@ export declare const transformUtils: {
         /** 子表处理工厂 */
         subTableCoreFactory: SubTableCoreFactory;
         /** 纸张信息 */
-        paper: any;
+        formConfig: Record<string, any>;
+        /** 与 Store/渲染端共用的实例级二维关联配置。 */
+        tableRelations?: readonly RuntimeTableRelation[];
     }) => {
         _DICT: {};
         _OPCT: {};
@@ -137,8 +137,12 @@ export declare const transformUtils: {
         _OPCT: {};
         _MCTABLE: {};
     };
-    /** 数据转成真实提交数据（二维表要平铺） */
-    getSubmitFormData: (formData: any, paper: IPaper) => Partial<{}>;
+    /** 数据转成真实提交数据（二维表要平铺）；layout 是所有 Sheet 的业务表汇总索引。 */
+    getSubmitFormData: (formData: any, layout: {
+        subTable2DList?: any[];
+        checkTable2DList?: any[];
+        materialConsumeTableList?: any[];
+    }) => Partial<{}>;
     getFormDataIdsMap: (formData: any, preserveKeys?: string[]) => any;
 };
 export {};

package/dist/src/nocode-base/src/runtime/async-task-coordinator.d.ts

@@ -0,0 +1,66 @@
+import { BusinessFieldIdentity } from './field-identity';
+/** 任务从登记到结束的状态；失败任务会保留到替换、取消或实例销毁。 */
+export type RuntimeAsyncTaskStatus = 'pending' | 'fulfilled' | 'rejected' | 'cancelled';
+/** 暴露给界面和诊断逻辑的任务信息，不包含 Promise、序号等内部对象。 */
+export interface RuntimeAsyncTaskSnapshot {
+    /** 实例内稳定的任务键，例如 upload:file:{widgetId}:{fileUid}。 */
+    key: string;
+    /** 业务字段路径，用于提交失败时指出具体字段。 */
+    fieldKey?: string;
+    /** 模型 + 字段身份，数据路径相同时也能指出具体业务字段。 */
+    fieldIdentity?: BusinessFieldIdentity;
+    /** 任务所属 Sheet，用于后续错误导航和标签提示。 */
+    sheetId?: string;
+    /** 提交是否必须等待此任务完成。 */
+    required: boolean;
+    status: RuntimeAsyncTaskStatus;
+    /** rejected 状态对应的原始错误。 */
+    error?: unknown;
+}
+export interface RunRuntimeAsyncTaskOptions {
+    /** 任务对应的业务字段路径。 */
+    fieldKey?: string;
+    /** 模型 + 字段身份，数据路径相同时也能指出具体业务字段。 */
+    fieldIdentity?: BusinessFieldIdentity;
+    /** 任务对应的工作表。 */
+    sheetId?: string;
+    /** 默认 true；为 true 时提交事务会等待它并检查执行结果。 */
+    required?: boolean;
+    /** 默认 true；同 key 新任务开始前是否主动终止旧任务。 */
+    replace?: boolean;
+}
+/**
+ * 表单实例级异步任务中心。
+ *
+ * 上传、扫码、设备读取、公式和远程回填可能在切换 Sheet 后才返回。协调器按任务 key
+ * 保存当前有效任务，同 key 的新任务会让旧结果失效，从而阻止过期响应覆盖新输入。
+ * RuntimePersistenceCoordinator 在提交前调用 waitForRequired()，保证提交数据已经包含所有
+ * 必须完成的异步结果。每个 RuntimeInstanceRecord 只创建一个协调器，由全部 Sheet 共享。
+ */
+export declare class RuntimeAsyncTaskCoordinator {
+    /** 只保留仍需跟踪的任务；成功任务完成后立即移除，失败任务保留用于提交报错。 */
+    private readonly tasks;
+    /** 实例内单调递增的任务版本，用于识别同 key 的过期响应。 */
+    private sequence;
+    /**
+     * 登记并执行一个异步任务。
+     *
+     * executor 应使用传入的 AbortSignal 中止可取消的网络或设备操作。即使底层操作不支持
+     * 中止，完成回调仍会通过 sequence 和 signal 判断是否过期；过期结果统一返回 undefined，
+     * 调用方不得再据此回填字段。
+     */
+    run<T>(key: string, executor: (signal: AbortSignal) => Promise<T>, options?: RunRuntimeAsyncTaskOptions): Promise<T | undefined>;
+    /** 取消指定 key 的当前任务；后续返回值会被 run() 的竞态检查丢弃。 */
+    cancel(key: string): void;
+    /**
+     * 等待全部 required 任务达到稳定状态。
+     *
+     * 一轮任务完成后的字段回填可能触发新的公式或远程任务，因此这里循环读取任务表，直到
+     * 没有新的 pending required 任务。稳定后统一检查失败项，使提交事务得到明确失败原因。
+     */
+    waitForRequired(keyPrefix?: string): Promise<void>;
+    /** 返回只读用途的任务快照，避免外部代码操作内部 Promise 和 AbortController。 */
+    snapshots(): RuntimeAsyncTaskSnapshot[];
+    /** 实例销毁时取消全部任务，防止卸载后的异步响应继续回填数据。 */
+    dispose(): void;
+}

package/dist/src/nocode-base/src/runtime/conversions/business-row.d.ts

@@ -0,0 +1,2 @@
+/** 历史查询结果的 _item 包装只在结果输入边界展开，展示和关联筛选消费同一行结构。 */
+export declare function normalizeHistoricalBusinessRow(row: any): any;

package/dist/src/nocode-base/src/runtime/conversions/field-config.d.ts

@@ -0,0 +1,4 @@
+/** 仅复制发生转换的分支，不修改传入的模板或后端运行时快照。 */
+export declare function normalizeHistoricalFieldConfig(value: any): any;
+/** 历史 RDO 的 __DEFAULT__ 是部分字段默认值；在选中对象输入边界补齐后再交给自动填充。 */
+export declare function normalizeHistoricalAutofillRow(defaults: Record<string, any> | undefined, row: Record<string, any>): Record<string, any>;

package/dist/src/nocode-base/src/runtime/conversions/historical-annotation.d.ts

@@ -0,0 +1,15 @@
+import { RuntimeFieldRegistry } from '../runtime-field-registry';
+import { RuntimeFormStateStore } from '../runtime-form-state-store';
+export interface HistoricalAnnotationConversionContext {
+    /** 所属实例的统一字段索引，用于补齐模型身份及真实业务字段。 */
+    fields: RuntimeFieldRegistry;
+    /** 所属实例的数据，只查询稳定行键，不按当前下标猜测历史行。 */
+    formState: RuntimeFormStateStore;
+    sheetId?: string;
+}
+/**
+ * 已携带稳定行键的旧 __RID__/__FIELD__ 坐标转为统一字段位置，移除冗余 __COL__ 列下标。
+ * 新字段位置和行级位置直接保留；纯下标路径、模型歧义或不存在的行返回 undefined。
+ * 只返回转换结果，不修改批注原记录、模板或填报数据。
+ */
+export declare function convertHistoricalAnnotationLocation(path: string, { fields, formState, sheetId }: HistoricalAnnotationConversionContext): string | undefined;

package/dist/src/nocode-base/src/runtime/conversions/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 历史数据转换的统一目录。
+ * 后续格式转换按对象分别建文件，在模板/草稿/批注等输入边界调用；
+ * 转换后交给标准 runtime，不在组件或实例服务内分散识别历史结构。
+ * 转换函数只整理数据，不发请求、不操作 DOM，也不自行保存业务数据。
+ */
+export * from './v1-runtime';
+export * from './historical-annotation';
+export * from './field-config';
+export { normalizeAIOcrTmpl } from './ocr-template';
+export * from './business-row';

package/dist/src/nocode-base/src/runtime/conversions/ocr-template.d.ts

@@ -0,0 +1,7 @@
+import { DeviceLink } from '../../hooks/device-link/types';
+export declare const DEFAULT_RECOMMENDED_PROMPT = "\u4EFB\u52A1\uFF1A\u56FE\u7247OCR\u6587\u5B57\u63D0\u53D6\n\u89C4\u5219\uFF1A\u4E0D\u865A\u6784\u5185\u5BB9\uFF0C\u627E\u4E0D\u5230\u6570\u636E\u8FD4\u56DE\u7A7A\uFF0C\u4EC5\u8F93\u51FA\u63D0\u53D6\u7ED3\u679C\n\u7ED3\u679C\u586B\u5145\u81F3${\u76EE\u6807\u5B57\u6BB5}\n\u586B\u5199\u63D0\u53D6\u89C4\u5219\uFF1A";
+/**
+ * 补齐 OCR 模板新增字段，并保持历史配置的原有行为。
+ * 历史模板没有提示词模式时按原来的普通模式处理。
+ */
+export declare function normalizeAIOcrTmpl(tmpl: DeviceLink.AIOcrTmpl): DeviceLink.AIOcrTmpl;

package/dist/src/nocode-base/src/runtime/conversions/v1-runtime.d.ts

@@ -0,0 +1,21 @@
+import { NormalizedRuntimeDocument, RuntimeNodeMap } from '../multi-sheet-runtime';
+/** v1 没有 Sheet 标识，转换时使用固定值，保证同一份模板每次打开结果一致。 */
+export declare const LEGACY_RUNTIME_SHEET_ID = "__legacy_sheet__";
+export declare const LEGACY_RUNTIME_SHEET_TITLE = "\u5DE5\u4F5C\u8868 1";
+/** 历史 runtimeJson 中存放在 paper.props、实际属于整份实例的配置。 */
+export declare const LEGACY_RUNTIME_FORM_CONFIG_KEYS: readonly ["globalParams", "paramsMapList", "unitConversionRules", "inspectionDecisionRule", "customDataSource", "objectInitialValues", "javascript", "checkSignatureConfig", "keepExceptionHighlight", "objectFieldList", "dateObjects"];
+/** 历史运行时：paper 和所有节点都直接放在文档顶层。 */
+export interface RuntimeDocumentV1 extends RuntimeNodeMap {
+    schemaVersion?: 1;
+    formConfig?: Record<string, any>;
+    paper: any;
+}
+/** 使用新对象移除已提升到表单层的配置，不修改传入的历史模板。 */
+export declare function stripLegacyFormConfigFromPaper(paper: Record<string, any>): {
+    props: any;
+};
+/**
+ * 将顶层 paper + nodes 包装为单 Sheet，并把历史表单配置提升到 formConfig。
+ * 保留来源版本 1；本函数不保存模板。输出的节点关系由 normalizeRuntime 统一校验。
+ */
+export declare function convertV1Runtime(runtime: Record<string, any>): NormalizedRuntimeDocument;

package/dist/src/nocode-base/src/runtime/date-compliance.d.ts

@@ -0,0 +1,8 @@
+import { FIELD_TYPE } from '../../../shared/enum';
+/**
+ * 日期数据合规处理函数
+ * - 日期字段：截断时间部分，仅保留日期 (例: 2021-05-06 → 2021-05-06, 2021-05-06 00:00:00 → 2021-05-06, 2021-05-06 5:21:12 → 2021-05-06)，格式不符返回空
+ * - 日期时间字段：补充时间部分为00:00:00 (例: 2021-05-06 → 2021-05-06 00:00:00)，格式不符返回空
+ * - 时间字段：截断日期部分，仅保留时间部分 (例: 2021-05-06 5:21:12 → 5:21:12)，格式不符返回空
+ */
+export declare function formatDateCompliance(value: any, fieldTypeVal: FIELD_TYPE): any;

package/dist/src/nocode-base/src/runtime/field-identity.d.ts

@@ -0,0 +1,21 @@
+export interface BusinessFieldIdentity {
+    fieldId?: string;
+    modelKey?: string;
+    subModelKey?: string;
+}
+/** 实际数据字段键与业务身份分开：关联字段写 fieldLink，其余字段写 field。 */
+export declare function getRuntimeDataFieldId(props?: Record<string, any>): string;
+/**
+ * 生成多 Sheet 实例内稳定的业务字段键。
+ * 所有字段都按模型 + 字段区分，不同模型允许存在相同字段 key。
+ */
+export declare function getBusinessFieldKey(field: BusinessFieldIdentity): string;
+/** 一个具体填报位置；二维单元格使用子行自己的 rowKey，无须附加数字列号。 */
+export interface RuntimeFieldPosition extends BusinessFieldIdentity {
+    subFieldKey?: string;
+    rowKey?: string;
+}
+/** 模型和各级键分别编码，避免字段/行键中的下划线、点或分隔符产生歧义。 */
+export declare function buildRuntimeFieldPath(position: RuntimeFieldPosition): string;
+/** 所有校验、批注及导航共用一个解析入口；数字下标路径不再参与新运行时识别。 */
+export declare function parseRuntimeFieldPath(path: string): RuntimeFieldPosition | undefined;

package/dist/src/nocode-base/src/runtime/formula-utils.d.ts

@@ -0,0 +1,7 @@
+import { IParseFormulaVar } from '../types';
+export declare const getParseFormulaVarInfos: (expr?: string) => {
+    rowArgs: string[];
+    parseInfos: IParseFormulaVar[];
+};
+/** 当前行变量从 formData 解析；主表及子表汇总变量从完整实例解析，可跨 Sheet 引用。 */
+export declare const calculateFormula: (expr: string, formData: any, instanceFormState: any) => Promise<any>;

package/dist/src/nocode-base/src/runtime/index.d.ts

@@ -0,0 +1,18 @@
+export * from './multi-sheet-runtime';
+export * from './conversions';
+export * from './runtime-context';
+export * from './field-identity';
+export * from './table-row-identity';
+export * from './runtime-instance-controller';
+export * from './runtime-sheet-service';
+export * from './runtime-form-state-store';
+export * from './async-task-coordinator';
+export * from './runtime-dependency-service';
+export * from './runtime-instance-registry';
+export type { RuntimeConsoleDebug, RuntimeConsoleDebugTarget, RuntimeSubmitDataDebugOptions, } from './runtime-console-debug';
+export * from './runtime-rule-compiler';
+export * from './runtime-field-registry';
+export * from './runtime-persistence-coordinator';
+export * from './runtime-instance-event-bus';
+export * from './runtime-validation-service';
+export { calculateFormula, getParseFormulaVarInfos } from './formula-utils';

package/dist/src/nocode-base/src/runtime/multi-sheet-runtime.d.ts

@@ -0,0 +1,43 @@
+/** 当前真实多 Sheet 运行时格式版本。缺少版本号的历史数据按 v1 解析。 */
+export declare const MULTI_SHEET_SCHEMA_VERSION: 2;
+export type RuntimeNodeMap = Record<string, any>;
+export interface RuntimeSheetV2 {
+    sheetId: string;
+    title: string;
+    paper: any;
+    nodes: RuntimeNodeMap;
+}
+export interface RuntimeDocumentV2 {
+    schemaVersion: typeof MULTI_SHEET_SCHEMA_VERSION;
+    /** 整份实例只执行一次的数据、规则和脚本配置。 */
+    formConfig: Record<string, any>;
+    /** 数组顺序就是创建顺序，同时也是运行端标签和打印顺序。 */
+    sheets: RuntimeSheetV2[];
+}
+export interface NormalizedRuntimeSheet extends RuntimeSheetV2 {
+    /** Sheet 自己拥有的 paper + nodes，不包含实例级 formConfig。 */
+    dataCenter: RuntimeNodeMap;
+}
+export interface NormalizedRuntimeDocument {
+    /** 原始数据所属版本；调用方后续不需要再分支解析数据结构。 */
+    schemaVersion: 1 | typeof MULTI_SHEET_SCHEMA_VERSION;
+    formConfig: Record<string, any>;
+    sheets: NormalizedRuntimeSheet[];
+}
+/**
+ * 将历史 v1 和真实多 Sheet v2 统一为同一种读取结构。
+ *
+ * - v1：顶层 paper + nodes，包装成一个固定标识的虚拟 Sheet。
+ * - v2：读取有序 sheets，并为现有单 Sheet 渲染器组装 dataCenter。
+ * - 未知版本：直接报错，避免旧客户端误写更高版本数据。
+ */
+export declare function normalizeRuntime(runtime: unknown): NormalizedRuntimeDocument;
+/**
+ * 将各 Sheet 独立编译得到的旧式 dataCenter 封装为 v2 文档。
+ * 保存前复用统一解析器，保证整份模板的节点唯一性和引用完整性。
+ */
+export declare function createRuntimeDocumentV2(sheets: Array<{
+    sheetId: string;
+    title: string;
+    runtime: RuntimeNodeMap;
+}>, formConfig?: Record<string, any>): RuntimeDocumentV2;

package/dist/src/nocode-base/src/runtime/runtime-console-debug.d.ts

@@ -0,0 +1,36 @@
+import { RuntimeInstanceRegistry } from './runtime-instance-registry';
+export interface RuntimeSubmitDataDebugOptions {
+    /** 默认 false；true 时执行正式提交校验，失败时沿用错误导航。 */
+    validate?: boolean;
+    /** 多个宿主具有相同 uniqueId 时，用 list() 返回的 registryId 指定宿主。 */
+    registryId?: string;
+}
+export interface RuntimeConsoleDebug {
+    /** 列出全部宿主当前已注册的实例，并用 console.table 展示概要。 */
+    list(): Array<ReturnType<RuntimeInstanceRegistry['getDebugSummaries']>[number] & {
+        registryId: string;
+    }>;
+    /** 查看并打印实例快照；只有一份实例时可不传 uniqueId。 */
+    inspect(uniqueId?: string, registryId?: string): ReturnType<RuntimeInstanceRegistry['debug']>;
+    /** 只返回填报数据快照，方便在控制台展开或 copy()。 */
+    data(uniqueId?: string, registryId?: string): Record<string, any>;
+    /**
+     * 默认跳过校验，收口编辑器并打印转换后的 payload，不发送请求，也不产生校验结果。
+     * options.validate=true 才执行校验/错误导航；使用 await 获取结果。
+     */
+    submitData(uniqueId?: string, options?: RuntimeSubmitDataDebugOptions): ReturnType<RuntimeInstanceRegistry['debugSubmitData']>;
+    /** 查看真实注册字段及数据路径，包含内部 value_ 和引用位置；返回独立快照。 */
+    fields(uniqueId?: string, registryId?: string): ReturnType<RuntimeInstanceRegistry['getFieldDebugSnapshot']>['fields'];
+    /** 查看某个 Sheet 的完整节点和分页；省略 sheetId 时查看活动 Sheet。 */
+    sheet(sheetId?: string, uniqueId?: string, registryId?: string): ReturnType<RuntimeInstanceRegistry['getSheetDebugSnapshot']>;
+}
+export interface RuntimeConsoleDebugTarget {
+    ncbRuntime?: RuntimeConsoleDebug;
+}
+declare global {
+    interface Window {
+        ncbRuntime?: RuntimeConsoleDebugTarget['ncbRuntime'];
+    }
+}
+/** Registry 的浏览器接入实现；类型导入避免与 Registry 产生运行时循环依赖。 */
+export declare function attachRuntimeConsoleDebug(registry: RuntimeInstanceRegistry, target: RuntimeConsoleDebugTarget): () => void;

package/dist/src/nocode-base/src/runtime/runtime-context.d.ts

@@ -0,0 +1,122 @@
+import { IPageData } from '../types';
+import { NormalizedRuntimeDocument, RuntimeNodeMap } from './multi-sheet-runtime';
+import { SubTableCoreFactory } from '../core/factory/sub-table-factory';
+import { FormTmplBomController } from '../hooks/material-consume/tmpl-bom-controller';
+import { ICheckTableConfig } from '../interface/front-config';
+export type RuntimeSheetStatus = 'idle' | 'initializing' | 'ready' | 'error';
+/**
+ * 模板中一个字段的业务身份及版式位置，不代表子表中的某一条填报数据。
+ * 具体数据行由 RuntimeFieldPosition.rowKey（front_row_key_）另行定位。
+ *
+ * 普通子表字段示例：modelKey = subModelKey = 'detail_model'，
+ * subFieldKey = 'items'，fieldId = 'qty'，表示 formState.items 某行的 qty。
+ * 两个模型 key 相同是正常的：字段属于该子模型，也位于该子模型的子表中。
+ */
+export interface RuntimeFieldLocation {
+    /** 字段所在工作表的稳定 ID，用于跨 Sheet 查询和导航。 */
+    sheetId: string;
+    /** 字段所在的模板节点 ID，通常是单元格节点；不是单元格内部控件的 widgetId。 */
+    nodeId?: string;
+    /** 业务字段 key，不含模型前缀；检验表内部结果字段也可能是 value_。 */
+    fieldId: string;
+    /**
+     * 字段所属模型，来自设计态 fieldMeta.model，不表示表单主模型。
+     * 普通子表字段填写子模型 key；关联模型字段填写其所属模型 key。
+     * 表单主模型另由实例基础信息 basicInfo.modelKey 表达。
+     */
+    modelKey?: string;
+    /**
+     * 承载字段数据的子表数组 key，例如 items，对应 formState.items；主表字段通常为空。
+     * 它描述数据路径，不是模型 key；二维交叉字段通过该数组中的 _2DTABLE_ 子行取值。
+     */
+    subFieldKey?: string;
+    /**
+     * 字段所在子表的模型 key，不是主模型 key；主表字段通常为空。
+     * 普通子表字段与 modelKey 相同；引用其他模型字段时，两者可能不同。
+     * 当前业务身份取 subModelKey ?? modelKey，再与 fieldId 组合生成 businessKey。
+     */
+    subModelKey?: string;
+    /**
+     * 是否为用户实际放置的字段；联动引用、公式输入等内部依赖为 false。
+     * 不表示当前是否可编辑：被禁用的已放置字段仍为 true。
+     */
+    placement: boolean;
+}
+/** 全部 Sheet 汇总后的实例级业务索引。 */
+export interface RuntimeBusinessIndex {
+    /** 主模型展示信息来自全部 Sheet 的初始化扫描，校验文案不跟随当前标签变化。 */
+    modelDisplay: {
+        key: string;
+        name: string;
+    };
+    subTableInfo: any[];
+    foreignFields: any[];
+    subModelFields: any[];
+    useDefaultValueFields: any[];
+    useAppendixFields: any[];
+    useSignatureFields: any[];
+    useSignFields: any[];
+    useClsReasonDataLink: string[];
+    useClsGroupDataLink: string[];
+    /** 跨 Sheet 提交和校验消费的业务版式索引。 */
+    subTable2DList: any[];
+    checkTable2DList: any[];
+    materialConsumeTableList: any[];
+    materialBalanceTableList: any[];
+    fixedTables: any[];
+    fixedTableLenMap: Record<string, any>;
+    fixedTableFieldMap: Record<string, any>;
+}
+/** Sheet 级状态：只保存该 Sheet 的版式、分页和界面状态。 */
+export interface RuntimeSheetContext {
+    sheetId: string;
+    title: string;
+    dataCenter: RuntimeNodeMap;
+    pageData: IPageData[];
+    scrollTop: number;
+    /** formState 变化后是否需要重新分页。 */
+    paginationDirty: boolean;
+    /** 最近一次成功分页对应的 formState revision。 */
+    paginationRevision: number;
+    /** 分页失败保留上一份可用布局；与模板初始化的 status/errorMessage 分开管理。 */
+    paginationError?: string;
+    status: RuntimeSheetStatus;
+    errorMessage?: string;
+}
+/**
+ * 业务初始化阶段产生的实例共享服务及快照。
+ *
+ * 数据 Store、脚本执行器和运行时基础服务由 RuntimeInstanceRecord 管理。
+ * 这里只保留业务模块需要的对象，不再镜像数据和脚本实例。
+ */
+export interface RuntimeInstanceServices {
+    subTableCoreFactory?: SubTableCoreFactory;
+    tmplBomController?: FormTmplBomController;
+    /** 本次初始化取得的检验表快照，保留给实例级业务流程使用。 */
+    checkTableConfig?: ICheckTableConfig;
+}
+/** 实例配置、业务索引与 Sheet 状态；业务数据统一从实例记录的 FormStateStore 获取。 */
+export interface RuntimeInstanceContext {
+    uniqueId: string;
+    instanceId: string;
+    templateId: string;
+    schemaVersion: NormalizedRuntimeDocument['schemaVersion'];
+    formConfig: Record<string, any>;
+    defaultData: Record<string, any>;
+    businessIndex: RuntimeBusinessIndex;
+    /** 初始化阶段的业务服务与快照；运行时基础服务从 RuntimeInstanceRecord 获取。 */
+    services: RuntimeInstanceServices;
+    activeSheetId: string;
+    /** 顺序与 runtimeJson.sheets 一致，也是标签和打印顺序。 */
+    sheets: RuntimeSheetContext[];
+}
+export interface CreateRuntimeInstanceContextOptions {
+    uniqueId: string;
+    instanceId: string;
+    templateId: string;
+    runtime: NormalizedRuntimeDocument;
+    defaultData: Record<string, any>;
+    activeSheetId?: string;
+}
+/** 从统一解析结果建立“实例 + Sheet”两级运行时状态。 */
+export declare function createRuntimeInstanceContext(options: CreateRuntimeInstanceContextOptions): RuntimeInstanceContext;

package/dist/src/nocode-base/src/runtime/runtime-dependency-service.d.ts

@@ -0,0 +1,82 @@
+import { FormStateChange, RuntimeFormStateStore } from './runtime-form-state-store';
+import { RuntimeAsyncTaskCoordinator } from './async-task-coordinator';
+/** 条件输出按设计控件 + 类型 + Store 稳定行路径区分；二维行也使用自己的稳定身份。 */
+export declare function getRuntimeDependencyOutputKey(widgetId: string, type: string, rowPath: string): string;
+/** 业务身份与数据路径分别保存：不同模型字段不能靠相同 fieldId 识别。 */
+export interface RuntimeDependencyFieldReference {
+    modelKey?: string;
+    subModelKey?: string;
+    fieldId?: string;
+    subFieldKey?: string;
+    /** 必须与 Store 变更路径一致；不能直接在旧路径前拼接模型名。 */
+    dataPath: string;
+}
+/** 异步规则在提交结果前必须检查有效性，任务返回后的检查无法撤销已经写入的数据。 */
+export interface RuntimeDependencyExecution {
+    signal: AbortSignal;
+    isCurrent(): boolean;
+    /** 原子替换本规则的全部条件输出，自动清除已经删除的行；过期执行不能发布。 */
+    replaceOutputs(values: ReadonlyMap<string, unknown>): boolean;
+}
+export interface RuntimeDependencyEffect {
+    id: string;
+    targetField?: RuntimeDependencyFieldReference;
+    sheetId?: string;
+    /** 普通字段依赖；空数组表示常量表达式，仅初始化和结构变化时执行。 */
+    sourceFields?: RuntimeDependencyFieldReference[];
+    /** 目标子表行/列结构依赖，只匹配该结构或其父路径，不匹配普通单元格写入。 */
+    structureFields?: string[];
+    run(change: FormStateChange, execution: RuntimeDependencyExecution): void | Promise<void>;
+}
+/**
+ * 实例级联动调度器，统一执行 formulaExpr、条件属性及赋值 effect。
+ * 按 Store 路径筛选规则，同一微任务合并变更，公式产生的新变更继续进入下一轮。
+ * 排队阶段就登记 required 任务，提交会等待整条联动链；过期与销毁的执行不可回写。
+ */
+export declare class RuntimeDependencyService {
+    private readonly formState;
+    private readonly asyncTasks;
+    private readonly effects;
+    private readonly pendingChanges;
+    private readonly executions;
+    /** 每条规则拥有自己的输出集合，替换和注销规则时同时释放。 */
+    private readonly outputKeys;
+    /** 条件输出只有本服务可写，组件与校验通过 getOutput 读取。 */
+    private readonly outputs;
+    private scheduled;
+    private disposed;
+    /** 不收敛的公式链不能无限占用微任务，也不能被提交当作成功。 */
+    private formulaRounds;
+    private readonly unsubscribe;
+    constructor(formState: RuntimeFormStateStore, asyncTasks: RuntimeAsyncTaskCoordinator, 
+    /** 打印副本只读取已计算的条件结果，不注册或重新执行业务规则。 */
+    initialOutputs?: Readonly<Record<string, unknown>>);
+    register(effect: RuntimeDependencyEffect): () => void;
+    private replaceOutputs;
+    private clearOutputs;
+    getOutput<T = unknown>(key: string): T | undefined;
+    /** 条件结果与数据一起进入打印快照，未访问的 Sheet 不依赖控件挂载重新计算。 */
+    getOutputSnapshot(): Record<string, unknown>;
+    /** 调试查询只描述调度状态，不返回规则执行函数或可写的条件结果引用。 */
+    getDebugSnapshot(): {
+        scheduled: boolean;
+        pendingChangeCount: number;
+        runningRuleIds: string[];
+        rules: {
+            id: string;
+            targetField?: RuntimeDependencyFieldReference;
+            sheetId?: string;
+            /** 普通字段依赖；空数组表示常量表达式，仅初始化和结构变化时执行。 */
+            sourceFields?: RuntimeDependencyFieldReference[];
+            /** 目标子表行/列结构依赖，只匹配该结构或其父路径，不匹配普通单元格写入。 */
+            structureFields?: string[];
+        }[];
+        outputs: Record<string, unknown>;
+    };
+    runAll(source?: FormStateChange['source']): Promise<void>;
+    dispose(): void;
+    private matches;
+    private cancelExecution;
+    private schedule;
+    private runEffects;
+}

package/dist/src/nocode-base/src/runtime/runtime-field-initializer.d.ts

@@ -0,0 +1,26 @@
+import { IBasicInfoItem } from '../types';
+import { RuntimeInstanceRecord } from './runtime-instance-registry';
+type InitializerMetadata = {
+    materialNo?: string;
+    params?: string;
+    instanceStatus?: string;
+};
+export declare class RuntimeFieldInitializer {
+    private readonly record;
+    private readonly info;
+    private readonly metadata;
+    private readonly initialized;
+    private readonly tasks;
+    private readonly requests;
+    private suite?;
+    private disposed;
+    private scheduled;
+    private readonly unsubscribe;
+    constructor(record: RuntimeInstanceRecord, info: IBasicInfoItem, metadata: InitializerMetadata);
+    /** 初次加载等待全部目标；失败保留在任务中心，不能把未完成的默认值当成可提交数据。 */
+    initialize(): Promise<void>;
+    private request;
+    private readDefault;
+    dispose(): void;
+}
+export {};