# One Account Mobile

#### Team：Investor Platform
#### Authors： Yuta, Hoso
#### Created On: 2021/05/31
#### Last updated：2021/06/02
#### JIRA Epic: One Account
#### Reference document
* [PRD document](https://docs.google.com/document/d/1rbZFKlVAoB0O6hfQ4wRHlOTtecqCiJ9lQal28qGnHiM/edit)
* [Miro flow chart](https://miro.com/app/board/o9J_km0pruU=/?moveToWidget=3074457351762402911&cot=14)
* [Figma mobile prototype](https://www.figma.com/proto/cnYfkV8LoKMWukDoSA04PO/05_One-Account_Wirframe?node-id=1321%3A749&viewport=11911%2C-3499%2C0.5088087320327759&scaling=scale-down)
* [Figma web prototype](https://www.figma.com/proto/I7RbT6lPSNzsttJBEs97br/One-Account-%E5%BE%8C%E5%8F%B0%E7%B3%BB%E7%B5%B1%E8%A8%AD%E8%A8%88?page-id=0%3A1&node-id=237%3A159&viewport=114%2C305%2C0.02744034118950367&scaling=min-zoom)

<br/><br/>

# 手機驗證
## Summary(包含沒有要做到的項目)

開戶前，需先進行手機驗證確保非幽靈帳號，並無其他方法。

### 畫面
新增：
* 07_01_01_初次下載頁面
* 07_02_01_開戶介紹頁
* 07_02_02_FATCA
* 07_02_03_個人資料保護法
* 07_03_01_驗證手機號碼

已有：
* 07_04_01_輸入驗證碼

### API
[手機驗證 Sequence Diagram](https://hackmd.io/@y_z5uxWUQ-W_HzbMDBzaHA/H1uaxV0K_/%2FeYgGD0wVSjWZeuFk-UaE8Q)

新增：
* 傳送驗證碼
* 驗證驗證碼

### 待討論
* API Spec

## Solution
### Design
* **Summmary**

基本的頁面流程與 API，比較需要注意的是進入手機驗證頁後的動畫。
* **Data Model / Schema Changes**

Data validation methods：
* 新增專門處理 validation format (mail, phone number) 的 class
* 驗證手機號碼 regex ```"^09\d{8}$"```

* **Business Logic**

流程：
* 開啟 app 時須優先顯示**初始登入註冊頁**，條件有二個，除此之外都是進入登入頁，可利用判斷 app 最後停留頁面是否在初始登入註冊頁或開戶流程決定。
1. 第一次開啟 app
2. 上次離開 app 時是在初始登入註冊頁。
* 在驗證手機號碼頁，按下發送驗證碼，會打傳送驗證碼 API
* 在驗證碼頁，當使用者填完所有欄位，直接打驗證驗證碼 API

* **Presentaion Layer**
UI / UX：
* 按下初始登入註冊頁的我要開戶，進入開戶介紹頁有 layout 的[微動畫](https://www.figma.com/proto/cnYfkV8LoKMWukDoSA04PO/05_One-Account_Wirframe?node-id=1321%3A749&viewport=11911%2C-3499%2C0.5088087320327759&scaling=scale-down)
* 按下註冊介紹頁的開始，進入手機驗證頁會有圓形展開[動畫](https://www.figma.com/proto/cnYfkV8LoKMWukDoSA04PO/05_One-Account_Wirframe?node-id=1565%3A81&viewport=11911%2C-3499%2C0.5088087320327759&scaling=scale-down)
* 在驗證手機號碼頁，手機欄位為空時，發送驗證碼按鈕狀態為 disable，當有數字時才會enable

錯誤處理：
* 在驗證手機號碼頁，送出 API 前需要判斷手機格式是否錯誤，如果為否，需顯示**手機號碼格式錯誤**
* 在驗證手機號碼頁，API 遇到任何錯誤直接利用 dialog & response error 顯示。

* **Other questions to answer**

### QA Plan
## Further Consideration

<br/><br/>

# 基本資料、身份驗證

## Summary

整合全景與 cyberlink 的 third party，將辨識後的圖片傳到後臺，從後台得到資料，放到前端基本資料欄位，加速使用者填寫資料速度。

### 畫面
新增：
* 07_05_01_驗證身份介紹頁
* OCR 身分證與第二證件頁
* 07_08_01_拍完證件
* 人臉辨識頁
* 07_10_01_確認身份證資訊
* 07_11_01_基本資料
* 07_13_01_設定約定帳戶

### API
[基本資料及身份驗證 Sequence diagarm](https://hackmd.io/@y_z5uxWUQ-W_HzbMDBzaHA/H1uaxV0K_/%2FO7X9eYEySU628DzrT2sLeQ)
新增：
* OCR 身分證照片、第二證件、人臉辨識照片
* 基本資料與照片 UUID
* 行業別
* 服務據點？
* 服務專員？
* 銀行列表？

### 待討論
* API Spec
* ~~傳送照片 API 是否要一支 API 解決，或是多支~~
* 基本資料、服務據點與服務專員分開傳送嗎？
* 銀行與分行資料是否一支 API，不需要分兩支 API
* 銀行存摺
* 全景 OCR
* 提示與錯誤訊息(已交由 Sandra 處理)

## Solution
### Design
* **Summmary**

身份驗證牽涉到圖片上傳，上傳時機、loading與錯誤處理時機點需要釐清，確保使用者體驗良好，上傳圖檔後從後台得到的 UUID 需要暫存，在上傳基本資料時一併帶入。
基本資料牽涉到多筆資料抓取 API，包含行業別、服務據點、服務專員與銀行列表，打這些 API 的時機都需要討論確保雙平台有同樣的體驗。

* **Data Model / Schema Changes**

* **Business Logic**
API：
* 身分證與第二證件 API 一起使用
* 人臉辨識
* 憑證 API
* 行業別、服務據點 API 在傳送人臉辨識後也一並抓取。
* 照片 API，一次上傳身分證正反面、第二證件、人臉辨識，content type: multipart/form-data，image 格式 binary。

流程：

* 使用者在驗證身份介紹頁按下

* **Presentaion Layer**

UI / UX

OCR 提示與錯誤訊息(config)
| key | value |
| -------- | -------- |
| DetectGuideTimeoutHin | 請對齊藍色偵測框 |
| AutoDetectingHint | 尋找證件中
| DetectGuideHint | "" |
| EditPageGuideTitle | 請將四個點對齊身分證四角 |
| DetectPreviewGuideHint |"" |
| ScreenOrientationHint | 為增加證件辨識度請將手機轉至橫式拍照 |
| DetectGuideHintBlurryMessage | 太模糊，無法辨識證件 |
| DetectGuideHintReflectiveLightMessage | 有反光，無法辨識證件 |
| DetectGuideHintVerifyFailMessage | 非正確的證件類型 |
| DetectGuideHintShadowFailMessage | 有陰影，無法辨識證件 |
| AlertMessageVerifyReflectiveLightFail | 因反光無法辨識證件，請重新拍攝|
| AlertMessageVerifyCardTypeFail | 非正確的證件類型，請重新拍攝 |
| AlertMessageVerifyBlurryFail | 因太模糊無法辨識證件，請重新拍攝 |
| AlertMessageVerifyShadowFail | 因陰影過大無法辨識證件，請重新拍攝 |

備註：
* ""表空字串

### QA Plan

## Further Consideration
### Third Party
<br/><br/>

# 簽署文件

## Summary
### 畫面
* 07_22_01_契約簽署
* 07_23_01_契約一覽
* 07_23_02_FATCA、CRS 聲明書暨個資同意書
* 07_23_03_各項聲明書與同意書
* 07_23_04_金融消費者保護法
* 07_23_05_交易總約定書
* 07_23_06_交易風險預告書

### API
[契約簽署 Sequence Diagram](https://hackmd.io/@y_z5uxWUQ-W_HzbMDBzaHA/H1uaxV0K_/%2FuhImazuOSMeBKvyQXlg7xg)
[短憑證簽署 Sequence Diagarm](https://hackmd.io/@y_z5uxWUQ-W_HzbMDBzaHA/H1uaxV0K_/%2FQjKqjJd6TcSUqDm3PZW_Jg)

* 取得通行證
* 取得契約檔案
* 簽署後將簽章值與驗章通行證傳給server

### Third Party
手機端需與TWID@SDK整合，想像中需要驗證通行證與簽署文件兩個流程。
https://drive.google.com/file/d/1bnoyrWnqE8_dVKuO23L7CEdi3mNdstVI/view?usp=sharing
https://hackmd.io/w38Wo9UbRvuB-IZH8Bavfg#TWID-%E7%B4%B0%E7%AF%80

### 待決定的事
* API細節
* 讀取動畫出現的時機
* 如何取得簽署所需要的契約
* 於背景跟server拿
* 寫死在client
* 簽署文件需要的時間多長，API是否設計成async API
* error message提供使用者失敗資訊或重試

## Solution
### Design
* **Summmary**
此頁面牽涉到App, Mobile-Backend, TWID三方的溝通，API設計與整體流程需再參酌後端的設計。

* **Data Model / Schema Changes**

* **Business Logic**
**流程**
1. 到簽署畫面介紹畫面，按開始後打API取得通行證
1. 以通行證呼叫TWID@SDK的憑證作業API
1. 若成功跳轉到文件列表頁面，**於背景取得簽署所需要的契約（待定）**
2. 若失敗則留在原頁面，針對error message提供使用者失敗資訊或重試
1. 可點入各個文件瀏覽細節（optional）
1. 按同意後用進行簽章流程，呼叫TWID@SDK的簽章功能，執行簽章
1. 若成功則打API將簽章值與驗章通行證交給server
2. 若失敗則針對error message提供使用者失敗資訊或重試
1. 待server複驗結果
1. 成功後跳到下一頁（polling or API return success）
2. 若失敗則針對error message提供使用者失敗資訊或重試
* **Presentaion Layer**
* 所有的動畫都是從畫面右邊滑進

### QA Plan

## Further Consideration

# KYC

## Summary
### 畫面

### API
[KYC Sequence Diagram](https://hackmd.io/@y_z5uxWUQ-W_HzbMDBzaHA/H1uaxV0K_/%2FctXDm40ATNOBlMZTio9nFA)

<br/><br/>

# 寄送初始密碼

## Summary
### 畫面
**新增：**
* 07_24_01_開戶申請已送出
* 07_24_02_其他解決方法
* 07_24_04_修改信箱
* 02_03_01_首頁_開戶申請審核中
* 02_03_02_首頁_開戶需補件
* 02_04_01_首頁_開戶申請已通過_未申購
* 02_04_02_點選馬上申購（已有類似頁面）

**已有：**
* 修改信箱OTP
* 第一次登入修改密碼

### API
**新增：**
* 重新寄送初始密碼
* 更新email
* 取得開戶狀態
* 開戶進度
* 若需補件，補件相關細節
* 補件API
* 預期是會有page & query上次填寫紀錄的頁面（若缺少的東西不是圖片的話）
* 上傳補件結果預期是跟註冊時用同一套API來更新資料

**已有：**
* authenticate-user
* leave-a-message
* send-verification-code
* check-verification-code
* set-password
* get-direct-sales-info

### 待決定的事
* OTP寄送&驗證的功能是否要一致化
* API細節
* 補件之API

## Solution
### Design
* **Summmary**
重發密碼流程相對單純，主要是固定的UI的繪製與交互。
補件部分則較複雜，需要從後端回傳的資料來導向指定的頁面*並顯示上次填寫內容*（待定）。
* **Data Model / Schema Changes**

* **Business Logic**
**申請相關流程**
1. 到初始密碼已送出頁面
1. 輸入初始密碼進行驗證，驗證成功則進入密碼修改頁面
1. 輸入初始密碼進行驗證，驗證失敗跳出錯誤訊息，留在原頁面
1. 倒數結束後可要求重新發送初始密碼
1. 「其他解決辦法」進入**其他解決辦法**頁面
1. 進入「其他解決辦法」
1. 可選擇修改email，進入OTP頁面
1. 可選擇留言給客服或來電
1. 完成OTP驗證後可重新設定email
1. 設定成功跳轉回**開戶申請已送出**頁面
1. 設定失敗跳出錯誤訊息，留在原頁面
1. 設定完新密碼之後到登入頁面

**申請已送出後流程**
1. 主畫面取得開戶進度
1. 若審核中
1. 若需補件
1. 如何連結到補件畫面
1. 若成功開通
1. 可連結至外部網站（目前是固定的）
1. 可前往申購畫面（目前是提供聯絡服務專員的電話）

**檢查email格式:** `[a-zA-Z0-9\\+\\.\\_\\%\\-\\+]{1,256}\\@[a-zA-Z0-9][a-zA-Z0-9\\-]{0,64}(\\.[a-zA-Z0-9][a-zA-Z0-9\\-]{0,25})+`
*ref: https://developer.android.com/reference/android/util/Patterns#EMAIL_ADDRESS*

* **Presentaion Layer**

### QA Plan

## Further Consideration

## TWID 細節
### TWID@SDK 錯誤處理
[reference](https://docs.google.com/document/d/1bnoyrWnqE8_dVKuO23L7CEdi3mNdstVI/edit#heading=h.1v1yuxt)
**處理方式（待定）**
* 使用流程錯誤：要求重試
* 需要額外設置：要求進行相對應的行動
* 手機無法支援：顯示失敗原因，要求換手機進行或聯絡我們
* TWID端出錯：要求重試，並把相關資訊回報給我們
* App端出錯：傳送相關資訊給我們
* 偶發：可直接重試（UI上可能需要提示使用者），重複發生時回報給我們

#### SDK端錯誤碼
比較偏環境&App整合的錯誤所導致的問題
| 回應代碼 | 回應訊息 | App行為 |
| -------- | -------- | -------- |
|0|成功|NA|
||手機或電信設置錯誤|
|1000|APP執行的權限不足，請先允許開放權限。|需要額外設置|
|1001|不支援已JB或Root的行動裝置|手機無法支援|
|1002|請關閉WiFi網路，改用4G網路。|需要額外設置|
|1003|行動網路未連線，請開啟4G網路。|需要額外設置|
|1004|使用的電信網路或漫遊網路不支援。|手機無法支援|
|2000|下載資訊midProfile讀取失敗，請重新操作。|偶發|
|2001|下載資訊midProfile驗證失敗，請重新操作。|偶發|
|2002|電信業者連線失敗，請確認網路連線後重新操作。|偶發|
|2003|電信業者驗證失敗|TWID端出錯|
|2004|電信業者驗證失敗(雙卡機中2張SIM卡皆失敗)|TWID端出錯|
|2005|電信業者驗證失敗，漫遊服務不支援。|手機無法支援|
||使用者使用流程錯誤|
|2999|裝置解鎖驗證失敗，請重新操作。|使用流程錯誤|
|3000|需要裝置解鎖驗證，請設置後重新操作。|需要額外設置|
|3001|裝置解鎖驗證取消，請重新操作。|使用流程錯誤|
||SDK內部錯誤|
|3002|TWID Portal連線失敗，請確認網路連線後重新操作。|需要額外設置/TWID端出錯|
|3003|TWID Portal訊息無效，請稍後再試。|TWID端出錯|
|3004|TWID Portal服務異常，請稍後再試。|TWID端出錯|
||SDK整合流程錯誤|
|3005|未提供正確的身分證字號|App端出錯|
|3006|未提供電話號碼|App端出錯|
|未知錯誤|
|4005|APP作業異常，未確認憑證狀態，請重新操作。|偶發|
|4006|APP作業異常，無需進行憑證作業，請重新操作。|偶發|
|5005|APP作業異常，參數錯誤，請重新操作。|偶發/App端出錯|

#### 安控元件
核心的安控元件出錯
| 回應代碼 | 回應訊息 | App行為 |
| -------- | -------- | -------- |
|0|成功|NA|
|2001|參加單位未被授權|App端出錯|
|2002|無效的識別授權|App端出錯|
|2003|無法取得伺服器時間|偶發/App端出錯|
|2004|這個網域未被授權|App端出錯|
|2006|沒有讀取裝置資訊的權限|需要額外設置/App端出錯|
|3001|金鑰已經存在|App端出錯|
|3002|找不到金鑰|App端出錯|
|3003|認證失敗|TWID端出錯|
|3004|金鑰已經存在|App端出錯|
|3005|用戶取消|使用流程錯誤|
|3006|裝置不支援 Touch-ID 或是未開啟 Touch-ID|手機無法支援/需要額外設置|
|3007|無法增加金鑰鏈項目|TWID端出錯|
|3008|請完成裝置上的密碼鎖定(如：Touch ID, Face ID)，再繼續操作。|需要額外設置|
|3099|存取金鑰鏈時發生錯誤|TWID端出錯|
|4001|查無簽章回條之憑證|TWID端出錯|
|4002|使用者取消簽章|使用流程錯誤|
|4003|簽章回條發生錯誤|TWID端出錯|
||憑證、金鑰、密碼出錯||
|5001|一般錯誤|偶發|
|5005|錯誤的參數|App端出錯|
|5006|網站不存在|App端出錯|
|5008|Base64 編碼錯誤|TWID端出錯|
|5010|找不到指定憑證|App端出錯|
|5011|申請憑證ID不符|App端出錯|
|5040|憑證格式錯誤|App端出錯/TWID端出錯|
|5060|金鑰不存在|App端出錯|
|5061|簽章失敗|TWID端出錯|
|5062|驗章失敗|TWID端出錯|
|5063|加密失敗|TWID端出錯|
|5064|解密失敗|TWID端出錯|
|5065|產生金鑰失敗|TWID端出錯|
|5066|刪除憑證失敗|TWID端出錯|
|5067|執行簽章時, 尚未選擇簽章憑證|App端出錯|
|5070|使用者按下"取消"按鈕|使用流程錯誤|
|5071|密碼錯誤|使用流程錯誤/App端出錯|
|5072|請確認裝置TouchId為開啟狀態|需要額外設置|
|5073|密碼錯誤超過限定次數，金鑰已被鎖定|App端出錯/使用流程錯誤|
|5074|密碼錯誤超過限定次數，金鑰已被抹除|App端出錯/使用流程錯誤|
|5075|金鑰無法還原(非綁定)|TWID端出錯|
|5076|金鑰無法還原(綁定)|TWID端出錯|
|5101|金鑰已存在|TWID端出錯/App端出錯|
|5102|儲存金鑰失敗|*TBD*|
|5103|讀取金鑰失敗|TWID端出錯|
|5110|儲存憑證失敗|*TBD*|
|5111|匯入憑證失敗|TWID端出錯|
|5112|讀取憑證失敗|TWID端出錯|
|5113|刪除憑證失敗|*TBD*|
|5120|憑證沒有設定密碼|*TBD*|
|5121|變更密碼失敗|*TBD*|
|5301|金鑰長度錯誤|*TBD*|
|5302|金鑰產生失敗|TWID端出錯|
|5305|ASN1編碼失敗|TWID端出錯|
|6001|解密驗章失敗|*TBD*|
|6002|憑證驗章失敗|*TBD*|
|6003|無法剖析簽章憑證|*TBD*|
|6004|無法剖析簽章資料|*TBD*|
|6005|無法剖析根憑證資訊|*TBD*|
|6006|憑證練驗證失敗|*TBD*|
|9001|加解密演算法錯誤|*TBD*|
|9002|加解密格式錯誤|*TBD*|
|9003|加解密密碼長度錯誤|*TBD*|
|9004|加密錯誤|*TBD*|
|9005|解密錯誤|*TBD*|
|9006|解密錯誤,找不到可用憑證|*TBD*|

# 中離與重做
## Summary
[flow chart](https://miro.com/app/board/o9J_km0pruU=/?moveToWidget=3074457360040108451&cot=14)
檢查短憑證

### 畫面

### API

### 待決定的事

## Solution
### Design
### QA Plan
## Further Consideration

# Third Party

## 台網

### Summary

system parameter key: WebCom
system parameter value: 22957098
server url: https://twca-portal.tcstock.com.tw:8443/IDPortal