# 限時取餐 Meal Time - API 文件

## URL Path Documentation

### Root Path: `http://meal-time-api.herokuapp.com`

所有 api 區分成六個類別：
* /users
* /vendors
* /products
* /orders
* /messages
* /faqs

### [使用者 User](#User)

- `page` 頁數，預設為 1
- `limit` 查詢筆數
- `sort` 依...排序，預設為 'id'
- `order` 正序/反序，預設為 'DESC'，另可輸入 'ASC'

| 說明 | Method | Path | 權限驗證 |
| -------------------- | ----- | ------------------- | ------- |
| 註冊使用者 | POST | /users/register | 無 |
| 登入使用者 | POST | /users/login | 無 |
| 取得自己的使用者資料 | GET | /users/profile/me | 會員 |
| 修改自己的使用者資料 | PATCH | /usersprofile/me | 會員 |
| 修改自己的密碼 | PATCH | /users/password | 會員 |
| 取得單一使用者資料 | GET | /users/profile/:id | 管理員 |
| 修改單一使用者資料 | PATCH | /users/profile/:id | 管理員 |
| 取得所有使用者資料 | GET | /users/profile | 管理員 |
| 更改使用者權限 | PATCH | /users/auth/:id | 管理員 |

### [賣家 Vender](#Vendor)

| 說明 | Method | Path | 權限驗證 |
| ----------------- | ------ | ------------------ | ------- |
| 註冊賣家 | POST | /vendors/register | 會員 |
| 取得自己的賣家資料 | GET | /vendors/profile/me | 賣家 |
| 修改自己的賣家資料 | PATCH | /vendors/profile/me | 賣家 |
| 取得有效單一賣家資料 | GET | /vendors/profile/:id| 無 |
| 取得單一賣家資料 | GET | /vendors/admin/profile/:id| 管理員 |
| 取得所有有效賣家資料 | GET | /vendors/profile | 無 |
| 取得所有賣家資料 | GET | /vendors/admin/profile | 管理員 |
| 修改單一賣家資料 | PATCH | /vendors/profile/:id| 管理員 |
| 修改自己的營業狀態 | PATCH | /vendors/set-open | 賣家 |
| 修改單一賣家權限 | PATCH | /vendors/auth/:id | 管理員 |

### [賣場分類 Vendor Category](#Vendor-Category)

| 說明 | Method | Path | 權限驗證 |
| ---------------- | ------ | -------------- | ------- |
| 取得所有賣場分類 | GET | /vendor-categories | 無 |
| 取得單一賣場分類 | GET | /vendor-categories/:id | 管理員 |
| 新增賣場分類 | POST | /vendor-categories | 管理員 |
| 編輯賣場分類 | PATCH | /vendor-categories/:id | 管理員 |
| 刪除賣場分類 | DELETE | /vendor-categories/:id | 管理員 |

### [產品分類 Product Category](#Category)

| 說明 | Method | Path | 權限驗證 |
| ---------------- | ------ | -------------- | ------- |
| 取得所有賣場分類 | GET | /products-categories | 無 |
| 新增賣場分類 | POST | /products-categories | 管理員 |
| 編輯賣場分類 | PATCH | /products-categories/:id | 管理員 |
| 刪除賣場分類 | DELETE | /products-categories/:id | 管理員 |

### [產品 Product](#Product)

「取得分頁商品」、「取得該分類商品」、「取得該賣家商品」、「取得搜尋商品結果」可加入以下 query string 參數：
- `page` 頁數，預設為 1
- `limit` 查詢筆數，預設為 10
- `sort` 依...排序，預設為 'id'，另可輸入 'price'、'quantity'、'manufactureDate'、'expiryDate'
- `order` 正序/反序，預設為 'DESC'，另可輸入 'ASC'
- `keyword` 搜尋關鍵字（僅限取得搜尋商品結果）
- `category` 篩選分類，可輸入分類 id
- `notSupplied` 是否篩選掉過期與售罄的商品，參數 'true' 為檢視，預設為不檢視
- `filter` 賣家管理商品可帶此參數，可輸入 'all'、'available '、'unavailable'、'expiry'、'soldOut'，預設為 'all'
+ 'all' 全部商品
+ 'available' 供應中商品（不包含過期與完售）
+ 'unavailable' 未供應
+ 'expiry' 過期商品（包含過期且完售）
+ 'soldOut' 完售商品（包含過期且完售）

| 說明 | Method | Path | 權限驗證 |
| -------------------- | ------ | ---------------------- |:-------- |
| 取得分頁商品 | GET | /products | 無 |
| 取得該分類商品 | GET | /products/category/:id | 無 |
| 取得該賣家商品 | GET | /products/vendor/:id | 無 |
| 取得搜尋商品結果 | GET | /products/search | 無 |
| 取得單ㄧ商品詳細資料 | GET | /products/:id | 無 |
| 新增商品 | POST | /products/ | 賣家 |
| 編輯商品 | PATCH | /products/:id | 賣家 |
| 刪除商品 | DELETE | /products/:id | 賣家 |
| 取得賣家管理商品列表 | GET | /products/vendor/manage/:id | 賣家 |
| 取得購物車資料 | POST | /cart | 無 |

