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

金蝶云星空K3Cloud生产退料单WEBAPI深度开发实战业务场景与技术挑战在制造业ERP与MES系统集成过程中生产退料单的自动化处理一直是企业数字化转型的关键环节。金蝶云星空作为国内领先的ERP解决方案其标准API接口虽然提供了基础的下推功能但在面对一行生产用料清单对应多行退料单的复杂业务场景时往往显得力不从心。这种场景常见于以下情况混合退料类型同一物料需要区分良品退料、来料不良退料和作业不良退料分批退料处理同一生产任务需要分多次退回剩余物料多仓库退料同一物料需要退回到不同仓库标准API的局限性主要体现在单行分录只能生成一行退料单分录无法灵活处理多退料类型关联同一源单行缺乏对复杂业务规则的扩展支持开发环境与基础配置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开发插件金蝶云星空SDK1.2 基础数据结构定义public class PRD_PickMtrlReturnInfo { public string ACCESSTOKEN { get; set; } // 接口认证令牌 public string FBILLNO { get; set; } // 单据编号 public string FSrcId { get; set; } // 源单编号 public ListPRD_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.FIDt2.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()) { // 构建选中行集合 ListListSelectedRow selectedRows new ListListSelectedRow(); 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; ListTupleint, int linkCopyCount new ListTupleint, 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 Tupleint, 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 性能优化建议数据库查询优化使用参数化查询替代字符串拼接添加适当的索引提高查询效率内存管理及时释放大对象内存避免不必要的对象克隆批量操作减少单据保存次数合并相似操作// 优化后的数据库查询 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 ListSqlParam(); 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 ListBillConvertLine Lines { get; set; } } public class BillConvertLine { public string SourceEntryId { get; set; } public Dictionarystring, 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 ListPRD_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)); } }