# 取得員工 APP 使用歷程
Custos-EnterpriseAPP-API-013
V3.0
2023.09.14

Custos 企業會員之員工登入 Custos Enterprise APP 後，取得個人 APP 使用歷程。

[toc]
## 作業啟動
1. 以傳入之使用者 token 取得使用者流水編號 #emp_data_id
2. 傳入參數 節碳生活功能代碼 #function_id、查詢起始日期 #begin_date、查詢迄止日期 #end_date
3. 記錄 SystemLog：#emp_data_id|取得員工 APP 使用歷程|作業啟動

## API 作業啟動
1. 以 #emp_data_id 取得使用者所屬企業流水編號 #corp_data_id、語系代碼 #language_setting
2. 以 #function_id 分別查詢以下資料表；若 #function_id 未傳則查詢全部資料表

|#function_id|資料表|說明|
|-|-|-|
|1|corp_ls_stairs_records|以 happen_date 為日期條件|
|2、3、4|corp_ls_photo_album|以 create_date 為日期條件|
|5、6|corp_ls_transportation_records|以 create_date 為日期條件|

取得員工 APP 使用歷程紀錄 (若起迄日期未傳入則撈取所有資料)
參考 SQL：
*select happen_date as date, function_id, floors as results from corp_ls_stairs_records where corp_data_id = #corp_data_id and emp_data_id = #emp_data_id and happen_date >= '#begin_date' and happen_date <= '#end_date' order by happen_date desc*

*select create_date as date, function_id, 1 as results from corp_ls_photo_album where corp_data_id = #corp_data_id and emp_data_id = #emp_data_id and create_date >= '#begin_date' and create_date <= '#end_date' order by create_date desc*

*select create_date as date, function_id, mileage as results from corp_ls_transportation_records where corp_data_id = #corp_data_id and emp_data_id = #emp_data_id and create_date >= '#begin_date' and create_date <= '#end_date' order by create_date desc*

上述所有資料集全部做 union 後，再依照 date 降冪排序。

