@gct-paas/excel 0.1.26 → 0.1.27

package/dist/src/nocode-base/src/hooks/material-consume/bom-validator.d.ts

@@ -1,38 +1,53 @@
 import { IBomEntry, IMaterialConsumeData } from './types';
-import { MaterialConsumptionPatternEnum } from '../../constant';
+/** 扫码校验通过后抛给填充层的完整计划（下标相对入参 arr） */
+export interface ScanFillPlan {
+    target: BomEntryValidator;
+    current: BomEntryValidator;
+    needSwitch: boolean;
+    needInsert: boolean;
+    /** 建组时空占位插入下标；无需建组时为 -1 */
+    groupInsertIndex: number;
+    memberIndexes: number[];
+    emptyProductIndexes: number[];
+    emptyLotIndexes: number[];
+    /** 组内再新增一行的下标 */
+    appendIndex: number;
+}
 export declare class BomEntryValidator {
     bomEntry: IBomEntry;
     /** 是否启用顺序投料 */
     enableSequenceLoading: boolean;
-    /** 批次数量 */
-    materialNoNum: number;
+    /** 批次/生产数量读取函数 */
+    private getMaterialNoNum;
     /** 历史填报数据 */
     historyData: IMaterialConsumeData[];
     /** 表单实例的批次号 */
     mainMaterialNo: string;
     /** 物料消耗模式 */
-    mcPattern: MaterialConsumptionPatternEnum;
+    noBomMode: boolean;
     /** 该明细使用到的产品的id集合 */
     productIds: string[];
     /** 物料和code的映射 */
     productCodes: Record<string, string>;
     /** 历史数据中已经消耗的 */
     hasConsumed: number;
-    /** 需求总量 */
-    total: number;
     /** 剩于可消耗数量 */
     get remainingNum(): number;
+    /** 批次/生产数量（用时读取，避免构造快照过期） */
+    get materialNoNum(): number;
+    /** 需求总量 = 数量倍数 × BOM 单位用量 */
+    get total(): number;
     constructor(bomEntry: IBomEntry, 
     /** 是否启用顺序投料 */
     enableSequenceLoading: boolean, 
-    /** 批次数量 */
-    materialNoNum: number, 
+    /** 批次/生产数量读取函数 */
+    getMaterialNoNum: () => number, 
     /** 历史填报数据 */
     historyData: IMaterialConsumeData[], 
     /** 表单实例的批次号 */
     mainMaterialNo: string, 
     /** 物料消耗模式 */
-    mcPattern: MaterialConsumptionPatternEnum);
+    noBomMode: boolean);
     /**
      * 翻译物料的code
      * @param productId
@@ -45,8 +60,29 @@ export declare class BomEntryValidator {
      * @return {*}
      */
     filterGroupData(arr: IMaterialConsumeData[]): IMaterialConsumeData[];
+    /** 行是否属于本 BOM 组（优先 bom_entry_id_，避免跨组 product_id_ 误判） */
+    isRowInGroup(row: IMaterialConsumeData): boolean;
+    /** 组内已选中的物料（整批替代；不排除当前行） */
+    getGroupExistingProductId(tableData: IMaterialConsumeData[]): string | undefined;
+    /**
+     * 本组 product_id_ 下拉可选范围
+     * - 未开替代料：仅主料
+     * - 整批替代：组内已有 → 锁定该物料；否则主料+替代料
+     * - 混用等：主料+替代料
+     */
+    getSelectableProductIds(tableData: IMaterialConsumeData[]): string[];
     validateSubstitute(arr: IMaterialConsumeData[]): void;
     validateLotMixing(arr: IMaterialConsumeData[]): void;
