# hamster_kingdee

**Repository Path**: mssqlserver/hamster_kingdee

## Basic Information

- **Project Name**: hamster_kingdee
- **Description**: 金蝶云星空WebAPI二次封装应用。方便第三方异构系统与星空系统对接。
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 13
- **Created**: 2022-01-27
- **Last Updated**: 2022-01-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# hamster_kingdee

### 介绍
金蝶云星空（下称星空系统）WebAPI二次封装应用，方便第三方异构系统与星空系统对接。  
星空系统对单据的操作动作拆分粒度比较细，而且WebAPI字段数目多，这样很好地支持了业务管控，但是带来的问题就是操作步骤多，这些步骤还包含了星空系统的校验逻辑。给于第三方对接团队带来了极大的心理压力和工作负担，严重的会导致项目失败。因此，在实际的实施工作中，第三方基本上会要求金蝶实施方对星空系统的接口做二次封装。  
本应用将常用的单据操作筛选出来，并将多个操作步骤整合到一个请求中，而且简化了字段，这样既简化了系统对接，也降低了工作人员的工作量。

### 软件架构
本软件使用金蝶云星空系统自定义插件机制开发而成。   
开发语言：C#  
环境：.NET Framework 4.0

### 安装教程

1. 编译项目生成Hamster.K3Cloud.WebAPI.ServerExtend.dll；
2. 复制到金蝶安装目录：\Kingdee\K3Cloud\WebSite\Bin（默认为：C:\Program Files (x86)\Kingdee\K3Cloud\WebSite\Bin）
3. 重启IIS服务器

