---
# System prepended metadata

title: ESG碳足跡-使用者管理API 知識文件

---

## 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);


```