+    /**
+     * 通用校验 3（带即将写入的行）：组内已有行 + row 的批次去重后，是否超过混批次数。
+     * - 非按批次 / 未开混批校验 / row 不属于本组 → 直接通过
+     * - 排除空物料；空批次不计入
+     */
+    validateLotMixingWithRow(row: IMaterialConsumeData, arr: IMaterialConsumeData[]): void;
+    /** 指定物料批次：material_no_ 须在 specified_material_entries_ 的 name_ 范围内 */
+    validateSpecifiedMaterialNo(row: IMaterialConsumeData): void;
+    /** 整组指定批次校验：组内每一行有批次值的都检查 */
+    validateSpecifiedMaterialNoForGroup(arr: IMaterialConsumeData[]): void;
     /**
      * 校验数量
      * @param arr
@@ -73,6 +109,12 @@ export declare class BomEntryValidator {
         max: any;
         min: any;
     }>;
+    /**
+     * 通用校验 5：本组上料数量是否满足 qty_validation_rule_。
+     * 前置假设：必填、替代料、混批等已由调用方完成。
+     * @param sequential 是否按顺序上料；eq 规则在非顺序模式下允许少上
+     */
+    validateGroupQty(arr: IMaterialConsumeData[], sequential?: boolean, groupNo?: number): Promise<void>;
     /**
      * 按顺序投料用
      * 检查数据中的当前明细的填报是否已经完成
@@ -84,26 +126,28 @@ export declare class BomEntriesValidator {
     entries: IBomEntry[];
     /** 是否启用顺序投料 */
     enableSequenceLoading: boolean;
-    /** 批次数量 */
-    materialNoNum: number;
+    /** 批次/生产数量读取函数 */
+    getMaterialNoNum: () => number;
     /** 历史填报数据 */
     historyData: IMaterialConsumeData[];
     /** 表单实例的批次号 */
     mainMaterialNo: string;
     /** 物料消耗模式 */
-    mcPattern: MaterialConsumptionPatternEnum;
+    noBomMode: boolean;
     bomEntryValidators: BomEntryValidator[];
     constructor(entries: IBomEntry[], 
     /** 是否启用顺序投料 */
     enableSequenceLoading: boolean, 
-    /** 批次数量 */
-    materialNoNum: number, 
+    /** 批次/生产数量读取函数 */
+    getMaterialNoNum: () => number, 
     /** 历史填报数据 */
     historyData: IMaterialConsumeData[], 
     /** 表单实例的批次号 */
     mainMaterialNo: string, 
     /** 物料消耗模式 */
-    mcPattern: MaterialConsumptionPatternEnum);
+    noBomMode: boolean);
+    /** 当前批次/生产数量 */
+    get materialNoNum(): number;
     /**
      * 翻译物料的code
      * @param productId
@@ -116,13 +160,70 @@ export declare class BomEntriesValidator {
      * @return {*}
      */
     findUtilByProductId(productId: string): BomEntryValidator | undefined;
+    /** 编辑行所属组 id；空物料且无 bom_entry_id_ 时返回 null */
+    private getRowGroupId;
+    /**
+     * 是否有正在编辑的组。
+     * 一组可多行同时 !is_confirmed_；正常应只有一组。
+     * @returns 有编辑行且只落在一组 → true；无编辑行 → false；跨多组编辑 → 抛错
+     */
+    hasEditingGroup(arr: IMaterialConsumeData[]): boolean;
+    /** 取当前唯一编辑组的 BOM 明细 id；没有则 undefined */
+    getEditingGroupId(arr: IMaterialConsumeData[]): string | undefined;
+    /**
+     * 行 → BOM 明细在 bomEntryValidators 中的下标，找不到返回 -1
+     */
+    resolveEntryIndex(row: IMaterialConsumeData): number;
+    /**
+     * 行所属组在序号列中的 groupOrderIndex（0-based；-1 未绑 BOM 组）
+     * 与 material-consume-table 序号列逻辑一致
+     */
+    resolveGroupOrderIndex(row: IMaterialConsumeData, arr: IMaterialConsumeData[]): number;
+    /** 已知 BomEntryValidator 时算 groupOrderIndex */
+    resolveGroupOrderIndexByUtil(util: BomEntryValidator, arr: IMaterialConsumeData[]): number;
+    /** 非顺序上料：BOM 组在表中首次出现的顺序（0-based） */
+    private resolveEntryOrderInTable;
+    /**
+     * 定位顺序上料时的当前编辑组对应 BOM 明细。
+     * 编辑行无物料时，用前后组夹出范围，取 (prev, next) 开区间起点。
+     */
+    findSequenceBomEntry(arr: IMaterialConsumeData[]): BomEntryValidator | undefined;
     /**
      * 检验是否符合顺序投料的顺序要求
      * @param row 当前编辑的行
      * @param arr 所有的数据
      * @return {*}
      */
