当前位置： 首页 > news >正文

金蝶云星空K3Cloud实战：手把手教你搞定生产退料单WEBAPI自定义（附完整C#代码）

news 2026/4/22 12:50:45

金蝶云星空K3Cloud生产退料单WEBAPI深度开发实战

业务场景与技术挑战

在制造业ERP与MES系统集成过程中，生产退料单的自动化处理一直是企业数字化转型的关键环节。金蝶云星空作为国内领先的ERP解决方案，其标准API接口虽然提供了基础的下推功能，但在面对"一行生产用料清单对应多行退料单"的复杂业务场景时，往往显得力不从心。

这种场景常见于以下情况：

  • 混合退料类型：同一物料需要区分良品退料、来料不良退料和作业不良退料
  • 分批退料处理：同一生产任务需要分多次退回剩余物料
  • 多仓库退料：同一物料需要退回到不同仓库

标准API的局限性主要体现在：

  1. 单行分录只能生成一行退料单分录
  2. 无法灵活处理多退料类型关联同一源单行
  3. 缺乏对复杂业务规则的扩展支持

开发环境与基础配置

1.1 开发环境准备

// 必需的金蝶云星空开发组件 using Kingdee.BOS; using Kingdee.BOS.Core; using Kingdee.BOS.Orm.DataEntity; using Kingdee.BOS.ServiceHelper; using Kingdee.BOS.App.Data;

开发工具要求：

  • Visual Studio 2019/2022
  • .NET Framework 4.6.1+
  • 金蝶云星空BOS开发插件
  • 金蝶云星空SDK

1.2 基础数据结构定义

