销售物流信息及其二开简介

    星空供应链领域销售模块下的销售订单，发货通知单，销售出库单和销售退货单都有一个物流跟踪页签，在这个页签下可以手动输入物流公司和物流单号等信息，当然也可以通过快递100获取电子面单自动回填物流公司和物流单号到这个页签中，或者通过快递管家订单导入后再打印回填，供应链领域销售模块下的单据中的物流单号轨迹信息（销售物流信息列表）都是通过调用快递100相关接口实现的，因此使用前需要配置好相关参数，如下图1-0所示为配置界面：

图1-0

在非常早的版本(大概是2019年之前的版本)这个页签下是启用了两个表格，左侧是保存物流单号，右侧是物流单号对应的轨迹信息，通过BOSIDE可以看出来，如下图1-1所示：

图1-1

    最新的版本只保留左侧的表格用于保存物流单号，弃用了右侧的物流单号轨迹信息。但是为了兼容老版本，这个BOS IDE 里面还是可以看到右侧的这个表格，只是它默认不可见，且它对应的数据库表也是存在的，这可以通过操作界面看到默认只显示左侧单据体，如下图1-2所示 ：

图1-2

     如果客户如果想在新版本继续使用右侧的物流详细子单据体，需要自行扩展元数据并将子单据体设置为可见，另外需要自行调用快递100相关物流接口并将接口返回信息填充到子单据体中，T_SAL_ORDERTRACEDETAIL、T_SAL_DELIVERYTRACEDETAIL、  T_SAL_OUTSTOCKTRACEDETAIL、 T_SAL_RETSTOCKTRACEDETAIL分别代表销售订单， 发货通知单，销售出库单，销售退货单上的物流详细表。有关调用快递100物流信息及读取快递100参数配置可反编译程序集文件'Kingdee.K3.SCM.Sal.Business.PlugIn.dll'，并定位到类'Kingdee.K3.SCM.Sal.Business.PlugIn.SalLogistInfoEdit'定义中，如下图1-2.1所示：

图1-2.1

    通版是通过‘销售物流信息列表’统一管理销售订单，发货通知单，销售出库单，销售退货单上的物流单号对应的物流详情，这与采购模块是不同的，目前的版本采购模块依然使用单据上的两个表格表示，主要是因为销售模块是发出功能而采购模块是接收功能，采购也仅仅只是个别单据要物流单号，且是手工输入物流单号并查询物流详情，销售模块就是有太多单据要输入物流单号且对接了快递100，这意味着快递单号不仅仅是手工输入还可以通过第三方回填，此时在一个地方维护就方便了，如下图1-3所示：

图1-3

    销售物流信息列表中的表头是通过视图‘V_SAL_LOGISTICSINFO’ 汇集了销售订单，发货通知单，销售出库单，销售退货单上的物流跟踪页签中的物流信息的（通过exec sp_helptext 'V_SAL_LOGISTICSINFO'可以看到它用UNION了这几个单据），表体是一个物理表 T_SAL_LOGISTINFODETAIL。销售物流信息中的物流刷新功能是可以有手动刷新或自动定时刷新功能的。在快递100参数中配置好后，手动刷新功能可通过上图1-3中的列表菜单或编辑界面中的菜单 '刷新物流信息'实现。自动定时刷新是通过‘销售物流更新’执行计划实现的，如下图1-4所示：

图1-4

    自动定时刷新物流也是需要通过快递100参数配置的，勾选了参数'定时更新销售物流信息并进行时间范围控制'才会自动定时刷新物流信息（由于快递100的实时物流查询接口跨自然月重复收费原则（收费策略可能会有变动，建议咨询快递100官方以获取最新收费策略），其中的控制范围内的天数建议输入小于10天内的值），如下图1-5红框所示：

    图1-5    

    执行计划‘销售物流更新’，它默认值是3分钟（注意这里所说的3分钟不是说每个物流单号每三分钟就刷新一次物流详情）执行一次，执行计划配置的后台插件名为 ‘Kingdee.K3.SCM.App.Core.UpdateSalLogisticsInfo,Kingdee.K3.SCM.App.Core’。此UpdateSalLogisticsInfo类主要依据中中间表‘T_SAL_LOGISTICINFOPLAN ’，此表除了物流单号，物流公司等物流信息外，还有一些标识字段，比如用于标识当前时间的FDATETIME和用于指示当前物流单号是否被刷新过的标识FSTATUS。最新版本的执行计划代码逻辑大致为：

步骤1：当天凌晨过几分时(假设为2021-09-07 00:00:01)第一个执行计划（假设用S1指代第一个执行计划）进来，S1首先判断是否勾选了参数'定时更新销售物流信息并进行时间范围控制'，如果没有勾选，执行计划直接返回，不做后续处理。

