---
# System prepended metadata

title: 'DMS APP: API 規格書'

---

# DMS APP: API 規格書
## 功能代碼：DPA001
- 檢視全部碼頭狀態
- 檢視單一碼頭詳情
- 碼頭報到 (交貨開始)
- 碼頭報到 (交貨結束)

## API 規格

| 編號 | API                                                 | Method | 說明                                 |
| ---- | --------------------------------------------------- | ------ | ------------------------------------ |
| 1    | /wolverine/api/v1/DPA001/init                       | GET    | 畫面初始 API (包含各個 `optionList`) |
| 2    | /wolverine/api/v1/DPA001/query                      | POST   | 查詢碼頭總覽資訊                     |
| 3    | /wolverine/api/v1/DPA001/query/{dockNum}            | GET    | 查詢碼頭詳情                         |
| 4    | /wolverine/api/v1/DPA001/dock/status/{dockNum}      | PUT    | 更新碼頭狀態                         |
| 5    | /wolverine/api/v1/DPA001/dock/order/query/{dockNum} | POST   | 查詢碼頭單據 (報到用)                |
| 6    | /wolverine/api/v1/DPA001/dock/checkIn/{dockNum}     | POST   | 碼頭報到 (交貨開始)                  |
| 7    | /wolverine/api/v1/DPA001/dock/checkOut/{dockNum}    | POST   | 碼頭報到 (交貨結束)                  |

## 1. GET /wolverine/api/v1/DPA001/init
> 回傳畫面上呈現所需要的一些 `optionList`

### Request
>`N/A`

### Response
#### 參數說明
| 參數                           | 型態 | 說明           | 範例          |
| ------------------------------ | ---- | -------------- | ------------- |
| acceptedDockCategoryOptionList | list | 碼頭出入庫類型 | value & label |
| dockStatusOptionList           | list | 碼頭狀態       | value & label |
| dockUsageCategoryOptionList    | list | 單據出入庫類型 | value & label |
| dockOrderStatusOptionList      | list | 單據狀態       | value & label |

#### 範例
```json
{
    "result": {
        "acceptedDockCategoryOptionList" : [
            {
                "label": "出庫" ,
                "value": "2"
            },
            {
                "label": "入庫" ,
                "value": "1"
            },
            {
                "label": "入出庫" ,
                "value": "3"
            }
        ],
        "dockStatusOptionList": [
            {
                "label": "可用",
                "value": "1"
            },
            {
                "label": "不可用",  
                "value": "2"
            }
        ],
        "略"
    }
}
```



## 2. POST /wolverine/api/v1/DPA001/query
> 碼頭總覽查詢

### 說明
- Backend:
  - 碼頭查詢結果的排序依照　（由上到下）
    1. 依照 customDockNum
    2. 低樓層到高樓層

### Request
#### 參數說明
| 參數           | 型態   | 說明                              | 範例    |
| -------------- | ------ | --------------------------------- | ------- |
| comNum         | number | 使用者所選的公司編號              | 1       |
| customDockName | string | 使用者想查詢的碼頭名稱 (模糊查詢) | "碼頭1" |

#### 範例
```json
{
    "comNum": 1,
    "customDockName": "碼頭"
}
```
```json
{
    "comNum": 3
}
```

### Response
#### 參數說明
| 參數                 | 型態   | 說明                               | 範例              |
| -------------------- | ------ | ---------------------------------- | ----------------- |
| dockNum              | number | 碼頭編號 (unique) (N/A)            | `1`               |
| contractDetailNum    | number | 客戶對應該碼頭的合約細節編號 (N/A) | `23`              |
| customDockName       | string | 客戶對應該碼頭的顯示名稱 (label)   | `"1 - 1F"`        |
| acceptedDockCategory | string | 碼頭出入庫類型 (value)             | `"2"`             |
| isSpecificDock       | string | 是否為專用碼頭 (value)             | `true` or `false` |
| dockStatus           | string | 碼頭狀態 (value)                   | `"2"`             |
| subStatusDo          | object | 子狀態的物件 (obj)                 | `N/A`             |
| subStatusType        | string | 子狀態的類型 (value)               | `1`               |
| subStatusTime        | string | 子狀態的時間描述 (label)           | `41` or `10:00`   |