public class PRD_PickMtrlReturnInfo { public string ACCESSTOKEN { get; set; } // 接口认证令牌 public string FBILLNO { get; set; } // 单据编号 public string FSrcId { get; set; } // 源单编号 public List<PRD_PickMtrlEntry2> FDetailEntity { get; set; } // 明细集合 } public class PRD_PickMtrlEntry2 { public string FEntryId { get; set; } // 明细内码 public string FSrcEntryId { get; set; } // 源单明细内码 public string FMaterialId { get; set; } // 物料编码 public string FQty { get; set; } // 实发数量 public string FStockID { get; set; } // 仓库编码 public string FEntrtyMemo { get; set; } // 备注 public string FReturnType { get; set; } // 退料类型(1/2/3) public string FReturnReason { get; set; }// 退料原因 public string FISUPDATEQTY { get; set; } // 不更新未领标志 public bool IsUsed { get; set; } = false;// 行使用标记 }

核心业务逻辑实现

2.1 主入口方法设计

public CommonReturnEntity Push_PRD_ReturnMtrl(Context ctx, PRD_PickMtrlReturnInfo data) { CommonReturnEntity returnEntity = new CommonReturnEntity { Code = "0", IMSsage = "成功" }; // 关键参数配置 string convertRuleKey = "PRD_PPBOM2RETURNMTRL"; // 单据转换规则 string FormKey = "PRD_PPBOM"; // 源单标识 string tableName = "T_PRD_PPBOM"; // 源单表名 string tableNameEntry = "T_PRD_PPBOMENTRY"; // 源单明细表名 string sourceBillTypeId = "(All)"; // 源单单据类型 string entryEntityKey = "FEntity"; // 源单明细标识 string targetFormId = "PRD_ReturnMtrl"; // 目标单标识 string targetEntryOrm = "Entity"; // 目标单明细ORM实体 string qty = "FAPPQty"; // 目标单数量标识 string entrtyMemo = "FEntrtyMemo"; // 目标单备注标识 try { returnEntity = ConvertBillReturn(ctx, data, FormKey, tableName, tableNameEntry, entryEntityKey, sourceBillTypeId, targetFormId, convertRuleKey, targetEntryOrm, qty, entrtyMemo); } catch (Exception e) { returnEntity.Code = "1006"; returnEntity.IMSsage = e.Message; } finally { // 日志记录逻辑 } return returnEntity; }

2.2 单据转换核心算法

public CommonReturnEntity ConvertBillReturn(Context ctx, PRD_PickMtrlReturnInfo data, string FormKey, string tableName, string tableNameEntry, string entryEntityKey, string sourceBillTypeId, string targetFormId, string convertRuleKey, string targetEntryOrm, string qty, string entrtyMemo) { // 数据校验逻辑 if (string.IsNullOrWhiteSpace(data.FSrcId)) return new CommonReturnEntity { Code = "1006", IMSsage = "源单编号不能为空！" }; // 源单查询SQL string sql = $@"/*dialect*/ select t1.FPrdOrgId,t1.FEntrustOrgId,t1.FID,t1.FBILLNO,t2.FSEQ,t2.FENTRYID from {tableName} t1 inner join {tableNameEntry} t2 on t1.FID=t2.FID where t1.FBILLNO='{data.FSrcId}'"; var obj = DBUtils.ExecuteDynamicObject(ctx, sql); if (obj == null || obj.Count == 0) return new CommonReturnEntity { Code = "1006", IMSsage = $"未查询到上游单据：{data.FSrcId}！" }; // 事务处理 using (KDTransactionScope trans = new KDTransactionScope()) { // 构建选中行集合 List<ListSelectedRow> selectedRows = new List<ListSelectedRow>(); foreach (var rowObj in obj) { if (data.FDetailEntity.Select(s => s.FSrcEntryId).ToList() .Contains(rowObj["FENTRYID"].ToString())) { ListSelectedRow listSelectedRow = new ListSelectedRow( rowObj["FID"].ToString(), rowObj["FENTRYID"].ToString(), (int)rowObj["FSEQ"], FormKey); listSelectedRow.EntryEntityKey = entryEntityKey; selectedRows.Add(listSelectedRow); } } // 下推配置 ConvertOption convertOption = new ConvertOption { TargetOrgId = Convert.ToInt64(obj[0]["FEntrustOrgId"]) == 0 ? Convert.ToInt64(obj[0]["FPrdOrgId"]) : Convert.ToInt64(obj[0]["FEntrustOrgId"]), sourceFormId = FormKey, sourceBillTypeId = sourceBillTypeId, targetFormId = targetFormId, ConvertRuleKey = convertRuleKey, IsDraft = true, IsSave = false, IsAudit = false, Option = OperateOption.Create(), BizSelectRows = selectedRows.ToArray() }; // 执行下推 PushResult result_push = GSBAppServiceContext.BillConvertService.ConvertBills(ctx, convertOption); if (!result_push.result.IsSuccess) return new CommonReturnEntity { Code = "1", IMSsage = Returns(result_push.result) }; // 处理多行复制逻辑 DynamicObject[] TargetBillData = result_push.TargetBillData; foreach (var billItem in TargetBillData) { var entrys = billItem["Entity"] as DynamicObjectCollection; List<Tuple<int, int>> linkCopyCount = new List<Tuple<int, int>>(); // 确定需要复制的行 int index = 0; foreach (var entryItem in entrys) { DynamicObjectCollection links = entryItem["FEntity_Link"] as DynamicObjectCollection; string srcEntryId = Convert.ToString(links[0]["SId"]); var recEntryData = data.FDetailEntity.Where(p => p.FSrcEntryId == srcEntryId).ToList(); int needCopyCount = recEntryData.Count - 1; if (recEntryData.Count > 0) { linkCopyCount.Add(new Tuple<int, int>(index, needCopyCount)); } index++; } // 执行行复制 foreach (var tupleItem in linkCopyCount) { DynamicObject needCopyDy = entrys[tupleItem.Item1]; for (int ii = 0; ii < tupleItem.Item2; ii++) { DynamicObject copyedDy = (DynamicObject)Kingdee.BOS.Orm.OrmUtils.Clone(needCopyDy); copyedDy["seq"] = entrys.Count + 1; entrys.Add(copyedDy); } } } // 单据暂存与后续处理 IOperationResult results = GSBAppServiceContext.BillConvertService .DraftBillData(ctx, targetFormId, TargetBillData); long Fsaveid = Convert.ToInt64(results.OperateResult[0].PKValue); // 创建单据视图并更新字段 IBillView billView = FourSDataManagerUtil.CreateBillView(ctx, targetFormId, Fsaveid); ((IBillViewService)billView).LoadData(); IDynamicFormViewService dynamicFormViewPush = billView as IDynamicFormViewService; // 更新单据头信息 dynamicFormViewPush.UpdateValue("FBILLNO", 0, data.FBILLNO); dynamicFormViewPush.UpdateValue("F_BHR_SJLY", 0, "1"); // 更新单据体信息 DynamicObjectCollection BillDataEntitys = billView.Model.DataObject["Entity"] as DynamicObjectCollection; int rowindex = 0; foreach (var item in BillDataEntitys) { DynamicObjectCollection links = item["FEntity_Link"] as DynamicObjectCollection; string srcEntryId = Convert.ToString(links[0]["SId"]); var recEntryData = data.FDetailEntity .Where(p => p.FSrcEntryId == srcEntryId && p.IsUsed == false) .FirstOrDefault(); if (recEntryData == null) continue; recEntryData.IsUsed = true; dynamicFormViewPush.UpdateValue("F_BHR_EntryId", rowindex, recEntryData.FEntryId); if (!string.IsNullOrEmpty(recEntryData.FMaterialId)) dynamicFormViewPush.SetItemValueByNumber("FMaterialId", recEntryData.FMaterialId, rowindex); dynamicFormViewPush.UpdateValue("FReturnType", rowindex, recEntryData.FReturnType); if (!string.IsNullOrEmpty(recEntryData.FStockID)) dynamicFormViewPush.SetItemValueByNumber("FStockID", recEntryData.FStockID, rowindex); dynamicFormViewPush.UpdateValue("FAPPQty", rowindex, recEntryData.FQty); dynamicFormViewPush.SetItemValueByNumber("FReturnReason", recEntryData.FReturnReason, rowindex); if (recEntryData.FISUPDATEQTY == "1" && recEntryData.FReturnType != "3") dynamicFormViewPush.UpdateValue("FIsUpdateQty", rowindex, true); rowindex++; } // 保存并提交单据 IOperationResult sResult = FourSDataManagerUtil.SaveBill(ctx, billView, OperateOption.Create().SetIgnoreWarning(true)); if (!sResult.IsSuccess) { return new CommonReturnEntity { Code = "1006", IMSsage = Returns(sResult, "保存失败") }; } sResult = AppServiceContext.SubmitService.Submit(ctx, billView.BusinessInfo, new object[] { Fsaveid }, "Submit", OperateOption.Create().SetIgnoreWarning(true)); if (!sResult.IsSuccess) { return new CommonReturnEntity { Code = "1006", IMSsage = Returns(sResult, "提交失败") }; } // 审核单据 var Result = BusinessDataServiceHelper.Audit(ctx, billView.BusinessInfo, new object[] { Fsaveid }, OperateOption.Create().SetIgnoreWarning(true)); trans.Complete(); } return new CommonReturnEntity { Code = "0", IMSsage = "成功" }; }

关键技术与难点解析

3.1 动态对象操作技巧

金蝶云星空的DynamicObject是处理业务数据的核心对象，需要掌握以下关键操作：

// 获取动态对象集合 DynamicObjectCollection entrys = billItem["Entity"] as DynamicObjectCollection; // 克隆动态对象 DynamicObject copyedDy = (DynamicObject)Kingdee.BOS.Orm.OrmUtils.Clone(needCopyDy); // 更新动态对象属性 copyedDy["seq"] = entrys.Count + 1; // 添加对象到集合 entrys.Add(copyedDy);

3.2 行复制算法优化

原始方案的行复制逻辑存在性能瓶颈，改进后的算法：

// 改进后的行复制逻辑 List<(int Index, int Count)> copyOperations = new List<(int, int)>(); for (int i = 0; i < entrys.Count; i++) { var links = entrys[i]["FEntity_Link"] as DynamicObjectCollection; string srcEntryId = links[0]["SId"].ToString(); int matchCount = data.FDetailEntity.Count(p => p.FSrcEntryId == srcEntryId); if (matchCount > 1) { copyOperations.Add((i, matchCount - 1)); } } // 批量执行复制（减少集合修改次数） foreach (var op in copyOperations.OrderByDescending(x => x.Index)) { var template = entrys[op.Index]; var newEntries = Enumerable.Range(0, op.Count) .Select(_ => (DynamicObject)Kingdee.BOS.Orm.OrmUtils.Clone(template)) .ToList(); for (int i = 0; i < newEntries.Count; i++) { newEntries[i]["seq"] = entrys.Count + i + 1; } entrys.InsertRange(op.Index + 1, newEntries); }

3.3 事务处理与异常管理

using (KDTransactionScope trans = new KDTransactionScope()) { try { // 业务逻辑处理 trans.Complete(); } catch (Exception ex) { // 记录详细错误日志 Logger.Error("ConvertBillReturn", ex.ToString()); throw; // 重新抛出异常，由外层捕获处理 } }

调试与性能优化

4.1 日志记录策略

// 详细的调试日志记录 Logger.Info("ConvertBillReturn", $"开始处理单据 {data.FBILLNO}"); Logger.Debug("SelectedRows", JsonConvert.SerializeObject(selectedRows)); Logger.Debug("TargetBillData", JsonConvert.SerializeObject(TargetBillData));

4.2 性能优化建议

  1. 数据库查询优化：

    • 使用参数化查询替代字符串拼接
    • 添加适当的索引提高查询效率

  2. 内存管理：

    • 及时释放大对象内存
    • 避免不必要的对象克隆

  3. 批量操作：

    • 减少单据保存次数
    • 合并相似操作
// 优化后的数据库查询 string sql = @"/*dialect*/ SELECT t1.FPrdOrgId, t1.FEntrustOrgId, t1.FID, t1.FBILLNO, t2.FSEQ, t2.FENTRYID FROM T_PRD_PPBOM t1 INNER JOIN T_PRD_PPBOMENTRY t2 ON t1.FID = t2.FID WHERE t1.FBILLNO = @billNo"; var parameters = new List<SqlParam>(); parameters.Add(new SqlParam("@billNo", KDDbType.String, data.FSrcId)); var obj = DBUtils.ExecuteDynamicObject(ctx, sql, parameters.ToArray());

扩展应用与最佳实践

5.1 通用化设计思路

将核心逻辑抽象为通用服务：

public interface IBillConvertService { CommonReturnEntity ConvertBillWithMultiLines( Context ctx, string sourceFormId, string targetFormId, string convertRuleKey, BillConvertRequest request); } public class BillConvertRequest { public string SourceBillNo { get; set; } public string TargetBillNo { get; set; } public List<BillConvertLine> Lines { get; set; } } public class BillConvertLine { public string SourceEntryId { get; set; } public Dictionary<string, object> Fields { get; set; } }

5.2 安全与权限控制

// 接口调用权限验证 if (!GSBAppServiceContext.AuthService.CheckPermission(ctx, "API_PRD_ReturnMtrl")) { return new CommonReturnEntity { Code = "403", IMSsage = "无权限调用此接口" }; } // 数据访问权限过滤 string orgFilter = GetUserOrgFilter(ctx); sql += $" AND t1.FPrdOrgId IN ({orgFilter})";

5.3 单元测试建议

[TestClass] public class ReturnMtrlConverterTests { [TestMethod] public void TestConvertWithMultipleLines() { // 准备测试数据 var request = new PRD_PickMtrlReturnInfo { FSrcId = "TEST001", FDetailEntity = new List<PRD_PickMtrlEntry2> { new PRD_PickMtrlEntry2 { FSrcEntryId = "1001", /* 其他字段 */ }, new PRD_PickMtrlEntry2 { FSrcEntryId = "1001", /* 其他字段 */ } } }; // 执行测试 var result = converter.ConvertBillReturn(/* 参数 */); // 验证结果 Assert.AreEqual("0", result.Code); Assert.AreEqual(2, GetBillLineCount(result.Data)); } }
http://www.jsqmd.com/news/681915/

相关文章：

  • 4月22日成都地区包钢产无缝钢管(8163-20#;外径42-630mm)现货报价 - 四川盛世钢联营销中心
  • 别再只会用QMessageBox::information了！Qt对话框进阶：手把手教你打造自定义按钮和详细信息的弹窗
  • 从模型到芯片：手把手教你用RKNN-Toolkit Lite在RV1126开发板上跑通第一个AI Demo
  • 手把手教你用STM32F411CEU6和W25Q128打造一个超迷你的U盘（附完整代码）
  • ExplorerPatcher终极指南：免费恢复Windows 11经典界面与高效工作流
  • NeRF实战：用Google Colab免费GPU，30分钟从照片生成你的第一个3D模型
  • Tesseract OCR终极指南：如何用开源引擎实现高效文字识别
  • openKylin 2.0 SP2第三次更新：优化关键模块，新增装包功能提升速度
  • TI C2000 DSP的CAN中断实战：一个邮箱如何接收多个ID的数据帧？
  • 5分钟快速上手PKHeX自动合法性插件：宝可梦数据合规终极指南
  • 从‘秒’到‘纳秒’：手把手教你用`std::chrono`设计一个带暂停/重置功能的跨平台计时器类
  • 别再只用MD5了！深入对比PostgreSQL的SCRAM-SHA-256和MD5，附AWS RDS实战配置避坑指南
  • Django后台进阶：用SimpleUI自定义菜单与数据展示，打造你的专属运营中台
  • 22日成都市批发兼零售螺旋焊管(Q235B;内径DN200-3500mm)现货报价 - 四川盛世钢联营销中心
  • Mac音乐解密神器：3分钟解锁QQ音乐加密格式，让音乐自由播放
  • ComfyUI-Impact-Pack：AI图像精细化处理的全能工具包
  • Visual Syslog Server：Windows平台最完整的日志集中管理终极指南
  • 彻底告别激活烦恼：KMS智能激活脚本终极解决方案
  • 目前口碑好的GEO全托管供应商找哪家 - 小张小张111
  • 如何高效解决B站视频下载难题：BiliDownloader实战指南
  • 联想电脑开机进入 Diagnostics UEFI 界面？一文教你快速退出 + 排查原因
  • 抖音无水印视频下载终极教程：3步免费批量保存完整作品集
  • DPABI实战：手把手教你搞定静息态fMRI统计分析与多重比较矫正（附避坑指南）
  • BiliDownloader：高效智能的B站视频下载解决方案
  • RT-Thread BSP提交指南：从个人项目到社区贡献，你的代码如何通过审核并入主分支
  • 5步高效解决Windows程序启动失败：Visual C++运行库完整修复指南
  • C++客户端开发面试复盘：除了华为OD，这些QT和设计模式问题你也可能遇到
  • 回溯——全排列
  • 从MATLAB到Cadence：一个完整CTSDM数模混合芯片的后端验证避坑实录
  • 告别EV2400？手把手教你用STM32F407模拟BQ34Z100对BQ34Z100进行参数配置与读写