kcode-pi 0.1.0

package/vendor/kingdee-skills/ok-cosmic/assets/snippets/operation/OpAddValidatorsSample.java

@@ -0,0 +1,137 @@
+/**
+ * onPreparePropertys + onAddValidators 示例。
+ * <p>
+ * 适用插件：操作插件
+ * 优先封装：AbstractOperationServicePlugInExt、AbstractValidatorExt、DynamicObjectUtils
+ * 原生兜底：PreparePropertysEventArgs、AddValidatorsEventArgs、ExtendedDataEntity
+ * 相关 lint 规则：STYLE-003、STYLE-010
+ * <p>
+ * 使用场景：
+ * 1. preparePropertys 显式准备头/体字段
+ * 2. onAddValidators 按规则拆分校验器
+ * 3. 单据头校验、分录聚合校验、分录行级校验分开处理
+ * 4. 错误信息挂到操作结果里，而不是直接抛异常
+ */
+package kd.cd.common.snippets.operation;
+
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.dataentity.entity.DynamicObjectCollection;
+import kd.bos.dataentity.resource.ResManager;
+import kd.bos.entity.ExtendedDataEntity;
+import kd.bos.entity.plugin.AddValidatorsEventArgs;
+import kd.bos.entity.plugin.PreparePropertysEventArgs;
+import kd.cd.common.plugin.AbstractOperationServicePlugInExt;
+import kd.cd.common.plugin.AbstractValidatorExt;
+import kd.cd.common.util.DynamicObjectUtils;
+import kd.cd.core.util.BigDecimalUtils;
+
+import java.math.BigDecimal;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.stream.Collectors;
+
+public class OpAddValidatorsSample extends AbstractOperationServicePlugInExt {
+    private static final String TARGET_BILL_TYPE = "kdcd_measuresettlebill_B_02";
+    private static final String FIELD_BILL_NO = "billno";
+    private static final String FIELD_CONTRACT = "kdcd_contract";
+    private static final String FIELD_BILL_TYPE = "kdcd_billtype";
+    private static final String FIELD_INITIALIZATION = "kdcd_initialization";
+    private static final String ENTRY_MEASURE_DETAIL = "kdcd_measuredelail";
+    private static final String FIELD_TOTAL_TAX = "kdcd_totaltax";
+    private static final String ENTRY_INVOICE_DETAIL = "kdcd_invoicedetail";
+    private static final String FIELD_PRICE_TAX_TOTAL = "kdcd_pricetaxtotal";
+    private static final String FIELD_SEQ = "seq";
+
+    @Override
+    public void onPreparePropertys(PreparePropertysEventArgs e) {
+        super.onPreparePropertys(e);
+        List<String> fieldKeys = e.getFieldKeys();
+        fieldKeys.add(FIELD_BILL_NO);
+        fieldKeys.add(FIELD_CONTRACT);
+        fieldKeys.add(FIELD_CONTRACT + ".number");
+        fieldKeys.add(FIELD_BILL_TYPE);
+        fieldKeys.add(FIELD_BILL_TYPE + ".number");
+        fieldKeys.add(FIELD_INITIALIZATION);
+        fieldKeys.addAll(entryFields(ENTRY_MEASURE_DETAIL, ENTRY_INVOICE_DETAIL));
+    }
+
+    @Override
+    public void onAddValidators(AddValidatorsEventArgs e) {
+        super.onAddValidators(e);
+        e.addValidator(new ContractRequiredValidator());
+        e.addValidator(new InvoiceAmountEqualsValidator());
+        e.addValidator(new InvoiceAmountPositiveValidator());
+    }
+
+    private static class ContractRequiredValidator extends AbstractValidatorExt {
+        @Override
+        public void validate() {
+            for (ExtendedDataEntity ext : getDataEntities()) {
+                DynamicObject bill = ext.getDataEntity();
+                if (shouldSkip(bill)) {
+                    continue;
+                }
+                if (bill.getDynamicObject(FIELD_CONTRACT) == null) {
+                    addMessageWithErrCode(ext, "kdcd_contract_required", "合同不能为空");
+                }
+            }
+        }
+    }
+
+    private static class InvoiceAmountEqualsValidator extends AbstractValidatorExt {
+        @Override
+        public void validate() {
+            for (ExtendedDataEntity ext : getDataEntities()) {
+                DynamicObject bill = ext.getDataEntity();
+                if (shouldSkip(bill)) {
+                    continue;
+                }
+
+                DynamicObjectCollection measureRows = bill.getDynamicObjectCollection(ENTRY_MEASURE_DETAIL);
+                DynamicObjectCollection invoiceRows = bill.getDynamicObjectCollection(ENTRY_INVOICE_DETAIL);
+                BigDecimal measureTotal = DynamicObjectUtils.sumOf(measureRows, FIELD_TOTAL_TAX);
+                BigDecimal invoiceTotal = DynamicObjectUtils.sumOf(invoiceRows, FIELD_PRICE_TAX_TOTAL);
+                if (!BigDecimalUtils.equals(measureTotal, invoiceTotal)) {
+                    addMessageWithErrCode(ext, "kdcd_invoice_amount_not_match", "发票明细价税合计必须等于计量明细本期价税合计");
+                }
+            }
+        }
+    }
+
+    private static class InvoiceAmountPositiveValidator extends AbstractValidatorExt {
+        @Override
+        public void validate() {
+            for (ExtendedDataEntity ext : getDataEntities()) {
+                DynamicObject bill = ext.getDataEntity();
+                if (shouldSkip(bill)) {
+                    continue;
+                }
+
+                DynamicObjectCollection invoiceRows = bill.getDynamicObjectCollection(ENTRY_INVOICE_DETAIL);
+                List<String> invalidSeqs = invoiceRows.stream()
+                        .filter(row -> !BigDecimalUtils.largeThanZero(
+                                BigDecimalUtils.nullToZero(row.getBigDecimal(FIELD_PRICE_TAX_TOTAL))))
+                        .map(row -> String.valueOf(row.get(FIELD_SEQ)))
+                        .collect(Collectors.toList());
+                if (!invalidSeqs.isEmpty()) {
+                    addMessageWithErrCode(
+                            ext,
+                            "kdcd_invoice_row_amount_not_positive",
+                            String.format(
+                                    ResManager.loadKDString("发票明细第%s行价税合计必须大于 0", "OpAddValidatorsSample_0", "kd-cd-common-snippets"),
+                                    String.join("、", invalidSeqs)
+                            )
+                    );
+                }
+            }
+        }
+    }
+
+    private static boolean isTargetBill(DynamicObject bill) {
+        return TARGET_BILL_TYPE.equals(DynamicObjectUtils.nullSafeGet(bill, FIELD_BILL_TYPE + ".number"));
+    }
+
+    private static boolean shouldSkip(DynamicObject bill) {
+        return !isTargetBill(bill) || Boolean.TRUE.equals(DynamicObjectUtils.nullSafeGet(bill, FIELD_INITIALIZATION));
+    }
+}