-    validateSequenceLoading(row?: IMaterialConsumeData, arr: IMaterialConsumeData[]): Promise<void>;
+    validateSequenceLoading(row: IMaterialConsumeData, arr: IMaterialConsumeData[]): Promise<void>;
+    /** 表中是否已有该 BOM 组（有物料行或带 bom_entry_id_ 的空行） */
+    private groupExistsInTable;
+    /**
+     * 按 BOM 顺序计算 target 组应插入的下标：
+     * 插到表中「第一个 BOM 下标更大的组」之前；没有则表末。
+     */
+    private resolveBomOrderInsertIndex;
+    /**
+     * 组装扫码填充计划：切组/建组标记 + 相对 arr 的下标。
+     * needInsert 时优先填 groupInsertIndex 占位行，勿再直接用 member/append 下标（会错位）。
+     */
+    private buildScanFillPlan;
+    /**
+     * 通用校验 2：物料是否允许写入目标组（不改动原 validateSubstitute）
+     */
+    private assertGroupSubstitute;
+    /**
+     * 扫码定位目标组 + 通用校验 2，返回填充计划（切组/建组/下标）。
+     * 不改表数据。
+     */
+    validateSequenceScan(row: IMaterialConsumeData, arr: IMaterialConsumeData[]): ScanFillPlan;
+    /**
+     * 单组整组校验（提交编辑态组 / 切组前复用）
+     */
+    validateGroup(arr: IMaterialConsumeData[], util: BomEntryValidator): Promise<void>;
+    /**
+     * 切组前校验当前编辑组：BOM 内 + 必填、有效期、替代料、混批、数量校验
+     */
+    validateCurrentGroupForSwitch(arr: IMaterialConsumeData[], current: BomEntryValidator): Promise<void>;
     /**
      * 校验物料是否在bom里被使用
      * @param row 单行的数据
@@ -143,6 +244,10 @@ export declare class BomEntriesValidator {
      * @param arr
      */
     validateLotMixing(arr: IMaterialConsumeData[]): void;
+    /**
+     * 通用校验 3（扫码/写入前）：用 row + 表内同行组数据对比混批次数，不改动原 validateLotMixing
+     */
+    validateLotMixingWithRow(row: IMaterialConsumeData, arr: IMaterialConsumeData[]): void;
     /**
      * 校验数量
      * @param arr
@@ -159,10 +264,23 @@ export declare class BomEntriesValidator {
      */
     validate(arr: IMaterialConsumeData[]): Promise<void>;
     /**
-     * 检查扫描数据是否可以插入
+     * 检查扫描数据是否可以插入，通过后返回填充计划（记录模式无 plan）
+     */
+    validateScanCanInsert(row: IMaterialConsumeData, arr: IMaterialConsumeData[]): Promise<ScanFillPlan | undefined>;
+    /**
+     * 校验当前编辑行的数据
      * @param arr
+     * @returns
+     */
+    validateEditRow(arr: IMaterialConsumeData[]): Promise<void>;
+    /**
+     * 顺序上料提交：表中最后一组之前，必须上料组不能缺失（仅结构/顺序，不校验数量）
+     */
+    private assertSubmitSequenceOrder;
+    /**
+     * 提交整表校验：必须上料组须存在；顺序上料校验组序；表中存在的组走整组校验（不含库存）
      */
-    validateScanCanInsert(arr: IMaterialConsumeData[]): Promise<void>;
+    validateAllRows(arr: IMaterialConsumeData[]): Promise<void>;
     /**
      * 把扫描数据按情况插入到数组的位置，返回新数组
      * @param row
@@ -175,3 +293,7 @@ export declare class BomEntriesValidator {
      */
     getAllMaterialIds(): (string | undefined)[];
 }
+/** 行是否属于指定 BOM 组（未 deleted_，且 product_id_ 或 bom_entry_id_ 匹配） */
+export declare function isRowInBomGroup(row: IMaterialConsumeData, util: BomEntryValidator): boolean;
+/** 设置整组编辑态：editing=true → is_confirmed_=false */
+export declare function setGroupEditState(table: IMaterialConsumeData[], util: BomEntryValidator, editing: boolean): void;