### 使用说明
使用文档：《[使用文档](https://gitee.com/hsg4ok_admin/hamster_kingdee/wikis/%E5%AE%89%E8%A3%85%E9%83%A8%E7%BD%B2)》

#### 接口报文样例  
```json
{
	"LocalFormId": "PUR_ReceiveBill",
	"NextFormId": "STK_InStock",
	"RuleId": "PUR_ReceiveBill-STK_InStock",
	"NextQueryEntryKey": "PUR_ReceiveEntry",
	"NextEntryKey": "FInStockEntry",
    "ActionName": "PushAndUpdate",
	"IsAutoSubmitAndAudit": true,
	"Modle": {
		"FInStockEntry": [{
			"FLot": {
				"FNumber": "111"
			},
			"FNote": "测试单据体备注1",
			"FRealQty": "10",
			"FSrcBillEntryID": "113928",
			"FGiveAway": false,
			"FProduceDate": "2021-06-13 00:00:00",
			"FExpiryDate": "2025-06-13 00:00:00"
		}, {
			"FLot": {
				"FNumber": "111"
			},
			"FNote": "测试单据体备注2",
			"FRealQty": "10",
			"FSrcBillEntryID": "113931",
			"FGiveAway": false,
			"FProduceDate": "2021-06-13 00:00:00",
			"FExpiryDate": "2025-06-13 00:00:00"
		}]
	}
}
```
**如果使用Postman等类似工具进行测试，则报文如下**
```JSON
{
	"parameters": [{
		"LocalFormId": "PUR_ReceiveBill",
		"NextFormId": "STK_InStock",
		"RuleId": "PUR_ReceiveBill-STK_InStock",
		"NextQueryEntryKey": "PUR_ReceiveEntry",
		"NextEntryKey": "FInStockEntry",
		"ActionName": "PushAndUpdate",
		"IsAutoSubmitAndAudit": true,
		"Model": {
			"FInStockEntry": [{
				"FLot": {
					"FNumber": "111"
				},
				"FNote": "测试单据体备注1",
				"FRealQty": "10",
				"FSrcBillEntryID": "113928",
				"FGiveAway": false,
				"FProduceDate": "2021-06-13 00:00:00",
				"FExpiryDate": "2025-06-13 00:00:00"
			}, {
				"FLot": {
					"FNumber": "111"
				},
				"FNote": "测试单据体备注2",
				"FRealQty": "10",
				"FSrcBillEntryID": "113931",
				"FGiveAway": false,
				"FProduceDate": "2021-06-13 00:00:00",
				"FExpiryDate": "2025-06-13 00:00:00"
			}]
		}
	}]
}
```  
使用Postman等工具发送报文，需要将正式报文包含在{"parameters": []}中。  

**上方样例报文使用的场景：**  
用户在星空系统创建了一个采购收料通知单，当单据被审核之后，该单据的数据发送到了第三方系统（一般为仓库管理系统[WMS]）。当第三方系统的用户完成了这个单据的作业之后（一般为仓库收货入库），将上述报文发送到星空系统。那么插件将自动做如下操作：  
1. 自动从收料通知单下推采购入库单；  
2. 将批号、备注、实收数量等业务数据更新到下推的对应的分录明细中；  
3. 自动提交和审核该采购入库单。

#### 参数说明
**固定参数**  
LocalFormId 当前单据的FormId  
NextFormId 下游单据FormId  
RuleId 下推规则标识串  
NextQueryEntryKey 上下游单据查询标识串  
NextEntryKey 分录明细Key  
ActionName 动作名称  
IsAutoSubmitAndAudit 是否自动提交和审核  

固定参数用于指明单据的操作。  
***LocalFormId*** 和 ***NextFormId*** 是星空系统的单据ID，可以在BOS系统中查看。  
***RuleId*** 是星空系统单据下推规则，可以在BOS系统中查看。  
***NextQueryEntryKey*** 是单据关联关系表中FSTableName（源单表名）字段中的值（省略了前导 ***t_***）。  
***NextEntryKey*** 为单据明细属性Key。  
***ActionName*** 单据操作的动作名称，当前支持以下几种动作：  
1. **Push** 下推  
2. **Save** 保存（创建和更新）  
3. **Delete** 删除
4. **Audit** 审核
5. **UnAudit** 反审核
7. **PushAndUpdate** 下推并更新 

*备注说明*
- *创建和更新都可以使用 Save 动作。如果 Model 中没有设置 FID 或者 FBillNo 字段的值，则为创建单据，反之则为更新。更新单据时 FID 或者 FBillNo 必须填写一项，FSrcBillEntryID（明细内码）必填；*
- *使用 PushAndUpdate 动作时 固定参数NextQueryEntryKey必填。用于查找上下游单据的对应关系。*  

***IsAutoSubmitAndAudit*** 是否自动提交审核

**单据参数**  
***Modle*** 单据字段对象  
Model为单据参数集合，对应[官方文档](https://openapi.open.kingdee.com/ApiCenterDoc)中WebAPI接口中的**Model**，参数格式与要求与官方文档一致。

**特殊参数**  
***FSrcBillEntryID*** 源单分录明细内码。此参数主要用于需要指定明细内码的操作动作，例如：更新、下推等。对应FEntryID。

**说明**  
1. 本应用还不是很完善，支持的动作有限；  
2. 没有支持撤销接口，撤销接口金蝶云星空官方在20210422 PT 146874补丁及其以后的补丁中包含；  
3. 调用失败，数据回退支持不好。例如在连续动作下推->更新->提交->审核中，如果审核动作没有通过星空系统的校验，那么下推的单据无法被清理，需要手动处理，然后第三方系统再次发起请求。原因是在没有PT 146874补丁的系统，不支持撤销动作接口；  
4. 保存接口还不支持新增明细分录的功能，新增明细分录的功能将在增强版中提供支持；
5. 本项目完全开源，并且没有任何使用限制，可以商用。

### 支持我们
如果您觉得有价值或者对您的朋友会有帮助，那么就将本项目分享出去吧。  
我们也需要大家的支持

![输入图片说明](wechatQR.png)![输入图片说明](alipayQR.png)

### 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request