# Warehouse Project

## Get Started

仓储平台通过Http协议对外提供服务，开发者可以使用Http请求进行相应的仓库操作，也可以使用封装的SDK与仓储平台进行数据交互。由于签名算法暂时没有对外开放 jar，推荐使用已封装的SDK作为首选方式。

### Step 1. Apply for app key

仓储平台开发者网站，暂未开通，执行 `git clone ssh://dev@10.10.101.21/source/warehouse.git` 下载项目到本地, 启动项目 `warehouse-online-app` 进行企业用户或仓储提供商的 `app key` 注册，注册成功后并保存生成的 `app key` 和 `secret key`。

### Step 2. Create maven project 

使用IDE创建一个Maven项目，当然也可以使用普通的Java项目，但在生产环境不利于依赖的管理，不推荐手动进行依赖管理和项目构建。

### Step 3. Add sdk dependencies

在使用仓储平台之前，需要下载依赖  warehouse-uas-sdk 和 warehouse-common 两个依赖。

```xml
<!-- Maven -->
<dependencies>
  <dependency>
    <groupId>com.uas.platform.warehouse</groupId>
    <artifactId>warehouse-uas-sdk</artifactId>
    <version>0.1.2-SNAPSHOT</version>
  </dependency>
  <dependency>
    <groupId>com.uas.platform.warehouse</groupId>
    <artifactId>warehouse-common</artifactId>
    <version>0.1.2-SNAPSHOT</version>
  </dependency>
</dependencies>
```

### Step 4. Write a sample demo 

创建一个供企业用户使用的客户端，发起发货操作，并获取仓储服务商的发货回传信息。

```java
// Create a client
String endpoint = "192.168.253.31:20300";
String appKey = "0677881a1d5a48dfa3a1e32a7b65e7a5";
String secretKey = "6E8958941CB53DC48D7B32F4E7DD57C67E54B8FD";
Warehouse client = new Warehouse(endpoint, appKey, secretKey);

// Create Shipment instance, and set data to this instance
Shipment shipment = new Shipment();
// ...

String result = client.shipFromWarehouse("深圳新宁仓", shipment);
System.out.println("Ship Status: " + result);

List<ShipmentReply> replies = client.gainShipReplyNotice();
System.out.println("Reply Notice: " + replies);
```

启动程序，发送出货单通知到仓储提供商，供仓储提供商进行出库操作，并获取仓储提供商已经处理完成的出库回传信息。

## Introduction

仓储平台由 `warehouse-common` 、`warehouse-backend-app` 、`warehouse-uas-sdk` 、 `warehouse-transport` 四部分组成。

- warehouse-common，提供通用的工具类、数据传输对象以及统一的响应数据格式
- warehouse-backend-app，承担仓储平台提供服务的功能
- warehouse-uas-sdk，仓储平台服务访问客户端，分别为企业用户和仓储提供商提供仓储操作的方法
- warehouse-transport, 仓储平台传输层，负责企业用户与平台、平台与仓储提供商之间的数据传输

## Extend

仓储平台的每一条通知数据和回传数据都存储在对应的数据库表一条记录中，通过记录的单据类型字段加以区分。由于传入仓储平台的数据在反序列化时无法使用抽象类进行对象的创建，而用户拉取的数据在序列化时可以将抽象对象正确的序列化，因而，仓储平台的数据上传操作，如企业用户发起通知、仓储提供商上传操作回传信息，都需要指定完整的数据格式，向仓储平台上传数据的操作在扩展仓储平台功能时，需要被实现。

### Step 1. Git clone warehouse project

```shell
git clone ssh://dev@10.10.101.21/source/warehouse.git
```

### Step 2. Create Data Transfer Object class

在 `warehouse-common` 项目 `domain` 包下创建一个对应仓储回传的 `package` ，分别创建如下数据传输对象，以出货操作为例：

-  ShipCommon，提供出货通知和出货回传两个数据传输对象公共的方法和常量
-  ShipmentReply，保存仓储提供商处理收到的出货通知后的回传结果

在 `warehouse-uas-sdk` 项目 `domain` 包下创建一个对应业务单据的实体类以及明细类，创建对象如下：

- Shipment，保存企业用户发起出货通知时所需的数据信息，如单据编号等
- ShipmentDetail，保存出货通知中明细的信息，可选，根据具体需要决定是否创建

### Step 3. Create persistence entity class

避免业务数据结构的暴露，因此，在 `warehouse-backend-app` 项目中参考上述数据传输对象创建持久化对象，以及 DAO 接口类。持久化对象需要配置数据库映射信息，DAO 如何使用和方法命名规范请参考 spring-data-jpa 文档。

### Step 4. Create business service

创建仓储操作的数据存储业务逻辑，包含企业用户发起通知的数据和仓储提供商回传数据的仓储逻辑。`warehouse-backend-app` 项目下 `service` 包中创建对应业务单据的服务接口类以及实现类，然后在 `NotificationService` 中提供单据处理回传的业务方法实现。

### Step 5. Expose related http interface

`com.uas.platform.warehouse.backend.api.NotificationController` 中创建企业用户发起操作的接口和仓储提供商回传操作结果的接口，并调用相应的业务类执行业务操作。

### Step 6. Encapsulate http request

企业用户和仓储提供商的仓储操作封装在 `Warehouse` 和 `WarehouseProvider` 两个客户端类中，每个仓储操作都要在对应的客户端类中实现数据上传和数据获取的方法。

Author: huxz
Mail: huxz@usoftchina.com