# 新增員工節碳生活資料
Custos-EnterpriseAPP-API-012
V3.0
2023.09.11

Custos 企業會員之員工使用 Custos Enterprise APP 各項節碳生活功能，期間所節省下來的碳將記錄於資料庫；若累積之碳數量已達兌換標準，將於新增時直接完成兌換，呈現於 APP 中。

[toc]
## 作業啟動
1. 以傳入之使用者 token 取得使用者流水編號 #emp_data_id
2. 傳入參數 節碳生活功能代碼 #function_id、節碳生活功能完成資料、節碳生活功能完成日期 #happen_date、手機平台 #modify_oper
3. 記錄 SystemLog：#emp_data_id|新增員工節碳生活資料|作業啟動

節碳生活功能代碼參照 corp_ls_function 檔：
1：爬樓梯 Take Stairs
2：環保袋 BYO Bag
3：環保餐具 BYO Tableware
4：無肉餐 Meatless Meals
5：腳踏車 Ride Bicycle
6：大眾運輸 Public Transportation
7：跳蚤市場交易 Marketplace Transaction

## API 作業啟動
1. 以 #emp_data_id 取得使用者所屬企業流水編號 #corp_data_id、使用者所屬部門代碼 #dept_data_id、語系代碼 #language_setting
2. 根據所傳入之 #function_id，寫入資料表：
1：corp_ls_stairs_records
2, 3, 4：corp_ls_photo_album
5, 6：corp_ls_transportation_records、corp_ls_transportation_record_details

