kcode-pi 0.1.0

package/vendor/kingdee-skills/ok-cosmic/assets/WriteBackPlugInTemplate.java

@@ -0,0 +1,286 @@
+package kd.cd.common;
+
+import kd.bos.entity.BillEntityType;
+import kd.bos.entity.LinkSetItemElement;
+import kd.bos.entity.botp.plugin.AbstractWriteBackPlugIn;
+import kd.bos.entity.botp.plugin.args.AfterBuildSourceBillIdsEventArgs;
+import kd.bos.entity.botp.plugin.args.AfterCalcWriteValueEventArgs;
+import kd.bos.entity.botp.plugin.args.AfterCloseRowEventArgs;
+import kd.bos.entity.botp.plugin.args.AfterCommitAmountEventArgs;
+import kd.bos.entity.botp.plugin.args.AfterExcessCheckEventArgs;
+import kd.bos.entity.botp.plugin.args.AfterReadSourceBillEventArgs;
+import kd.bos.entity.botp.plugin.args.AfterSaveSourceBillEventArgs;
+import kd.bos.entity.botp.plugin.args.BeforeCloseRowEventArgs;
+import kd.bos.entity.botp.plugin.args.BeforeCreateArticulationRowEventArgs;
+import kd.bos.entity.botp.plugin.args.BeforeExcessCheckEventArgs;
+import kd.bos.entity.botp.plugin.args.BeforeExecWriteBackRuleEventArgs;
+import kd.bos.entity.botp.plugin.args.BeforeReadSourceBillEventArgs;
+import kd.bos.entity.botp.plugin.args.BeforeSaveSourceBillEventArgs;
+import kd.bos.entity.botp.plugin.args.BeforeSaveTransEventArgs;
+import kd.bos.entity.botp.plugin.args.BeforeTrackEventArgs;
+import kd.bos.entity.botp.plugin.args.FinishWriteBackEventArgs;
+import kd.bos.entity.botp.plugin.args.PreparePropertysEventArgs;
+import kd.bos.entity.botp.plugin.args.RollbackSaveEventArgs;
+
+/**
+ * 单据反写插件骨架模板（原生 AbstractWriteBackPlugIn）。
+ * 该类仅用于示例写法，生成后请按实际业务删除无用事件并替换占位常量。
+ */
+public class WriteBackPlugInTemplate extends AbstractWriteBackPlugIn {
+
+    /**
+     * 触发时机: 在需要了解当前插件可访问上下文能力时调用。
+     * 参数要点: 无入参；仅展示当前插件可通过 this. 访问的方法能力。
+     * 典型用途: 作为模板提示，指导在各事件内选择正确的上下文 API。
+     */
+    private void getContextSample() {
+        // this.getCurrLinkSetItem();
+        // this.getTargetSubMainType();
+        // this.getOpType();
+        // this.setContext(null, null, null);
+    }
+
+    // 占位常量：复制模板后请统一替换为业务真实 key。
+    private static final String FIELD_TGT_AMOUNT = "writeback_amount";
+    private static final String FIELD_SRC_TOTAL = "totalamount";
+
+    // ===== 反写预处理阶段 =====
+
+    /**
+     * 触发时机: 反写执行前，框架准备目标单字段阶段。
+     * 参数要点: e.getFieldKeys() 为后续反写读取字段集合。
+     *
+     */
+
+    @Override
+    public void preparePropertys(PreparePropertysEventArgs e) {
+        super.preparePropertys(e);
+        e.getFieldKeys().add(FIELD_TGT_AMOUNT);
+    }
+
+    /**
+     * 触发时机: 系统构建来源单据 ID 集合后。
+     * 参数要点: e 可读取来源单范围，用于诊断或二次过滤。
+     */
+    @Override
+    public void afterBuildSourceBillIds(AfterBuildSourceBillIdsEventArgs e) {
+        super.afterBuildSourceBillIds(e);
+        this.getCurrLinkSetItem();
+    }
+
+    /**
+     * 触发时机: 读取来源单前。
+     * 参数要点: e.getFieldKeys() 控制来源单需加载字段。
+     *
+     */
+
+    @Override
+    public void beforeReadSourceBill(BeforeReadSourceBillEventArgs e) {
+        super.beforeReadSourceBill(e);
+        e.getFieldKeys().add(FIELD_SRC_TOTAL);
+    }
+
+    /**
+     * 触发时机: 来源单读取完成后。
+     * 参数要点: 可访问来源单数据并做缓存，供后续规则使用。
+     */
+    @Override
+    public void afterReadSourceBill(AfterReadSourceBillEventArgs e) {
+        super.afterReadSourceBill(e);
+        this.getTargetSubMainType();
+    }
+
+    // ===== 超额与规则执行阶段 =====
+
+    /**
+     * 触发时机: 超额校验前。
+     * 参数要点: 可按业务改写超额校验上下文。
+     */
+
+    @Override
+    public void beforeExcessCheck(BeforeExcessCheckEventArgs e) {
+        super.beforeExcessCheck(e);
+        this.getCurrLinkSetItem();
+    }
+
+    /**
+     * 触发时机: 超额校验后。
+     * 参数要点: 可读取超额结果并决定后续行为。
+     */
+    @Override
+    public void afterExcessCheck(AfterExcessCheckEventArgs e) {
+        super.afterExcessCheck(e);
+        this.getTargetSubMainType();
+    }
+
+    /**
+     * 触发时机: 执行反写规则前。
+     * 参数要点: 可做最终拦截和环境准备。
+     */
+
+    @Override
+    public void beforeExecWriteBackRule(BeforeExecWriteBackRuleEventArgs e) {
+        super.beforeExecWriteBackRule(e);
+        this.getOpType();
+    }
+
+    /**
+     * 触发时机: 反写值计算完成后。
+     * 参数要点: 可读取计算结果并做二次修正。
+     */
+    @Override
+    public void afterCalcWriteValue(AfterCalcWriteValueEventArgs e) {
+        super.afterCalcWriteValue(e);
+        this.getOpType();
+    }
+
+    // ===== 关联行与关行处理 =====
+
+    /**
+     * 触发时机: 创建关联行前。
+     * 参数要点: 可按条件跳过关联行生成。
+     */
+
+    @Override
+    public void beforeCreateArticulationRow(BeforeCreateArticulationRowEventArgs e) {
+        super.beforeCreateArticulationRow(e);
+        this.getCurrLinkSetItem();
+    }
+
+    /**
+     * 触发时机: 关行前。
+     * 参数要点: 可校验关行条件并拦截。
+     */
+    @Override
+    public void beforeCloseRow(BeforeCloseRowEventArgs e) {
+        super.beforeCloseRow(e);
+        this.getCurrLinkSetItem();
+    }
+
+    /**
+     * 触发时机: 关行后。
+     * 参数要点: 可记录关行结果并同步状态。
+     */
+
+    @Override
+    public void afterCloseRow(AfterCloseRowEventArgs e) {
+        super.afterCloseRow(e);
+        this.getTargetSubMainType();
+    }
+
+    // ===== 提交与保存阶段 =====
+
+    /**
+     * 触发时机: 反查来源/去向链路前。
+     * 参数要点: 可覆盖链路追踪策略。
+     */
+    @Override
+    public void beforeTrack(BeforeTrackEventArgs e) {
+        super.beforeTrack(e);
+        this.getCurrLinkSetItem();
+    }
+
+    /**
+     * 触发时机: 反写数量/金额提交后。
+     * 参数要点: 可读取提交汇总结果。
+     */
+
+    @Override
+    public void afterCommitAmount(AfterCommitAmountEventArgs e) {
+        super.afterCommitAmount(e);
+        this.getOpType();
+    }
+
+    /**
+     * 触发时机: 保存事务提交前。
+     * 参数要点: 适合同事务内最后修正。
+     */
+    @Override
+    public void beforeSaveTrans(BeforeSaveTransEventArgs e) {
+        super.beforeSaveTrans(e);
+        this.getTargetSubMainType();
+    }
+
+    /**
+     * 触发时机: 保存来源单前。
+     * 参数要点: 可校验来源单最终写入数据。
+     */
+
+    @Override
+    public void beforeSaveSourceBill(BeforeSaveSourceBillEventArgs e) {
+        super.beforeSaveSourceBill(e);
+        this.getTargetSubMainType();
+    }
+
+    /**
+     * 触发时机: 保存来源单后。
+     * 参数要点: 可进行后置日志、状态同步。
+     */
+    @Override
+    public void afterSaveSourceBill(AfterSaveSourceBillEventArgs e) {
+        super.afterSaveSourceBill(e);
+        this.getTargetSubMainType();
+    }
+
+    /**
+     * 触发时机: 保存失败并回滚时。
+     * 参数要点: e 包含回滚上下文，可做补偿记录。
+     */
+
+    @Override
+    public void rollbackSave(RollbackSaveEventArgs e) {
+        super.rollbackSave(e);
+        this.getOpType();
+    }
+
+    /**
+     * 触发时机: 反写流程结束（成功或失败后收尾阶段）。
+     * 参数要点: 可统一释放资源、输出日志。
+     */
+    @Override
+    public void finishWriteBack(FinishWriteBackEventArgs e) {
+        super.finishWriteBack(e);
+        this.getCurrLinkSetItem();
+    }
+
+    // ===== 上下文与元信息 =====
+
+    /**
+     * 获取当前关联关系项。
+     * 注意: 模板示例返回 null，实际使用时需根据业务逻辑实现。
+     */
+    @Override
+    public LinkSetItemElement getCurrLinkSetItem() {
+        super.getCurrLinkSetItem();
+        return null;
+    }
+
+    /**
+     * 获取目标单据类型。
+     * 注意: 模板示例返回 null，实际使用时需根据业务逻辑实现。
+     */
+    @Override
+    public BillEntityType getTargetSubMainType() {
+        super.getTargetSubMainType();
+        return null;
+    }
+
+    /**
+     * 获取操作类型。
+     * 注意: 模板示例返回 null，实际使用时需根据业务逻辑实现。
+     */
+    @Override
+    public String getOpType() {
+        super.getOpType();
+        return null;
+    }
+
+    /**
+     * 设置上下文信息。
+     * 注意: 模板示例为空实现，实际使用时需根据业务逻辑实现。
+     */
+    @Override
+    public void setContext(BillEntityType targetSubMainType, String opType, LinkSetItemElement linkSetItem) {
+        super.setContext(targetSubMainType, opType, linkSetItem);
+    }
+}

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