### [訂單 Order](#Order)
「取得訂單列表」、「取得自己買的訂單列表」、「取得自己賣的訂單列表」可加入以下 query string 參數：
- `page` 頁數，預設為 1
- `limit` 查詢筆數，預設為 10
- `sort` 依...排序，預設為 'id'，另可輸入 'totalPrice'、'totalQuantity'
- `order` 正序/反序，預設為 'DESC'，另可輸入 'ASC'
- `status` 已完成 'completed'、未完成 'uncompleted'、已取消 'canceled'，預設為所有
- `clientId` 依 id 查詢買家所買的商品（限「取得自己買的訂單列表」且身分為管理員）
- `vendorId` 依 id 查詢賣家所賣的商品（限「取得自己賣的訂單列表」且身分為管理員）

| 說明 | Method | Path | 權限驗證 |
| -------------------- | ------ | -------------------- | --- |
| 取得訂單列表 | GET | /orders | 管理員 |
| 取得自己買的訂單列表 | GET | /orders/buy | 會員 |
| 取得自己賣的訂單列表 | GET | /orders/sell | 賣家 |
| 取得單一訂單明細 | GET | /orders/:id | 會員 |
| 成立訂單 | POST | /orders | 會員 |
| 訂單完成 | PATCH | /orders/complete/:id | 會員 |
| 訂單取消 | PATCH | /orders/cancel/:id | 會員 |
| 刪除訂單 | DELETE | /orders/:id | 管理員 |

### [訊息 Message](#Message)

| 說明 | Method | Path | 權限驗證 |
| ---------------------- | ----- | ---------------------------- | ------- |
| 使用者取得所有與賣家的訊息 | GET | /messages/user | 會員 |
| 使用者取得與單一賣家的訊息 | GET | /messages/user/:id | 會員 |
| 賣家取得所有與使用者的訊息 | GET | /messages/vendor | 賣家 |
| 賣家取得與單一使用者的訊息 | GET | /messages/vendor/:id | 賣家 |
| 使用者向賣家傳送訊息 | POST | /messages/user/:id | 會員 |
| 賣家向使用者傳送訊息 | POST | /messages/vendor/:id | 賣家 |
| 使用者取得與管理員的訊息 | GET | /messages-to-admin | 會員 |
| 使用者向管理員傳送訊息 | POST | /messages-to-admin | 會員 |
| 管理員取得所有與使用者的訊息 | GET | /messages-to-admin/admin | 管理員 |
| 管理員取得與單一使用者的訊息 | GET | /messages-to-admin/admin/:id | 管理員 |
| 管理員向使用者傳送訊息 | POST | /messages-to-admin/admin/:id | 管理員 |
| 使用者向管理員傳送檢舉訊息 | POST | /report-messages | 會員 |
| 管理員取得所有檢舉訊息 | GET | /report-messages/admin | 管理員 |
| 管理員取得單一檢舉訊息 | GET | /report-messages/admin/:id | 管理員 |

### [常見問題 FAQ](#FAQ)

| 說明 | Method | Path | 權限驗證 |
| ---------------- | ------ | ----------------- | ------- |
| 取得所有常見問題 | GET | /faqs | 無 |
| 取得單一常見問題 | GET | /faqs/:id | 管理員 |
| 新增常見問題 | POST | /faqs | 管理員 |
| 編輯常見問題 | PATCH | /faqs/:id | 管理員 |
| 刪除常見問題 | DELETE | /faqs/:id | 管理員 |

### [常見問題分類 FAQ Category](#FAQ-Category)

| 說明 | Method | Path | 權限驗證 |
| ---------------- | ------ | -------------- | ------- |
| 取得所有問題分類 | GET | /faq-categories | 無 |
| 取得單一問題分類 | GET | /faq-categories/:id | 管理員 |
| 新增問題分類 | POST | /faq-categories | 管理員 |
| 編輯問題分類 | PATCH | /faq-categories/:id | 管理員 |
| 刪除問題分類 | DELETE | /faq-categories/:id | 管理員 |

## API Details & Examples

需要身份驗證的 API，使用者登入後會拿到一組 toke, 需在 headers 帶上 token： `Authorization: 'Bearer <token>'`。

> 若註冊成賣家後會再拿到另一組更新 vendorId 的 token，需要更新 headers。

需要上傳圖片的 API，data 需以 `FormData` 格式傳入：

fetch(url, {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>'
  },
  body: formData
})

其餘則以 `JSON` 格式，要帶上 content-type。例：

fetch(url, {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'content-type': 'application/json'
  },
  body: JSON.stringify({
    username,
    password,
  })
})

### [User](https://hackmd.io/@meal-time/Bk6t9GVVK)
### [Vendor](https://hackmd.io/@meal-time/HJmWsf4Vt)
### [Vendor-Category](https://hackmd.io/@meal-time/Sk-4nMNVt)
### [Product-Category](https://hackmd.io/@meal-time/Hk0f-8rNF)
### [Product](https://hackmd.io/@meal-time/BJjwILHEF)
### [Order](https://hackmd.io/@meal-time/ry9a8IS4t)
### [Message](https://hackmd.io/@meal-time/rJyYnMN4t)
### [FAQ](https://hackmd.io/@meal-time/SJ_4TGN4Y)
### [FAQ-Category](https://hackmd.io/@meal-time/HkG2pz44F)