> - unique: 唯一值。
> - N/A: 不用顯示。
> - label: 可以直接顯示回傳值。
> - value: 要從 /init 回傳的 `optionList` 裡面讀取對應的 `label` 顯示。
> - obj: 一個物件，裡面會包含其他參數。

#### 範例
```json
{
    "result": [
        {
            "dockNum": 1,
            "contractDetailNum": 1,
            "customDockName": "1-1F",
            "acceptedDockCategory": "2",
            "isSpecificDock": true,
            "dockStatus": "1",
            "subStatusDo": {
                "substatusType": "1",
                "subStatusTime": "10:00",
            }
        },
        {
            "dockNum": 2,
            "contractDetailNum": 2,
            "customDockName": "2-1F",
            "acceptedDockCategory": "1",
            "isSpecificDock": false,
            "dockStatus": "2",
            "subStatusDo": {
                "substatusType": "2",
                "subStatusTime": "41",
            }
        }
    ],
    "status": "ok"
}
```




## 3. GET /wolverine/api/v1/DPA001/query/{dockNum}
> 查詢碼頭狀態詳情

### 說明
- Backend:
  - 單據查詢結果的排序依照　（由上到下）
    1. 預計交貨時間的 start time 由早到晚


### Request
#### 參數說明
| 參數    | 型態   | 說明     | 範例 |
| ------- | ------ | -------- | ---- |
| dockNum | number | 碼頭編號 | 1    |

#### 範例
```
/wolverine/api/v1/DPA001/query/2
/wolverine/api/v1/DPA001/query/3
/wolverine/api/v1/DPA001/query/46
```

### Response
#### 參數說明
| 參數                     | 型態    | 說明                               | 範例                |
| ------------------------ | ------- | ---------------------------------- | ------------------- |
| dockNum                  | number  | 碼頭編號 (unique) (N/A)            | `1`                 |
| contractDetailNum        | number  | 客戶對應該碼頭的合約細節編號 (N/A) | `23`                |
| customDockName           | string  | 客戶對應該碼頭的顯示名稱 (label)   | `"1 - 1F"`          |
| acceptedDockCategory     | string  | 碼頭出入庫類型 (value)             | `"2"`               |
| isSpecificDock           | boolean | 是否為專用碼頭 (N/A)               | `true` or `false`   |
| dockStatus               | string  | 碼頭狀態 (N/A)                     | `"2"`               |
| subStatusDo              | object  | 子狀態的物件 (obj)                 | `N/A`               |
| subStatusType            | string  | 子狀態的類型 (N/A)                 | `"1"`               |
| subStatusTime            | string  | 子狀態的時間描述 (N/A)             | `"41"` or `"10:00"` |
| onGoingOrderList         | list    | 進行中的單據清單 (N/A)             | `N/A`               |
| upComingOrderList        | list    | 即將到來的單據清單 (N/A)           | `N/A`               |
| reservationCode          | string  | 單號 (label)                       | `"2212260000004"`   |
| dockUsageCategory        | string  | 單據出入庫類型 (value)             | `"1"`               |
| dockOrderStatus          | string  | 單據狀態 (value)                   | `"2"`               |
| expectedUsagePeriodStart | string  | 單據預期使用時段 (開始) (label)    | `"10:00"`           |
| expectedUsagePeriodEnd   | string  | 單據預期使用時段 (開始) (label)    | `"11:00"`           |
| expectedUsagePeriodGap   | number  | 單據預期使用時段長度 (label)       | `60`                |
| supplierComName          | string  | 供應商公司名稱 (label)             | `"義美食品"`        |
| carrierComName           | string  | 承運商公司名稱 (label)             | `"新竹物流"`        |
| driverName               | string  | 司機姓名 (label)                   | `"賈苡秉"`          |
| licensePlateNo           | string  | 車牌號碼 (label)                   | `ETH2323`           |