@@ -0,0 +1,93 @@
+/**
+ * 上传并绑定附件到附件面板示例。
+ * <p>
+ * 适用插件：表单插件、操作插件、服务层
+ * 优先封装：AttachmentUtils、AttPanelUploader
+ * 原生兜底：AttachmentServiceHelper、附件面板原生控件 API
+ * 相关 lint 规则：STYLE-007、RESOURCE-001、RESOURCE-004
+ * <p>
+ * 使用场景：
+ * 1. 已拿到第三方文件 URL、byte[] 或 InputStream，需要挂到当前单据附件面板；
+ * 2. 后台接口建单成功后，继续补传电子回单、影像件、证照等附件；
+ * 3. 希望走仓库推荐链路：AttPanelUploader 上传，再 bindTo(...) 绑定。
+ * 4. 需要控制同名覆盖或大小校验策略。
+ */
+package kd.cd.common.snippets.attachment;
+
+import kd.bos.dataentity.resource.ResManager;
+import kd.bos.exception.ErrorCode;
+import kd.bos.exception.KDBizException;
+import kd.bos.logging.Log;
+import kd.bos.logging.LogFactory;
+import kd.cd.common.attachment.AttachmentUtils;
+import kd.cd.common.attachment.upload.AttPanelUploader;
+import kd.cd.common.attachment.upload.PanelUploadResult;
+import kd.cd.core.tuple.State;
+
+import java.io.IOException;
+import java.io.InputStream;
+
+public class AttachmentUploadBindSample {
+    private static final Log log = LogFactory.getLog(AttachmentUploadBindSample.class);
+    private static final String TARGET_FORM_ID = "kdcd_basicapplication";
+    private static final String ATTACHMENT_PANEL_KEY = "attachmentpanel";
+    private static final String RES_APP_ID = "kd-cd-common-snippets";
+    private static final String ERR_CODE_ATTACHMENT = "AttachmentUploadBindSample_001";
+
+    // --- 已有文件 URL：先下载，再上传并绑定 ---
+    public static State uploadUrlToPanel(Object pkValue, String fileUrl, String fileName) {
+        try (InputStream in = AttachmentUtils.download(fileUrl)) {
+            if (in == null) {
+                return State.of(false, ResManager.loadKDString("附件下载失败或文件为空", "AttachmentUploadBindSample_0", RES_APP_ID));
+            }
+            return AttPanelUploader.of(TARGET_FORM_ID, pkValue)
+                    .upload(in, fileName)
+                    .bindTo(ATTACHMENT_PANEL_KEY);
+        } catch (IOException e) {
+            log.error(ResManager.loadKDString("附件下载异常", "AttachmentUploadBindSample_1", RES_APP_ID), e);
+            return State.of(false, String.format(
+                    ResManager.loadKDString("附件下载异常：%s", "AttachmentUploadBindSample_2", RES_APP_ID),
+                    e.getMessage()
+            ));
+        }
+    }
+
+    // --- 已有 byte[]：适合接口返回文件流、SFTP 下载结果、报表导出结果 ---
+    public static void uploadBytesToPanelOrThrow(Object pkValue, byte[] bytes, String fileName) {
+        if (bytes == null || bytes.length == 0) {
+            throw new KDBizException(new ErrorCode(
+                    ERR_CODE_ATTACHMENT,
+                    ResManager.loadKDString("上传附件不能为空", "AttachmentUploadBindSample_3", RES_APP_ID)
+            ));
+        }
+        State state = AttPanelUploader.of(TARGET_FORM_ID, pkValue)
+                .upload(bytes, fileName)
+                .bindTo(ATTACHMENT_PANEL_KEY);
+        if (!state.isTrue()) {
+            throw new KDBizException(new ErrorCode(
+                    ERR_CODE_ATTACHMENT,
+                    String.format(
+                            ResManager.loadKDString("附件上传绑定失败：%s", "AttachmentUploadBindSample_4", RES_APP_ID),
+                            state.text()
+                    )
+            ));
+        }
+    }
+
+    // --- 已有 InputStream：适合页面临时区文件、网关下载流、OSS/SFTP 输入流 ---
+    public static State uploadStreamToPanel(Object pkValue, InputStream inputStream, String fileName) {
+        return AttPanelUploader.of(TARGET_FORM_ID, pkValue)
+                .upload(inputStream, fileName)
+                .bindTo(ATTACHMENT_PANEL_KEY);
+    }
+
+    // --- 需要控制上传参数：覆盖同名文件、跳过大小校验 ---
+    public static State uploadWithOptions(Object pkValue, byte[] bytes, String fileName, boolean overrideExistFile, boolean skipUploadSizeCheck) {
+        AttPanelUploader uploader = AttPanelUploader.of(TARGET_FORM_ID, pkValue);
+        uploader.setOverrideExistFile(overrideExistFile);
+        uploader.setSkipUploadSizeCheck(skipUploadSizeCheck);
+
+        PanelUploadResult result = uploader.upload(bytes, fileName);
+        return result.bindTo(ATTACHMENT_PANEL_KEY);
+    }
+}

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

