kcode-pi 0.1.0

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

@@ -0,0 +1,132 @@
+/**
+ * View 生命周期与页面控制示例。
+ * <p>
+ * 适用插件：表单插件、单据插件
+ * 优先封装：AbstractFormPluginExt、PageCache
+ * 原生兜底：PreOpenFormEventArgs、BeforeClosedEvent、Toolbar
+ * 相关 lint 规则：SCENE-006、SCENE-007、SCENE-008
+ * <p>
+ * 使用场景：
+ * 1. preOpenForm 阶段决定是否允许打开页面；
+ * 2. afterBindData 阶段按新增/编辑/审核状态控制可见性和锁定性；
+ * 3. 局部刷新、工具栏重放、页面关闭、pageCache 暂存；
+ * 4. 运行时修改控件标题。
+ */
+package kd.cd.common.snippets.form;
+
+import kd.bos.bill.OperationStatus;
+import kd.bos.dataentity.resource.ResManager;
+import kd.bos.form.FormShowParameter;
+import kd.bos.form.control.Toolbar;
+import kd.bos.form.events.BeforeClosedEvent;
+import kd.bos.form.events.PreOpenFormEventArgs;
+import kd.cd.common.plugin.AbstractFormPluginExt;
+
+import java.time.DayOfWeek;
+import java.time.LocalDate;
+import java.util.EventObject;
+import java.util.HashMap;
+import java.util.Map;
+
+public class ViewControlOpsSample extends AbstractFormPluginExt {
+    private static final String FIELD_TOTAL_AMOUNT = "totalamount";
+    private static final String FIELD_AUDITOR = "auditor";
+    private static final String ENTRY_KEY = "entryentity";
+    private static final String ENTRY_DESC = "dealdesc";
+    private static final String MAIN_TOOLBAR = "tbmain";
+    private static final String PAGE_CACHE_SKIP_DIRTY_CHECK = "skip_dirty_check";
+    private static final String RES_APP_ID = "kd-cd-common-snippets";
+
+    @Override
+    public void preOpenForm(PreOpenFormEventArgs e) {
+        super.preOpenForm(e);
+        if (LocalDate.now().getDayOfWeek() == DayOfWeek.SUNDAY) {
+            e.setCancel(true);
+            e.setCancelMessage(ResManager.loadKDString("对不起，周日不能制单。", "ViewControlOpsSample_0", RES_APP_ID));
+        }
+    }
+
+    @Override
+    public void afterBindData(EventObject e) {
+        super.afterBindData(e);
+        FormShowParameter showParameter = getView().getFormShowParameter();
+        OperationStatus status = showParameter.getStatus();
+        if (OperationStatus.ADDNEW.equals(status)) {
+            getView().showTipNotification(ResManager.loadKDString("当前是新增页面。", "ViewControlOpsSample_1", RES_APP_ID));
+        } else if (OperationStatus.EDIT.equals(status)) {
+            getView().showTipNotification(ResManager.loadKDString("当前是编辑页面。", "ViewControlOpsSample_2", RES_APP_ID));
+        }
+
+        lockAlwaysReadonlyFields();
+        toggleAuditFieldVisibility();
+        focusFirstEntryRow();
+    }
+
+    public void lockAlwaysReadonlyFields() {
+        getView().setEnable(false, FIELD_TOTAL_AMOUNT);
+
+        int rowCount = getModel().getEntryRowCount(ENTRY_KEY);
+        for (int row = 0; row < rowCount; row++) {
+            getView().setEnable(false, row, ENTRY_DESC);
+        }
+    }
+
+    public void toggleAuditFieldVisibility() {
+        String billStatus = String.valueOf(getModel().getValue("billstatus"));
+        getView().setVisible("C".equalsIgnoreCase(billStatus), FIELD_AUDITOR);
+    }
+
+    public void focusFirstEntryRow() {
+        if (getModel().getEntryRowCount(ENTRY_KEY) > 0) {
+            getModel().setEntryCurrentRowIndex(ENTRY_KEY, 0);
+        }
+    }
+
+    public void replaySaveToolbar() {
+        Toolbar toolbar = getControl(MAIN_TOOLBAR);
+        if (toolbar != null) {
+            toolbar.itemClick("bar_save", "save");
+        }
+    }
+
+    public void refreshLocally(int rowIndex) {
+        getView().updateView(FIELD_TOTAL_AMOUNT);
+        if (rowIndex >= 0) {
+            getView().updateView(ENTRY_DESC, rowIndex);
+        }
+        getView().updateView(ENTRY_KEY);
+    }
+
+    public void refreshFromDatabase() {
+        getView().invokeOperation("refresh");
+    }
+
+    public void renameControlCaption(String controlKey, String caption) {
+        Map<String, Object> text = new HashMap<>(1);
+        text.put("zh_CN", caption);
+
+        Map<String, Object> payload = new HashMap<>(1);
+        payload.put("text", text);
+        getView().updateControlMetadata(controlKey, payload);
+    }
+
+    public void rememberInPageCache(String key, String value) {
+        getPageCache().put(key, value);
+    }
+
+    public String readFromPageCache(String key) {
+        return getPageCache().get(key);
+    }
+
+    @Override
+    public void beforeClosed(BeforeClosedEvent e) {
+        super.beforeClosed(e);
+        if ("true".equalsIgnoreCase(getPageCache().get(PAGE_CACHE_SKIP_DIRTY_CHECK))) {
+            e.setCheckDataChange(false);
+        }
+    }
+
+    public void closeCurrentPage() {
+        getView().close();
+    }
+}

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