步骤2：如果勾选了参数‘定时更新销售物流信息并进行时间范围控制’，则判断表‘ T_SAL_LOGISTICINFOPLAN ’中是否有当天的记录(FDATETIME为当天的记录)。如果有记录，则直接跳转到步骤3；如果没有记录， 则获取单据日期大于等于当前时间减去控制范围内的天数，且签收状态为未签收的物流信息，并将此获取到的记录填充到‘T_SAL_LOGISTICINFOPLAN’表。举个例子，如果快递100参数配置的‘控制范围内的天数’为7，假设当前时间为2021-09-07，且‘T_SAL_LOGISTICINFOPLAN’ 表中的FDATETIME字段都是2021-09-06前的记录，则销售订单，发货通知单，销售出库单，销售退货单单据日期大于等于2021-09-01，且单据上的物流页签中的物流单号未签收的记录都会被填充到'T_SAL_LOGISTICINFOPLAN'表中(此时这个表中的FDATETIME为2021-09-07，FSTATUS为0，并且删除了这个表中2021-09-07之前的记录)。

步骤3：接着从‘T_SAL_LOGISTICINFOPLAN’表中读取前100条FSTATUS=‘0’的记录，对这100个记录的物流单号调用快递100API接口查询物流信息（至少间隔1秒钟查询一个单的物流信息，100个物流单据至少要100秒钟才能完成），查询完后，不管是否是签收，都更新FSTATUS字段为'1'，FSTATUS已经被标识为1的记录当天都不会被处理，如果没有读取到前100条FSTATUS=‘0’的记录，则什么都不做。

步骤4：在随后的3分钟，第二个执行计划(假设用S2指代第二个执行计划)进来，S2也要先经过步骤1，再到步骤2，在步骤2时由于3分钟前的执行计划S1已经对‘T_SAL_LOGISTICINFOPLAN’表做了处理（S1会确保表中肯定有当天的记录），所以S2在进入步骤2判断时会直接跳转到步骤3，在步骤3中，S2依然是取前100条FSTATUS='0'的记录，但此时由于前面的执行计划S1已经将‘T_SAL_LOGISTICINFOPLAN’表中某些记录的FSTATUS标识为'1'，所以表中总的FSTATUS=‘0’的记录数会随着每3分钟另一个执行计划的执行而减少100条，直到没有记录为止，也就是表T_SAL_LOGISTICINFOPLAN中所有的FSTATUS都是1。

    针对上面的四个步骤可以看出，如果当天一共查询出350条物流单号，那么只要前4个执行计划实例进来就能全部刷新完，也就是大概12，13分钟就能完成，也就是说当天凌晨大概00：15点之后的执行计划实例虽然都进来了，但是它们看到没有数据要刷新物流，什么事都没有做就返回了。通版这样做只是为了兼容物流数据比较多的客户去完成刷新，有些客户一天内就有上万条物流单号要刷新，且快递100建议每次物流刷新接口要至少间隔一秒再调用，如果客户物流单号量大于一天内的秒数则始终有物流单号是刷新不到的。针对少量物流数据的客户，虽然也能刷新到，但是如果T_SAL_LOGISTICINFOPLAN表中的某个物流单号在当天早上，中午，下午或者晚上都分别有新的物流信息到达。这个时刻执行计划就在当天刷新不到，只能等到第2天（次日）凌晨后才能刷新到，前提要确保快递100参数配置中的控制范围内的天数包含了次日。这样大概就会有最大1天左右的延迟刷新。对于实时性有要求的客户可购买快递管家物流推送服务以达到实时获取物流信息的目的。

    二开情形1：如果不想购买快递管家物流推送服务，通过上面的4个步骤可以看出控制关键点是表T_SAL_LOGISTICINFOPLAN中的FSTATUS字段，如果物流数据量不太，完全可以二开一个执行计划，在二开的执行计划中直接定时将FSTATUS刷新为0，类似于执行以下SQL: UPDATE T_SAL_LOGISTICINFOPLAN SET FSTATUS = '0' WHERE FSTATUS = '1' ，这样通版的执行计划在进入步骤3时就能查询到FSTATUS=‘0’的记录，但是要注意这样的二开执行计划最好控制6，7个小时执行一次不宜过于频繁，也可以直接在执行计划中将整个T_SAL_LOGISTICINFOPLAN表中的记录删除，另外一个要注意的点是快递100参数配置中的‘控制范围内的天数’最多只能配置成最大30天，即使客户在BOS中二开放开这个限制输入40天，内部执行计划也会只获取前30天的数据，这么做只是为了确保快递100查询物流时不多重收费(可能某个物流单号由于异常一直没有签收，或者由于星空系统异常导致一直没有更新成功，那么跨月调用快递100物流刷新接口时会多重收费（收费策略可能会有变动，建议咨询快递100官方以获取最新收费策略），所以通版控制了最多30天，这30天其实也不能完全控制是物流的时间，因为它只是星空单据的时间而不是物流单号的时间)，另外通版后续的2022.3.31版本已经推出快递100物流推送服务。此功能可以替代本执行计划且没有延迟等缺陷，详情请参阅：https://vip.kingdee.com/article/288016181233754624?productLineId=1 。

    二开情形2：有些客户已经在非销售模块下的单据上二开添加过类似销售出库单上的物流跟踪页签，比如有些客户在分步式调出单上已经二开添加了一个物流跟踪的单据体用于存放分步式调出单的物流信息。根据上面所述，通版销售物流信息列表统一管理了销售模块下单据上的物流信息，一个销售物流信息记录是由视图V_SAL_LOGISTICSINFO确定表头，表T_SAL_LOGISTINFODETAIL确定表体的，通版不会包含分步式调出单上的物流信息，因此需要二开视图V_SAL_LOGISTICSINFO，添加一个UNION ALL将分步式调出单上的物流信息也查询出来（要确保FID字段唯一，每次更新补丁时会被通版冲刷掉，因此也要注意下），这样通版的手动刷新物流信息和自动刷新物流信息就能兼容二开单据上的物流信息列表，即分步式调出单上的物流跟踪详情也会被记录到表T_SAL_LOGISTINFODETAIL中。假设客户在分步式调出单上二开的物流跟踪信息单据体对应的表为T_STK_STKTRANSFEROUTTRACE，则可以修改视图V_SAL_LOGISTICSINFO，在通版视图脚本后追加类似以下的语句即可：