@@ -0,0 +1,168 @@
+/**
+ * BOTP 链路查询与下推示例。
+ * <p>
+ * 适用插件：操作插件、转换插件、服务层
+ * 优先封装：BotpUtils、OpUtils
+ * 原生兜底：PushArgs、DrawArgs、ConvertServiceHelper、OperationServiceHelper
+ * 相关 lint 规则：STYLE-003、STYLE-004、STYLE-005
+ * <p>
+ * 使用场景：
+ * 1. 查全部上下游：{@code findAllSourceBills / findAllTargetBills}
+ * 2. 只查某一种上下游单据：传 {@code 目标单类型 + 当前单类型 + 主键集}
+ * 3. 只看直接关系：{@code findDirectSourceBills / findDirectTargetBills}
+ * 4. 下推但不保存：{@code pushNoSave}
+ * 5. 下推后补字段再保存：{@code OpUtils.executeOperateOrThrow("save", ...)}
+ */
+package kd.cd.common.snippets.botp;
+
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.dataentity.entity.DynamicObjectCollection;
+import kd.bos.dataentity.resource.ResManager;
+import kd.bos.orm.query.QCP;
+import kd.bos.orm.query.QFilter;
+import kd.cd.common.operate.OpUtils;
+import kd.cd.common.util.BotpUtils;
+import kd.cd.common.util.DynamicObjectUtils;
+import kd.cd.common.util.PushResult;
+import kd.cd.core.util.CollectionUtils;
+import kd.bos.servicehelper.QueryServiceHelper;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+public class BotpTracePushSample {
+    private static final String MEASURE_SETTLE = "kdcd_measuresettlebill";
+    private static final String AP_PAYAPPLY = "ap_payapply";
+    private static final String CAS_PAYBILL = "cas_paybill";
+    private static final String CEXP_DEDUCTION = "kdcd_cexp_deduction";
+    private static final String RES_APP_ID = "kd-cd-common-snippets";
+
+    // ==================== 场景1：全链路下查 ====================
+
+    /**
+     * 以“源单主键 -> 目标单类型 -> 目标单主键集”结构返回全部下游。
+     * 适合做整条链路预览或按单据类型分组校验。
+     */
+    public static Map<Long, Map<String, Set<Long>>> findAllTargetBills(Collection<Long> measureIds) {
+        if (CollectionUtils.isEmpty(measureIds)) {
+            return Collections.emptyMap();
+        }
+        return BotpUtils.findAllTargetBills(MEASURE_SETTLE, measureIds);
+    }
+
+    /**
+     * 只关心一种目标单据类型时，直接使用扁平化 API。
+     */
+    public static Set<Long> findAllPayApplyIds(Collection<Long> measureIds) {
+        if (CollectionUtils.isEmpty(measureIds)) {
+            return Collections.emptySet();
+        }
+        return BotpUtils.findAllTargetBillsFlat(AP_PAYAPPLY, MEASURE_SETTLE, measureIds);
+    }
+
+    // ==================== 场景2：直接下查 ====================
+
+    /**
+     * 付款申请单只往下看一层付款处理单，不追完整链路。
+     */
+    public static Set<Long> findDirectPayBillIds(Collection<Long> payApplyIds) {
+        if (CollectionUtils.isEmpty(payApplyIds)) {
+            return Collections.emptySet();
+        }
+        return BotpUtils.findDirectTargetBills(CAS_PAYBILL, AP_PAYAPPLY, payApplyIds).values().stream()
+                .flatMap(Set::stream)
+                .collect(Collectors.toSet());
+    }
+
+    // ==================== 场景3：反查上游 ====================
+
+    /**
+     * 从扣款清单反查全部来源计量结算单。
+     */
+    public static Set<Long> findAllMeasureIdsByDeduction(Collection<Long> deductionIds) {
+        if (CollectionUtils.isEmpty(deductionIds)) {
+            return Collections.emptySet();
+        }
+        return BotpUtils.findAllSourceBillsFlat(MEASURE_SETTLE, CEXP_DEDUCTION, deductionIds);
+    }
+
+    /**
+     * 只看直接来源时，仍然建议保留“目标单主键 -> 源单主键集”的映射，后续更好回填。
+     */
+    public static Map<Long, Set<Long>> findDirectMeasureIdsByDeduction(Collection<Long> deductionIds) {
+        if (CollectionUtils.isEmpty(deductionIds)) {
+            return Collections.emptyMap();
+        }
+        return BotpUtils.findDirectSourceBills(MEASURE_SETTLE, CEXP_DEDUCTION, deductionIds);
+    }
+
+    // ==================== 场景4：链路结果回填/提示 ====================
+
+    /**
+     * 构建“源单 -> 指定目标单”的映射，适合附件复制、状态回写、批量关联处理。
+     */
+    public static Map<Long, Set<Long>> findMeasureToDeductionMap(QFilter filter) {
+        DynamicObjectCollection rows = QueryServiceHelper.query(MEASURE_SETTLE, "id", filter.toArray());
+        Set<Long> measureIds = DynamicObjectUtils.setOf(rows, "id");
+        if (CollectionUtils.isEmpty(measureIds)) {
+            return Collections.emptyMap();
+        }
+        return BotpUtils.findAllTargetBills(CEXP_DEDUCTION, MEASURE_SETTLE, measureIds);
+    }
+
+    /**
+     * 只提示某一类下游单据时，先查目标主键，再回查单号，避免把整条链路拼到消息里。
+     */
+    public static String buildPayApplyExistsMessage(Long measureId, String measureBillNo) {
+        Set<Long> payApplyIds = BotpUtils.findAllTargetBillsFlat(
+                AP_PAYAPPLY,
+                MEASURE_SETTLE,
+                Collections.singleton(measureId)
+        );
+        if (CollectionUtils.isEmpty(payApplyIds)) {
+            return null;
+        }
+        QFilter filter = new QFilter("id", QCP.in, payApplyIds);
+        DynamicObjectCollection rows = QueryServiceHelper.query(AP_PAYAPPLY, "id,billno", filter.toArray());
+        Map<Long, String> billNoMap = rows.stream().collect(Collectors.toMap(
+                row -> row.getLong("id"),
+                row -> row.getString("billno"),
+                (left, right) -> left
+        ));
+        String payApplyNos = billNoMap.values().stream().sorted().collect(Collectors.joining("、"));
+        return String.format(
+                ResManager.loadKDString("计量结算单[%s]已生成付款申请单：%s", "BotpTracePushSample_0", RES_APP_ID),
+                measureBillNo,
+                payApplyNos
+        );
+    }
+
+    // ==================== 场景5：下推生成 ====================
+
+    /**
+     * 下推但先不保存，适合需要补字段、补分录、做二次校验的场景。
+     */
+    public static DynamicObject pushNoSave(Long measureId, String ruleId) {
+        PushResult pushResult = BotpUtils.pushNoSave(MEASURE_SETTLE, AP_PAYAPPLY, measureId, ruleId)
+                .failThenThrow();
+        return pushResult.getSingleDataPack();
+    }
+
+    /**
+     * 下推后补充头字段，再调用统一保存操作。
+     */
+    public static DynamicObject pushAndSave(Long measureId, String sourceBillNo, String ruleId) {
+        DynamicObject targetBill = pushNoSave(measureId, ruleId);
+        if (targetBill == null) {
+            return null;
+        }
+        targetBill.set("kdcd_sourcebillno", sourceBillNo);
+        OpUtils.executeOperateOrThrow("save", AP_PAYAPPLY, new DynamicObject[]{targetBill});
+        return targetBill;
+    }
+}