@@ -0,0 +1,170 @@
+/**
+ * 列表插件基础交互示例。
+ * <p>
+ * 适用插件：列表插件
+ * 优先封装：ShowParameterUtils、FilterUtils
+ * 原生兜底：SetFilterEvent、PackageDataEvent、HyperLinkClickArgs
+ * 相关 lint 规则：STYLE-002、STYLE-013
+ * <p>
+ * 使用场景：
+ * 1. 列表界面加载时动态追加过滤条件；
+ * 2. 操作列按钮按行状态动态显隐；
+ * 3. 列数据格式化显示；
+ * 4. 列表操作后打开关联页面。
+ */
+package kd.cd.common.snippets.list;
+
+import kd.bos.bill.BillShowParameter;
+import kd.bos.bill.OperationStatus;
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.dataentity.resource.ResManager;
+import kd.bos.entity.datamodel.ListSelectedRow;
+import kd.bos.entity.datamodel.ListSelectedRowCollection;
+import kd.bos.entity.datamodel.events.PackageDataEvent;
+import kd.bos.entity.list.column.ColumnDesc;
+import kd.bos.form.IPageCache;
+import kd.bos.form.ShowType;
+import kd.bos.form.events.AfterDoOperationEventArgs;
+import kd.bos.form.events.HyperLinkClickArgs;
+import kd.bos.form.events.SetFilterEvent;
+import kd.bos.form.operatecol.OperationColItem;
+import kd.bos.list.BillList;
+import kd.bos.list.ListShowParameter;
+import kd.bos.list.column.ListOperationColumnDesc;
+import kd.bos.orm.query.QCP;
+import kd.bos.orm.query.QFilter;
+import kd.cd.common.form.ShowParameterUtils;
+import kd.cd.common.plugin.AbstractListPluginExt;
+import kd.cd.common.util.DynamicObjectUtils;
+import kd.cd.common.util.FilterUtils;
+import kd.cd.core.util.CollectionUtils;
+
+import java.util.List;
+import java.util.Objects;
+
+public class ListPluginBasicSample extends AbstractListPluginExt {
+    private static final String LOG_FORM_ID = "outapilog";
+    private static final String SHOW_LOG_OP = "showlog";
+    private static final String STATUS = "status";
+    private static final String ENABLE = "enable";
+    private static final String FUZZY_CACHE_KEY = "fuzzyfilterkey";
+
+    // --- setFilter: 列表加载时追加过滤条件 ---
+    @Override
+    public void setFilter(SetFilterEvent e) {
+        super.setFilter(e);
+        IPageCache cache = getView().getPageCache();
+        String fuzzyFilterStr = cache.get(FUZZY_CACHE_KEY);
+        if (fuzzyFilterStr != null) {
+            e.setCustomQFilters(FilterUtils.deSerializeQFilter(fuzzyFilterStr));
+        }
+
+        // 特殊权限过滤：非管理员只能看未标记的数据
+        QFilter permFilter = new QFilter("require_super_auth", QCP.equals, false);
+        QFilter specialDataPermFilter = e.getSpecialDataPermQFilter();
+        if (specialDataPermFilter != null) {
+            specialDataPermFilter.and(permFilter);
+        } else {
+            e.setSpecialDataPermQFilter(permFilter);
+        }
+    }
+
+    // --- packageData: 操作列按钮按行状态动态显隐、列数据格式化 ---
+    @SuppressWarnings("unchecked")
+    @Override
+    public void packageData(PackageDataEvent e) {
+        Object source = e.getSource();
+
+        // 操作列按钮显隐控制
+        if (source instanceof ListOperationColumnDesc) {
+            DynamicObject rowData = e.getRowData();
+            boolean isAudited = "C".equals(DynamicObjectUtils.nullSafeGet(rowData, STATUS));
+            boolean isEnabled = "1".equals(DynamicObjectUtils.nullSafeGet(rowData, ENABLE));
+
+            List<OperationColItem> items = (List<OperationColItem>) e.getFormatValue();
+            for (OperationColItem item : items) {
+                if (SHOW_LOG_OP.equals(item.getOperationKey())) {
+                    item.setVisible(isAudited && isEnabled);
+                }
+            }
+            return;
+        }
+
+        // 列数据格式化
+        if (source instanceof ColumnDesc) {
+            String fieldKey = ((ColumnDesc) source).getFieldKey();
+            if ("port".equals(fieldKey)) {
+                Integer port = (Integer) e.getRowData().get("port");
+                e.setFormatValue(port == null || port == 0 ? "-" : String.valueOf(port));
+            } else if ("connectstate".equals(fieldKey)) {
+                DynamicObject rowData = e.getRowData();
+                if (!"C".equals(DynamicObjectUtils.nullSafeGet(rowData, STATUS))) {
+                    e.setFormatValue("");
+                }
+            }
+        }
+    }
+
+    // --- afterDoOperation: 操作完成后打开关联页面 ---
+    @Override
+    public void afterDoOperation(AfterDoOperationEventArgs args) {
+        super.afterDoOperation(args);
+        String opKey = getOpKey(args);
+        if (!SHOW_LOG_OP.equals(opKey)) {
+            return;
+        }
+
+        BillList billList = getBillList();
+        ListSelectedRow rowInfo = billList.getCurrentSelectedRowInfo();
+        if (rowInfo == null) {
+            return;
+        }
+
+        String number = rowInfo.getNumber();
+        String name = rowInfo.getName();
+
+        ListShowParameter lsp = ShowParameterUtils.getList(LOG_FORM_ID, ShowType.MainNewTabPage, true);
+        lsp.getListFilterParameter().getQFilters().add(new QFilter("opname", QCP.equals, number));
+        if (name != null) {
+            lsp.setCaption(String.format(
+                    ResManager.loadKDString("%s-日志", "ListPluginBasicSample_0", "kd-cd-common-snippets"),
+                    name
+            ));
+        }
+        billList.clearSelection();
+        getView().showForm(lsp);
+    }
+
+    // --- billListHyperLinkClick: 拦截默认打开逻辑，改成自定义弹窗 ---
+    @Override
+    public void billListHyperLinkClick(HyperLinkClickArgs args) {
+        if (!Objects.equals("billno", args.getHyperLinkClickEvent().getFieldName())) {
+            return;
+        }
+        args.setCancel(true);
+
+        ListSelectedRowCollection rows = getCurrentListAllRowCollection();
+        int rowIndex = args.getRowIndex();
+        if (rows == null || rowIndex < 0 || rowIndex >= rows.size()) {
+            return;
+        }
+
+        ListSelectedRow rowInfo = rows.get(rowIndex);
+        BillShowParameter showParameter = ShowParameterUtils.getBill(
+                rowInfo.getFormID(),
+                rowInfo.getPrimaryKeyValue(),
+                OperationStatus.EDIT,
+                ShowType.Modal
+        );
+        getView().showForm(showParameter);
+    }
+
+    public ListSelectedRowCollection currentSelections() {
+        ListSelectedRowCollection selectedRows = getSelectedRows();
+        if (CollectionUtils.isNotEmpty(selectedRows)) {
+            return selectedRows;
+        }
+        BillList billList = getBillList();
+        return billList == null ? selectedRows : billList.getSelectedRows();
+    }
+}

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