> - unique: 唯一值。
> - N/A: 不用顯示。
> - label: 可以直接顯示回傳值。
> - value: 要從 /init 回傳的 `optionList` 裡面讀取對應的 `label` 顯示。
> - obj: 一個物件，裡面會包含其他參數。
#### 範例
```json
{
    "result": [
        {
            "dockNum": 1,
            "contractDetailNum": 1,
            "customDockName": "1-1F",
            "acceptedDockCategory": "2",
            "isSpecificDock": true,
            "dockStatus": "1",
            "subStatusDo": {
                "substatusType": "1",
                "subStatusTime": "10:00",
            },
            "onGoingOrderList": [
                {
                    "reservationCode": "221114000007",
                    "dockUsageCategory": "1",
                    "dockOrderStatus": "2",
                    "expectedUsagePeriodStart": "10:00",
                    "expectedUsagePeriodEnd": "11:00",
                    "expectedUsagePeriodGap": 60,
                    "supplierComName": "義美食品",
                    "carrierComName": "新竹物流",
                    "driverName": "賈苡秉",
                    "licensePlateNo": "ETH2323"
                }
            ],
            "upComingOrderList": [
                {
                    "reservationCode": "221114000008",
                    "dockUsageCategory": "1",
                    "dockOrderStatus": "2",
                    "expectedUsagePeriodStart": "11:00",
                    "expectedUsagePeriodEnd": "11:30",
                    "expectedUsagePeriodGap": 30,
                    "supplierComName": "義美食品",
                    "carrierComName": "新竹物流",
                    "driverName": "賈苡秉",
                    "licensePlateNo": "ETH5656"
                },
                {
                    "reservationCode": "221114000009",
                    "dockUsageCategory": "2",
                    "dockOrderStatus": "1",
                    "expectedUsagePeriodStart": "11:30",
                    "expectedUsagePeriodEnd": "12:00",
                    "expectedUsagePeriodGap": 30,
                    "supplierComName": "義美食品",
                    "carrierComName": "新竹物流",
                    "driverName": "賈苡秉",
                    "licensePlateNo": "ETH7878"
                }
            ],
        }
    ],
    "status": "ok"
}
```

## 4. PUT /wolverine/api/v1/DPA001/dockStatus/{dockNum}
> 更新碼頭狀態

### Request
#### 參數說明
| 參數                 | 型態   | 說明               | 範例  |
| -------------------- | ------ | ------------------ | ----- |
| dockAvailableType    | string | 實體碼頭可用狀態   | `"1"` |
| dockAvailableSubType | string | 實體碼頭可用子狀態 | `"2"` |

#### 範例
````json
{
    "dockAvailableType": "2",
    "dockAvailableSubType": "1"
}
````

### Response
#### Success
```json
{
    "status": "ok"
}
```

#### Fail
> 依照現存的業務邏輯

## 5. POST /wolverine/api/v1/DPA001/dock/order/query/{dockNum}
> 查詢碼頭單據 (車牌報到用)

### Request
#### 參數說明
| 參數           | 型態   | 說明     | 範例        |
| -------------- | ------ | -------- | ----------- |
| licensePlateNo | string | 車牌號碼 | `"ETH2323"` |

#### 範例
```json
{
    "licensePlateNo": "ETH2323"
}
```

### Response
#### 參數說明
| 參數                     | 型態   | 說明                            | 範例              |
| ------------------------ | ------ | ------------------------------- | ----------------- |
| reservationCode          | string | 單號 (label)                    | `"2212260000004"` |
| dockUsageCategory        | string | 單據出入庫類型 (value)          | `"1"`             |
| dockOrderStatus          | string | 單據狀態 (value)                | `"2"`             |
| expectedUsagePeriodStart | string | 單據預期使用時段 (開始) (label) | `"10:00"`         |
| expectedUsagePeriodEnd   | string | 單據預期使用時段 (開始) (label) | `"11:00"`         |
| expectedUsagePeriodGap   | number | 單據預期使用時段長度 (label)    | `60`              |
| supplierComName          | string | 供應商公司名稱 (label)          | `"義美食品"`      |
| carrierComName           | string | 承運商公司名稱 (label)          | `"新竹物流"`      |
| driverName               | string | 司機姓名 (label)                | `"賈苡秉"`        |
| licensePlateNo           | string | 車牌號碼 (label)                | `ETH2323`         |

