@gct-paas/excel 0.1.37 → 0.1.39-beta.1

package/dist/src/nocode-base/src/hooks/useRuntimeInstanceServices.d.ts

@@ -0,0 +1,44 @@
+import { RuntimeEditorFlusher } from '../runtime/runtime-instance-controller';
+type RuntimeInstanceIdSource = () => string | undefined;
+/**
+ * 组件获取实例配置、控制器和共享服务的统一入口，按需解构返回的 computed 引用。
+ * 默认从字段上下文取实例 ID；宿主或纸张组件可传入 ID getter，跟随 props 切换。
+ * 所有引用共享一次实例解析，服务仍由 Registry 创建和销毁，Hook 只负责读取。
+ */
+export declare function useRuntimeInstanceServices(uniqueIdSource?: RuntimeInstanceIdSource): {
+    instance: import('vue').ComputedRef<import('..').RuntimeInstanceRecord | undefined>;
+    /** 控制器负责 Sheet 切换、编辑器收口和提交；尚未挂载时为空。 */
+    controller: import('vue').ComputedRef<import('..').RuntimeInstanceController | undefined>;
+    /** 表单级配置独立于 Sheet 的 paper；实例未注册时提供空配置。 */
+    formConfig: import('vue').ComputedRef<Record<string, any>>;
+    /** 实例切换时重新取对应 Store；读取数据使用 .value.state，写入使用 Store 方法。 */
+    formStateStore: import('vue').ComputedRef<import('..').RuntimeFormStateStore | undefined>;
+    /**
+     * 实例级异步任务协调器：上传、扫码和远程回填通过 .value.run() 登记任务。
+     * 同 key 的新任务使旧结果失效；提交前等待 required 任务，所有 Sheet 共用同一份。
+     */
+    asyncTasks: import('vue').ComputedRef<import('..').RuntimeAsyncTaskCoordinator | undefined>;
+    /**
+     * 实例级联动调度器：监听 Store 变更，统一执行公式、赋值及条件必填/禁用规则。
+     * 组件通过 .value.getOutput() 读取条件结果，未挂载的 Sheet 也参与联动计算。
+     */
+    dependencies: import('vue').ComputedRef<import('..').RuntimeDependencyService | undefined>;
+    /**
+     * 实例级字段注册表：按模型 + 字段身份查询控件及其 Sheet、节点和数据路径。
+     * 供校验、联动、分页失效及导航定位使用；只维护位置索引，不保存填报数据或错误。
+     */
+    fields: import('vue').ComputedRef<import('..').RuntimeFieldRegistry | undefined>;
+    /** 分页与业务位置导航共用同一实例服务。 */
+    sheetService: import('vue').ComputedRef<import('..').RuntimeSheetService | undefined>;
+    /** 暂存与提交共享同一协调器，实例替换时整体切换。 */
+    persistence: import('vue').ComputedRef<import('..').RuntimePersistenceCoordinator | undefined>;
+    /** 校验规则及调度由当前实例持有，签名和失焦校验直接调用此服务。 */
+    validation: import('vue').ComputedRef<import('..').RuntimeValidationService | undefined>;
+    /** 实例共享的业务 BOM 控制器，打印副本持有独立展示控制器。 */
+    tmplBomController: import('vue').ComputedRef<import('./material-consume').FormTmplBomController | undefined>;
+    /** 当前实例的 UI 事件总线，批注等展示事件不会跨实例传播。 */
+    events: import('vue').ComputedRef<import('..').RuntimeInstanceEventBus | undefined>;
+};
+/** 注册需要在 Sheet 切换前提交内部状态的编辑器 */
+export declare function useRuntimeEditorFlusher(flusher: RuntimeEditorFlusher): void;
+export {};

package/dist/src/nocode-base/src/hooks/useRuntimeRowState.d.ts

@@ -0,0 +1,16 @@
+import { FormStateMutationSource } from '../runtime/runtime-form-state-store';
+/** 字段组件和业务辅助函数共用的显式行写入口，调用时必须声明修改来源。 */
+export interface RuntimeRowWriter {
+    setRowField(fieldKey: string, value: any, source: FormStateMutationSource): void;
+    patchRow(values: Record<string, any>, source: FormStateMutationSource): void;
+}
+/**
+ * 组件只读取 formData，写入通过此 Hook
+ * 每次调用都重新读取当前行和实例，避免动态表换行或草稿恢复后继续修改旧对象
+ */
+export declare function useRuntimeRowState(rowSource: () => Record<string, any>): {
+    setRowField: (fieldKey: string, value: any, source: FormStateMutationSource) => void;
+    patchRow: (values: Record<string, any>, source: FormStateMutationSource) => void;
+    getRowFieldPath: (fieldKey: string) => string;
+    markRowFieldUserModified: (fieldKey: string) => void;
+};

package/dist/src/nocode-base/src/hooks/validation/attach.d.ts