@@ -0,0 +1,68 @@
+/**
+ * 列表 preOpenForm 按父页面字段动态过滤示例。
+ * <p>
+ * 适用插件：列表插件
+ * 优先封装：FormUtils、AbstractListPluginExt
+ * 原生兜底：PreOpenFormEventArgs、ListShowParameter、QFilter
+ * 相关 lint 规则：当前无专门规则，可参考 SCENE-003、STYLE-015
+ * <p>
+ * 使用场景：从父单据打开 F7/列表时，
+ * 根据父页面表头或当前分录字段给列表追加过滤条件。
+ */
+package kd.cd.common.snippets.list;
+
+import kd.bos.entity.datamodel.IDataModel;
+import kd.bos.form.IFormView;
+import kd.bos.form.events.PreOpenFormEventArgs;
+import kd.bos.list.ListShowParameter;
+import kd.bos.orm.query.QCP;
+import kd.bos.orm.query.QFilter;
+import kd.cd.common.form.FormUtils;
+import kd.cd.common.plugin.AbstractListPluginExt;
+import kd.cd.core.util.CharSequenceUtils;
+
+import java.util.List;
+
+public class ListPreOpenFilterSample extends AbstractListPluginExt {
+    private static final String PARENT_FORM_ID = "cas_claimbill";
+    private static final String PARENT_ENTRY_KEY = "entryentity";
+    private static final String FIELD_CORE_BILL_TYPE = "e_corebilltype";
+    private static final String FIELD_PAYMENT_TYPE = "paymenttype";
+    private static final String FIELD_PAYER_NO = "recbasepayer.number";
+
+    // --- 从父页面打开列表前，动态追加过滤 ---
+    @Override
+    public void preOpenForm(PreOpenFormEventArgs e) {
+        super.preOpenForm(e);
+        ListShowParameter showParameter = (ListShowParameter) e.getFormShowParameter();
+        if (!PARENT_FORM_ID.equals(showParameter.getParentFormId())) {
+            return;
+        }
+        // 获取noPlugin的parentView，防止跨节点报错
+        IFormView parentView = FormUtils.getViewByPageId(showParameter.getParentPageId(), true);
+        if (parentView == null) {
+            return;
+        }
+
+        IDataModel parentModel = parentView.getModel();
+        int rowIndex = parentModel.getEntryCurrentRowIndex(PARENT_ENTRY_KEY);
+        if (rowIndex < 0) {
+            return;
+        }
+
+        String coreBillType = (String) parentModel.getValue(FIELD_CORE_BILL_TYPE, rowIndex);
+        String paymentType = String.valueOf(parentModel.getValue(FIELD_PAYMENT_TYPE));
+        if (!"ar_finarbill".equals(coreBillType) || !"bd_customer".equals(paymentType)) {
+            return;
+        }
+
+        String payerNumber = parentModel.getDataEntity().getString(FIELD_PAYER_NO);
+        if (CharSequenceUtils.isBlank(payerNumber)) {
+            return;
+        }
+
+        List<QFilter> qFilters = showParameter.getListFilterParameter().getQFilters();
+        qFilters.add(new QFilter("asstact.number", QCP.equals, payerNumber));
+        qFilters.add(new QFilter("billstatus", QCP.equals, "C"));
+    }
+}

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