UNION ALL
SELECT ((((CONVERT(VARCHAR(8000), OD.FID) + '-') + OT.FOBJECTTYPEID) + '-') + CONVERT(VARCHAR(8000), 
OD.FENTRYID)) FID, ((((CONVERT(VARCHAR(8000), OD.FID) + '-') + OT.FOBJECTTYPEID) + '-') + 
CONVERT(VARCHAR(8000), OD.FENTRYID)) FMASTERID, 
((CONVERT(VARCHAR(8000), OD.FID) + '-') + OT.FOBJECTTYPEID) FORDERID, OT.FDATE, OT.FBASECURRID, 
OT.FBILLTYPEID, OT.FBILLNO FSALBILLNO, OT.FOBJECTTYPEID, OT.FSTOCKORGID, OT.FCUSTID FCUSTOMERID, 
OD.FTRACESTATUS, OD.FLOGCOMID, OD.FCARRYBILLNO, OD.FPHONENUMBER, OD.FFROM, OD.FTO 
FROM T_STK_STKTRANSFEROUT OT 
INNER JOIN T_STK_STKTRANSFEROUTTRACE OD ON OT.FID = OD.FID

    二开情形3：如果想在销售物流信息列表添加自定义的列，比如说客户想在列表中添加一列关联的上游单号，则需要重写整个V_SAL_LOGISTICSINFO视图(每个UNION ALL 从句都要添加新列，且每次更新补丁后此视图都可能会被通版冲刷掉，所以每次升级都得重新配置视图)，以销售出库单为列，记录销售出库单上游单号的字段是在销售出库单详细信息中，明细信息与物流信息没有绝对一对一关系，它们都是单据体，这种情况下就应当取分录中的第一行（或者某一行）信息再去关联出库单主表信息，脚本大致为：

UNION  ALL
 SELECT TO_CHAR(UT.FID) || '-' || OU.FOBJECTTYPEID || '-' || TO_CHAR(UT.FENTRYID) AS FID, 
 TO_CHAR(UT.FID) || '-' || OU.FOBJECTTYPEID || '-' || TO_CHAR(UT.FENTRYID) AS FMASTERID,
 TO_CHAR(UT.FID) || '-' || OU.FOBJECTTYPEID AS FORDERID, OU.FDATE, UI.FSETTLECURRID, OU.FBILLTYPEID, 
 OU.FBILLNO AS FSALBILLNO, OU.FOBJECTTYPEID, OU.FSALEORGID, OU.FCUSTOMERID AS FCUSTOMERID,
 UT.FTRACESTATUS, UT.FLOGCOMID, UT.FCARRYBILLNO, UT.FPHONENUMBER, UT.FFROM, UT.FTO, 
 T.FSRCBILLNO
 FROM  T_SAL_OUTSTOCK OU
 INNER JOIN  T_SAL_OUTSTOCKTRACE  UT ON OU.FID = UT.FID
 INNER JOIN T_SAL_OUTSTOCKFIN UI ON UI.FID = UT.FID
 INNER JOIN 
 (
 SELECT OER.FID, MAX(OER.FSRCBILLNO) FSRCBILLNO
 FROM T_SAL_OUTSTOCKENTRY_ROER 
 GROUP BY OER.FID
 ) T ON OU.FID = T.FID

