@gct-paas/word 0.1.74-beta.2 → 0.1.74-beta.21

package/dist/domain/table/business/warehouse/warehouse-inventory/types.d.ts

@@ -1,5 +1,27 @@
 /** 库存盘点行数据来源 */
 export type WarehouseInventoryRowSource = 'manual' | 'auto' | 'scan';
+/**
+ * 盘点维度
+ * - warehouse_summary：按仓库汇总盘点（库存表，物料+批号+仓库）
+ * - location_detail：按库位精细盘点（库存明细，物料+批号+仓库+库位）
+ */
+export declare const STOCKTAKE_DIMENSION: {
+    readonly warehouseSummary: "warehouse_summary";
+    readonly locationDetail: "location_detail";
+};
+export type StocktakeDimension = (typeof STOCKTAKE_DIMENSION)[keyof typeof STOCKTAKE_DIMENSION];
+/** 设计态盘点维度下拉选项 */
+export declare const STOCKTAKE_DIMENSION_OPTIONS: readonly [{
+    readonly label: "按仓库汇总盘点";
+    readonly value: "warehouse_summary";
+    readonly showTip: false;
+    readonly tip: "按SKU汇总总数核对，不支持自动调整库存";
+}, {
+    readonly label: "按库位精细盘点";
+    readonly value: "location_detail";
+    readonly showTip: false;
+    readonly tip: "按库存明细逐条核对";
+}];
 /** 盘点状态 key → 展示文案 */
 export declare const STOCKTAKE_STATUS: {
     readonly waiting: "待盘点";
@@ -9,25 +31,3 @@ export declare const STOCKTAKE_STATUS: {
 };
 export type StocktakeStatusKey = keyof typeof STOCKTAKE_STATUS;
 export type StocktakeStatusLabel = (typeof STOCKTAKE_STATUS)[StocktakeStatusKey];
-/** 库存盘点子表行数据 */
-export interface IWarehouseInventoryRow {
-    id_?: string;
-    production_identification_id_?: string;
-    product_id_?: string;
-    product_id_name_?: string;
-    product_id_code_?: string;
-    product_id_spec_?: string;
-    warehouse_id_?: string;
-    location_id_?: string;
-    stock_num_?: number;
-    stocktake_num_?: number;
-    diff_num_?: number;
-    stocktake_status_?: StocktakeStatusKey;
-    deleted_?: boolean;
-    /** 行数据来源：手动 / 自动加载 / 扫码 */
-    row_source_?: WarehouseInventoryRowSource;
-    /** remoteSync 自动解析库位后为 true，库位字段只读 */
-    _location_auto_resolved_?: boolean;
-    /** 接口返回多条库存时的候选库位 ID，用于库位下拉过滤 */
-    _inventory_location_ids_?: string[] | null;
-}

package/dist/domain/table/business/warehouse/warehouse-out/actions/index.d.ts

@@ -0,0 +1 @@
+export * from './scan';

package/dist/domain/table/business/warehouse/warehouse-out/actions/scan.d.ts

@@ -0,0 +1,7 @@
+import { BusinessScanHandler } from '../../../shared/scan-action';
+/**
+ * 出库明细表：扫码后入行
+ * - 连续扫码不覆盖已有行
+ * - 同一物料+批次：数量累加
+ */
+export declare const handleWarehouseOutScan: BusinessScanHandler;

package/dist/domain/table/business/warehouse/warehouse-out/index.d.ts

@@ -0,0 +1,3 @@
+export { profile as warehouseOutProfile, TABLE_TYPE } from './profile';
+export * from './profile';
+export * from './actions';

package/dist/domain/table/business/warehouse/warehouse-out/profile/field-keys.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 出库明细表字段 key 统一定义
+ */
+/** 单字段 key */
+export declare const F: {
+    /** 物料 */
+    readonly product: "product_id_";
+    /** 库存主键（出库选物料时写 option.id_，用于唯一回显） */
+    readonly inventory: "inventory_id_";
+    /** 物料名称 */
+    readonly productName: "product_id_name_";
+    /** 物料编码 */
+    readonly productCode: "product_id_code_";
+    /** 物料规格 */
+    readonly productSpec: "product_id_spec_";
+    /** 物料批号 */
+    readonly materialNo: "material_no_";
+    /** 物料批号ID */
+    readonly materialNoId: "material_no__id_";
+    /** 数量 */
+    readonly qty: "qty_";
+    /** 仓库 */
+    readonly warehouse: "warehouse_id_";
+    /** 库位 */
+    readonly location: "location_id_";
+    /** 工单 */
+    readonly mfgOrder: "mfg_order_id_";
+    /** 生产批次/SN */
+    readonly lotSn: "lot_sn_id_";
+    /** 有效期 */
+    readonly validity: "validity_";
+    /** 唯一码 */
+    readonly uniqueCode: "unique_code_";
+    /** 复检日期 */
+    readonly reInspectionDate: "re_inspection_date_";
+};
+export type WarehouseOutFieldKey = (typeof F)[keyof typeof F];
+/**
+ * 设计态输入属性固定禁用、运行态只读的字段
+ * 物料编码 / 名称 / 规格 / 物料批号 / 仓库 / 库位 / 工单 / 生产批次/SN / 有效期 / 复检日期
+ */
+export declare const DISABLED_INPUT_FIELDS: readonly ["product_id_name_", "product_id_code_", "product_id_spec_", "material_no_", "warehouse_id_", "location_id_", "mfg_order_id_", "lot_sn_id_", "validity_", "re_inspection_date_"];
+/** 物料清空时需一并清空的字段 */
+export declare const CLEAR_ON_PRODUCT_EMPTY: readonly ["inventory_id_", "product_id_name_", "product_id_code_", "product_id_spec_", "material_no_", "material_no__id_", "warehouse_id_", "location_id_", "mfg_order_id_", "lot_sn_id_", "validity_", "re_inspection_date_"];

package/dist/domain/table/business/warehouse/warehouse-out/profile/fields.d.ts

@@ -0,0 +1,2 @@
+import { BusinessFieldProfile } from '../../../../types';
+export declare const fields: BusinessFieldProfile[];

package/dist/domain/table/business/warehouse/warehouse-out/profile/index.d.ts

@@ -0,0 +1,3 @@
+import { BusinessSubTableProfile } from '../../../../types';
+export declare const TABLE_TYPE: "warehouse-out";
+export declare const profile: BusinessSubTableProfile;

package/dist/domain/table/business/warehouse/warehouse-out/runtime/register-handlers.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/domain/table/business/warehouse/warehouse-out/runtime/row-change-handlers.d.ts

@@ -0,0 +1,5 @@
+import { Doc } from '../../../../../../core';
+/**
+ * 物料清空时，同步清空选库存带回的填充字段
+ */
+export declare function handleProductIdChange(doc: Doc, subFieldKey: string, rowIndex: number): void;

package/dist/domain/table/business/warehouse/warehouse-outbound/index.d.ts

@@ -0,0 +1,2 @@
+export { profile as warehouseOutboundProfile, TABLE_TYPE } from './profile';
+export * from './profile';

package/dist/domain/table/business/warehouse/warehouse-outbound/profile/field-keys.d.ts

@@ -0,0 +1,34 @@
+/**
+ * EQM 出库明细表（WAREHOUSE_OUTBOUND）字段 key
+ */
+export declare const F: {
+    /** 库存主键（选备件时写 option.id_，用于唯一回显） */
+    readonly inventory: "inventory_id_";
+    /** 备件 */
+    readonly part: "part_id_";
+    /** 备件 id（展示 / 文本） */
+    readonly partLb: "part_id__lb_";
+    /** 备件编码 */
+    readonly partCode: "part_id_code_";
+    /** 备件名称 */
+    readonly partName: "part_id_name_";
+    /** 备件规格 */
+    readonly partSpec: "part_id_spec_";
+    /** 有效期 */
+    readonly validity: "validity_";
+    /** 库位 */
+    readonly location: "location_id_";
+    /** 库区 */
+    readonly storageZone: "storage_zone_id_";
+    /** 仓库 */
+    readonly warehouse: "warehouse_id_";
+    /** 数量单位 */
+    readonly qtyUom: "qty_uom_id_";
+    /** 数量 */
+    readonly qty: "qty_";
+};
+export type WarehouseOutboundFieldKey = (typeof F)[keyof typeof F];
+/** 设计态固定禁用、运行态只读 */
+export declare const DISABLED_INPUT_FIELDS: readonly ["part_id__lb_", "part_id_code_", "part_id_name_", "part_id_spec_", "location_id_", "storage_zone_id_", "warehouse_id_", "qty_uom_id_"];
+/** 备件清空时需一并清空的字段 */
+export declare const CLEAR_ON_PART_EMPTY: readonly ["inventory_id_", "part_id_code_", "part_id_name_", "part_id_spec_", "validity_", "location_id_", "storage_zone_id_", "warehouse_id_", "qty_uom_id_"];

package/dist/domain/table/business/warehouse/warehouse-outbound/profile/fields.d.ts

@@ -0,0 +1,2 @@
+import { BusinessFieldProfile } from '../../../../types';
+export declare const fields: BusinessFieldProfile[];

package/dist/domain/table/business/warehouse/warehouse-outbound/profile/index.d.ts

@@ -0,0 +1,3 @@
+import { BusinessSubTableProfile } from '../../../../types';
+export declare const TABLE_TYPE: "warehouse-outbound";
+export declare const profile: BusinessSubTableProfile;

package/dist/domain/table/business/warehouse/warehouse-outbound/runtime/register-handlers.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/domain/table/business/warehouse/warehouse-outbound/runtime/row-change-handlers.d.ts

@@ -0,0 +1,2 @@
+import { Doc } from '../../../../../../core';
+export declare function handlePartIdChange(doc: Doc, subFieldKey: string, rowIndex: number): void;

package/dist/domain/table/design/ribbon-options.d.ts

@@ -1,8 +1,15 @@
 import { DropdownOption, DropdownOptionGroup } from '../../../base';
+import { BusinessSubTableType } from '../types';
 /** 表头（挂在数据表 Ribbon 首位） */
 export declare const TABLE_HEADER_RIBBON_OPTION: DropdownOption;
+export interface RibbonTableOptionsParams {
+    /** 当前套件 key，用于 ribbonSuites 过滤 */
+    suiteKey?: string;
+    /** 套件级需从 Ribbon 隐藏的业务表类型 */
+    hiddenBusinessTableTypes?: BusinessSubTableType[];
+}
 /** 生成 Ribbon「数据表」「业务表」下拉选项 */
-export declare function getRibbonTableOptions(): {
+export declare function getRibbonTableOptions(params?: RibbonTableOptionsParams): {
     dataTables: DropdownOption[];
     businessTables: DropdownOptionGroup[];
 };

package/dist/domain/table/design/validate-nested-table-region.d.ts

@@ -0,0 +1,31 @@
+import { Wtbl, Wtc } from '../../../core/model/document';
+import { TableCellSelectionBounds } from './validate-table-selection';
+export type NestedTableMutexReason = 'cell-has-nested' | 'outer-has-region';
+/**
+ * 业务表/数据表互斥校验（内外表）
+ *
+ * 规则 3：内表已标业务/数据区 → 外表该单元格不支持再标（被规则 4 涵盖）
+ * 规则 4：外表选中单元格含有内表 → 不支持标为业务/数据表
+ * 内表视角：外层宿主单元格已被外表标为业务/数据区 → 内表不支持再标
+ *
+ * @param table  当前操作的表格（外表或内表）
+ * @param bounds 当前光标选区对应的单元格范围（来自 resolveTableCellSelectionBounds）
+ */
+export declare function validateNestedTableRegionMutex(table: Wtbl, bounds?: TableCellSelectionBounds | null): {
+    ok: boolean;
+    existingLabel?: string;
+    reason?: NestedTableMutexReason;
+};
+export declare function getNestedTableRegionMutexMessage(reason?: NestedTableMutexReason, existingLabel?: string): string;
+/**
+ * 校验互斥并弹出警告。返回 true 表示可以继续标记。
+ */
+export declare function assertNestedTableRegionMutex(table: Wtbl, bounds?: TableCellSelectionBounds | null): boolean;
+/**
+ * 设置子表前的综合校验（嵌套互斥 + 同一行唯一子表）
+ */
+export declare function assertSubTableRegionPlacement(table: Wtbl, bounds?: TableCellSelectionBounds | null): boolean;
+/**
+ * 从起止单元格构造互斥校验所需的 bounds。
+ */
+export declare function buildBoundsFromCellRange(startCell: Wtc, endCell: Wtc): TableCellSelectionBounds | null;

package/dist/domain/table/design/validate-table-selection.d.ts

@@ -18,6 +18,14 @@ export type ValidateTableSelectionOptions = {
     /** 与这些类型区域重叠时不视为非法 */
     ignoreOverlapTypes?: string[];
 };
+/**
+ * 同一行并排多个子表（列不重叠）时，布局展开只保留后设 region，需提前拦截。
+ * 若选区与已有 region 重叠，交由 findCrossRegion 处理，此处返回 undefined。
+ */
+export declare function findSameRowSubTableConflict(table: Wtbl, bounds: TableCellSelectionBounds): TableRegion | undefined;
+export declare function getSameRowSubTableConflictMessage(existing?: TableRegion): string;
+/** 校验通过返回 true；冲突时弹出提示并返回 false */
+export declare function assertSameRowSubTableAllowed(table: Wtbl, bounds: TableCellSelectionBounds): boolean;
 /** 解析已有逻辑区域的展示名称 */
 export declare function resolveTableRegionLabel(region: TableRegion): string;
 /** 从当前光标选区解析表格单元格范围 */

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

@@ -14,3 +14,4 @@ export * from './design/hooks/on-subtable-create';
 export * from './design/hooks/on-field-attach';
 export * from './design/hooks/on-repeating-default-props';
 export * from './design/validate-table-selection';
+export * from './design/validate-nested-table-region';

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

@@ -46,8 +46,15 @@ export declare class LinkageEngine {
      * 1.当前行同名字段 → 2.context 隐式字段 → 3.主表映射字段 → 4.主表顶层同名字段（配置允许时）
      */
     private resolveLinkFieldValue;
-    /** 判断下拉联动是否需要启用 */
-    private shouldEnableSelectLinkage;
+    /**
+     * 解析实际生效的上游字段：
+     * 1. 首选 linkFieldKey（requireLinkWidget=false 或不要求控件 / 控件已拖入）
+     * 2. 否则若配置了 fallbackLinkFieldKey，且回退上游可用 → 用回退上游
+     * 3. 都不可用 → null（不启用联动）
+     */
+    private resolveActiveLinkFieldKey;
+    /** 判断某个上游字段当前是否可作为联动来源 */
+    private isLinkFieldAvailable;
     /**
      * 级联变更需清空的字段：
      * - 显式配置了 clearOnLinkChange（含空数组）→ 使用配置值

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

@@ -4,4 +4,6 @@ export declare class MainFieldBindEngine {
     private readonly doc;
     constructor(doc: Doc);
     apply(bindings: MainFieldBindingDef[]): void;
+    /** 按字段类型匹配 */
+    private matchesMainFieldBinding;
 }

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

@@ -1,5 +1,5 @@
 import { Doc } from '../../../core';
-import { BusinessFieldProfile } from '../types';
+import { BizServiceApiDef, BusinessFieldProfile, ResolveBizServiceApi } from '../types';
 /**
  * 从字段匹配配置中提取有效字段 key
  * @returns 单个字符串字段名；数组 / 空值返回 undefined
@@ -8,6 +8,11 @@ export declare function resolveFieldKeyFromMatch(fieldProfile: BusinessFieldProf
 export declare function toNumber(value: unknown, fallback?: number): number;
 /** 读取填报上下文参数；空值（null / undefined / 空串）统一返回 undefined */
 export declare function readContextParam(doc: Doc, paramKey: string): unknown;
+/** 解析 initLoad / remoteSync 的 biz 接口 */
+export declare function resolveConfiguredBizApi(config: {
+    api?: BizServiceApiDef;
+    resolveApi?: ResolveBizServiceApi;
+}, regionProps?: Record<string, unknown> | null): BizServiceApiDef;
 /** 写入子字段级联查询参数到 doc.paramsConfig._subFieldConfig */
 export declare function setSubFieldQueryParams(doc: Doc, fieldValuePath: string, queryParams: Record<string, unknown>): void;
 /** 控件字段条目：用于跨 engine 统一遍历 getWidgetInstances */

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

@@ -74,4 +74,6 @@ export declare class TableRuntime {
      */
     buildDownstreamClears(pendingUpdates: Record<string, unknown>): Record<string, undefined>;
     private findContext;
+    /** 合并各业务子表 mainFieldBindings，按 fieldType + paramKey 去重 */
+    private mergeMainFieldBindings;
 }

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

@@ -9,16 +9,23 @@ import { SubTableLayoutType } from '../../core/model/document/wtcRegionRef';
 export type DataTableType = 'dynamic-table' | 'fixed-table' | 'two-d-table';
 /**
  * 业务表类型
- * @property warehouse-in-out    - 出入库明细表
- * @property warehouse-inventory - 库存盘点表
+ * @property warehouse-in        - 入库明细表（EDHR / WAREHOUSE_IN）
+ * @property warehouse-inbound   - 入库明细表（EQM / WAREHOUSE_INBOUND）
+ * @property warehouse-out       - 出库明细表（EDHR / WAREHOUSE_OUT）
+ * @property warehouse-outbound  - 出库明细表（EQM / WAREHOUSE_OUTBOUND）
+ * @property warehouse-in-out    - 出入库明细表（兼容老文档，Ribbon 已隐藏）
+ * @property warehouse-inventory - 库存盘点表（EDHR / STOCKTAKE）
+ * @property part-stocktake      - 备件库存盘点表（EQM / PART_STOCKTAKE）
+ * @property device-part-consume - 备件消耗表（EQM / DEVICE_PART_CONSUME）
  * @property warehouse-allocate  - 库存调拨表
  * @property material-consume    - 物料消耗表
  * @property material-balance    - 物料平衡表
+ * @property material-requisition - 生产收料表
  * @property check-table         - 检验表
  * @property pretreatment-list   - 预处理表
  * @property entrust-steril-batch-list - 委托灭菌生产批次表
  */
-export type BusinessSubTableType = 'warehouse-in-out' | 'warehouse-inventory' | 'warehouse-allocate' | 'material-consume' | 'material-balance' | 'check-table' | 'pretreatment-list' | 'entrust-steril-batch-list';
+export type BusinessSubTableType = 'warehouse-in' | 'warehouse-inbound' | 'warehouse-out' | 'warehouse-outbound' | 'warehouse-in-out' | 'warehouse-inventory' | 'part-stocktake' | 'device-part-consume' | 'warehouse-allocate' | 'material-consume' | 'material-balance' | 'material-requisition' | 'check-table' | 'pretreatment-list' | 'entrust-steril-batch-list';
 /** 所有子表类型（数据表 + 业务表） */
 export type TableType = DataTableType | BusinessSubTableType;
 /**
@@ -101,6 +108,8 @@ export interface BusinessSubTableProfile extends TableProfileBase {
     /** Ribbon 业务表分组名 */
     ribbonGroup: string;
     ribbonGroupDivider?: boolean;
+    /** 仅在这些套件的 Ribbon 中展示；省略则所有套件可见（仍受 suite hidden 列表约束） */
+    ribbonSuites?: SuiteKey[];
     /** 字段级行为配置 */
     fields?: BusinessFieldProfile[];
     /** 隐式上游字段，必要的情况下可与下游字段进行级联配合 */
@@ -124,8 +133,9 @@ export interface BusinessSubTableProfile extends TableProfileBase {
 export type TableProfile = DataTableProfile | BusinessSubTableProfile;
 /** 主表字段绑定：从填报上下文写入主模型字段 */
 export interface MainFieldBindingDef {
+    /** 字段类型 */
     fieldType: FIELD_TYPE;
-    /** 排除的内置字段 key */
+    /** 排除的字段 key */
     excludeFieldKeys?: string[];
     source: {
         type: 'context';
@@ -140,13 +150,20 @@ export interface BizServiceApiDef {
     /** 请求方式，默认 post */
     method?: 'get' | 'post';
 }
+/** 按表实例 props 动态解析 biz 接口 */
+export type ResolveBizServiceApi = (input: {
+    regionProps?: Record<string, unknown> | null;
+}) => BizServiceApiDef;
 /** 文档初始化批量加载 */
 export interface InitLoadDef {
     /** 加载属性写死开关，为 true 时直接启用 initLoad */
     enabled?: boolean;
     /** 对应 widgetMeta.props 上的开关属性名 */
     enabledByWidgetProp?: string;
-    api: BizServiceApiDef;
+    /** 静态接口；与 resolveApi 至少配置其一 */
+    api?: BizServiceApiDef;
+    /** 有则优先于 api（按设计态 props 切换数据源） */
+    resolveApi?: ResolveBizServiceApi;
     /** listAll 类接口 query 构建 */
     listQuery?: Array<{
         fromContext: {
@@ -154,6 +171,8 @@ export interface InitLoadDef {
         };
         queryKey: string;
     }>;
+    /** 固定写入请求体的字段 */
+    fixedBody?: Record<string, unknown>;
     /** 行内任一字段有值则跳过加载 */
     skipIfRowHasAny?: string[];
     /** 服务端已返回非空子表行时跳过 */
@@ -168,6 +187,8 @@ export interface InitLoadDef {
 /** 远程同步：身份字段变更 → 调接口 → 回写行数据 */
 export interface RemoteSyncDef {
     api: BizServiceApiDef;
+    /** 有则优先于 api（按设计态 props 切换数据源） */
+    resolveApi?: ResolveBizServiceApi;
     /** 这些字段变更时触发 */
     triggerFields: string[];
     /** 作为 POST body 从行读取的字段 */
@@ -282,6 +303,11 @@ export interface SelectSourceDef {
     isTree?: boolean;
     allowManualInput?: boolean;
     persistOptionId?: boolean;
+    /**
+     * 将 option 的 `id_` 写入行内该字段（如出库物料 → `inventory_id_`）。
+     * 用于同 product 多库存行时按库存主键唯一回显；有值时选中/高亮都走此字段，不再用 companion `_id_`
+     */
+    optionIdField?: string;
     baseQuery?: Record<string, unknown>;
     /**
      * baseQuery 多条件时的组合方式
@@ -289,8 +315,15 @@ export interface SelectSourceDef {
      */
     filterCombine?: 'and' | 'or';
     searchFields?: string[];
-    /** quick：快速搜索；缺省继承 fieldType 默认 buildQuery */
-    searchStyle?: 'quick' | 'like';
+    /**
+     * 搜索拼装方式：
+     * - quick：OR(iLike 字段) + 可选过滤，走 query/exp
+     * - like：类型注释保留，实际等同不写（走 fieldType 默认 buildQuery）
+     * - param：搜索框值写入 searchKeywordParam；biz 请求体与 pageNo/pageSize 平铺（不走 query/exp）
+     */
+    searchStyle?: 'quick' | 'like' | 'param';
+    /** param 模式下，搜索框值写入的请求参数名 */
+    searchKeywordParam?: string;
     /** 下拉 Option 的 value/label 字段映射 */
     optionMapping?: {
         value?: string;
@@ -312,10 +345,24 @@ export interface BusinessFieldProfile {
     locked?: ('readonly' | 'disabled' | 'required')[];
     /** 下拉数据源与列展示 */
     selectSource?: SelectSourceDef;
+    /**
+     * 按表实例 props 动态解析下拉数据源；返回值优先于 selectSource。
+     * 返回 null/undefined 时回退 selectSource。
+     */
+    resolveSelectSource?: (input: {
+        regionProps?: Record<string, unknown> | null;
+    }) => SelectSourceDef | null | undefined;
     /** 下拉级联 */
     select?: SelectBehaviorDef;
     /** 选中下拉项后，从 option 数据同步填充同行多个字段 */
     fillFromOption?: FieldOptionFillDef[];
+    /**
+     * 按表实例 props 动态解析回填规则；返回值优先于 fillFromOption。
+     * 返回 null/undefined 时回退 fillFromOption。
+     */
+    resolveFillFromOption?: (input: {
+        regionProps?: Record<string, unknown> | null;
+    }) => FieldOptionFillDef[] | null | undefined;
 }
 /** 级联查询上下文：buildLinkQuery 回调入参 */
 export interface LinkQueryContext extends RuleContext {
@@ -328,6 +375,11 @@ export interface LinkQueryContext extends RuleContext {
 export interface SelectBehaviorDef {
     /** 上游字段 key 可与本字段同处一行 也可在子表外但需配合 implicitFields  */
     linkFieldKey: string;
+    /**
+     * 首选上游控件未拖入时的回退上游字段。
+     * 例：库位优先按库区联动；未拖库区时回退按仓库联动。
+     */
+    fallbackLinkFieldKey?: string;
     /**
      * 是否要求上游字段拖入子表表单才启用联动
      *
@@ -339,6 +391,7 @@ export interface SelectBehaviorDef {
      * | `false` | 不要求拖上游控件；行内无值时回退读主表 `$.{linkFieldKey}`，进行联动
      *
      * 与 `implicitFields` 配合：主表上游建议同时写 implicitFields（主表变更时刷新所有行 + 清空下游）。
+     * 若配置了 `fallbackLinkFieldKey`：首选上游未拖入时，对回退上游同样按本开关判断。
      */
     requireLinkWidget?: boolean;
     /** 构建下拉查询参数 */