package/dist/src/nocode-base/src/hooks/material-consume/index.d.ts

@@ -2,3 +2,4 @@ export * from './types';
 export * from './tmpl-bom-controller';
 export * from './mc-render';
 export * from './material-consume-table-controller';
+export * from './service';

package/dist/src/nocode-base/src/hooks/material-consume/material-consume-group-merge.d.ts

@@ -0,0 +1,20 @@
+import { ITd } from '../../types';
+import { BomEntriesValidator } from './bom-validator';
+import { IMaterialConsumeData } from './types';
+/** 按组合并的组级只读字段（不含 qty_） */
+export declare const GROUP_MERGE_FIELDS: Set<keyof IMaterialConsumeData>;
+/** 是否为按组合并列：序号组件 + 组级字段 */
+export declare function isGroupMergeCell(tdInfo: ITd): boolean;
+/** 连续相同 key 的行属于同一合并组 */
+export declare function getGroupMergeKey(row: IMaterialConsumeData, validator: BomEntriesValidator): string;
+/**
+ * 当前页可见行的组 rowspan 计划
+ * - spans[i] > 1：组首行，值为 rowspan
+ * - spans[i] === 1：单行组，正常渲染
+ * - spans[i] === 0：组内后续行，跳过该列 td
+ */
+export declare function calcGroupRowSpans(rows: IMaterialConsumeData[], validator: BomEntriesValidator): number[];
+/** 计算某一 BOM 组的总上料数量 */
+export declare function calcGroupQtyConsumedTotal(entryIdx: number, tableData: IMaterialConsumeData[], validator: BomEntriesValidator): number;
+/** 回写全表 qty_consumed_total_（组内每行写相同值，便于提交） */
+export declare function syncGroupQtyConsumedTotals(tableData: IMaterialConsumeData[], validator: BomEntriesValidator): void;

package/dist/src/nocode-base/src/hooks/material-consume/material-consume-table-controller.d.ts

@@ -3,7 +3,7 @@ import { FormTmplBomController } from './tmpl-bom-controller';
 import { Ref } from 'vue';
 import { BomEntriesValidator } from './bom-validator';
 import { ISubTable, ParseRuleProps } from '../../types';
-import { IUnitConversionRule, ScanParamType } from '../../types/common/base';
+import { ScanParamType, IUnitConversionRule } from '../../types/common/base';
 import { FormModelController } from '../form-model/form-model-controller';
 import { MaterialConsumptionPatternEnum } from '../../constant';
 export declare class MCDataUtil {
@@ -62,8 +62,12 @@ export declare class MaterialConsumeTableController {
     unitConversionRules: IUnitConversionRule[];
     /** 主表 formState（由组件 setup 注入），用于读取主表字段值 */
     mainFormState: Ref<any>;
-    /** 批次数量 */
-    get materialNoNum(): number;
+    /** 表单数据状态（由组件 setup 注入）：未填报 / STASH / SUBMIT */
+    dataStatus?: string;
+    /** 表单是否已暂存或提交（已处理过则不再跑初始化） */
+    get isDataProcessed(): boolean;
+    /** 批次数量或生产数量 */
+    get materialNoNum(): any;
     /** 物料消耗模式（自身没有配置的话取环境的默认值） */
     get mcPattern(): MaterialConsumptionPatternEnum;
     /**
@@ -122,6 +126,11 @@ export declare class MaterialConsumeTableController {
      * 根据bom明细构造子表数据(初始化时)
      */
     calcFormState(): IMaterialConsumeData[] | undefined;
+    /**
+     * 未填报时初始化消耗表行数据
+     * @param defaultData 子表行默认值（含工序等）
+     */
+    initTableData(defaultData?: Record<string, any>): void;
     /**
      * 根据数据计算需要禁用的字段
      * @param row
@@ -135,17 +144,34 @@ export declare class MaterialConsumeTableController {
     getProductQuery(): {
         'id_.in': (string | undefined)[];
     } | undefined;
+    /**
+     * 行级 product_id_ / material_no_ 查询共用入参
+     */
+    private buildProductQueryOptions;
+    /**
+     * 行级 product_id_ 下拉过滤（覆盖全局 id_.in）
+     */
+    getProductQueryForRow(row: IMaterialConsumeData, rowIndex?: number): import('./product-id-query').ProductIdQuery | undefined;
+    /**
+     * 行级 material_no_ 批次过滤：有物料按物料；无物料与 product_id_ 可选范围一致
+     */
+    getMaterialNoQueryForRow(row: IMaterialConsumeData, rowIndex?: number): import('./product-id-query').MaterialNoQuery;
     /**
      * 是否是第一行且物料是空行
      * @return {*}
      */
     isFirstBlankRow(): boolean;
+    /**
+     * 是否有正在编辑的组。
+     * 一组可多行同时为编辑态；同时只能有一组处于编辑态。
+     */
+    hasEditingGroup(showMessage?: boolean): boolean;
     /**
      * 解析扫码的数据
      * 并判断是否能存入表中,返回对象则表示可以存入
      * @param str
      */
-    protected parseScanStr(str: string): Promise<void>;
+    protected parseScanStr(data: any, transformedData: any): Promise<void>;
     /** 扫描是否已经打开 */
     isScanOpen: boolean;
     /**
@@ -170,9 +196,17 @@ export declare class MaterialConsumeTableController {
         formModelController: FormModelController;
         unitConversionRules?: IUnitConversionRule[];
         mainFormState?: Ref<any>;
+        /** 表单 dataStatus，未填报才允许初始化行数据 */
+        dataStatus?: string;
+        /** 子表行默认值 */
+        defaultRowData?: Record<string, any>;
     }): Promise<void>;