3. 若 #function_id 為 1，寫入資料
corp_ls_stairs_records.corp_data_id = #corp_data_id
corp_ls_stairs_records.dept_data_id = #dept_data_id
corp_ls_stairs_records.emp_data_id = #emp_data_id
corp_ls_stairs_records.function_id = #function_id
corp_ls_stairs_records.floors = '【節碳生活功能完成資料】'(傳入之參數 #floors)
corp_ls_stairs_records.happen_date = '#happen_date'
corp_ls_stairs_records.modify_oper = '#modify_oper'
corp_ls_stairs_records.language_setting = '#language_setting'

將新增之資料 record_id 暫存於變數 #data_id
* 寫入前，先檢查同樣 happen_date 是否已有資料，若有，則略過不予新增；下方 6. 同樣不予新增。

4. 若 #function_id 為 2, 3, 4，寫入資料
corp_ls_photo_album.corp_data_id = #corp_data_id
corp_ls_photo_album.dept_data_id = #dept_data_id
corp_ls_photo_album.emp_data_id = #emp_data_id
corp_ls_photo_album.function_id = #function_id
corp_ls_photo_album.photo_image = '【節碳生活功能完成資料】'(此項目為照片檔案上傳，照片檔案名稱 #photo_image)
corp_ls_photo_album.is_approval = 'N'
corp_ls_photo_album.modify_oper = '#modify_oper'
corp_ls_photo_album.language_setting = '#language_setting'

將新增之資料 photo_id 暫存於變數 #data_id

5. 若 #function_id 為 5, 6，需額外傳入 開始時間 #start_datetime、開始 GPS 座標 #start_gps、結束時間 #end_datetime、結束 GPS 座標 #end_gps、距離 #mileage，寫入資料
corp_ls_transportation_records.corp_data_id = #corp_data_id
corp_ls_transportation_records.dept_data_id = #dept_data_id
corp_ls_transportation_records.emp_data_id = #emp_data_id
corp_ls_transportation_records.function_id = #function_id
corp_ls_transportation_records.start_datetime = '#start_datetime'
corp_ls_transportation_records.start_gps = '#start_gps'
corp_ls_transportation_records.end_datetime = '#end_datetime'
corp_ls_transportation_records.end_gps = '#end_gps'
corp_ls_transportation_records.mileage = '#mileage'
corp_ls_transportation_records.modify_oper = '#modify_oper'
corp_ls_transportation_records.language_setting = '#language_setting'

將新增之資料 record_id 暫存於變數 #data_id

開始紀錄後，APP 每隔 10 秒會回傳 GPS 位置 #relay_gps，需寫入 corp_ls_transportation_record_details 明細檔，記錄當下的座標與時間 #relay_datetime；API 會計算從上一個 relay 點到這一個 relay 點，其距離與速度為何，分別以變數 #relay_mileage 與 #relay_speed 暫存

corp_ls_transportation_record_details.record_id = #data_id
corp_ls_transportation_record_details.relay_datetime = '#relay_datetime'
corp_ls_transportation_record_details.relay_gps = '#relay_gps'
corp_ls_transportation_record_details.relay_gps = '#relay_gps'
corp_ls_transportation_record_details.mileage = '#relay_mileage'
corp_ls_transportation_record_details.speed = '#relay_speed'

==腳踏車設定速度區間為 5~40 km/hour，大眾運輸則為 10~80 km/hour；不在此區間內的資料將不與計列==

6. 寫入企業節碳生活記錄檔 corp_ls_carbon_records 與員工個人節碳記錄檔corp_ls_emp_carbon_records
corp_ls_carbon_records.corp_data_id = #corp_data_id
corp_ls_carbon_records.dept_data_id = #dept_data_id
corp_ls_carbon_records.emp_data_id = #emp_data_id
corp_ls_carbon_records.function_id = #function_id
corp_ls_carbon_records.life_style_data_id = #data_id
corp_ls_carbon_records.leaves = #leaves_num (由 API 計算)
corp_ls_carbon_records.carbon_saving = #carbon_saving (由 API 計算)
corp_ls_carbon_records.happen_date = '#happen_date'
corp_ls_carbon_records.modify_oper = '#modify_oper'
corp_ls_carbon_records.language_setting = '#language_setting'

寫入員工個人節碳記錄檔 corp_ls_emp_carbon_records (若無資料則新增)
先取得目前紀錄

*select leaves_accum as old_leaves_accum, carbon_accum as old_carbon_accum from corp_ls_emp_carbon_records
where emp_data_id = #emp_data_id*

取得資料存入變數 #old_leaves_accum，加上前述 #leaves_num 成為 #new_leaves_num；#old_carbon_accum，加上前述 #carbon_saving 成為 #new_carbon_accum。

corp_ls_emp_carbon_records.corp_data_id = #corp_data_id
corp_ls_emp_carbon_records.dept_data_id = #dept_data_id
corp_ls_emp_carbon_records.emp_data_id = #emp_data_id
corp_ls_emp_carbon_records.leaves_accum = #new_leaves_num
corp_ls_emp_carbon_records.carbon_accum = #new_carbon_accum
corp_ls_emp_carbon_records.language_setting = '#language_setting'

## 作業結束
記錄 SystemLog：#emp_data_id|新增員工節碳生活資料|作業結束

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

## 規格及範例
|API No|EnterpriseAPP-API-012|
|-|-|
|API Name|setEmpCarbonRecord|
|URL|${url}/APP/setData/setEmpCarbonRecord|
|Purpose|新增員工節碳生活資料|
|Description|透過 API 寫入員工與所屬企業之節碳生活記錄|
|Protocol|JSON over HTTP POST|
|Content-Type|application/json|

**Request**
|參數|型態|必填|長度|說明|
|-|-|:-:|:-:|-|
|token|String|Y||使用者驗證字串|
|function_id|INT|Y||節碳生活功能代碼|
|floors|INT|N||funciton_id 為 1 時必填，爬樓梯層數|
|happen_date|Date|Y||funciton_id 為 1 時填入爬樓梯發生日期；其餘填入使用當天日期|
|photo_image|String|N||function_id 為 2, 3, 4 時必填，照片檔案名稱|
|start_datetime|Datetime|N||function_id 為 5, 6 時必填，起始時間|
|start_gps|String|N|45|function_id 為 5, 6 時必填，起始 GPS 座標值|
|end_datetime|Datetime|N||function_id 為 5, 6 時必填，結束時間|
|end_gps|String|N|45|function_id 為 5, 6 時必填，結束 GPS 座標值|
|mileage|INT|N||function_id 為 5, 6 時必填，距離 (公尺)|
|modify_oper|String|Y|10|手機平台，iOS 或 Android|

**Response**
|參數|型態|必回|說明|
|-|-|:-:|-|
|result|String|Y|API 執行結果，Y：成功，N：失敗|
|message|String|N|API 執行失敗的訊息說明|

**Request Sample 1**

var input = {
  "token": "xxx",
  "function_id": 1,
  "floors": 3,
  "happen_date": "2023-09-10",
  "language_setting": "zh-TW"
}

**Request Sample 2**

var input = {
  "token": "xxx",
  "function_id": 2,
  "photo_image": "xxx.png",
  "happen_date": "2023-09-10",
  "language_setting": "zh-TW"
}

**Request Sample 3**

var input = {
  "token": "xxx",
  "function_id": 5,
  "start_datetime": "2023-09-10 08:03:10",
  "start_gps": "23.6415843, 121.35248743",
  "end_datetime": "2023-09-10 08:07:16",
  "end_gps": "23.6518793, 121.38513702",
  "mileage": "5406",
  "happen_date": "2023-09-10",
  "language_setting": "zh-TW"
}

**Response Sample**

{	
  "result": "Y",	 //API 結果，Result = Y 時才會有資料
  "message": "...",	 //API 訊息，Ex："執行失敗，原因：XXXXXXXXX"
}