3. 若需取得腳踏車 (#function_id 為 5) 或大眾運輸 (#function_id 為 6) 之統計數據，需傳入參數 #period，根據下列說明，取得對應數據並計算後，回傳數據陣列及加總數字給 APP：
|#period|說明|
|-|-|
|T|取得當日所有數據資料，以每一筆資料之起始時間降冪排列|
|D|取得當日 00:00:00 至 23:59:59 之數據資料，以小時為單位加總，記於起始時間；例如：08:10~08:20 有一筆紀錄 3 km，08:35~08:45 有另一筆紀錄 2.8 km，回傳之數據資料應為 08 5.8 km|
|W|取得前 7 日之數據資料，以 1~7 表示週一到週日；例如 3456712 表示從上週三到本週二|
|M|取得前 30 日之數據資料，以 YYYY-MM-DD 表示|

**#period 為 T 時需取出 corp_ls_transportation_records.record_id 欄位回傳**

## 作業結束
記錄 SystemLog：#emp_data_id|取得員工 APP 使用歷程|作業結束

## 例外處理
若執行中有發生異常，將攔截到的 exception 訊息記錄 ErrorLog：[YYYYMMDDHHMMSS] EnterpriseAPP-API-013 發生異常：【#攔截到的 exception 訊息】

## 規格及範例
|API No|EnterpriseAPP-API-013|
|-|-|
|API Name|getEmpRecordHistory|
|URL|${url}/APP/getData/getEmpRecordHistory|
|Purpose|取得員工 APP 使用歷程|
|Description|透過 API 取得員工 APP 使用歷程|
|Protocol|JSON over HTTP POST|
|Content-Type|application/json|

**Request**
|參數|型態|必填|長度|說明|
|-|-|:-:|:-:|-|
|token|String|Y||使用者驗證字串|
|function_id|INT|Y||節碳生活功能代碼|
|begin_date|Datetime|N||查詢起始日期|
|end_date|Datetime|N||查詢迄止日期|
|period|String|N|1|統計區間 T/D/W/M；腳踏車與大眾運輸使用|

**Response**
|參數|型態|必回|說明|
|-|-|:-:|-|
|result|String|Y|API 執行結果，Y：成功，N：失敗|
|message|String|N|API 執行失敗的訊息說明|
|total_mileage|INT|N|腳踏車與大眾運輸時回傳之總里程數，單位為公尺|
|total_time|INT|N|腳踏車與大眾運輸時回傳之總分鐘數|
|total_leaves|INT|N|腳踏車與大眾運輸時回傳之總樹葉數|
|data|Object|N|物件陣列，傳回各項節碳生活功能歷程紀錄；result = N 時為空陣列([])|

**Request Sample 1: 查詢使用歷程**

var input = {
  "token": "xxx",
  "function_id": 2,
  "begin_date": "2023-08-01",
  "end_date": "2023-09-30"
}

**Request Sample 2: 查詢今日腳踏車紀錄**

var input = {
  "token": "xxx",
  "function_id": 5,
  "period": "T",
}

**Request Sample 3: 查詢當日腳踏車紀錄**

var input = {
  "token": "xxx",
  "function_id": 5,
  "period": "D",
}

**Request Sample 4: 查詢過去 7 天腳踏車紀錄**

var input = {
  "token": "xxx",
  "function_id": 5,
  "period": "W",
}

**Request Sample 5: 查詢過去 30 天腳踏車紀錄**

var input = {
  "token": "xxx",
  "function_id": 5,
  "period": "M",
}

**Response Sample 1: 回傳使用歷程 或 今日腳踏車紀錄**

{	
  "result": "Y",	//API 結果，Result = Y 時才會有 data 資料
  "message": "...",	//API 訊息，Ex："執行失敗，原因：XXXXXXXXX"
  "data": [	        //依照日期降冪排列
      {	
         "date": "2023/08/15 08:10:15", 	//歷程紀錄執行時間，取自回傳資料的 date 欄位
         "function_id": 2,	//節碳生活功能 id，取自回傳資料的 function_id
         "results": "10"	//當次已完成數值，取自回傳資料的 results
      },	
      {...}	
   ]	
}

**Response Sample 2: 回傳當日腳踏車紀錄**

{	
  "result": "Y",	 //API 結果，Result = Y 時才會有 data 資料
  "message": "...",	 //API 訊息，Ex："執行失敗，原因：XXXXXXXXX"
  "total_mileage": 2723, //腳踏車與大眾運輸時回傳之總里程數，單位為公尺
  "total_time": 17,   //腳踏車與大眾運輸時回傳之總分鐘數
  "total_leaves": 23,    //腳踏車與大眾運輸時回傳之總樹葉數
  "data": [	         
      { 
          "hour": 0,
          "result": "0"
      },
      { 
          "hour": 1,
          "result": "0"
      },
      { 
          "hour": 2,
          "result": "0"
      },
      { ... },
      { 
          "hour": 8,
          "result": "4.1"
      },
      { 
          "hour": 9,
          "result": "0"
      },
      { ... },
      { 
          "hour": 18,
          "result": "4.1"
      },
      { ... },
      { 
          "hour": 23,
          "result": "0"
      },
   ]	
}

**Response Sample 3: 過去 7 天腳踏車紀錄**

{	
  "result": "Y",	//API 結果，Result = Y 時才會有 data 資料
  "message": "...",	//API 訊息，Ex："執行失敗，原因：XXXXXXXXX"
  "total_mileage": 2723, //腳踏車與大眾運輸時回傳之總里程數，單位為公尺
  "total_time": 17,   //腳踏車與大眾運輸時回傳之總分鐘數
  "total_leaves": 21,    //腳踏車與大眾運輸時回傳之總樹葉數
  "data": [	        
      { 
          "weekday": 5,   //星期六
          "result": "13"
      },
      { 
          "weekday": 6,   //星期日
          "result": "12"
      },
      { 
          "weekday": 0,   //星期一
          "result": "10.7"
      },
      { 
          "weekday": 1,   //星期二
          "result": "11.5"
      },
      { 
          "weekday": 2,   //星期三
          "result": "9.2"
      },
      { 
          "weekday": 3,   //星期四
          "result": "13"
      },
      { 
          "weekday": 4,   //星期五
          "result": "13"
      }
   ]	
}

**Response Sample 4: 回傳過去 30 天腳踏車紀錄**

{	
  "result": "Y",	//API 結果，Result = Y 時才會有 data 資料
  "message": "...",	//API 訊息，Ex："執行失敗，原因：XXXXXXXXX"
  "total_mileage": 2723, //腳踏車與大眾運輸時回傳之總里程數，單位為公尺
  "total_time": 17,   //腳踏車與大眾運輸時回傳之總分鐘數
  "total_leaves": 84,     //腳踏車與大眾運輸時回傳之總樹葉數
  "data": [	        
      { 
          "date": "2023-09-04",
          "result": "13"
      },
      { 
          "date": "2023-09-05",
          "result": "12.1"
      },
      { 
          "date": "2023-09-06",
          "result": "12.3"
      },
      { ... },
      { 
          "date": "2023-10-03",
          "result": "11.8"
      }
   ]	
}