+    /**
+     * 按当前 materialNoNum 回写各行 qty_required_（校验侧 total 已通过 getter 实时读取）
+     */
+    syncQtyRequiredFromBom(): void;
     /** 校验有效期 */
-    validateExpiration(row: IMaterialConsumeData): void;
+    validateExpiration(row: any): void;
     /**
      * 单位转化规则钩子
      * 触发时机：扫码插入自动确认、手动点确认按钮（均汇聚到 confirm）
@@ -212,15 +246,23 @@ export declare class MaterialConsumeTableController {
      */
     hasEditingRow(showMessage?: boolean): boolean;
     /**
-     * 选中行开启编辑
+     * 选中行开启编辑（顺序上料：校验当前编辑组后整组切换；非顺序上料：始终编辑态，无需操作）
      * @param row
      */
-    editRow(row: IMaterialConsumeData): void;
+    editRow(row: IMaterialConsumeData): Promise<void>;
     /**
      * 更新整个数组的所有行的已消耗数量
      * @param row
      */
     updateRowConsumed(): void;
+    /**
+     * 组级：更新 qty_consumed_total_（同组 qty_ 之和）
+     */
+    updateGroupQtyConsumedTotal(): void;
+    /**
+     * qty 相关派生字段统一入口（改 qty_ / 扫码 / 删行 等都走这里）
+     */
+    updateDerivedQtyFields(): void;
     /**
      * 设置默认值，如工序，需求数量/已消耗数量
      * @param row
@@ -235,5 +277,5 @@ export declare class MaterialConsumeTableController {
         row: IMaterialConsumeData;
         value: any;
         option?: any;
-    }): void;
+    }): Promise<void>;
 }

package/dist/src/nocode-base/src/hooks/material-consume/mc-render.d.ts

@@ -56,6 +56,14 @@ export declare class MCRender implements IMcRender {
         subModelKey?: string;
         formModelController: FormModelController;
     }): Promise<ParseRuleProps | undefined>;
+    /**
+     * 扫码返回多条候选时，弹窗选择其中一条
+     * 取消返回 undefined
+     */
+    openMultiRowsModal(opts: {
+        rows: any[];
+        title?: string;
+    }): Promise<any | undefined>;
     /**
      * 销毁所有固定的模态
      */

package/dist/src/nocode-base/src/hooks/material-consume/product-id-query.d.ts