@@ -0,0 +1,95 @@
+/**
+ * 消息通知示例。
+ * <p>
+ * 适用插件：操作插件、服务层、后台任务
+ * 优先封装：当前仓库无专门消息封装，保持最小原生写法
+ * 原生兜底：MessageCenterServiceHelper、MessageInfo
+ * 相关 lint 规则：当前无专门规则，可参考 STYLE-013、STYLE-015
+ * <p>
+ * 使用场景：
+ * 1. 系统内消息通知；
+ * 2. 短信通知；
+ * 3. 云之家机器人通知；
+ * 4. 邮件通知。
+ */
+package kd.cd.common.snippets.message;
+
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.dataentity.entity.LocaleString;
+import kd.bos.dataentity.resource.ResManager;
+import kd.bos.logging.Log;
+import kd.bos.logging.LogFactory;
+import kd.bos.servicehelper.workflow.MessageCenterServiceHelper;
+import kd.bos.workflow.engine.msg.info.MessageInfo;
+import kd.cd.core.util.CharSequenceUtils;
+import kd.cd.core.util.CollectionUtils;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+import java.util.stream.Collectors;
+
+public class MessageNotifySample {
+    private static final Log log = LogFactory.getLog(MessageNotifySample.class);
+
+    // --- 系统内消息通知 ---
+    public static boolean sendSystemMessage(List<Long> userIds, String title, String content) {
+        if (CollectionUtils.isEmpty(userIds)) {
+            return false;
+        }
+
+        try {
+            MessageInfo messageInfo = new MessageInfo();
+            LocaleString titleLocale = new LocaleString();
+            titleLocale.setLocaleValue_zh_CN(title);
+            messageInfo.setMessageTitle(titleLocale);
+
+            LocaleString contentLocale = new LocaleString();
+            contentLocale.setLocaleValue_zh_CN(content);
+            messageInfo.setMessageContent(contentLocale);
+
+            messageInfo.setUserIds(userIds);
+            messageInfo.setType(MessageInfo.TYPE_ALARM);
+            messageInfo.setNotifyType("mcenter,yunzhijia");
+
+            MessageCenterServiceHelper.batchSendMessages(Collections.singletonList(messageInfo));
+            return true;
+        } catch (Exception e) {
+            log.warn("系统内消息发送失败", e);
+            return false;
+        }
+    }
+
+    // --- 构建预警消息内容 ---
+    public static String buildAlarmMessage(String apiNum, String apiName, int successCount, int failCount, String failRate) {
+        return String.format(
+                ResManager.loadKDString(
+                        "接口异常预警%n接口编号：%s%n接口名称：%s%n成功次数：%d%n失败次数：%d%n失败率：%s%%",
+                        "MessageNotifySample_0",
+                        "kd-cd-common-snippets"
+                ),
+                apiNum, apiName, successCount, failCount, failRate
+        );
+    }
+
+    // --- 从分录获取通知用户ID列表 ---
+    public static List<Long> getUserIdsFromEntry(DynamicObject bill, String entryKey, String userFieldKey) {
+        return bill.getDynamicObjectCollection(entryKey).stream()
+                .map(row -> (DynamicObject) row.get(userFieldKey))
+                .filter(Objects::nonNull)
+                .map(obj -> obj.getLong("id"))
+                .distinct()
+                .collect(Collectors.toList());
+    }
+
+    // --- 从分录获取手机号列表 ---
+    public static List<String> getPhonesFromEntry(DynamicObject bill, String entryKey, String userFieldKey) {
+        return bill.getDynamicObjectCollection(entryKey).stream()
+                .map(row -> (DynamicObject) row.get(userFieldKey))
+                .filter(Objects::nonNull)
+                .map(obj -> obj.getString("phone"))
+                .filter(CharSequenceUtils::isNotBlank)
+                .distinct()
+                .collect(Collectors.toList());
+    }
+}

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

