@gct-paas/word 0.1.52-beta.2 → 0.1.52-beta.3

package/dist/domain/table/registry.d.ts

@@ -1,17 +1,14 @@
-import { DropdownOption, DropdownOptionGroup } from '../../base';
-import { BusinessSubTableProfile, TableProfile } from './types';
-/** 表头（挂在数据表 Ribbon 首位） */
-export declare const TABLE_HEADER_RIBBON_OPTION: DropdownOption;
+import { BusinessSubTableProfile, TableCategory, TableProfile } from './types';
 /** 所有已注册的子表 Profile */
 declare const ALL_TABLE_PROFILES: TableProfile[];
+/** 按分类获取 Profile 列表 */
+export declare function getProfilesByCategory(category: TableCategory): TableProfile[];
 /** 按表类型获取 Profile */
 export declare function getProfile(type: string): TableProfile | undefined;
 /** 按 Ribbon 下拉项 value 获取 Profile */
 export declare function getProfileByRibbonAction(ribbonAction: string): TableProfile | undefined;
 /** 按 layoutType 获取 Profile */
 export declare function getProfileByLayoutType(layoutType: string): TableProfile | undefined;
-/** 按 layout 类型获取展示名称 */
-export declare function getTableLabelByLayoutType(layoutType: string): string;
 /**
  * 收集所有已注册业务表的 refModelType
  * 用于判断 master_slave 字段是否属于业务子模型
@@ -19,11 +16,4 @@ export declare function getTableLabelByLayoutType(layoutType: string): string;
 export declare function getAllBusinessRefModelTypes(): string[];
 /** 按 refModelType 获取业务表 Profile */
 export declare function getBusinessProfileByRefModelType(refModelType: string): BusinessSubTableProfile | undefined;
-/**
- * 生成 Ribbon「数据表」「业务表」下拉选项
- */
-export declare function getRibbonTableOptions(): {
-    dataTables: DropdownOption[];
-    businessTables: DropdownOptionGroup[];
-};
 export { ALL_TABLE_PROFILES };

package/dist/domain/table/runtime/api/biz-service-api.d.ts

@@ -0,0 +1,6 @@
+import { BizServiceApiDef } from '../../types';
+export declare function callBizService(apiDef: BizServiceApiDef, body: Record<string, unknown>): Promise<unknown>;
+/** 解析 biz-service 返回体 */
+export declare function unwrapBizServiceData<T extends Record<string, unknown>>(res: unknown): T | null;
+/** listAll 类接口取数组 */
+export declare function unwrapBizServiceList(res: unknown): Record<string, unknown>[];

package/dist/domain/table/runtime/engines/init-load-engine.d.ts

@@ -0,0 +1,16 @@
+import { Doc } from '../../../../core';
+import { TableRuntimeContext } from '../table-runtime-context';
+export declare class InitLoadEngine {
+    private readonly doc;
+    constructor(doc: Doc);
+    apply(ctx: TableRuntimeContext): Promise<void>;
+    /**
+     * 判断当前子字段是否需要跳过赋值逻辑
+     * @param subFieldKey 子字段数据存储的key
+     * @param skipIfRowHasAny 存在任意一个指定字段有值时，就跳过该子字段
+     * @returns true-跳过，false-不跳过
+     */
+    private shouldSkip;
+    private readExistingRows;
+    private hasNonemptyRow;
+}

package/dist/domain/table/runtime/engines/linkage-engine.d.ts