@@ -0,0 +1,31 @@
+import { BomEntriesValidator } from './bom-validator';
+import { IMaterialConsumeData } from './types';
+/** RDO 将空 id_.in / versionIn 视为不筛选，无候选时用占位 version id 使下拉返回空列表 */
+export declare const EMPTY_PRODUCT_VERSION_ID = "__mc_no_selectable_product__";
+/** 指定批次开启但列表为空时，使批次下拉返回空列表 */
+export declare const EMPTY_LOT_NAME = "__mc_no_selectable_lot__";
+export type ProductIdQuery = {
+    'id_.in': (string | undefined)[];
+};
+export declare function isEmptyProductQuery(query?: ProductIdQuery): boolean;
+export type MaterialNoQuery = {
+    'product_id_.versionIn': (string | undefined)[] | null;
+    'name_.in'?: string[];
+};
+export interface BuildProductIdQueryOptions {
+    validator: BomEntriesValidator;
+    tableData: IMaterialConsumeData[];
+    row: IMaterialConsumeData;
+    rowIndex?: number;
+    enableSequenceLoading: boolean;
+    /** 记录模式且未启 personal BOM 时为 true */
+    skipFilter: boolean;
+}
+/** 构建 product_id_ 行级下拉查询条件 */
+export declare function buildProductIdQuery(options: BuildProductIdQueryOptions): ProductIdQuery | undefined;
+/**
+ * 构建 material_no_ 行级批次过滤
+ * - 有 product_id_：仅该物料版本
+ * - 无 product_id_：与 product_id_ 下拉可选范围一致
+ */
+export declare function buildMaterialNoQuery(options: BuildProductIdQueryOptions): MaterialNoQuery;

package/dist/src/nocode-base/src/hooks/material-consume/scan-fill.d.ts

@@ -0,0 +1,10 @@
+import { BomEntryValidator, ScanFillPlan } from './bom-validator';
+import { IMaterialConsumeData } from './types';
+export type ValidateCurrentGroupForSwitch = (table: IMaterialConsumeData[], current: BomEntryValidator) => void | Promise<void>;
+/**
+ * 按 ScanFillPlan 切组 / 建组 / 填充，返回新表（不改入参 arr）。
+ * needSwitch 时通过 options.validateCurrentGroupForSwitch 先校验当前组。
+ */
+export declare function applyScanFillPlan(arr: IMaterialConsumeData[], scanRow: IMaterialConsumeData, plan?: ScanFillPlan, options?: {
+    validateCurrentGroupForSwitch?: ValidateCurrentGroupForSwitch;
+}): Promise<IMaterialConsumeData[]>;

package/dist/src/nocode-base/src/hooks/material-consume/scan-validator.d.ts