#### 範例
```json
{
    "result": [
        {
            "reservationCode": "221114000008",
            "dockUsageCategory": "1",
            "dockOrderStatus": "2",
            "expectedUsagePeriodStart": "11:00",
            "expectedUsagePeriodEnd": "11:30",
            "expectedUsagePeriodGap": 30,
            "supplierComName": "義美食品",
            "carrierComName": "新竹物流",
            "driverName": "賈苡秉",
            "licensePlateNo": "ETH5656"
        }
    ],
    "status": "ok"
}
```





## 6. POST /wolverine/api/v1/DPA001/dock/checkIn/{dockNum}
> 碼頭報到

### 說明
- 不管專用還是一般碼頭，都是 call 同一個 api，後端可以自己判斷這個碼頭是不是專用碼頭。
- `isForceCheckIn` 預設為 `false`。
- 如果 `hasAlert` 為 `true`，要顯示提示訊息 (`alertMsg`)，當使用者點選`確定`，即可強制報到 (`isForceCheckIn = true`)。

### Request
#### 參數說明
| 參數            | 型態   | 說明         | 範例              |
| --------------- | ------ | ------------ | ----------------- |
| reservationCode | string | 單號         | `"2211050000006"` |
| isForceCheckIn  | string | 是否強制報到 | `true` or `false` |

#### 範例
```json
{
    "reservationCode": "221105000006",
    "isForceCheckIn": true
}
```

### Response
#### 參數說明
| 參數            | 型態    | 說明           | 範例                                                   |
| --------------- | ------- | -------------- | ------------------------------------------------------ |
| hasAlert        | boolean | 是否有提示訊息 | `true` or `false`                                      |
| reservationCode | string  | 單號           | `"2211070000006"`                                      |
| alertMsg        | string  | 提示訊息       | `"原預計交貨單據為 XXX，要改為報到專用碼頭單 AAA 嗎?"` |

#### 範例
會有以下幾種情況
- 成功
- 失敗
  - 既有的失敗訊息 (必填沒填 or unauthorized or 業務邏輯檢核錯誤)
  - 特殊業務邏輯檢核 (判斷 `hasAlert` 為 `true`)
    - 確認要報到專用碼頭單?
    - 原預計交貨單據是XXX，要改為報到專用碼頭單?

> 成功
> ```json
> {
>     "result": {
>         "hasAlert": false,
>         "reservationCode": "2211010000007"
>     },
>     "status": "ok",
> }
> ```

> 失敗 (既有的失敗訊息)
> ```json
> {
>     "errors": [
>         {
>             "code": "com.alp.dp.a0.controller.v1.DpA001",
>             "message": "[單號]不得為空白!"
>         }
>     ],
>     "status": "fail"
> }
> ```

> 失敗 (特殊業務邏輯檢核)
> ```json
> {
>     "result": {
>         "hasAlert": true,
>         "alertMsg": "原預計交貨單據為 XXX，要改為報到專用碼頭單 AAA 嗎?"
>     },
>     "status": "ok"
> }
> ```

## 7. PUT /wolverine/api/v1/DPA001/dock/checkOut/{dockNum}
> 碼頭報到 (交貨結束)

### Request
#### 參數說明
| 參數            | 型態   | 說明 | 範例              |
| --------------- | ------ | ---- | ----------------- |
| reservationCode | string | 單號 | `"2210040000004"` |

#### 範例
```json
{
    "reservationCode": "2210040000004"
}
```

### Response
#### Success
```json
{
    "status": "ok"
}
```

#### Fail
> 依照現存的業務邏輯