package/vendor/kingdee-skills/ok-cosmic/assets/snippets/operation/OperationOptionBridgeSample.java

@@ -0,0 +1,228 @@
+/**
+ * 界面插件与操作插件之间通过 OperateOption 传值示例。
+ * <p>
+ * 适用插件：表单插件、操作插件
+ * 优先封装：AbstractFormPluginExt、AbstractOperationServicePlugInExt
+ * 原生兜底：OperateOption、BeforeDoOperationEventArgs、AfterOperationArgs
+ * 相关 lint 规则：SCENE-001、STYLE-013
+ * <p>
+ * 使用场景：
+ * 1. 提交前先打开复核页，用户确认后带 continue 标记重新执行提交；
+ * 2. 界面插件把临时参数传给操作插件；
+ * 3. 操作插件把处理结果回写到 option，供界面插件展示提示。
+ */
+package kd.cd.common.snippets.operation;
+
+import kd.bos.bill.OperationStatus;
+import kd.bos.dataentity.OperateOption;
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.dataentity.resource.ResManager;
+import kd.bos.entity.plugin.args.AfterOperationArgs;
+import kd.bos.entity.plugin.args.BeginOperationTransactionArgs;
+import kd.bos.form.CloseCallBack;
+import kd.bos.form.FormShowParameter;
+import kd.bos.form.ShowType;
+import kd.bos.form.events.AfterDoOperationEventArgs;
+import kd.bos.form.events.BeforeDoOperationEventArgs;
+import kd.bos.form.events.ClosedCallBackEvent;
+import kd.bos.form.operate.FormOperate;
+import kd.cd.common.form.ShowParameterUtils;
+import kd.cd.common.plugin.AbstractFormPluginExt;
+import kd.cd.common.plugin.AbstractOperationServicePlugInExt;
+import kd.cd.core.util.CharSequenceUtils;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+import java.util.Map;
+
+public class OperationOptionBridgeSample {
+    public static final String OP_SUBMIT = "submit";
+    public static final String REVIEW_FORM_ID = "xxxx_submitreview";
+    public static final String REVIEW_CALLBACK_ID = "submit_review";
+    public static final String OPTION_CUSTOM_ITEM = "customItem";
+    public static final String OPTION_SKIP_SUBMIT_REVIEW = "skipSubmitReview";
+    public static final String OPTION_REVIEW_COMMENT = "reviewComment";
+    public static final String OPTION_ALL_BILL_NO = "allBillNo";
+    public static final String OPTION_WARNING_SUMMARY = "warningSummary";
+    public static final String FIELD_RISK_FLAG = "xxxx_riskflag";
+    public static final String FIELD_REVIEW_COMMENT = "xxxx_reviewcomment";
+    public static final String FIELD_CUSTOM_TAG = "xxxx_customtag";
+
+    /**
+     * 界面插件侧：提交前拦截、弹复核页、读取操作插件回传值。
+     * 同文件中同时放了操作插件示例，lint 可能把本类里的 getView() 误判到操作插件上下文。
+     */
+    public static class BillViewSide extends AbstractFormPluginExt {
+        @Override
+        public void beforeDoOperation(BeforeDoOperationEventArgs e) {
+            super.beforeDoOperation(e);
+            FormOperate operate = (FormOperate) e.getSource();
+            if (!OP_SUBMIT.equals(operate.getOperateKey())) {
+                return;
+            }
+
+            bindSharedOption(operate.getOption());
+            if (shouldSkipSubmitReview(operate.getOption()) || !needOpenSubmitReview()) {
+                return;
+            }
+
+            e.setCancel(true);
+            openSubmitReviewDialog();
+        }
+
+        @Override
+        public void afterDoOperation(AfterDoOperationEventArgs e) {
+            super.afterDoOperation(e);
+            FormOperate operate = (FormOperate) e.getSource();
+            if (!OP_SUBMIT.equals(operate.getOperateKey()) || !e.getOperationResult().isSuccess()) {
+                return;
+            }
+
+            String allBillNo = operate.getOption().getVariableValue(OPTION_ALL_BILL_NO, "");
+            String warningSummary = operate.getOption().getVariableValue(OPTION_WARNING_SUMMARY, "");
+            if (CharSequenceUtils.isBlank(allBillNo) && CharSequenceUtils.isBlank(warningSummary)) {
+                return;
+            }
+
+            StringBuilder msg = new StringBuilder("提交成功");
+            if (CharSequenceUtils.isNotBlank(allBillNo)) {
+                msg.append("：").append(allBillNo);
+            }
+            if (CharSequenceUtils.isNotBlank(warningSummary)) {
+                msg.append("；").append(warningSummary);
+            }
+            e.getOperationResult().setMessage(msg.toString());
+        }
+
+        @Override
+        public void closedCallBack(ClosedCallBackEvent e) {
+            super.closedCallBack(e);
+            // 回调数据类型和复核页的回传类型保持一致即可。
+            if (!REVIEW_CALLBACK_ID.equals(e.getActionId())) {
+                return;
+            }
+            @SuppressWarnings("unchecked")
+            Map<String, Object> reviewData = (Map<String, Object>) e.getReturnData();
+            if (reviewData == null || !isConfirmed(reviewData)) {
+                return;
+            }
+
+            OperateOption option = OperateOption.create();
+            bindSharedOption(option);
+            option.setVariableValue(OPTION_SKIP_SUBMIT_REVIEW, "true");
+
+            String reviewComment = extractReviewComment(reviewData);
+            if (CharSequenceUtils.isNotBlank(reviewComment)) {
+                option.setVariableValue(OPTION_REVIEW_COMMENT, reviewComment);
+            }
+            getView().invokeOperation(OP_SUBMIT, option);
+        }
+
+        private void bindSharedOption(OperateOption option) {
+            String customItem = resolveCustomItem();
+            if (CharSequenceUtils.isNotBlank(customItem)) {
+                option.setVariableValue(OPTION_CUSTOM_ITEM, customItem);
+            }
+        }
+
+        private boolean needOpenSubmitReview() {
+            return Boolean.TRUE.equals(getModel().getValue(FIELD_RISK_FLAG));
+        }
+
+        private boolean shouldSkipSubmitReview(OperateOption option) {
+            return "true".equalsIgnoreCase(option.getVariableValue(OPTION_SKIP_SUBMIT_REVIEW, "false"));
+        }
+
+        private void openSubmitReviewDialog() {
+            FormShowParameter fsp = ShowParameterUtils.getForm(
+                    REVIEW_FORM_ID,
+                    OperationStatus.ADDNEW,
+                    ShowType.Modal,
+                    "720px",
+                    "420px"
+            );
+            fsp.setCustomParam("billNo", getModel().getValue("billno"));
+            fsp.setCustomParam("customItem", resolveCustomItem());
+            fsp.setCloseCallBack(new CloseCallBack(this, REVIEW_CALLBACK_ID));
+            getView().showForm(fsp);
+        }
+
+        private String resolveCustomItem() {
+            Object customTag = getModel().getValue(FIELD_CUSTOM_TAG);
+            String text = customTag == null ? "" : String.valueOf(customTag).trim();
+            return CharSequenceUtils.isBlank(text) ? "default-tag" : text;
+        }
+
+        private boolean isConfirmed(Map<String, Object> returnData) {
+            return Boolean.TRUE.equals(returnData.get("confirmed"));
+        }
+
+        private String extractReviewComment(Map<String, Object> returnData) {
+            Object comment = returnData.get("reviewComment");
+            return comment == null ? "" : String.valueOf(comment).trim();
+        }
+    }
+
+    /**
+     * 操作插件侧：读取界面参数并回写结果摘要。
+     */
+    public static class SaveSubmitOpSide extends AbstractOperationServicePlugInExt {
+        @Override
+        public void beginOperationTransaction(BeginOperationTransactionArgs e) {
+            super.beginOperationTransaction(e);
+            if (!OP_SUBMIT.equals(e.getOperationKey())) {
+                return;
+            }
+
+            String customItem = getOption().getVariableValue(OPTION_CUSTOM_ITEM, "");
+            String reviewComment = getOption().getVariableValue(OPTION_REVIEW_COMMENT, "");
+            for (DynamicObject bill : e.getDataEntities()) {
+                if (CharSequenceUtils.isNotBlank(customItem)) {
+                    bill.set("remark", appendRemark(bill.getString("remark"), customItem));
+                }
+                if (CharSequenceUtils.isNotBlank(reviewComment)) {
+                    bill.set(FIELD_REVIEW_COMMENT, reviewComment);
+                }
+            }
+        }
+
+        @Override
+        public void afterExecuteOperationTransaction(AfterOperationArgs e) {
+            super.afterExecuteOperationTransaction(e);
+            if (!OP_SUBMIT.equals(e.getOperationKey()) || !getOperationResult().isSuccess()) {
+                return;
+            }
+
+            List<String> billNoList = new ArrayList<>();
+            boolean hasRiskBill = false;
+            for (DynamicObject bill : e.getDataEntities()) {
+                String billNo = bill.getString("billno");
+                if (CharSequenceUtils.isNotBlank(billNo)) {
+                    billNoList.add(billNo);
+                }
+                hasRiskBill = hasRiskBill || isRiskBill(bill);
+            }
+            getOption().setVariableValue(OPTION_ALL_BILL_NO, String.join("、", billNoList));
+            if (hasRiskBill) {
+                getOption().setVariableValue(OPTION_WARNING_SUMMARY, "命中风险复核，已按复核意见继续提交");
+            }
+        }
+
+        private String appendRemark(String remark, String customItem) {
+            String line = String.format(
+                    ResManager.loadKDString("界面参数:%s", "OperationOptionBridgeSample_0", "kd-cd-common-snippets"),
+                    customItem
+            );
+            if (CharSequenceUtils.isBlank(remark)) {
+                return line;
+            }
+            return remark + System.lineSeparator() + line;
+        }
+
+        private boolean isRiskBill(DynamicObject bill) {
+            return Boolean.TRUE.equals(bill.get(FIELD_RISK_FLAG));
+        }
+    }
+}