注意上面的语法中的'||'，|| 主要是为了满足KSQL的语法，可以通过BOS IDE翻译成SQL Server语句，然后再扩展基础资料'销售物流信息'，添加一列到单据头并对应为脚本中的FSRCBILLNO（FSRCBILLNO就是二开的显示的新列，代表源单号）。客户可通过类似的方法添加其它二开列，比如想添加发货组织，可以在上面KSQL脚本的 T.FSRCBILLNO后面追加 , OU.FSTOCKORGID，然后再扩展'销售物流信息'，拖拽一个组织类型的字段，将其字段名配置成为FSTOCKOGID。

    二开情形4：如果客户想在'销售物流信息'列表中的'刷新物流信息'按钮点击后想自定义逻辑，比如在上面二开情形2的时候提供了OD.FTRACESTATUS字段，这个物流状态字段默认是没有值的，那么就要在'刷新物流信息'时赋值物流状态，则可更新到2022年6月补丁，二开一个继承至通版基础资料'销售物流信息'的表单插件（SalLogistInfoEdit类，Kingdee.K3.SCM.Sal.Business.PlugIn.dll组件中，下同），另外二开一个继承至通版的列表插件（SalLogistInfoList），并重写其中的相关方法，在BOS IDE中禁用通版插件，注册和启用二开的插件即可。要重写的方法有：Kingdee.K3.SCM.Sal.Business.PlugIn.SalLogistInfoEdit.CustomHandleLogisticDetails(BOS.Context contxt, CustomKuaiDi100Result results) 和Kingdee.K3.SCM.Sal.Business.PlugIn.SalLogistInfoList.CustomHandleBatchLogisticDetails(BOS.Context contxt, List<Core.SAL.CustomKuaiDi100Result> allResults)

类 CustomKuaiDi100Result 的定义义说明如下图2-1和图2-2所示：

    图2-1

图2-2

如果是启用了执行计划'销售物流更新'去自动刷新物流信息，则可以二开一个继承至通版UpdateSalLogisticsInfo的插件(在程序集文件 Kingdee.K3.SCM.App.Core.dll中)并重写其中的 CustomHandleLogisticDetails 方法，然后修改执行计划的服务插件字段，使用二开插件的命名空间全名替换即可，如下图2-3所示：

图2-3

如果使用了快递100的物流订阅自动推送功能或者使用了快递管家的物流推送功能，则需要二开一个继承至通版Kuaidi100HttpHandler插件（在程序集文件Kingdee.K3.SCM.Business.PlugIn.dll 中），重写其中的CustomLogisticsDetailInfo方法，并替换回调地址和Common.config定义，自定义回调处理程序伪代码如下图3-1所示：，其中的lastResult参数数据包可以参阅相关快递100和快递管家接口文档对应的属性。

图3-1

图3-2

图3-3

图3-4

图3-5

图3-6

    另外说明下：如果通版没有添加客户想要对接的物流公司编码（比如快递100对接了新的物流公司，但是金蝶云星空没有即时对应地更新），则可以手动在快递100物流公司列表中添加，但是要注意此物流公司编码一定要对应快递100官网上的公司编码，如果对不上，则很有可能刷新不到物流公司。比如客户添加了一个编码为SF的物流公司，用这个编码去刷新顺丰的物流单号轨迹信息是很有可能刷新不到的，要使用通版已经内置了的shunfeng的物流公司。有关支持的物流公司请参阅快递100接口官方文档 https://api.kuaidi100.com/document/5f0ffb5ebc8da837cbd8aefc#section_1  。

    受客户提单要求，通版后续将添加快递100物流订阅功能（PT-146906 [8.0.0.202203]发布时包含此功能），此功能可以代替执行计划刷新物流信息，且不会有最大一天的延迟等缺陷，详细参阅：http://ksm.kingdee.com:8000/rmp/feedback.action?&number=R20211207-2739，https://vip.kingdee.com/article/288016181233754624  和 https://api.kuaidi100.com/document/5f0ffa7f2977d50a94e1023b ，https://vip.kingdee.com/article/288016181233754624