@@ -0,0 +1,67 @@
+import { Doc } from '../../../../core';
+import { FieldChangeDetail } from '../../../../core/data/DataManager';
+import { EachRowOptions, TableRuntimeContext } from '../table-runtime-context';
+import { RuleContext } from '../../types';
+/** 下拉级联解析结果 */
+export interface BusinessSelectLinkageResult {
+    enabled: boolean;
+    linkFieldKey?: string;
+    linkValue?: unknown;
+    /** 为 false 时上游无值不阻断本字段下拉（可选过滤模式） */
+    requireLinkValue?: boolean;
+}
+/** 下拉级联联动类 */
+export declare class LinkageEngine {
+    private readonly doc;
+    constructor(doc: Doc);
+    /**
+     * 执行子表级联联动
+     * @param options.rowIndex 仅处理某一行；不传遍历全部行
+     * @param options.changedFieldKey 本次变更字段（onFieldChange 时传）
+     * @param options.fieldChange 变更详情，用于判断是否清空下游
+     */
+    applyForSubTable(ctx: TableRuntimeContext, options?: EachRowOptions & {
+        fieldChange?: FieldChangeDetail;
+    }): void;
+    /**
+     * 收集因上游字段变更需批量清空的下游字段更新对象（key=完整路径, value=undefined）。
+     * 供编排器在 onChange 写入前预清空使用。
+     */
+    collectClearUpdates(ctx: TableRuntimeContext, ruleCtx: RuleContext, changedFieldKey: string): Record<string, undefined>;
+    /**
+     * 解析指定子表下拉字段的级联联动信息（联动配置 + 上游值）
+     */
+    resolveSelectLinkage(ctx: TableRuntimeContext, fieldKey: string, runtimeValuePath?: string): BusinessSelectLinkageResult | null;
+    /**
+     * 下拉选中选项后，按 reverseFillFromOption 从选项反向填充同行其他字段
+     * @returns 待批量赋值的路径-值映射，空对象代表无需填充
+     */
+    buildSelectReverseFill(ctx: TableRuntimeContext, fieldKey: string, rowIndex: number, selectedOption?: Record<string, unknown> | null): Record<string, unknown>;
+    /** 单行级联处理：上游变更清空下游 + 重新生成所有下拉级联请求参数 */
+    private applyLinkageForRow;
+    /** 为配置下拉级联的字段生成并存储联动参数 */
+    private applySelectLinkageForField;
+    /**
+     * 解析下拉级联上游值，优先级：
+     * 1.当前行同名字段 → 2.context 隐式字段 → 3.主表映射字段 → 4.主表顶层同名字段（配置允许时）
+     */
+    private resolveLinkFieldValue;
+    /** 判断下拉联动是否需要启用 */
+    private shouldEnableSelectLinkage;
+    /**
+     * 级联变更需清空的字段：
+     * - 显式配置了 clearOnLinkChange（含空数组）→ 使用配置值
+     * - 未配置（undefined）→ 退化为清空字段自身
+     * 空数组可用于显式声明"由 rowHandlers 负责清空，linkage 不介入"
+     */
+    private getDownstreamClearFieldKeys;
+    /**
+     * 选中下拉项后，按 profile.fillFromOption 从 option 数据同步填充同行字段
+     * @returns 待批量赋值的路径-值映射，空对象代表无需填充
+     */
+    buildFillFromOption(ctx: TableRuntimeContext, fieldKey: string, rowIndex: number, selectedOption: Record<string, unknown>): Record<string, unknown>;
+    /** 将单条 FieldOptionFillDef 映射写入 updates */
+    private applyOptionFillDef;
+    /** 构建字段清空更新对象（同时清值与 _lb_ 标签） */
+    private buildClearUpdates;
+}

package/dist/domain/table/runtime/engines/main-field-bind-engine.d.ts

@@ -0,0 +1,7 @@
+import { Doc } from '../../../../core';
+import { MainFieldBindingDef } from '../../types';
+export declare class MainFieldBindEngine {
+    private readonly doc;
+    constructor(doc: Doc);
+    apply(bindings: MainFieldBindingDef[]): void;
+}

package/dist/domain/table/runtime/engines/remote-sync-engine.d.ts

