EMP001 (員工基本資料轉入)Router說明

發表於 2024-09-19 分類於 WDS 閱讀次數：

EMPM001(員工基本資料轉入) , 共五個 Router , 說明如下:

Router 1. 小視窗查詢作業流程

路由與方法設定

路由: [Route("QueryUnit")]

HTTP 方法: [HttpPost]

方法描述

方法摘要: 提供單位代號查詢功能，適用於小視窗顯示。

作業流程

查詢功能:

QueryUnitResult 方法會被呼叫來進行單位代號查詢會呼叫 commerService QueryUnitResult。
此方法接受一個可選的 inputVo 參數，若未輸入參數則不啟用任何限制條件，適合用於下拉選單。

查詢邏輯:

QueryUnitResult 會呼叫 _unitmstDao 的 QueryUnit 方法來查詢單位資料。
將查詢結果映射到 Unit_OutputVo 類型的列表中，並返回 ServiceResult<List<Unit_OutputVo>> 結果。

結果處理:

若查詢結果有資料，則設定狀態為 SUCCESS，並將結果返回給呼叫者。
若查詢結果無資料，則設定狀態為 NOTFOUND，並返回相應的提示信息。
若發生例外，則設定狀態為 FAILURE，並返回錯誤信息。

主要程式碼片段

#region 小視窗 => 單位代號
/// <summary>
/// 小視窗 => 單位代號
/// </summary>
/// <param name="inputVo"></param>
/// <remarks>不輸入<paramref name="inputVo"/>即不啟用任何限制條件, 可拿來當下拉選單</remarks>
/// <returns></returns>
public ServiceResult<List<Unit_OutputVo>> QueryUnitResult(Unit_InputVo inputVo = null)
{
    ServiceResult<List<Unit_OutputVo>> serviceResult = new ServiceResult<List<Unit_OutputVo>>();

    try
    {
        List<Unit_OutputVo> result = _unitmstDao.QueryUnit(inputVo)
                                                .Select(x => new Unit_OutputVo
                                                {
                                                    UNIT_ID = x.UNIT_ID,
                                                    UNIT_NAME = x.UNIT_NAME
                                                }).ToList();

        if (result.Count > 0)
        {
            serviceResult.status = CommonEnum.ACTION_STATUS.SUCCESS;
            serviceResult.message = SysMessage.S0100001;
            serviceResult.result = result;
        }
        else
        {
            serviceResult.status = CommonEnum.ACTION_STATUS.NOTFOUND;
            serviceResult.message = SysMessage.S0120001;
        }
    }
    catch (Exception ex)
    {
        serviceResult.status = CommonEnum.ACTION_STATUS.FAILURE;
        serviceResult.message = ex.Message;
        serviceResult.ex = ex;
    }

    return serviceResult;
}
#endregion

註解

ServiceResult<List<Unit_OutputVo>>: 定義了服務方法的返回結果，其中包括查詢狀態、消息和結果列表。
_unitmstDao.QueryUnit: 用於從資料庫中查詢單位資料的方法。
Unit_OutputVo: 查詢結果的輸出模型，包含單位代號和單位名稱。
CommonEnum.ACTION_STATUS: 定義了操作狀態的枚舉，例如 SUCCESS、NOTFOUND 和 FAILURE。
SysMessage: 系統消息類，用於返回提示信息。

這個流程涵蓋了從查詢單位代號到處理查詢結果的完整過程。

Router 2.後勤單位對應檔查詢作業流程

路由與方法設定

路由: [Route("Query")]
HTTP 方法: [HttpPost]

授權: [Authorize] — 認證身份通過才可執行

方法描述

方法摘要: 後勤單位對應檔查詢，根據輸入參數查詢資料庫中 STR_EMP_MASTER 表中的相關資料。

作業流程

查詢功能:

EMPM001Controller 會呼叫 EMPM001Service 的 QueryResult 方法。
EMPM001Service 會呼叫 EMPM001Dao 的 Query 方法，從資料庫中查詢 STR_EMP_MASTER 表中的數據。

查詢邏輯:

QueryResult 方法會檢查公司的 ID 和使用者帳號是否存在，若缺少則返回失敗消息。
若檢查通過，則調用 EMPM001Dao 的 Query 方法來根據 inputVo 查詢資料。

結果處理:

如果查詢結果有資料，則設定狀態為 SUCCESS，並返回查詢結果。
如果查詢結果無資料，則設定狀態為 NOTFOUND，並返回相應的提示信息。
若發生例外，則設定狀態為 FAILURE，並返回錯誤信息。

主要程式碼片段

1. QueryResult 方法:

#region EMPM001Service QUERY
public ServiceResult<List<EMPM001Q_OutputVo>> QueryResult(EMPM001Q_InputVo inputVo)
{
    _logger.LogInformation("查詢 開始 ");
    ServiceResult<List<EMPM001Q_OutputVo>> result = new();
    bool status = true;

    try
    {
        #region 公司別及使用者帳號檢核
        if (string.IsNullOrEmpty(this.CompanyId))
        {
            status = false;
            result.message = String.Format(SysMessage.B0020001, "公司別");
            result.status = ACTION_STATUS.FAILURE;
        }

        if (string.IsNullOrEmpty(this.UserId))
        {
            status = false;
            result.message = String.Format(SysMessage.B0020001, "使用者帳戶");
            result.status = ACTION_STATUS.FAILURE;
        }
        #endregion

        if (status)
        {
            List<EMPM001Q_OutputVo> list = _dao.Query(inputVo);

            // 查詢到資料
            if (list.Count > 0)
            {
                result.message = String.Format(SysMessage.S0100002, "後勤單位對應檔", list.Count);
                result.status = ACTION_STATUS.SUCCESS;
                result.result = list;
            }
            // 沒查到任何資料
            else
            {
                result.status = ACTION_STATUS.NOTFOUND;
                result.message = SysMessage.S0120001;
            }

            _logger.LogInformation($"查詢 結果 {result.status}, 共{list.Count}筆資料 ");
        }
    }
    catch (Exception ex)
    {
        _logger.LogError($"查詢 出現例外: {ex.Message} ");
        result.status = ACTION_STATUS.FAILURE;
        result.message = ex.Message;
        result.ex = ex;
    }

    _logger.LogInformation("查詢 結束 ");
    return result;
}
#endregion

2. Query 方法 (在 EMPM001Dao 類中):