package/vendor/kingdee-skills/ok-cosmic/assets/snippets/package-info.java

@@ -0,0 +1,19 @@
+/**
+ * 苍穹 Commons 示例样本总览。
+ * <p>
+ * 建议按“先选场景、再看 API”的顺序阅读：
+ * <ul>
+ *     <li>{@code attachment}: 附件上传、绑定、覆盖策略</li>
+ *     <li>{@code botp}: 上下游追踪、直接/全链路查询、下推生成</li>
+ *     <li>{@code data}: DynamicObject 安全操作、后端建单/保存/复制</li>
+ *     <li>{@code form}: 表单/单据插件常见交互、页面状态控制、弹窗、回调、树控件、F7 过滤</li>
+ *     <li>{@code list}: 列表插件过滤、列格式化、操作列控制</li>
+ *     <li>{@code message}: 系统消息与通知用户收集</li>
+ *     <li>{@code operation}: 操作插件、校验器注册、界面/操作参数桥接</li>
+ *     <li>{@code query}: 基础资料缓存查询、DataSet 聚合、批量取数</li>
+ *     <li>{@code task}: 后台任务与巡检型逻辑</li>
+ * </ul>
+ * <p>
+ * 每个样本尽量围绕一个明确场景展开，避免同一 API 在多个文件中重复铺陈。
+ */
+package kd.cd.common.snippets;

