# MCS-Lite API for SPIL

## Table of Contents
[TOC]

## Introduction

All data will be communicated using [Socket.io](https://socket.io/) events. After every data modification the server needs to respond with the new data to keep the UI in realtime.

All responses should be broadcasted so ALL clients (except the sender) will receive the latest data and be displayed on the UI.

Responses should follow the guidelines below unless specified otherwise:

* Data created, modified and deleted from the payload
* Status of the payload
* The status code
* The status message
* IT SHOULD NOT contain any sensitive data, such as user's password

Example Response:

This response is for [user registration](#Registration), as you can see it is very similar to the payload however it doesn't contain the password.

{
  "status": {
    "code": 200,
    "message": "User successfully registered"
  },
  "data": {
    "username": "Aska",
    "group": "CIMEadminGROUP"
  }
}

## Queries

### eRack Settings History

> Event: `query settings erack`

Response:

[
  {
    "id": 1,
    "function": "create",
    "last_updated": "2020/12/25 11:10:47",
    "erackID": "E-RACK-001",
    "modified_data": "新增'erackID'='E-RACK-001'",
    "user": "Aska"
  },
  ...
]

### Stocker Settings History

> Event: `query settings stocker`

Response:

[
  {
    "id": 1,
    "function": "create",
    "last_updated": "2020/12/25 11:10:47",
    "stockerID": "STK01",
    "modified_data": "新增'stockerID'='STK01'",
    "user": "Aska"
  },
  ...
]

### AGV Settings History

> Event: `query settings agv`

Response:

[
  {
    "id": 1,
    "function": "create",
    "last_updated": "2020/12/25 11:10:47",
    "vehicleID": "MR-001",
    "modified_data": "新增'vehicleID'='MR-001'",
    "user": "Aska"
  },
  ...
]

### Port Settings History

> Event: `query settings port`

Response:

[
  {
    "id": 1,
    "function": "create",
    "last_updated": "2020/12/25 11:10:47",
    "portID": "K021LE_LP1",
    "modified_data": "新增'portID'='K021LE_LP1'",
    "user": "Aska"
  },
  ...
]

### Carrier Settings History

> Event: `query settings carrier`

Response:

[
  {
    "id": 1,
    "function": "create",
    "last_updated": "2020/12/25 11:10:47",
    "type": "MP",
    "modified_data": "新增'type'='MP'",
    "user": "Aska"
  },
  ...
]

## eRack Settings

### Create eRack

> Event: `erack create`

Payload:

{
  "erackID": "E-RACK-001",
  "slotNo": 24,
  "location": "CSC2FLE",
  "function": "待作業區",
  "lowest_water_level": 10,
  "highest_water_level": 90
}

* `lowest_water_level`: water level below this value will throw an alarm.
* `highest_water_level`: water level above this value will throw an alarm.

### Edit eRack

> Event: `erack edit`

Payload:

{
  "erackID": "E-RACK-001",
  "slotNo": 24,
  "location": "TESTING",
  "function": "待作業區",
  "lowest_water_level": 20,
  "highest_water_level": 80
}

### Delete eRack

> Event: `erack delete`

Payload:

{
  "erackID": "E-RACK-001"
}

## Stocker Settings

### Create Stocker

> Event: `stocker create`

Payload:

{
  "stockerID": "STK01",
  "slotNo": 125,
  "location": "CSC2FLE",
  "lowest_water_level": 10,
  "highest_water_level": 90,
}

* `lowest_water_level`: water level below this value will throw an alarm.
* `highest_water_level`: water level above this value will throw an alarm.

### Edit Stocker

> Event: `stocker edit`

Payload:

{
  "stockerID": "STK01",
  "slotNo": 125,
  "location": "TESTING",
  "lowest_water_level": 20,
  "highest_water_level": 60,
}

### Copy/Duplicate Stocker

> Event: `stocker copy`

Payload:

{
  "stockerID": "STK01",
  "slotNo": 125,
  "location": "CSC2FLE",
  "lowest_water_level": 10,
  "highest_water_level": 90,
}

### Delete Stocker

> Event: `stocker delete`

Payload:

{
  "stockerID": "STK01"
}

## AGV Settings (搬運設備設定)

### Create AGV

> Event: `agv create`

Payload:

{
  "id": 1,
  "vehicleID": "MR-001",
  "type": "MR",
  "location": "CSC2FLE",
  "magazine": "MAG",
  "capacity": 6,
  "auto_charge": 30,
  "transfer_area": "LE_S1",
  "charge_station": "ABC_001",
  "manufacturer": "捷螺"
}

### Edit AGV

> Event: `agv edit`

Payload:

{
  "id": 1,
  "vehicleID": "MR-001",
  "type": "MR",
  "location": "CSC2FLE",
  "magazine": "MAG",
  "capacity": 4,
  "auto_charge": 10,
  "transfer_area": "LE_F1",
  "charge_station": "DEF_001",
  "manufacturer": "捷螺"
}

### Delete AGV

> Event: `agv delete`

Payload:

{
  "vehicleID": "MR-001"
}

### AGV Tool Settings

> Event: `agv tool query`

Response:

{
  "location": "TESTING-2F",
  "EQPID": "MR-001",
  "battery_warning": 30,
  "longest_transfer_time": 30,
  "last_updated": "2020/12/25 11:44:30",
  "last_updated_by": "Aska"
}

## Port Settings

### Create Port

> Event: `port create`

Payload:

{
  "id": 1,
  "portID": "K02LE_LP1",
  "type": "EQP",
  "EQPID": "K021LE",
  "function": "loader",
  "location": "CSC2FLE"
}

### Edit Port

> Event: `port edit`

Payload:

{
  "id": 1,
  "portID": "K02LE_LP1",
  "type": "EQP",
  "EQPID": "K021LE",
  "function": "loader",
  "location": "TESTING"
}

### Delete Port

> Event: `port delete`

Payload:

{
  "portID": "K02LE_LP1",
}

## Carrier Settings

### Create Carrier

> Event: `carrier create`

Payload:

{
  "id": 1,
  "type": "MP",
  "name": "MAG",
  "location": "CSC2FLE",
  "remark": ""
}

### Edit Carrier

> Event: `carrier edit`

Payload:

{
  "id": 1,
  "type": "MP",
  "name": "MAGA",
  "location": "TESTING",
  "remark": "REMARK REMARK REMARK"
}

### Delete Carrier

> Event: `carrier delete`

Payload:

{
  "type": "MP"
}

## Authentication

### User

#### Get Users

> Event: `query users`

Response:

[
  {
    "username": "Aska",
    "group": "CIMEadminGROUP"
  }
]

#### Registration

> Event: `auth registration`

Payload:

{
  "username": "Aska",
  "group": "CIMEadminGROUP",
  "password": "this_is_password"
}

#### Check Username

> Event: `auth check username`

Payload:

{
  "username": "Aska",
}

#### Login

> Event: `auth login`

Payload:

{
  "username": "Aska",
  "password": "this_is_password"
}

Response:

{
  "status": {
    "code": 200,
    "message": "Success"
  },
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eSI6MSwiaWF0IjoxNDQ0OTE3NjQwLCJuYmYiOjE0NDQ5MTc2NDAsImV4cCI6MTQ0NDkxNzk0MH0.KPmI6WSjRjlpzecPvs3q_T3cJQvAgJvaQAPtk1abC_E"
  }
}

`token` is a `JSONWebToken` which should contain details of the user, this can be decoded in the frontend to allow user access to the system.

#### Edit User Details

> Event: `auth edit user`

Payload:

{
  "username": "Aska",
  "group": "CIMEadminGROUP",
  "current_password": "********",
  "password": "new_password"
}

**NOTE:** The data sent will only contain modified data. If the data wasn't modified then it will be left out.

#### Delete User

> Event: `auth delete user`

Payload:

{
  "username": "Aska"
}

### Group Settings

#### Group Keys

* Transfer List 看板: `transfer_list_page`
* 搬運設備狀態看板: `transfer_status_page`
* 事件警報alarm看板: `alarm_page`
* 手動修改搬運命令UI: `manual_transfer_edit_page`
* 儲存設備及接口定義: `define_erack_and_port`
* 載具定義: `define_carrier`
* 搬運設備定義: `define_transfer_equipment`
* Alarm管理定義: `define_alarm_management`
* 搬運路徑rule: `transfer_route_rule`
* 搬運順序rule: `transfer_order_rule`
* 管理使用權限: `user_permissions_management`

#### Group Values

* Admin
* Edit
* View

#### Create Group

> Event: `auth create group`

Payload:

{
  "name": "CIMEadminGROUP",
}

#### Delete Group

> Event: `auth delete group`

Payload:

{
  "name": "CIMEadminGROUP"
}

### Permission Settings

#### Create Permission

Create a new permission

> Event: `auth create permission`

{
  "key": "transfer_list_page",
  "name": "Transfer List 看板"
}

#### Edit Permission

Edit permissions to group permissions. The `permissions` key will contain all permissions that needs to be edited, so permissions will be edited accordingly.

> Event: `auth edit permission`

Payload:

[
  {
    "id": 1,
    "name": "Transfer List 看板",
    "permission": "admin"
  },
  {
    "id": 2,
    "name": "手動修改搬運命令UI",
    "permission": "edit"
  },
  {
    "id": 3,
    "name": "新權限",
    "permission": "view"
  }
]

#### Delete Permission

> Event: `auth delete permission`

Payload:

{
  "key": "transfer_list_page"
}

## Error

### Error Response

{
  "status": {
    "code": 604,
    "message": "Duplicate Group Name"
  },
  "data": {}
}

### Error Codes

Code | Description |
---- | --------------------------------------- |
600 | Username already exists |
601 | Incorrect Username/Password |
602 | Failed to edit user details |
603 | Failed to delete user |
604 | Duplicate Group Name |
605 | User does not exist |
606 | Current password does not match existing|