# 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 |

#### 範例

{
    "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" |

#### 範例

{
    "comNum": 1,
    "customDockName": "碼頭"
}

{
    "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: 一個物件，裡面會包含其他參數。

#### 範例

{
    "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: 一個物件，裡面會包含其他參數。
#### 範例

{
    "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"` |

#### 範例

{
    "dockAvailableType": "2",
    "dockAvailableSubType": "1"
}

### Response
#### Success

{
    "status": "ok"
}

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

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

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

#### 範例

{
    "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` |

#### 範例

{
    "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` |

#### 範例

{
    "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"` |

#### 範例

{
    "reservationCode": "2210040000004"
}

### Response
#### Success

{
    "status": "ok"
}

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