## OverView
### API List
|API Name|功能|具權限者|
|---|---|---|
|**[Post]** LogIn|使用者登入|Admin/User|
|**[Get]** SingleUserDataQuery|查詢單一使用者資料|Admin/User|
|**[Update]** SingleUserDateUpdate|更新單一使用者資料|Admin/User|
|**[Post**] UserCreate|建立使用者|Admin|
|**[Get]** AllUserDataQuery|查詢所有使用者資料|Admin|
|**[Update]** MultipleUserDateUpdate|更新複數使用者資料|Admin|
|**[Delete]** UserDelete|刪除使用者|Admin|
|**[Post]** ResetPWD|重置密碼|Admin/User|
### Structure
使用者透過[Post]LogIn取得token
```mermaid
flowchart
LoginRequest((使用者登入))-->Login[[Login]]-->Token[/Token/]
```
使用者發出request，先後依序經過tokenAttribute、AuthorizationAttribute驗證。
```mermaid
flowchart TD
Request[/Request/]-->TokenFilter-->AuthorizationFilter --> APIs --> Return
subgraph APIs
SingleUserDataQuery
SingleUserDateUpdate
UserCreate
AllUserDataQuery
MultipleUserDateUpdate
UserDelete
end
TokenFilter[TokenAttribute]
AuthorizationFilter[AuthorizaitonAttribute]
SingleUserDataQuery[[查詢單一使用者資料]]
SingleUserDateUpdate[[更新單一使用者資料]]
UserCreate[[建立使用者]]
AllUserDataQuery[[查詢所有使用者資料]]
MultipleUserDateUpdate[[更新複數使用者資料]]
UserDelete[[刪除使用者]]
```
**User Information ER**
```mermaid
---
title: User Information Maintenance ER
---
erDiagram
s_user }o--|| s_role : ""
s_user{
%% User Information
varchar(36) acctId PK "Guid"
varchar(255) acct UK "Not Null"
varchar(20) adacct
varchar(64) pw UK "Not Null"
varchar(100) name
varchar(100) email "Not Null"
%%string picURL "URL"
varchar(100) organizationalunit
varchar(100) countryregion
%% Authorization Infomation
varchar(36) roleId FK "Guid"
%% state Information
bool active "Default: true"
int state
%% system Information
Datetime loginon
Datetime CreateOn
Datetime ModifiedOn
varchar(100) CreateBy
varchar(100) ModifiedBy
}
s_role{
GUID roleId PK
varchar(100) roleName "Admin/Dev/User"
%% state Information
bool active "Default: true"
int state
%% system Information
Datetime CreateOn
Datetime ModifiedOn
varchar(100) CreateBy
varchar(100) ModifiedBy
}
```
note:
* email設為not null 因為預計會使用email作為密碼重置所需資訊。
* CreatedBy和ModifiedBy，紀錄名字而非id。考慮到這些欄位讀取的機會比修改多，與其每次讀取都去join表，不如直接顯示名字。
**忘記密碼要求API**
```mermaid
flowchart TD
ResetRequest((Reset\n Request))-->Authentication[輸入帳號信箱] --> AcctEmailCheck{Acct & Email\n are correct}-->|true|GenerateNewPWD[生成新密碼]-->EncryptNewPwd[加密新密碼]-->WriteNewPWD[將新密碼密文寫入資料庫]-->SendEmail[發送含Token信件]
AcctEmailCheck-->|false|AccEmailNotCorrect[/AccEmailNotCorrect/]
GenerateNewPWD
```
**更改密碼API**
```mermaid
flowchart TD
ResetPWDtoken[/重置密碼token/] -->|Token|TokenAuthentication[驗證token] -->|OK|ResetPWDtoken2[/重置密碼token、帳號、新密碼/]-->TokenAccEmailCheck
subgraph API
TokenAccEmailCheck{確認帳號信箱} -->|true|EncrptNewPWD[加密新密碼]-->NewPWDWrite[寫入新密碼]--> ReturnPWDSucess[/密碼改動成功/]
TokenAccEmailCheck-->|false|TokenFail[/token錯誤/]
end
```
## [Put]UserDataUpdate
這支API用作使用者進行個人資料的維護。
'AcctId'作為查詢資料庫紀錄用設計為必填。
其餘可傳入參數僅包含's_user'中部分屬性，未包括密碼(pw)及權限相關屬性(active; roleId)。
由於'Acct'作為使用者登入使用，不可
### Request body
```csharp
{
"acctId": "string",//required, no empty or whitespace
"acct": "string",// no empty or whitespace
"adAcct": "string",
"name": "string",
"email": "string",// email format checked
"organizationalUnit": "string",
"countryRegion": "string"
}
```
* **各欄位可以空缺**，但是
* AcctId為必填，會檢查是否為空字串或空白，並檢查Id是否存在。
* Acct可空缺，但若填入，會檢查是否為空字串與或空白，以及是否與既有帳號重複。
* Email可空缺，但若填入，會檢查是否符合email格式。
### Sucess Response
```json
{
"id": "5a0896ca-fe83-4256-92ae-691738766496",
"summary": "Compleated",
"detail": "Data has Changed successfully.",
"code": "200200",
"info": null
}
```
### Exception Response
#### **AcctId** 例外狀況回報範例
AcctId為必填，並會檢查空字串與空白
```json
//AcctId屬性空缺
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-4b1e934266f63df182108ba9afd56c9a-a4583885d82d47f6-00",
"errors": {
"AcctId": [
"The AcctId field is required."
]
}
}
```
```json
//acctId 是空字串或空白
{
"id": "6f5aa86e-db2e-4ac5-834e-aa120896a9dd",
"summary": "Completed With Failures",
"detail": "The AcctId is required.",
"code": "200401",
"info": null
}
```
#### **Acct** 例外狀況回報範例
Acct可空缺，但若填入，會檢查是否為空字串與或全為空白；
```json
{
"id": "02e409ed-d433-4348-b82b-d0e00253d47e",
"summary": "Completed With Failures",
"detail": "Empty fields or white spaces are not allowed for account information.",
"code": "200401",
"info": null
}
```
#### **Email**
## [Post]UserDataCreate
### RequestPacket Spec
| 欄位名稱 | 欄位中文名稱 |可填寫| 資料型態 | 必填 | Unique | 預設 | 備註 |
|---------------------|--------------|---|----------|------|--------|--------------|-------------------------------|
| AcctId | Id | |GUID | - | PK | - | 系統帶入GUID |
| Acct | 帳號 | ✓ | - | ✓ | ✓ | - | 系統檢查是否Unique |
| AdAcct | AD帳號 | ✓ |string | | - | - | |
| Pw | 密碼 | ✓ | string | ✓ | - | - | 大小寫英數字 |
| Name | 用戶名稱 | ✓ |string | | - |(Acct) | 若無填寫系統帶入Acct |
| Email | 電子信箱 | ✓ |string | ✓ | - | - | 忘記密碼必須 |
| OrganizationalUnit | 組織單位 | ✓ |string | | - | - | |
| CountryRegion | 國家/區域 | ✓ |string | | - | - | |
|---------------------|--------------|---|----------|------|--------|--------------|-------------------------------|
| Active | 啟用狀態 | ✓ |bool | - | - | true | 角色建立預設開啟 |
| State | 使用者狀態 | ✓ |int | - | - | - | 預留欄位 |
| RoleId | 權限角色Id | ✓ |GUID | - | - | | |
|---------------------|--------------|---|----------|------|--------|--------------|-------------------------------|
| CreatedOn | 建立日期 | | DateTime | - | - | (Now()) | 建立時，系統帶入使用者建立日期 |
| ModifiedOn | 修改日期 | ✓ |DateTime | - | - | (CreatedOn) | 系統帶入建立日期，其他功能再行調整 |
| LoginOn | 上次登入時間 | |DateTime | - | - | - | 建立時留空 |
| CreatedBy | 建立者 |✓ |GUID | - | - | | |
| ModifiedBy | 上次修改者 | |GUID | - | - | - | |
* '預設'欄位中，以()標示之預設值，表示在應用層由API撰寫程式帶入，並非由資料庫本身撰寫SQL語法預設帶入。
* '備註'欄僅說明建立時的動作，各欄位其他行為，紀錄於其他與該欄位互動之API的說明中。
### Flowchart
```mermaid
flowchart TD
Input((使用者輸入資訊))-->RequestPacketCheck-->RequestPacketComplete-1-->DataInsertSQL[[DataInsertSQL]]-->RetreiveEstablishedData[[Retreive established user data]]-->RequestPacketComplete-2-->DataInsertSQL2[[DataInsertSQL2]]-->Accomplish
subgraph RequestPacketComplete-2
IfCreateByNullInsertAcctId
ModifiedByInsertCreateBy
end
```
* RequestPacketCheck Tasks
|流程圖區塊名稱|意義|實現方法|
|---|---|---|
|AcctRequired| 帳號不為空字串或空白| Attribute
|AcctUnique| 帳號不得重複 | Custom Attribute
|pwRequired| 密碼不得為空字串或空白| Attribute
|pwFormat| 密碼8~20字，包含英數字。| Attribute
|emailRequired| 電子信箱不得為空字串或空白| Attribute
|emailFormat| 電子信箱須為有效格式| Attribute
|IfRoldIdNotNullExists| 若RoldId非空，檢查RoldId是否存在| Custom Attribute
|IfCreateByNotNullExist| 若CreateBy非空，檢查CreateBy是否存在|Custom Attribute|
* RequestPacketComplete-1 Tasks
|流程圖區塊名稱|意義|實現方法|
|---|---|---|
|userIdInserGUID|AcctId 插入guid| exec|
|IfNameNullInsertAcc| 若名稱為空，預設帶入acct|exec|
|IfActiveNullInsertTrue| 若Active為空，預設帶入true| c#物件預設為true|
|CreateOnInsertNow|設定建立日期為現在 | exec|
|ModifiedOnInsertCreateOn| 設定建立日期為CreateOn| exec|
|password encrption|加密密碼|exec|
---
## 附錄
### 用來修改使用者資料相關的sql語法。
```sql
use carbon
-- CREATE TABLES s_role
create table s_role (
roleId varchar(36) not null,
roleName varchar(100) not null,
active bool default true,
state int,
CreatedOn datetime,
CreatedBy varchar(36),
ModifiedOn datetime,
ModifiedBy varchar(36),
primary key (roleId)
);
-- INSERT COLUMNS
insert s_role (roleId, roleName, CreatedOn, CreatedBy, ModifiedOn, ModifiedBy)
values
(UUID(),'Developer', Now(),'Developer', Now(), 'Developer'),
(UUID(),'Admin', Now(),'Developer', Now(), 'Developer'),
(UUID(),'User', Now(),'Developer', Now(), 'Developer');
-- modify columns
ALTER TABLE s_user
MODIFY pw VARCHAR(64) NOT null,
MODIFY email VARCHAR(100) NOT null;
-- drop columns
alter table s_user
drop pic
-- add columns
alter table s_user
ADD acctId VARCHAR(36) not null
ADD countryregion VARCHAR(100),
ADD active BOOL DEFAULT TRUE,
ADD state INT,
ADD loginon DATETIME,
ADD CreatedBy VARCHAR(36),
ADD ModifyBy VARCHAR(36);
-- Change column's name
CHANGE role roleId VARCHAR(36);
-- unique constraint
alter table s_user
add unique(acct, pw);
# one need to specify new primary key as you drop the old one.
-- modify primary key
ALTER TABLE s_user DROP PRIMARY key, add primary key (acctId);
insert s_user (acctId, acct, adacct, pw, name, email, organizationalunit, countryregion, roleId, CreatedOn, ModifiedOn, CreatedBy, ModifiedBy)
values
(UUID(),'TaiweiTest','TaiweiTest','P@s^2w.rd','TaiweiTest','2200767@systex.com','B216','Taiwan','88db3df4-c000-11ee-a1b9-6045bd2120d5',Now(),Now(),'Developer','Developer'),
(UUID(),'TestAdmin','TestAdmin','P@s^2w.rd2','TestAdmin','2200767@systex.com','B216','Taiwan','88db42bf-c000-11ee-a1b9-6045bd2120d5',Now(),Now(),'Developer','Developer');
-- add foreign key
alter table s_user
add foreign key (roleId)
references s_role (roleId);
```
Sign in with Wallet
Connect another wallet