@@ -0,0 +1,192 @@
+import { IBomEntry, IMaterialConsumeData } from './types';
+/**
+ * 扫码校验与填充
+ * 对应 scan-validation-logic.md
+ * 独立于 bom-validator.ts，只依赖 types 中的 IBomEntry / IMaterialConsumeData
+ */
+/** 横线下方三种扫码场景 */
+export declare enum ScanBizScenario {
+    /** 有 BOM，按顺序上料，同时只有一组可编辑 */
+    HAS_BOM_SEQUENTIAL = "has_bom_sequential",
+    /** 有 BOM，不按顺序上料，所有行可编辑 */
+    HAS_BOM_FREE = "has_bom_free",
+    /** 没有 BOM，所有行可编辑 */
+    NO_BOM = "no_bom"
+}
+/** 填充动作：新增行 / 回填空物料 / 回填空批次 */
+export type ScanFillAction = 'append' | 'fillEmptyProduct' | 'fillEmptyLot';
+export interface ScanValidatorOptions {
+    /** 是否按顺序上料 */
+    enableSequenceLoading: boolean;
+    /** BOM 明细列表，场景三可传空数组 */
+    bomEntries?: IBomEntry[];
+    /** 场景三：无 BOM 时是否按批次上料。有 BOM 时以明细 type_ 为准 */
+    byLotEnabled?: boolean;
+}
+/** 填充成功后的表数据与动作 */
+export interface ScanFillResult {
+    table: IMaterialConsumeData[];
+    groupSwitched: boolean;
+    fillAction: ScanFillAction;
+}
+/** 对齐 materialCheck 返回项 */
+export interface ScanCheckItem {
+    materialId: string;
+    materialNo?: string;
+    productionIdentificationName: string;
+}
+export type ResolveScanCandidatesResult = {
+    status: 'single';
+    row: IMaterialConsumeData;
+} | {
+    status: 'needSelect';
+    candidates: IMaterialConsumeData[];
+};
+/** handleScan 返回：多条待选，或已填充 */
+export type HandleScanResult = {
+    status: 'needSelect';
+    candidates: IMaterialConsumeData[];
+} | ({
+    status: 'filled';
+} & ScanFillResult);
+/**
+ * 把扫码接口一条结果转成表行。
+ * extra 可带数量、有效期等；物料/批次默认取接口字段，extra 可覆盖。
+ */
+export declare function toScanRow(item: ScanCheckItem, extra?: Partial<IMaterialConsumeData>): IMaterialConsumeData;
+/**
+ * 取一组允许出现的物料 id：主料，以及开启替代料时的替代料。
+ * 用于判断某物料是否属于该 BOM 明细组。
+ */
+export declare function getGroupProductIds(entry: IBomEntry): string[];
+/**
+ * 按物料 id 找到所属 BOM 明细（主料或替代料命中即返回）。
+ * 找不到说明物料不在当前 BOM 中。
+ */
+export declare function findEntryByProductId(entries: IBomEntry[], productId: string): IBomEntry | undefined;
+/**
+ * 三个场景共用的第一步：把接口返回列表收成单条 scanRow。
+ * - 0 条：抛错
+ * - 1 条：直接作为 scanRow
+ * - 多条：返回 needSelect，由调用方弹窗；本函数不改表、不跑后续校验
+ */
+export declare function resolveScanCandidates(rows: IMaterialConsumeData[]): ResolveScanCandidatesResult;
+/**
+ * 按「有无 BOM 明细 + 是否按顺序上料」判定场景。
+ * 不使用人为指定 / BOM 模式 / 记录模式。
+ */
+export declare function resolveScanScenario(options: {
+    enableSequenceLoading: boolean;
+    bomEntries?: IBomEntry[];
+}): ScanBizScenario;
+/**
+ * 通用校验 1：扫码物料是否出现在 BOM 明细（主料或替代料）中。
+ * 场景三无 BOM，不调用本函数。找不到则抛错。
+ */
+export declare function validateInBom(row: IMaterialConsumeData, entries: IBomEntry[]): void;
+/** 判断物料 id 是否属于该 BOM 组（主料或已启用的替代料） */
+export declare function isMemberOfGroup(productId: string | undefined, entry: IBomEntry): boolean;
+/**
+ * 通用校验 2：物料是否允许写入目标组。
+ * 查看 / 未开替代料：必须是主料。
+ * 整批替代：组内已有物料时必须与之一致。
+ * 混用替代：必须是主料或替代料。
+ */
+export declare function assertMaterialInGroup(productId: string | undefined, entry: IBomEntry, groupRows?: IMaterialConsumeData[]): void;
+/**
+ * 通用校验 3：按批次上料且开启混批时，同一组同一物料的不同批次数不能超过 lot_mixing_times_。
+ * includeIncomingLot 为 true 时，把即将写入的批次也算进去，避免先插入再超限。
+ */
+export declare function validateLotMixingForProduct(row: IMaterialConsumeData, groupRows: IMaterialConsumeData[], entry: IBomEntry, includeIncomingLot?: boolean): void;
+/**
+ * 通用校验 4：有效期为空则跳过；有效期当天结束仍早于现在则视为过期并抛错。
+ */
+export declare function checkExpiration(row: IMaterialConsumeData): void;
+/**
+ * 通用校验 5：开启数量校验时，同一组所有物料的上料之和 vs 组需求量。
+ * diff = 上料之和 - 需求量。eq：diff === 0；gte：diff >= 0；lte：diff <= 0；
+ * bounds：min <= diff <= max。
+ * 不按顺序上料且规则为 eq 时，允许 diff < 0（少上料），diff > 0 仍抛错。
+ */
+export declare function validateQtyForGroup(groupRows: IMaterialConsumeData[], entry: IBomEntry, sequential?: boolean): Promise<void>;
+/**
+ * 整组校验：切组前先对每一行走必填 + 通用 2、3、4，再整组跑一次通用 5。
+ * 任一项失败则中断，不切组、不填充。
+ */
+export declare function validateGroupRows(groupRows: IMaterialConsumeData[], entry: IBomEntry, sequential?: boolean): Promise<void>;
+/**
+ * 物料消耗表扫码校验与填充。
+ * 对应 scan-validation-logic.md；不依赖 bom-validator.ts。
+ */
+export declare class BomEntriesValidator {
+    private options;
+    constructor(options: ScanValidatorOptions);
+    /** 当前配置对应的扫码场景 */
+    get scenario(): ScanBizScenario;
+    /** BOM 明细，无 BOM 时为空数组 */
+    get entries(): IBomEntry[];
+    /** 按 sort_num_ 排序后的 BOM 明细，用于顺序上料定位当前组 / 下一组 */
+    get sortedEntries(): IBomEntry[];
+    /**
+     * 扫码总入口。
+     * 入参可为单条或接口返回的多条；不修改入参 table。
+     * 多条时返回 needSelect（调用方弹窗后再以选中的一条调用）；
+     * 单条则按场景走校验和填充，返回 filled。
+     * TODO: 待处理 — 尚未接入 Controller / 选择弹窗
+     */
+    handleScan(scanInput: IMaterialConsumeData | IMaterialConsumeData[], table: IMaterialConsumeData[]): Promise<HandleScanResult>;
+    /**
+     * 场景一：有 BOM 且按顺序上料。仅当前编辑组可写。
+     * 属于当前组：通用 2（含整批）→ 通用 3 → 填充。
+     * 不属于：前面组报错，否则切下一组。
+     */
+    private runScenario1;
+    /** 扫码物料属于前面组：已在表中 → 请勿重复上料；非必须且不在表中 → 请按顺序上料 */
+    private assertNotPreviousGroup;
+    /**
+     * 顺序上料切组：非必须且表中没有时，物料属于该组则收下，否则继续往后。
+     * 目标组不在表中：在当前组下方插入空行再填充。
+     */
+    private switchToNextGroup;
+    /** 在当前组最后一行下方插入目标组空占位行 */
+    private insertEmptyGroupBelow;
+    /**
+     * 场景二：有 BOM 但不按顺序。所有行可编辑，不切组。
+     * 表中没有该组：通用 2、3 后表末追加。有则通用 2、3 后走填充。
+     */
+    private runScenario2;
+    /**
+     * 场景三：没有 BOM。只校验有效期，不跑通用 1/2/3。
+     * 优先填空物料行，其次按批次填「有物料无批次」行，否则表末新增。
+     */
+    private runScenario3;
+    /**
+     * 顺序上料时定位「当前编辑组」在排序后 BOM 中的下标。
+     * 1. 编辑行有物料或 bom_entry_id_：按现逻辑匹配
+     * 2. 未初始化：取表中最后一组已出现（已确认）明细的序号，当前组 = BOM 下一条
+     * 3. 表里还没有任何组：第一组
+     */
+    private resolveCurrentGroupIndex;
+    /**
+     * 从表尾往前找最后一组已出现的 BOM 明细（已确认且有物料或 bom_entry_id_）。
+     * 找不到返回 -1。
+     */
+    private findLastAppearedGroupIndex;
+    /** 表中是否已有该 BOM 组（有物料行或带 bom_entry_id_ 的空行） */
+    private groupExistsInTable;
+    /**
+     * 收集空物料行下标。extra 可再限制范围（如仅当前编辑组、或匹配 bom_entry_id_）。
+     */
+    private collectEmptyProductIndexes;
+    /**
+     * 收集某 BOM 组在表中的范围：组成员行、空物料行、空批次行，以及默认插入位置。
+     * editingGroup 为 true 时，未确认的空物料行也算进该组。
+     */
+    private collectGroupScope;
+    /**
+     * 切组时改编辑态：当前组行确认（禁用），目标组行取消确认（可编辑）。
+     */
+    private applyGroupEditState;
+}
+/** 创建扫码校验器实例 */
+export declare function createBomValidator(options: ScanValidatorOptions): BomEntriesValidator;

package/dist/src/nocode-base/src/hooks/material-consume/service.d.ts

@@ -64,3 +64,5 @@ export declare function judgeUnique(opts: {
 }>;
 /** 是否有BOM授权 */
 export declare function isBomGranted(): Promise<any>;
+/** 查批次锁定记录（最新一条） */
+export declare function getLotLockedReason(production_identification_id_: string): Promise<string>;