@@ -0,0 +1,25 @@
+import { Doc } from '../../../../core';
+import { FieldChangeDetail } from '../../../../core/data/DataManager';
+import { RemoteSyncDef } from '../../types';
+import { SubtableFieldPath } from '../table-runtime-utils';
+import { TableRuntimeContext } from '../table-runtime-context';
+export declare class RemoteSyncEngine {
+    private readonly doc;
+    private readonly ruleEngine;
+    constructor(doc: Doc);
+    /** 将远程同步结果写回行 */
+    applyToRow(ctx: TableRuntimeContext, rowIndex: number, config: RemoteSyncDef, data: Record<string, unknown>, rowPatch?: Record<string, unknown>): void;
+    /** 按 profile.remoteSync 从行数据组装请求体；条件不足返回 null */
+    buildBody(row: Record<string, unknown>, config: RemoteSyncDef): Record<string, unknown> | null;
+    /** 字段变更时按 profile.remoteSync 调度同步 */
+    applyOnFieldChange(ctx: TableRuntimeContext, change: SubtableFieldPath, fieldChange?: FieldChangeDetail): void;
+    /** 按当前行拉取 remoteSync 并回写 */
+    private syncRow;
+    private scheduleRowSync;
+    /** 取当前 doc 的去重集合（按 doc 隔离，避免多文档同键互相抑制） */
+    private pendingKeys;
+    private pendingTriggers;
+    private clearMissFields;
+    private afterApply;
+    private pickFields;
+}

package/dist/domain/table/runtime/engines/row-runtime-engine.d.ts

@@ -0,0 +1,20 @@
+import { Doc } from '../../../../core';
+import { FieldChangeDetail } from '../../../../core/data/DataManager';
+import { SubtableFieldPath } from '../table-runtime-utils';
+import { TableRuntimeContext } from '../table-runtime-context';
+export declare class RowRuntimeEngine {
+    private readonly doc;
+    constructor(doc: Doc);
+    hasRowInit(ctx: TableRuntimeContext): boolean;
+    /** 对单行执行行初始化 */
+    applyRowInit(ctx: TableRuntimeContext, rowIndex: number, rowSource?: string): void;
+    /** 初始化时对所有行执行行初始化 */
+    applyRowInitForAllRows(ctx: TableRuntimeContext): void;
+    /** 字段变更时执行 when=onFieldChange 的行处理器（按 watch 过滤） */
+    applyRowHandlersOnFieldChange(ctx: TableRuntimeContext, change: SubtableFieldPath, fieldChange?: FieldChangeDetail): void;
+    /** 主表字段变更时，执行 when=onMainFieldChange 的上下文赋值，补填全部子表行 */
+    private assignmentsFor;
+    private handlersFor;
+    /** 从填报上下文取值写入行字段 */
+    private applyContextAssignment;
+}

package/dist/domain/table/runtime/engines/rule-engine.d.ts

@@ -0,0 +1,35 @@
+import { Doc } from '../../../../core';
+import { FieldChangeDetail } from '../../../../core/data/DataManager';
+import { TableRuntimeContext } from '../table-runtime-context';
+/** 字段态规则类 */
+export declare class RuleEngine {
+    private readonly doc;
+    constructor(doc: Doc);
+    /** 字段值变更后：应用 onFieldChange 规则 */
+    applyOnFieldChange(ctx: TableRuntimeContext, change: {
+        rowIndex: number;
+        fieldKey: string;
+    }, fieldChange?: FieldChangeDetail): void;
+    /** 子表插行后：应用 always + onRowInit 规则 */
+    applyOnRowInit(ctx: TableRuntimeContext, rowIndex: number): void;
+    /** 文档初始化后：应用 always + onRowInit 规则 */
+    applyOnInit(ctx: TableRuntimeContext): void;
+    /** remoteSync 等 enrichment 回写后：重新评估 always 规则（如条件只读） */
+    applyAlwaysForRow(ctx: TableRuntimeContext, rowIndex: number): void;
+    /**
+     * 执行整个子表下所有行的规则
+     * @param options.rowIndex 仅执行某一行；不传遍历全部行
+     * @param options.changedFieldKey 本次变更字段，仅 onFieldChange 使用
+     */
+    private applyForSubTable;
+    /** 执行单行下所有规则：每条规则按 fields 批量应用 effect */
+    private applyRulesForRow;
+    /** 执行字段运行时副作用：字段状态、接口参数、清空联动字段 */
+    private applyFieldRuntimeEffect;
+    /**
+     * 判断规则是否应当执行：匹配触发时机；onFieldChange 时按 watch 过滤
+     */
+    private shouldRunRule;
+    /** 解析 effect.queryParams */
+    private resolveQueryParams;
+}