package/vendor/kingdee-skills/ok-cosmic/assets/snippets/query/BaseDataQuerySample.java

@@ -0,0 +1,194 @@
+/**
+ * 基础资料查询示例。
+ * <p>
+ * 适用插件：表单插件、操作插件、服务层
+ * 优先封装：BusinessDataServiceHelper.loadFromCache(...)
+ * 原生兜底：BaseDataServiceHelper、QFilter、QueryServiceHelper
+ * 相关 lint 规则：STYLE-008、STYLE-015
+ * <p>
+ * 使用场景：根据编码、ID 或批量条件加载基础资料并回写界面。
+ * 关键点：
+ * 1. 基础资料优先走 BusinessDataServiceHelper.loadFromCache(...)。
+ * 2. 需要先按编码查主键时，优先用 QueryServiceHelper.query(...)。
+ * 3. 批量场景先查主键集合，再一次性 loadFromCache，避免循环查库。
+ * 4. 带组织权限过滤时使用 BaseDataServiceHelper.queryBaseData(...)。
+ */
+package kd.cd.common.snippets.query;
+
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.dataentity.entity.DynamicObjectCollection;
+import kd.bos.orm.query.QCP;
+import kd.bos.orm.query.QFilter;
+import kd.bos.servicehelper.BusinessDataServiceHelper;
+import kd.bos.servicehelper.QueryServiceHelper;
+import kd.bos.servicehelper.basedata.BaseDataServiceHelper;
+import kd.cd.common.plugin.AbstractFormPluginExt;
+import kd.cd.common.util.DynamicObjectUtils;
+import kd.cd.core.util.CollectionUtils;
+
+import java.util.Collection;
+import java.util.Collections;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+public class BaseDataQuerySample extends AbstractFormPluginExt {
+    private static final String BD_SUPPLIER = "bd_supplier";
+    private static final String BD_CUSTOMER = "bd_customer";
+    private static final String BOS_USER = "bos_user";
+    private static final String BD_TAXRATE = "bd_taxrate";
+    private static final String FIELD_ID = "id";
+    private static final String FIELD_NUMBER = "number";
+    private static final String FIELD_NAME = "name";
+    private static final String FIELD_ENABLE = "enable";
+    private static final String FIELD_STATUS = "status";
+
+    // ==================== 场景1：按主键批量走缓存查询 ====================
+
+    /**
+     * 根据主键集合批量走缓存，返回 id -> DynamicObject 映射
+     * 适用场景：已知主键集合，需要批量获取完整对象
+     */
+    public Map<Object, DynamicObject> loadEnabledAuditedSuppliers(Collection<?> supplierIds) {
+        if (CollectionUtils.isEmpty(supplierIds)) {
+            return Collections.emptyMap();
+        }
+
+        QFilter filter = new QFilter(FIELD_ID, QCP.in, supplierIds)
+                .and(new QFilter(FIELD_ENABLE, QCP.equals, true))
+                .and(new QFilter(FIELD_STATUS, QCP.equals, "C"));
+        return BusinessDataServiceHelper.loadFromCache(BD_SUPPLIER,
+                String.join(",", FIELD_ID, FIELD_NUMBER, FIELD_NAME), filter.toArray());
+    }
+
+    /**
+     * 批量加载用户信息（项目中常见场景：获取审批人姓名等）
+     *
+     * @param userIds 用户主键集合
+     * @return 用户名称拼接字符串
+     */
+    public String batchLoadUserNames(Collection<Object> userIds) {
+        if (CollectionUtils.isEmpty(userIds)) {
+            return "";
+        }
+        Map<Object, DynamicObject> map = BusinessDataServiceHelper.loadFromCache(BOS_USER,
+                new QFilter[]{new QFilter(FIELD_ID, QCP.in, userIds)});
+        return map.values().stream()
+                .map(o -> String.valueOf(o.get(FIELD_NAME)))
+                .collect(Collectors.joining("、"));
+    }
+
+    /**
+     * 批量加载并构建 Map（按编码或名称分组）
+     *
+     * @param supplierIds 供应商主键集合
+     * @return 编码 -> DynamicObject 映射
+     */
+    public Map<String, DynamicObject> loadSuppliersMapByNumber(Collection<?> supplierIds) {
+        Map<Object, DynamicObject> idMap = loadEnabledAuditedSuppliers(supplierIds);
+        return idMap.values().stream()
+                .collect(Collectors.toMap(o -> o.getString(FIELD_NUMBER), o -> o, (a, b) -> a));
+    }
+
+    // ==================== 场景2：按编码批量查询 ====================
+
+    /**
+     * 先按业务条件查主键集合，再批量加载缓存对象
+     */
+    public Map<Object, DynamicObject> queryAndLoadSuppliersByNumbers(Collection<String> supplierNumbers) {
+        if (CollectionUtils.isEmpty(supplierNumbers)) {
+            return Collections.emptyMap();
+        }
+        QFilter filter = new QFilter(FIELD_NUMBER, QCP.in, supplierNumbers);
+        DynamicObjectCollection rows = QueryServiceHelper.query(BD_SUPPLIER, "id", filter.toArray());
+        Set<Object> supplierIds = DynamicObjectUtils.setOf(rows, "id");
+        return loadEnabledAuditedSuppliers(supplierIds);
+    }
+
+    /**
+     * 根据税率值批量查询税率档案
+     *
+     * @param taxRates 税率值集合（如 6, 9, 13）
+     * @return 税率值 -> 税率档案对象
+     */
+    public Map<java.math.BigDecimal, DynamicObject> loadTaxRateByValues(Collection<java.math.BigDecimal> taxRates) {
+        if (CollectionUtils.isEmpty(taxRates)) {
+            return Collections.emptyMap();
+        }
+        QFilter filter = new QFilter("taxrate", QCP.in, taxRates)
+                .and(FIELD_ENABLE, QCP.equals, true)
+                .and(FIELD_STATUS, QCP.equals, "C");
+        Map<Object, DynamicObject> map = BusinessDataServiceHelper.loadFromCache(BD_TAXRATE,
+                String.join(",", FIELD_ID, FIELD_NUMBER, FIELD_NAME, "taxrate"), filter.toArray());
+        return map.values().stream()
+                .collect(Collectors.toMap(o -> o.getBigDecimal("taxrate"), o -> o, (a, b) -> a));
+    }
+
+    // ==================== 场景3：带组织权限过滤的批量查询 ====================
+
+    /**
+     * 根据税务登记号查询供应商/客户（带组织权限过滤）
+     * 适用场景：发票导入时根据税号匹配往来户
+     *
+     * @param orgId    组织ID
+     * @param taxNo    税务登记号
+     * @param isPurBiz 是否采购业务（true:供应商, false:客户）
+     * @return 供应商/客户对象
+     */
+    public DynamicObject querySupplierOrCustomerByTaxNo(long orgId, String taxNo, boolean isPurBiz) {
+        QFilter qfilter = new QFilter(FIELD_ENABLE, QCP.equals, Boolean.TRUE)
+                .and(FIELD_STATUS, QCP.equals, "C")
+                .and("tx_register_no", QCP.equals, taxNo);
+
+        String entity = isPurBiz ? BD_SUPPLIER : BD_CUSTOMER;
+        DynamicObjectCollection results = BaseDataServiceHelper.queryBaseData(
+                entity, orgId, qfilter, String.join(",", FIELD_ID, FIELD_NUMBER, FIELD_NAME, "entry_bank.bankaccount"));
+
+        if (!CollectionUtils.isEmpty(results)) {
+            return results.get(0);
+        }
+        return null;
+    }
+
+    // ==================== 场景4：批量查询用于数据转换/回填 ====================
+
+    /**
+     * 批量查询基础资料名称并做展示转换。
+     * <p>
+     * 为了避免“不同基础资料的名称字段不一致”这一类误导，
+     * 示例里把 nameField 显式作为参数传入。
+     *
+     * @param entityId  基础资料标识
+     * @param nameField 名称字段，如 name / fullname / shortname
+     * @param ids       主键集合
+     * @return 名称拼接字符串
+     */
+    public String batchLoadDimensionNames(String entityId, String nameField, Set<Long> ids) {
+        if (CollectionUtils.isEmpty(ids)) {
+            return "";
+        }
+        Map<Object, DynamicObject> valsFromDb = BusinessDataServiceHelper.loadFromCache(
+                entityId, nameField, new QFilter(FIELD_ID, QCP.in, ids).toArray());
+        List<String> names = valsFromDb.values().stream()
+                .map(x -> x.getString(nameField))
+                .collect(Collectors.toList());
+        return String.join("，", names);
+    }
+
+    // ==================== 场景5：查询主键集合用于后续处理 ====================
+
+    /**
+     * 查询满足条件的主键集合（用于后续批量操作）
+     *
+     * @param formId  表单标识
+     * @param filter  过滤条件
+     * @return 主键集合
+     */
+    public Set<Object> queryPkSetForBatchProcess(String formId, QFilter filter) {
+        DynamicObjectCollection rows = QueryServiceHelper.query(formId, "id", filter.toArray());
+        return DynamicObjectUtils.setOf(rows, "id");
+    }
+}