# 還有口罩嗎？ Mask Help Info

:::info
🔜 健保署維護、預計 2/6 上線的新制後端，請參考[口罩供需資訊平台（開發共筆）](https://g0v.hackmd.io/gGrOI4_aTsmpoMfLP1OU4A)
:::

----
## API Base Url: https://api.maskhelp.info
## API Doc: https://api.maskhelp.info/swagger-ui.html

---
:::info
[Toc]
:::

## 緣起：

(https://www.facebook.com/chencj/photos/a.940830375997785/2707919482622190/?type=3&theater)

大家好，因為口罩物資店家的資訊不夠明確，所以我們蒐集了跟經濟部有合作的各大藥局店家以及四大超商的資訊。

我跟好友 John Lin, Jimmy Hsu 合作一晚，生出來的API，可以用來記錄店家是否還有口罩販賣，

目前 API跟API 文件已經ＯＫ了，如果有需要的話可以直接取用。

我們會陸續把店家資訊補完的XD

比我們早先一步完成 https://mask.goodideas-studio.com/ 的 Chan Wei Wu
因為 google place 費用的關係，目前也開始改接這邊的API了 (剛剛有確認過因為我們取得超商資料集有名稱辨認的問題，他先使用原本自己的API)

希望各前端好友們拿去實作各種前端應用出來吧 >///<

API 有關的需求或是問題可以在 [mask-help-info-api issues](https://github.com/WJWang/mask-help-info-api/issues) 這邊開 issue ， API 的 source code 的關係因為我們趕著上線，目前用的是 internal 的 CD Flow, 我們會在找時間把 source code open 出來。

## 目標：蒐集全國販售口罩的地點，讓全民共同編輯販售口罩的資訊與回報是否店家還有貨。

## 目前使用這個 API 的服務(歡迎自行新增)：
- https://mask.goodideas-studio.com/ - by Chan Wei Wu
- [LINE Chatbot](https://line.me/ti/p/@592zrdyn) - by Eric Wu
- [LINE Chatbot](https://lin.ee/4nIuWCB) - by Ian Chen

-
## 主要
- 提供使用者以Loaction（經緯度）方式搜尋周圍有販售口罩的商家，以及口罩狀態與最後更新時間
- 提供使用者用地區Filter(eg. 台北市 中正區)周圍販售口罩的商家，以及口罩狀態與最後更新時間
- 提供使用者對店家販售狀態的變更口罩販售狀態(尚未有人回報 / 已賣完 / 有存貨)
- 目前讓使用者對「醫療級成人口罩」與「醫療級兒童口罩」 進行販售狀態的變更

## 使用方式:

參考 SwaggerUI 中的 Try It Out 點擊後可以按下 execution 看看資料結構跟 response

Swagger API 文件會跟著實作更新，原則上不會有不同步的問題。


## 呈現方式：提供 API Service 呈現方式不拘，可以用 App, Web, Chatbot...方式呈現
(Web client 的部分我們沒有擋CORS所以可以直接戳得到資訊)

## 資料來源：藥妝 / 超商店資料（待整理與格式轉換）：

- [原始資料似乎有誤，需重新驗證] 全國4大超商資料集：
- 原始資料來源：https://data.gcis.nat.gov.tw/od/detail?oid=0202BFA9-8116-4E63-A41A-58A5F4EAF7A2
- [整理完成資料，目前約17000筆] https://drive.google.com/open?id=1S_R1uNvIA7s6-G9DGmTgALCgwcLo7rAt

- [已完成] 康是美
- 原始資料來源389家：https://www.cosmed.com.tw/shop.aspx
- [已完成資料的CSV] https://drive.google.com/file/d/1Fx_V6EpEbyvq0x6nPwqi8MX3jatxa963/view?usp=sharing

- [已完成] 躍獅：
- 原始資料來源：http://www.yeschain.com.tw/stores.php?token=8ff6a8d03db2b8be9bcead847c0e5c0dd4ed7542f40861eed5fa1bbd52c073e9&city=&dist=&road=
- [已完成資料的CSV] https://drive.google.com/open?id=1ZNEuiGdSTTa1Lh0VE7aZTnpfe346zWv3

- [已完成] 佑全
- 原始資料來源：http://www.yourchance.com.tw/index.php?option=module&lang=cht&task=showlist&id=1&index=1
- [已完成資料的CSV] https://drive.google.com/open?id=1LYh3pfqxKXJicEAKCO5QRoW_tRJyzdI2

- [已完成] 杏一：
- 原始資料來源：https://event.medfirst.com.tw/StoreMap/Storelist.aspx
- [已完成資料的CSV]https://drive.google.com/open?id=1cNwgs9SLirdCDlXX5-AjHN6OYL_5XEFG

- [已完成] 屈臣氏：
- 原始資料來源：https://www.watsons.com.tw/store-finder
- [已完成資料的CSV(無gmPlaceID)]https://drive.google.com/open?id=18K9Jj9juuoDFkIDLIRtOqt2lVP7WS6_-
- 591家

- [整理中]維康：
- 原始資料來源：http://www.wellcare.com.tw/wellindex/03map.htm
- Map : https://www.google.com/maps/d/u/0/embed?mid=14FPBM32S2JBxulNqdHLAjkQHUNTZc_PY&ll=24.460198257194154%2C121.23721962135278&z=8
- http://www.wellcare.com.tw/wellindex/new-map/page/
- crawler
- embedded google map iframee -> get lat,lon directly

## ER 資料模型

* Supply

| CSV? | Column | Desc | Type | 範例值 |
| -------- | -------- | -------- | -------- | -------- |
| | id | ID | integer | 1 |
| V(必要) | category | 地點分類 (統一超商/全家/萊爾富/OK超商/康是美/屈臣氏/耀獅/杏一/佑全/維康) | varchar(16) | 統一超商 |
| V(必要) | lat | 緯度 | double | 25.0058474947871 |
| V(必要) | lng | 經度 | double | 121.498648801987 |
| V(非必要) | gm_place_id | Google Places API 的 Place ID (想說前端若要呈現詳細資料時，可以透過place api 來撈)
| V(必要) | city | 縣市 | varchar(32) | 台北市 |
| V(必要) | area | 區 | varchar(64) | 大安區 |
| V(必要) | address | 原始地址 | varchar(512) | xxxx |
| | coord | 經緯投影座標 | geometry(Point,4326) | SRID=4326;POINT(121.498648801987 25.0058474947871) |
| V(必要) | name | 公司名/店名 | varchar(64) | |
| | mask_status | 醫療口罩狀態 (UNKNOWN / AVAILABLE / SHORTAGE) | enum | | AVAILABLE |
| | children_mask_status | 兒童醫療口罩狀態 (UNKNOWN / AVAILABLE / SHORTAGE) | enum | AVAILABLE |
| | updated_time | 最後更新時間 | timestamp with time zone | 2017-04-11 08:06:07.977+00 |

### 目前進度與工作分配

| 目前狀態 | 任務項目 | 負責人 |
| -------- | -------- | -------- |
| 完成 | 資料庫模型設計 / Infra / CD Flow | John Lin |
| 完成 | 資料來源爬蟲 & 資料蒐集 & 格式轉換至CSV File | Jimmy Hsu, WJWang |
| 完成 | RESTFul API Service (Design & Docs) | John Lin |
| 完成 | RESTFul API Service (Implement) | John Lin |
| 進行中 | Web client 以 Map / List 呈現 (https://mask.goodideas-studio.com/) | Chan Wei Wu |
| 進行中 | Chatbot (https://line.me/ti/p/@592zrdyn) | Eric Wu |
| 進行中 | Chatbot,目前提供以Line送出定位點查詢附近10公里內的資料,其它功能開發中 (https://lin.ee/4nIuWCB) | Ian Chen |

----

*** 下方是早期開發用的相關規劃文件，api使用請以SwaggerUI為主 ***

# API 規格(Planing Section)

1. 取得完整縣市區域列表
* Endpoint: GET /api/city
* Response Example:

  [
     {
         "city": "台北市",
         "areas": [
             "大安區",
             "中正區"
         ]
     }
  ]

2. 查詢物資供給
* Endpoint: GET /api/supply?....
* Query Params (省略則不參與AND條件查詢):
* page: 分頁索引(必要, 0 開始)
* size: 分頁大小 (必要)
* city: 縣市名
* area: 區域名
* lat: 方圓中心緯度 (lat/lng/radius 必須一起下)
* lng: 方圓中心經度 (lat/lng/radius 必須一起下)
* radius: 方圓半徑公尺 (lat/lng/radius 必須一起下)
* maskStatus: 醫療口罩狀態: UNKNOWN / AVAILABLE / SHORTAGE
* childrenMaskStatus: 兒童醫療口罩: UNKNOWN / AVAILABLE / SHORTAGE
* Response Example

    [
        {
            "id": 1,
            "category": "統一超商",
            "lat": 23.5
            "lng": 121.111,
            "gmPlaceId": "ppppppppppp",
            "city": "台北市",
            "area": "大安區",
            "address": "xxxxxxxxxx",
            "name": "XXXX門市",
            "maskStatus": "AVAILABLE",
            "childrenMaskStatus": "SHORTAGE",
            "updatedTime": "2019-08-12T00:00:00.000+0000"
        }
    ]

3. 更新物資狀態
* Endpoint: PATCH /api/supply/{id}
* Request Example (省略就不會更新，例如以下就不會更新兒童口罩):

    {
        "maskStatus": "AVAILABLE"
    }

* Response: HTTP 204 (不會有payload)

4. ReCaptcha (暫時pending)
* SiteKey: 6LeMShYTAAAAABb9e3llcv-Iwuj2CFDu9mVkutwE