package/dist/domain/table/runtime/runtime-handlers.d.ts

@@ -0,0 +1,72 @@
+import { Doc } from '../../../core';
+import { RemoteSyncDef } from '../../types';
+import { TableRuntimeContext } from './table-runtime-context';
+/**
+ * 单行运行时处理器类型定义
+ * @param doc 文档实例
+ * @param subFieldKey 子表格字段标识key
+ * @param rowIndex 当前行下标
+ */
+export type RowRuntimeHandler = (doc: Doc, subFieldKey: string, rowIndex: number) => void;
+/** 初始化数据转换上下文对象 */
+export interface InitLoadMapContext {
+    /** 文档实例 */
+    doc: Doc;
+    /** 表格运行时上下文 */
+    runtimeCtx: TableRuntimeContext;
+    /** 是否开启分组 */
+    groupBy: boolean;
+}
+/**
+ * 初始化加载数据转换函数类型
+ * @param records 接口返回的原始行数据数组
+ * @param ctx 转换所需上下文
+ * @returns 处理完成后的行数据数组
+ */
+export type InitLoadRecordsMapper = (records: Record<string, unknown>[], ctx: InitLoadMapContext) => Record<string, unknown>[];
+/** remoteSync 回写解析上下文 */
+export interface RemoteSyncApplyContext {
+    doc: Doc;
+    runtimeCtx: TableRuntimeContext;
+    rowIndex: number;
+    /** 当前行数据 */
+    row: Record<string, unknown>;
+    config: RemoteSyncDef;
+    /** 本次触发 remoteSync 的字段 */
+    changedFieldKey?: string;
+}
+/** remoteSync 回写解析结果 */
+export interface RemoteSyncApplyResult {
+    /** 写入行字段（enrichment） */
+    apply: Record<string, unknown>;
+    /** 同行元数据补丁（如库位自动解析标记） */
+    rowPatch?: Record<string, unknown>;
+}
+/**
+ * remoteSync 回写解析器：根据接口返回条数决定 applyFields 的实际写入内容
+ */
+export type RemoteSyncApplyResolver = (records: Record<string, unknown>[], ctx: RemoteSyncApplyContext) => RemoteSyncApplyResult;
+/** 注册单行运行时钩子函数 */
+export declare function registerRowHandler(name: string, handler: RowRuntimeHandler): void;
+/** 注册初始化数据转换映射钩子函数 */
+export declare function registerInitLoadMapper(name: string, mapper: InitLoadRecordsMapper): void;
+/** 注册 remoteSync 回写解析钩子函数 */
+export declare function registerRemoteSyncApplyResolver(name: string, resolver: RemoteSyncApplyResolver): void;
+/**
+ * 执行指定名称的单行处理器
+ * @param name 注册名称
+ * @param doc 文档实例
+ * @param subFieldKey 子表格字段key
+ * @param rowIndex 当前行索引
+ */
+export declare function runRowHandler(name: string | undefined, doc: Doc, subFieldKey: string, rowIndex: number): void;
+/**
+ * 使用注册的转换函数处理初始化加载的表格数据
+ * @param name 注册名称
+ * @param records 接口原始行数据
+ * @param ctx 转换上下文
+ * @returns 转换后数据；无对应转换器时返回原数组
+ */
+export declare function mapInitLoadRecords(name: string | undefined, records: Record<string, unknown>[], ctx: InitLoadMapContext): Record<string, unknown>[];
+/** 使用注册的解析器决定 remoteSync 回写字段 */
+export declare function resolveRemoteSyncApply(name: string | undefined, records: Record<string, unknown>[], ctx: RemoteSyncApplyContext): RemoteSyncApplyResult | null;

package/dist/domain/table/runtime/table-runtime-context.d.ts