@@ -1,21 +1,15 @@
-import { FormRuleMeta } from './types';
-/** 规则上挂载的引用字段上下文 */
+import { FormRuleAttach } from './types';
+/** 公式校验器通过 rule 取得当前行，仅保留稳定行定位信息。 */
 export type AttachRuleContext = {
-    _belongFieldId?: string;
-    _optionValue?: any;
-    _multiple?: boolean;
     _subtableFieldId?: string;
-    _realRowIndex?: number;
-    _childSubTableDataIndex?: number;
+    _rowKey?: string;
 };
 /** 取规则对应的当前行 / 主表 formData */
 export declare function getCurrentFormData(_rule: AttachRuleContext, options: {
     formData?: any;
 }): any;
-/** 从 rule 或 meta.attach 解析上下文 */
-export declare function resolveAttachContext(rule: AttachRuleContext | undefined, metaAttach?: FormRuleMeta['attach']): AttachRuleContext | undefined;
 /** 引用字段是否处于激活选项下 */
-export declare function isAttachFieldActive(rule: AttachRuleContext | undefined, formData: Record<string, any> | undefined): boolean;
+export declare function isAttachFieldActive(attach: FormRuleAttach | null | undefined, formData: Record<string, any> | undefined): boolean;
 /** 当前行数据下引用字段是否应对用户呈现 */
 export declare function isReferenceOptionActive(referenceInfo: {
     belongFieldId?: string;

package/dist/src/nocode-base/src/hooks/validation/createValidateFactory.d.ts

@@ -5,6 +5,7 @@ type AssembleRulesInput = {
     fieldType?: string;
     validatorInfo: Record<string, any>;
     props: {
+        bizType?: string;
         minlength?: number | null;
         maxlength?: number | null;
         regex?: string;

package/dist/src/nocode-base/src/hooks/validation/merge.d.ts

@@ -18,7 +18,8 @@ export declare function mergeSubmitValidation(current: ValidationCommentMap, sub
 /** 子表结构变更后，去掉已失效 path 的错误态 */
 export declare function pruneValidationComments(current: ValidationCommentMap, validPaths: Set<string>): ValidationCommentMap;
 /**
- * display 合并：按本轮 validatedPaths 更新；清掉已卸载 path
+ * display 合并：按本轮 validatedPaths 更新；清掉已卸载 path。
+ * 可编辑字段的必填错误由提交校验产生，空值在 display/change 模式下不会重跑 manual 规则。
  */
-export declare function mergeDisplayValidation(current: ValidationCommentMap, displayResult: ValidationCommentMap, ruleKeys: string[], validatedPaths: string[]): ValidationCommentMap;
+export declare function mergeDisplayValidation(current: ValidationCommentMap, displayResult: ValidationCommentMap, ruleKeys: string[], validatedPaths: string[], resolvePayload: ResolvePayload): ValidationCommentMap;
 export {};

package/dist/src/nocode-base/src/hooks/validation/runValidation.d.ts

@@ -1,17 +1,14 @@
-import { IPaper } from '../../types';
-import { ValidationRunMode, ValidateResult } from './types';
+import { ValidationRunMode, ValidateResult, FormRuleEntry } from './types';
 type RunValidationOptions = {
+    entries: ReadonlyMap<string, FormRuleEntry>;
     mode?: ValidationRunMode;
     /** 表单级 keepExceptionHighlight */
     keepExceptionHighlight?: boolean | null;
+    /** 可选的目标字段路径；未传时校验当前表单的全部已注册字段 */
+    paths?: Iterable<string>;
 };
 /**
  * 按 mode 过滤规则并执行 async-validator
  */
-export declare function runValidation(formData: Record<string, any>, paper: IPaper, options?: RunValidationOptions): Promise<ValidateResult | undefined>;
-/** 供 merge 使用：取某 path 当前值与规则 */
-export declare function resolvePayloadForPath(path: string, flatData: Record<string, any>): {
-    value: any;
-    rules: any[];
-} | null;
+export declare function runValidation(formData: Record<string, any>, options: RunValidationOptions): Promise<ValidateResult>;
 export {};

package/dist/src/nocode-base/src/hooks/validation/types.d.ts

@@ -12,20 +12,22 @@ export type ValidateTrigger = 'change' | 'blur' | 'manual';
  * - display: 展示用（只读含必填；可编辑不含必填），不拦提交
  */
 export type ValidationRunMode = ValidateTrigger | 'all' | 'display';
+export interface FormRuleAttach {
+    belongFieldId: string;
+    optionValue: any;
+    multiple?: boolean;
+    subtableFieldId?: string;
+    rowKey?: string;
+    /** 嵌套引用条件从内层向外层串联，任一未激活就跳过当前字段。 */
+    parent?: FormRuleAttach;
+}
 export type FormRuleMeta = {
     /** 禁用 / 只读，不可编辑 */
     blocked: boolean;
     /** 字段级：是否在 display 时保留异常标红；未配置时跟随表单 */
     keepExceptionHighlight?: boolean;
     /** 布尔/枚举引用字段附着上下文（门禁用，不依赖 rule 对象上的挂载字段） */
-    attach?: {
-        belongFieldId: string;
-        optionValue: any;
-        multiple?: boolean;
-        subtableFieldId?: string;
-        realRowIndex?: number;
-        childSubTableDataIndex?: number;
-    } | null;
+    attach?: FormRuleAttach | null;
 };
 export type ValidateResult = {
     isValid: boolean;
@@ -42,3 +44,8 @@ export type ValidateResult = {
     flatData?: Record<string, any>;
 };
 export type ValidationCommentMap = Record<string, any[]> | null;
+/** 实例编译器原子发布的一条字段规则及门禁元数据。 */
+export interface FormRuleEntry {
+    rules: any[];
+    meta: FormRuleMeta;
+}

package/dist/src/nocode-base/src/hooks/validation/utils.d.ts

@@ -9,6 +9,12 @@ export declare const rangeCompareMessage: (op: RangeCompareOp, val: any) => stri
  */
 export declare const toUnixTimestamp: (input: any) => number | null;
 export declare const buildError: (validatorInfo: any, message: string) => string;
+/**
+ * 比较错误内容时显式包含 message：async-validator 的公式规则可能返回原生 Error，
+ * 其 message 不可枚举，直接 JSON.stringify 会漏掉变化后的上下限文案。
+ * 普通字段和业务校验共用此比较，保留字段及其他错误信息原有的变化判断。
+ */
+export declare function areValidationCommentsEqual(left: any[] | undefined, right: any[] | undefined): boolean;
 export declare const createRule: (validator: Function, message: string, trigger?: ValidateTrigger) => {
     required: boolean;
     validator: Function;

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

@@ -5,3 +5,5 @@ export * from './components';
 export * from './interface';
 export * from './emit';
 export * from './core';
+export { ensureFrontRowKey, ensureTableRowKeys } from './_utils_/uuid';
+export * from './runtime';

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

@@ -33,5 +33,5 @@ export declare const calcUtils: {
     pageListRecursion: (realDealWithList: Array<IDealWithItem | IDealWithItem[]>, maxHeight: number) => IPageItem[];
     /** 获取分页数据列表 */
     getPageData: (pageList: any, baseMarketObj: any) => IPageData[];
-    initCalc: (runtimeJson: any, formState: any) => IPageData[];
+    initCalc: (runtimeJson: any, formState: any) => any;
 };

package/dist/src/nocode-base/src/interface/check-ds-data.d.ts

@@ -16,6 +16,9 @@ export interface ICheckDsFetchResult {
     data: any[];
 }
 type CheckDsRuntimeContext = {
+    /** 表单级数据源、模型和脚本配置。 */
+    formConfig: Record<string, any>;
+    /** 当前 Sheet 的检验表结构与行坐标。 */
     paper: any;
     instanceId: string;
     cloneRuntimeJson: Record<string, any>;
@@ -32,14 +35,13 @@ export declare function getCheckTableSnapshotKey(checkInfo: ICheckTable2DInfo):
  * @returns 字段映射 + 原始数据；未配置 M08 数据源时返回 null
  */
 export declare function fetchMedProCheckDsData(payload: {
-    paper: any;
+    formConfig: Record<string, any>;
     instanceId: string;
 }): Promise<ICheckDsFetchResult | null>;
 /**
  * 非 MedPro + checkDsType = default：按检验计划拉取检验项
  */
 export declare function fetchCheckDsDataForTable(payload: {
-    paper: any;
     instanceId: string;
     checkInfo: ICheckTable2DInfo;
 }): Promise<ICheckDsTableFetchResult | null>;
@@ -47,7 +49,6 @@ export declare function fetchCheckDsDataForTable(payload: {
  * 非 MedPro + checkDsType = custom：按自定义检验项拉取
  */
 export declare function fetchCustomCheckDsData(payload: {
-    paper: any;
     instanceId: string;
     checkInfo: ICheckTable2DInfo;
 }): Promise<ICheckDsTableFetchResult | null>;

package/dist/src/nocode-base/src/interface/code-runner.d.ts

@@ -3,6 +3,8 @@ export declare class CodeRunner {
      * 导出方法
      */
     exports: any;
+    /** 实例替换或销毁后禁止再发起脚本事件。 */
+    private disposed;
     /**
      * constructor
      * @param runtimeJs 运行时 js
@@ -16,6 +18,8 @@ export declare class CodeRunner {
      * @returns
      */
     invoke(method: string, ...args: any[]): any;
+    /** 释放导出函数及其对表单数据的闭包引用；已开始执行的用户异步脚本由其自身结束。 */
+    dispose(): void;
     /**
      * 解析可用函数
      * @param code

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';