@@ -0,0 +1,198 @@
+package kd.cd.common.snippets;
+
+import kd.bos.dataentity.OperateOption;
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.dlock.DLock;
+import kd.bos.entity.operate.result.OperationResult;
+import kd.bos.logging.Log;
+import kd.bos.logging.LogFactory;
+import kd.bos.mq.MessageAcker;
+import kd.bos.mq.MessageConsumer;
+import kd.bos.servicehelper.BusinessDataServiceHelper;
+import kd.bos.servicehelper.operation.OperationServiceHelper;
+import kd.bos.servicehelper.operation.SaveServiceHelper;
+import kd.cd.common.operate.OpUtils;
+
+/**
+ * MQ 消息消费者示例 —— 苍穹消息队列消费端全场景。
+ * <p>
+ * 适用插件：MQ 消费者（实现 MessageConsumer 接口）
+ * 优先封装：（暂无 commons 封装）
+ * 原生兜底：MessageConsumer、MessageAcker、DLock、OperationServiceHelper
+ * 相关 lint 规则：（暂无）
+ * <p>
+ * 使用场景：
+ * 1. 简单消费模式：收到消息 → 执行操作 → ack/discard；
+ * 2. 分布式锁防重复消费：DLock + tryLock 保证同一消息不会并发处理；
+ * 3. MessageAcker 三种应答：ack（确认）、deny（拒绝回队列）、discard（废弃不重试）。
+ * <p>
+ * <b>配套配置：需在 resources 下创建 MQ XML 配置文件，并在启动类中声明。</b>
+ * XML 结构示例见本文件末尾注释。
+ */
+public class SampleMQConsumer implements MessageConsumer {
+    private static final Log log = LogFactory.getLog(SampleMQConsumer.class);
+
+    // ===================================================================
+    //  一、标准消费模式（执行操作 + 结果应答）
+    // ===================================================================
+
+    /**
+     * MQ 消费入口。
+     *
+     * @param message   消息体（类型取决于发送方，常见 String / String[] / JSON）
+     * @param messageId 消息唯一标识
+     * @param resend    是否为重发消息
+     * @param acker     消息应答器
+     */
+    @Override
+    public void onMessage(Object message, String messageId, boolean resend, MessageAcker acker) {
+        log.info("MQ 消费开始：messageId={}, message={}", messageId, message);
+        if (message == null) {
+            return;
+        }
+
+        // ---------- 场景 A：消息体为 String[]（常见于操作类消息） ----------
+        // 发送方约定：message[0] = 单据标识, message[1] = 主键
+        // consumeOperationMessage((String[]) message, messageId, acker);
+
+        // ---------- 场景 B：消息体为单据 PK + 分布式锁防重 ----------
+        consumeWithDLock(message, messageId, acker);
+    }
+
+    // ===================================================================
+    //  场景 A：操作类消息（如异步入账、复核、反复核）
+    // ===================================================================
+
+    /**
+     * 收到消息后调用平台操作。
+     * 典型用途：异步入账、异步审批、凭证复核等。
+     */
+    private void consumeOperationMessage(String[] message, String messageId, MessageAcker acker) {
+        String entityId = message[0];    // 单据标识
+        String pkValue = message[1];     // 单据主键
+        log.info("操作类消息：entityId={}, pk={}", entityId, pkValue);
+
+        try {
+            // 调用平台操作（如 "audit"、"submit"、"kdcd_dorule" 等）
+            OperationResult result = OperationServiceHelper.executeOperate(
+                    "audit", entityId, new Long[]{Long.valueOf(pkValue)}, OperateOption.create());
+
+            if (result.isSuccess()) {
+                log.info("操作执行成功，确认消息");
+                acker.ack(messageId);         // 确认：消费完成
+            } else {
+                String errMsg = OpUtils.getCompleteFailMsg(result);
+                log.info("操作执行失败：{}", errMsg);
+                // 更新单据的错误信息字段
+                DynamicObject entity = BusinessDataServiceHelper.loadSingle(pkValue, "kdcd_errmsg", entityId);
+                entity.set("kdcd_errmsg", errMsg);
+                SaveServiceHelper.update(entity);
+                acker.discard(messageId);     // 废弃：不再重试
+            }
+
+        } catch (Exception e) {
+            log.error("消费异常：{}", e.getMessage(), e);
+            acker.discard(messageId);         // 异常也废弃，避免无限重试
+        }
+    }
+
+    // ===================================================================
+    //  场景 B：分布式锁防重复消费（适用于外部接口调用等幂等场景）
+    // ===================================================================
+
+    /**
+     * 使用 DLock 分布式锁防止同一消息被多个消费者实例并发处理。
+     * 典型用途：调用外部接口、同步第三方数据。
+     */
+    private void consumeWithDLock(Object message, String messageId, MessageAcker acker) {
+        // 以消息内容（通常是单据 PK）作为锁的 key
+        try (DLock dLock = DLock.create(messageId)) {
+            if (dLock.tryLock()) {
+                // ---------- 加锁成功，处理消息 ----------
+                processMessageBody(message, messageId, acker);
+            } else {
+                // ---------- 加锁失败，返回队列等待重新消费 ----------
+                log.info("获取分布式锁失败，消息回队列：{}", messageId);
+                acker.deny(messageId);
+            }
+        }
+    }
+
+    /**
+     * 消息处理核心逻辑。
+     */
+    private void processMessageBody(Object message, String messageId, MessageAcker acker) {
+        String formId = "kdcd_api_message_pool";
+        DynamicObject bill = BusinessDataServiceHelper.loadSingle(message, "kdcd_status", formId);
+
+        // 幂等判断：已处理成功的跳过
+        String status = bill.getString("kdcd_status");
+        if ("1".equals(status)) {
+            log.info("消息已成功处理过，跳过：{}", messageId);
+            acker.discard(messageId);
+            return;
+        }
+
+        try {
+            // ====== 执行业务逻辑（如调用外部 API） ======
+            boolean success = callExternalApi(bill);
+
+            if (success) {
+                bill.set("kdcd_status", "1");       // 成功
+                SaveServiceHelper.update(bill);
+                acker.ack(messageId);               // 确认消费完成
+            } else {
+                bill.set("kdcd_status", "-1");      // 失败
+                SaveServiceHelper.update(bill);
+                acker.deny(messageId);              // 拒绝：返回队列稍后重试
+            }
+
+        } catch (Exception e) {
+            log.error("消息处理异常：{}", messageId, e);
+            bill.set("kdcd_status", "-1");
+            SaveServiceHelper.update(bill);
+            acker.discard(messageId);               // 异常废弃
+        }
+    }
+
+    private boolean callExternalApi(DynamicObject bill) {
+        // 模拟外部接口调用
+        return true;
+    }
+
+    // ===================================================================
+    //  MessageAcker 应答方式速查
+    // ===================================================================
+    //
+    //  acker.ack(messageId)     → 确认：消息已成功处理，从队列移除
+    //  acker.deny(messageId)    → 拒绝：消息返回队列，稍后重新投递消费
+    //  acker.discard(messageId) → 废弃：消息从队列移除，不再重试
+    //
+    //  选择原则：
+    //  - 处理成功 → ack
+    //  - 临时故障（如外部接口超时）→ deny（会重试）
+    //  - 业务逻辑失败或异常（不可能通过重试修复）→ discard
+
+    // ===================================================================
+    //  MQ XML 配置示例（放在 resources 根目录下）
+    // ===================================================================
+    //
+    //  文件名如：kdcd_sample_mq.xml
+    //
+    //  <root>
+    //      <!--所属云：如 fi=财务云、tmc=资金云、sys=系统-->
+    //      <region name="fi">
+    //          <!--name：队列名称（全局唯一） appid：所属应用-->
+    //          <queue name="kdcd_sample_queue" appid="gl">
+    //              <!--class：消费者实现类全路径 concurrency：消费者线程数-->
+    //              <consumer class="kd.cd.xxx.SampleMQConsumer" concurrency="5"/>
+    //          </queue>
+    //      </region>
+    //  </root>
+    //
+    //  启动类配置：
+    //  System.setProperty("mqConfigFiles.config", "kdcd_sample_mq.xml");
+    //
+    //  发送消息：
+    //  MQFactory.get().send("kdcd_sample_queue", messageObj);
+}

package/vendor/kingdee-skills/ok-cosmic/assets/snippets/mq/sample_mq.xml

@@ -0,0 +1,15 @@
+<root>
+    <!--所属云：fi=财务云、tmc=资金云、sys=系统、scm=供应链云 等-->
+    <region name="fi">
+        <!--name：队列名称（全局唯一） appid：所属应用（如 gl=总账、bei=银企互联）-->
+        <queue name="kdcd_sample_queue" appid="gl">
+            <!--class：消费者实现类全路径 concurrency：消费者线程数（一般 3~10）-->
+            <consumer class="kd.cd.xxx.biz.mq.SampleMQConsumer" concurrency="5"/>
+        </queue>
+
+        <!--同一 region 下可配置多个队列-->
+        <queue name="kdcd_another_queue" appid="gl">
+            <consumer class="kd.cd.xxx.biz.mq.AnotherMQConsumer" concurrency="3"/>
+        </queue>
+    </region>
+</root>