@@ -0,0 +1,48 @@
+import { Doc } from '../../../core';
+import { RepeatingRegion } from '../../../core/model/logic';
+import { BusinessFieldProfile, BusinessSubTableProfile, RuleContext } from '../types';
+/** 行遍历选项 */
+export interface EachRowOptions {
+    /** 指定仅遍历某一行；不传则遍历全部行 */
+    rowIndex?: number;
+    /** onFieldChange 时透传的变更字段 key */
+    changedFieldKey?: string;
+}
+/** 业务子表运行时上下文 */
+export declare class TableRuntimeContext {
+    readonly doc: Doc;
+    readonly profile: BusinessSubTableProfile;
+    readonly subFieldKey: string;
+    readonly region: RepeatingRegion;
+    private widgetFieldKeys?;
+    constructor(doc: Doc, profile: BusinessSubTableProfile, subFieldKey: string, region: RepeatingRegion);
+    /** 业务子模型 refModelType */
+    get refModelType(): string;
+    /** 子表数组路径 $.subFieldKey */
+    get arrayPath(): string;
+    /** 指定行路径 $.subFieldKey[rowIndex] */
+    rowPath(rowIndex: number): string;
+    /** 读取指定行数据 */
+    getRow(rowIndex: number): Record<string, unknown> | undefined;
+    /** 子表总行数，无数据默认返回 1 */
+    getRowCount(): number;
+    /** 构建单行规则执行上下文 */
+    buildRuleContext(rowIndex: number, changedFieldKey?: string): RuleContext;
+    /** 遍历子表数据行，支持指定单行或全量遍历，逐行注入 RuleContext */
+    eachRow(options: EachRowOptions, iteratee: (ctx: RuleContext) => void): void;
+    /** 在子表字段配置列表中查找指定字段配置 */
+    findFieldProfile(fieldKey: string): BusinessFieldProfile | undefined;
+    /** 本子表表单内已渲染的字段控件 key 集合 */
+    private get presentFieldWidgetKeys();
+    /** 本子表表单内是否存在绑定指定字段的控件 */
+    hasFieldWidget(fieldKey: string): boolean;
+    /**
+     * 判断变更字段是否是本子表的隐式联动上游字段
+     * 两种匹配：1.隐式字段自身 key；2.隐式字段映射的主表字段 key
+     */
+    isImplicitLinkField(changedFieldKey: string): boolean;
+    /** 一次模型遍历，收集文档内全部业务子表上下文 */
+    static collectAll(doc: Doc): TableRuntimeContext[];
+    /** 按子表唯一标识查找上下文 */
+    static find(doc: Doc, subFieldKey: string): TableRuntimeContext | undefined;
+}

package/dist/domain/table/runtime/table-runtime-utils.d.ts

@@ -0,0 +1,60 @@
+import { Doc } from '../../../core';
+import { FieldChangeDetail } from '../../../core/data/DataManager';
+import { BusinessFieldProfile } from '../../types';
+/** 子表字段路径解析结果 */
+export interface SubtableFieldPath {
+    subFieldKey: string;
+    rowIndex: number;
+    fieldKey: string;
+}
+/**
+ * 解析子表完整字段路径 $.subFieldKey[行号].fieldKey
+ * @returns 子表标识 / 行索引 / 字段标识；非子表路径返回 null
+ */
+export declare function parseSubtableFieldPath(path: string): SubtableFieldPath | null;
+/**
+ * 字段变更结构化类型
+ * - subtable：子表内字段变更
+ * - main：主表顶层字段变更
+ */
+export type BusinessFieldChange = {
+    kind: 'subtable';
+    subFieldKey: string;
+    rowIndex: number;
+    fieldKey: string;
+} | {
+    kind: 'main';
+    fieldKey: string;
+};
+/** 统一解析数据路径，区分主表 / 子表字段变更结构 */
+export declare function parseBusinessFieldChange(changedPath: string): BusinessFieldChange | null;
+/**
+ * 从字段匹配配置中提取有效字段 key
+ * @returns 单个字符串字段名；数组 / 空值返回 undefined
+ */
+export declare function resolveFieldKeyFromMatch(fieldProfile: BusinessFieldProfile): string | undefined;
+export declare function toNumber(value: unknown, fallback?: number): number;
+/** 字段值是否「空」：null / undefined / 空串 */
+export declare function isBlank(value: unknown): boolean;
+/** 字段值是否「有值」 */
+export declare function isPresent(value: unknown): boolean;
+/** 按字段列表拼接行分组/合并 key，空值视为 '' */
+export declare function buildRowGroupKey(row: Record<string, unknown>, fieldKeys: readonly string[], separator?: string): string;
+/** 读取填报上下文参数；空值（null / undefined / 空串）统一返回 undefined */
+export declare function readContextParam(doc: Doc, paramKey: string): unknown;
+/** 写入子字段级联查询参数到 doc.paramsConfig._subFieldConfig */
+export declare function setSubFieldQueryParams(doc: Doc, fieldValuePath: string, queryParams: Record<string, unknown>): void;
+/** 控件字段条目：用于跨 engine 统一遍历 getWidgetInstances */
+export interface WidgetFieldEntry {
+    field: any;
+    valuePath: unknown;
+}
+/** 收集文档内所有「带 field 的控件」条目 */
+export declare function getWidgetFieldEntries(doc: Doc): WidgetFieldEntry[];
+/** 判断两个字段值是否逻辑相等 */
+export declare function isSameFieldValue(a: unknown, b: unknown): boolean;
+/**
+ * 判断本次字段变更是否需要触发下游级联清空
+ * @returns true：新旧值不同，需要清空下游下拉
+ */
+export declare function shouldClearDownstreamForFieldChange(change?: FieldChangeDetail): boolean;