#region EMPM001Dao 的 Query
public List<EMPM001Q_OutputVo> Query(EMPM001Q_InputVo inputVo)
{
    StringBuilder sql = new StringBuilder();
    DynamicParameters parameters = new DynamicParameters();

    sql.Append(@"SELECT EMP_NO, EMP_CNAME, DEPT_NO,
                        REMIT_BANK, BANK_NAME, BANK_ACCOUNT_NO, 
                        UNIT_NAME AS DEPT_NAME
                FROM STR_EMP_MASTER M 
                LEFT JOIN (SELECT UNIT_ID, UNIT_NAME FROM UNIT_MST) S ON M.DEPT_NO = S.UNIT_ID
                WHERE 1 = 1 ");

    #region 查詢參數
    // 員工編號
    if (!string.IsNullOrEmpty(inputVo.EMP_NO))
    {
        sql.Append($"AND EMP_NO = :EMP_NO ");
        parameters.Add("EMP_NO", inputVo.EMP_NO);
    }

    // 員工姓名
    if (!string.IsNullOrEmpty(inputVo.EMP_CNAME))
    {
        sql.Append($"AND EMP_CNAME = :EMP_CNAME ");
        parameters.Add("EMP_CNAME", inputVo.EMP_CNAME);
    }

    // 單位代號
    if (!string.IsNullOrEmpty(inputVo.DEPT_NO))
    {
        sql.Append($"AND DEPT_NO = :DEPT_NO ");
        parameters.Add("DEPT_NO", inputVo.DEPT_NO);
    }

    // 銀行代號
    if (!string.IsNullOrEmpty(inputVo.REMIT_BANK))
    {
        sql.Append($"AND REMIT_BANK = :REMIT_BANK ");
        parameters.Add("REMIT_BANK", inputVo.REMIT_BANK);
    }

    // 銀行名稱
    if (!string.IsNullOrEmpty(inputVo.BANK_NAME))
    {
        sql.Append($"AND BANK_NAME = :BANK_NAME ");
        parameters.Add("BANK_NAME", inputVo.BANK_NAME);
    }

    // 銀行帳號
    if (!string.IsNullOrEmpty(inputVo.BANK_ACCOUNT_NO))
    {
        sql.Append($"AND BANK_ACCOUNT_NO = :BANK_ACCOUNT_NO ");
        parameters.Add("BANK_ACCOUNT_NO", inputVo.BANK_ACCOUNT_NO);
    }
    #endregion

    return _repository.Connection().Query<EMPM001Q_OutputVo>(sql.ToString(), parameters).ToList();
}
#endregion

註解

ServiceResult<List<EMPM001Q_OutputVo>>: 定義了服務方法的返回結果，包含查詢狀態、消息和結果列表。
_dao.Query: 查詢資料庫的方法，會根據輸入參數動態構建 SQL 查詢語句。
EMPM001Q_OutputVo: 查詢結果的輸出模型，包含各種員工相關資料。
ACTION_STATUS: 定義了操作狀態的枚舉，例如 SUCCESS、NOTFOUND 和 FAILURE。
SysMessage: 系統消息類，用於返回提示信息。

這個流程涵蓋了從查詢後勤單位對應檔到處理查詢結果的完整過程。

當然，以下是 Edit 路由的功能概述及其實現細節，使用中文描述：

Router 3: 後勤單位對應檔編輯

端點定義:

路由: /Edit
方法: PUT
授權: 必須認證 ([Authorize])

功能:

這個端點用於編輯後勤單位對應檔中的記錄。它支持新增、更新和刪除記錄。

編輯操作的流程

控制器 (EMPM001Controller)

控制器接收請求，並調用 EMPM001Service 的 EditResult 方法。
服務 (EMPM001Service)
- 方法: EditResult
- 參數: List<EMPM001E> inputVoList
- 返回類型: ServiceResult<int>
步驟:
- 欄位驗證: 使用 IsFieldCheck 檢查提供的數據是否有效。
- 映射: 使用 _mapper.Map 將 EMPM001E 物件轉換為 STR_EMP_MASTER。
- CRUD 操作:
  - 新增: 如果記錄的 _MARK() 狀態是 INSERT，則調用 _empDao.Insert(model)。
  - 更新: 如果記錄的 _MARK() 狀態是 UPDATE，則調用 _dao.Update(model)。
  - 刪除: 如果記錄的 _MARK() 狀態是 DELETE，則調用 _empDao.Delete(model)。
每個操作都包裹在 try-catch 區塊中，以處理潛在的異常。結果會被記錄，並根據操作結果提交或回滾事務。

結果: 返回一個 ServiceResult<int>，包含處理的記錄數量或錯誤詳細信息。

DAO (數據訪問對象) 操作

- **新增操作:**
1
2
3
4
public int Insert(STR_EMP_MASTER model)
{
    // 使用 repository 進行插入操作
}


- **更新操作:**
1
2
3
4
public int Update(STR_EMP_MASTER model)
{
    // 使用 repository 進行更新操作
}


- **刪除操作:**
1
2
3
4
public int Delete(STR_EMP_MASTER model)
{
    // 使用 repository 進行刪除操作
}

主要要點總結

- **身份驗證與授權:** 該端點受保護，需要經過身份驗證的用戶才能訪問。
- **CRUD 操作:** 根據記錄的狀態（`INSERT`、`UPDATE` 或 `DELETE`）支持新增、更新和刪除操作。
- **錯誤處理:** 為每個操作提供了全面的錯誤處理和記錄。
- **事務管理:** 使用事務來確保數據的一致性和完整性，遇到失敗時會進行回滾。

請求示例

要調用此端點，可以發送一個 PUT 請求到 `/Edit`，請求的內容是一個要編輯的記錄列表。每條記錄必須包含必要的字段和狀態標記（`INSERT`、`UPDATE` 或 `DELETE`）。

請求主體示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
[
    {
        "EMP_NO": "12345",
        "EMP_CNAME": "John Doe",
        "DEPT_NO": "D001",
        "REMIT_BANK": "BankA",
        "BANK_NAME": "Bank A",
        "BANK_ACCOUNT_NO": "1234567890",
        "_MARK": "INSERT"
    },
    {
        "EMP_NO": "67890",
        "EMP_CNAME": "Jane Smith",
        "DEPT_NO": "D002",
        "REMIT_BANK": "BankB",
        "BANK_NAME": "Bank B",
        "BANK_ACCOUNT_NO": "0987654321",
        "_MARK": "UPDATE"
    }
]


這種結構可以讓系統在單次請求中處理多條記錄，根據指定的狀態執行相應的操作。

Router 4: 文字檔轉入作業流程

路由與方法設定

路由: [Route("DownloadFile")]
HTTP 方法: [HttpPost]

授權: [Authorize]（認證身份通過才可執行）

方法描述

方法摘要: 當按下「文字轉入」按鈕時，進行文字檔轉入作業。

作業流程

驗證與呼叫:

EMPM001Controller 會呼叫 BaseController 的 SetAuthModel 來驗證公司代號、使用者代號、區域代號。
EMPM001Controller 會呼叫 EMPM001Service 的 DownloadFileResult 方法，並傳入 EMPM001DownloadFile_InputVo，返回結果為 status.status 代碼和 status.message。

下載檔案設定:

EMPM001Service 會呼叫 ConfigurationHelper 取得 FILE_UPLOAD_SETTING 檔案上傳路徑的 JSON 檔設定。
EMPM001Service 會利用 SftpHelper 進行 SFTP 連線，使用 sftpConn.E001 的登入參數。

檔案下載:

EMPM001Service 會呼叫 SftpHelper 的 DownloadFile 方法進行檔案下載。

解壓縮檔案:

下載後的檔案會使用 File.OpenRead(tarFileName) 方法讀取檔案，然後利用 ExtractTar 方法解壓縮 .tar 檔，將其內容提取為 .txt 文件。

檔案上傳與存儲:

EMPM001Service 會利用 FtpHelper 進行 FTP 連線，使用 FTPConn.E002 的登入參數。
EMPM001Service 會呼叫 FtpHelper 的 UploadFile 方法將解壓縮後的 .txt 文件上傳至財會主機。
上傳後的 .txt 文件會被寫入到 DB 的 CSV_TEMP 暫存表中，使用 CSV_TEMPDao 的 Insert 方法完成寫入。

轉入正式資料表:

EMPM001Service 會呼叫 EMPM001PKDao 的 GET_DATA 方法，將 CSV_TEMP 中的資料轉入正式的 EMP_001 表格，執行存儲過程 Execute("EMPM001.GET_DATA", ref parameters) 進行資料轉入。

主要程式碼片段

SFTP 下載伺服器設定:

case SFTPConn.E001:
    var list1 = _dao.Query(new WebAPI_Example_Common.Model.Gfaa.Table.SYS_PARM_D()
    {
        PARM_ID = "SFTP",
        PARM_VALUE1 = "EMPM001",
        PARM_ID_CODE = sftpConn.ToString()
    });

    var setting1 = list1.First();
    _host = setting1.PARM_VALUE3;
    _username = setting1.PARM_VALUE4;
    _password = setting1.PARM_VALUE5;
    _remotePath = setting1.PARM_VALUE6;
    _downloadPath = setting1.PARM_VALUE8;
    _port = Int32.Parse(setting1.PARM_VALUE9);

解壓縮 .tar 檔:

public void ExtractTar(String tarFileName, String destFolder)
{
    Stream inStream = File.OpenRead(tarFileName);
    TarArchive tarArchive = TarArchive.CreateInputTarArchive(inStream);
    tarArchive.ExtractContents(destFolder);
    tarArchive.Close();
    inStream.Close();
}

FTP 上傳伺服器設定與上傳:

case FTPConn.E002:
    var list2 = _dao.Query(new WebAPI_Example_Common.Model.Gfaa.Table.SYS_PARM_D()
    {
        PARM_ID = "FTP",
        PARM_VALUE1 = "EMPM001",
        PARM_ID_CODE = ftpConn.ToString()
    });

    var setting2 = list2.First();
    _host = setting2.PARM_VALUE3;
    _username = setting2.PARM_VALUE4;
    _password = setting2.PARM_VALUE5;
    _remotePath = setting2.PARM_VALUE6;
    _remoteOkPath = setting2.PARM_VALUE7;
    _port = 21;

public bool UploadFile(byte[] fileContent, string remoteFileName, bool useBinary, out string errorMessage)
{
    errorMessage = null;
    FtpWebRequest request;
    try
    {
        _logger.LogInformation($"FTP上傳檔案開始 檔案名稱:{remoteFileName}");
        request = (FtpWebRequest)WebRequest.Create($"ftp://{_host}/{_remotePath}/{remoteFileName}");
        request.Method = WebRequestMethods.Ftp.UploadFile;
        request.Credentials = new NetworkCredential(_username, _password);
        request.UseBinary = useBinary;
        using (Stream ftpStream = request.GetRequestStream())
        {
            ftpStream.Write(fileContent, 0, fileContent.Length);
        }

        if (!string.IsNullOrWhiteSpace(_remoteOkPath))
        {
            _logger.LogInformation($"FTP上傳檔案備份開始 檔案名稱:{remoteFileName}");
            request = (FtpWebRequest)WebRequest.Create($"ftp://{_host}/{_remoteOkPath}/{remoteFileName}");
            request.Method = WebRequestMethods.Ftp.UploadFile;
            request.Credentials = new NetworkCredential(_username, _password);
            request.UseBinary = useBinary;
            using (Stream ftpStream = request.GetRequestStream())
            {
                ftpStream.Write(fileContent, 0, fileContent.Length);
            }
        }
        _logger.LogInformation($"FTP上傳檔案成功 ");
        return true;
    }
    catch (Exception ex)
    {
        errorMessage = $"FTP上傳檔案失敗 {ex.Message}";
        _logger.LogError(errorMessage);
        return false;
    }
}

這個流程涵蓋了從下載文件、解壓縮、上傳、以及將資料轉入正式表格的整體作業。

Router 5 資料重整作業流程

路由與方法設定

路由: [Route("InsertData")]
HTTP 方法: [HttpPost]

授權: [Authorize]（認證身份通過才可執行）

方法描述

方法摘要: 當按下「資料重整」按鈕時，進行資料重整作業。

作業流程

驗證與呼叫:

ENON001Controller 會執行非同步作業 async Task<ApiResult> InsertData。
EMPM001Controller 會呼叫 BaseController 的 SetAuthModel 方法來驗證公司代號、使用者代號、區域代號。
EMPM001Controller 會呼叫 EMPM001Service 的 InsertDataResult(inputVo) 方法，並傳入 EMPM001DownloadFile_InputVo，返回結果為 status.status 代碼和 status.message。

記錄過程:

EMPM001Service 會呼叫 BaseService 的 ILogger 來記錄處理過程。

執行資料重整:

EMPM001Service 會呼叫 EMPM001PKDao 的 INS_DATA 方法，並傳入參數 P_FILE。
INS_DATA 方法會執行存儲過程 Execute("EMPM001.INS_DATA", ref parameters)。

主要程式碼片段

INS_DATA 方法:

public void INS_DATA(string P_FILE, out string p_err_msg)
{
    DynamicParameters parameters = new DynamicParameters();

    parameters.Add("P_FILE", P_FILE);

    parameters.Add(name: "P_ERR_MSG",
                    size: 200,
                    dbType: DbType.String,
                    direction: ParameterDirection.Output);

    Execute("EMPM001.INS_DATA", ref parameters);
    p_err_msg = parameters.Get<string>("P_ERR_MSG");
}

註解

SetAuthModel: 用於驗證所需的參數，如公司代號、使用者代號和區域代號。
InsertDataResult: 將 inputVo 傳入 EMPM001Service 的方法，處理資料重整操作。
INS_DATA: 呼叫存儲過程來處理資料重整，並傳回錯誤信息。

這個流程涵蓋了從驗證、記錄過程、到資料重整的整體作業。