package/dist/domain/table/runtime/table-runtime.d.ts

@@ -0,0 +1,64 @@
+import { Doc } from '../../../core';
+import { FieldChangeMap } from '../../../core/data/DataManager';
+import { BusinessSelectLinkageResult } from './engines/linkage-engine';
+/** resolveSelectLinkage 入参 */
+export interface ResolveSelectLinkageOptions {
+    subFieldKey?: string;
+    fieldKey?: string;
+    runtimeValuePath?: string;
+}
+/** buildSelectReverseFill 入参 */
+export interface BuildSelectReverseFillOptions {
+    subFieldKey: string;
+    fieldKey: string;
+    rowIndex: number;
+    selectedOption?: Record<string, unknown> | null;
+}
+/** buildFillFromOption 入参 */
+export interface BuildFillFromOptionOptions {
+    subFieldKey: string;
+    fieldKey: string;
+    rowIndex: number;
+    selectedOption: Record<string, unknown>;
+}
+export declare class TableRuntime {
+    private readonly doc;
+    private readonly contexts;
+    private readonly rule;
+    private readonly linkage;
+    private readonly row;
+    private readonly remoteSync;
+    private readonly initLoad;
+    private readonly mainFieldBind;
+    constructor(doc: Doc);
+    /** 文档是否包含业务子表 */
+    get hasBusinessTables(): boolean;
+    /** 文档初始化时执行全套运行时逻辑 */
+    onInit(): Promise<void>;
+    /**
+     * 子表新增行初始化：rowInit → 字段态规则 → 级联。
+     */
+    onRowInit(subFieldKey: string, rowIndex: number, rowSource?: string): void;
+    /**
+     * 批量字段变更：对每个变更只解析路径、查上下文一次，再分派给各 engine。
+     */
+    onFieldChanges(changedMap: FieldChangeMap): void;
+    /**
+     * 解析下拉字段级联联动信息（联动启用状态 + 上游值），供下拉组件使用。
+     */
+    resolveSelectLinkage(options: ResolveSelectLinkageOptions): BusinessSelectLinkageResult | null;
+    /**
+     * 下拉选中后从选项反向回填同行字段，供 onChange 使用。
+     */
+    buildSelectReverseFill(options: BuildSelectReverseFillOptions): Record<string, unknown>;
+    /**
+     * 选中下拉项后，按 profile.fillFromOption 同步填充同行字段（以 enrichment 写入，不触发 remoteSync）。
+     */
+    buildFillFromOption(options: BuildFillFromOptionOptions): Record<string, unknown>;
+    /**
+     * 批量构建因字段变更需清空的级联下游字段更新集合（写入前预清空）。
+     * 区分子表内字段变更 / 主表隐式联动字段变更两种场景。
+     */
+    buildDownstreamClears(pendingUpdates: Record<string, unknown>): Record<string, undefined>;
+    private findContext;
+}