Skill asset

編輯 Skill

Skill 是完整資料夾資產；建立後可逐一加入腳本、參考文件、範本、圖片與子資料夾。

Skill 名稱

唯一代稱

簡短說明

主要分類

標籤

SKILL.md

五種工具預設適用

---
name: chmc-library
description: CHMC.dll 完整 Agent 操作手冊，涵蓋加解密、日誌、組態、流水號、郵件發送、資料庫存取等所有封裝工具。
trigger: ["CHMC", "AES", "DES", "TripleDES", "Log", "Config", "LibLastID", "MailClient", "FileHelper", "DbHelperSQL", "DbTransaction", "StringHelper", "Sybase", "加解密", "加密", "解密", "日誌", "組態", "流水號", "郵件", "檔案下載", "編碼轉換"]
version: 1.0.0
author: AI Agent
---

# 🛠️ CHMC.dll (醫院共用基礎建設核心 DLL) 操作手冊

## 🎯 核心原則

作為一位具備深度資安保護意識的資深開發 Agent，你在開發任何需要讀寫組態、連線資料庫、寄發電子郵件、讀寫寫入日誌、加解密資料時，**優先、必須且絕對**只能使用 `CHMC.dll` 中已封裝好的方法。

**🚨 絕對禁止 (CRITICAL):**
1. **禁止自己刻**：嚴禁手動宣告 `System.Data.SqlClient.SqlConnection` 或 `Sybase.Data.AseClient.AseConnection`。
2. **禁止自造密碼學**：嚴禁直接使用 `System.Security.Cryptography` 下的類別，必須使用 `CHMC.AES` / `CHMC.DES` / `CHMC.TripleDES`。
3. **禁止亂寫 Log**：嚴禁自己寫 `File.WriteAllText` 來記錄錯誤，必須呼叫 `CHMC.Log.WriteLog()`。
4. **禁止組態硬編碼**：嚴禁將連線字串或設定寫死在程式碼中，必須透過 `CHMC.Config` 或 `Utility.SybaseConnectionString` 取得。

---

## 📦 模組詳細操作指南

### 1. 🗄️ 資料庫存取模組：`CHMC.DB.AseClient.DbHelperSQL`

負責攔截所有對 Sybase ASE 資料庫的存取。此模組會自動處理連線開啟/關閉與錯誤記錄，但**不處理 Business Logic**。所有的 Data Access Layer (DAL) 都**必須**繼承並使用此類別。

#### 核心方法與簽章 (CRITICAL)

**⚠️ `DbHelperSQL` 的方法不接受省略參數，請嚴格遵守以下簽章：**

##### A. 查詢資料並回傳 `DataSet`
```csharp
// 必須傳入完整 4 個參數！
// 參數1: SQL 語法 (string)
// 參數2: 執行類型 (CommandType.Text 或 CommandType.StoredProcedure)
// 參數3: 參數陣列 (AseParameter[])。若無參數，必須傳 null！
// 參數4: DataTable 的名稱 (string)。通常帶入 DAL 本身的 TableName 常數。
public DataSet FillDataSet(string sql, CommandType cmdType, IDataParameter[] parameters, string tableName)
```

##### B. 執行新增/修改/刪除 (回傳受影響的資料筆數)
```csharp
// 必須傳入完整 3 個參數！
// 參數1: SQL 語法 (string)
// 參數2: 執行類型 (CommandType.Text 或 CommandType.StoredProcedure)
// 參數3: 參數陣列 (AseParameter[])。若無參數，必須傳 null！
public int ExecuteNonQuery(string sql, CommandType cmdType, IDataParameter[] parameters)
```

**✅ 最佳實踐範例 (於 DAL 中):**
```csharp
// 查詢範例
string sql = "SELECT * FROM my_table_m WHERE id = @id";
AseParameter[] parameters = { new AseParameter("@id", id) };
// 若為 null 參數: parameters = null;
DataSet ds = base.FillDataSet(sql, CommandType.Text, parameters, "my_table_m");

// 執行範例
string sqlExec = "UPDATE my_table_m SET status = 1 WHERE id = @id";
int rows = base.ExecuteNonQuery(sqlExec, CommandType.Text, parameters);
```

---

### 2. 🔐 加解密模組：`CHMC.AES` / `CHMC.DES` / `CHMC.TripleDES`

統一的對稱式加解密工具，用於保護敏感資料。

#### A. AES (靜態方法)
```csharp
// 系統預設 Key / IV 加密
string encryptedText = CHMC.AES.Encrypt(plainText);
string decryptedText = CHMC.AES.Decrypt(encryptedText);

// 自訂 Key / IV 加密
string customEncrypted = CHMC.AES.Encrypt(myKey, myIv, plainText);
string customDecrypted = CHMC.AES.Decrypt(myKey, myIv, customEncrypted);
```

#### B. DES (實例化方法)
**⚠️ DES 必須先被 `new` 起來，不能當靜態方法呼叫！**
```csharp
CHMC.DES des = new CHMC.DES(myKey, myIv);
// 單筆字串
string encrypted = des.EncryptString(plainText);
string decrypted = des.DecryptString(encrypted);
// 批次 Byte 陣列
byte[] encBytes = des.Encrypt(plainBytes);
byte[] decBytes = des.Decrypt(encBytes);
```

#### C. TripleDES (靜態方法)
```csharp
string encryptedText = CHMC.TripleDES.Encrypt(plainText);
string customEncrypted = CHMC.TripleDES.Encrypt(myKey, myIv, plainText);
```

---

### 3. 📝 錯誤日誌紀錄：`CHMC.Log`

所有系統發生例外 (`Exception`) 時，**唯一且必須**使用的紀錄工具。會將訊息 寫入 `組態檔/appSettings/ErrorLogFolder` 指定的路徑 與 `組態檔/appSettings/ErrorLogName` 指定的檔名  結構中。

#### 核心方法
```csharp
// 1. 記錄一般字串資訊 / 警告
CHMC.Log.WriteLog("自定義錯誤訊息或除錯資訊");

// 2. (最常用) 攔截 Exception 並完整記錄
try {
    // 業務邏輯...
} catch (Exception ex) {
    CHMC.Log.WriteLog(ex); // 傳入 Exception 物件
    throw; // 或包裝後拋出
}
```

---

### 4. 🔤 字串與編碼轉換模組：`CHMC.StringHelper`

負責處理 Sybase 特有的 CP850 編碼問題，以及隨機字串生成。

#### A. Sybase 編碼轉換 (CRITICAL)
**⚠️ 若未進行轉換，中文存入或讀出 Sybase 資料庫將變成亂碼！**
```csharp
// 寫入資料庫前：將 Unicode (系統預設) 轉為 CP850 (Sybase 要求)
string cp850Str = CHMC.StringHelper.UnicodeTransCP850("中文測試");
// 範例: new AseParameter("@name", CHMC.StringHelper.UnicodeTransCP850(dto.Name))

// 從資料庫讀出後：將 CP850 轉回 Unicode 以利正確顯示
string unicodeStr = CHMC.StringHelper.CP850TransUnicode(dbValue);
```

#### B. 實用字串工具
```csharp
// 產生長度 10 的隨機亂數
string randomCode = CHMC.StringHelper.RandString(10);
// 進階產生：長度 10，要包含 [數字, 符號, 小寫字母, 大寫字母]
string strongPwd = CHMC.StringHelper.RandString(10, true, true, true, true);

// 數字轉為中文大寫 (如 1234 -> 壹仟貳佰參拾肆)
string financialChinese = CHMC.StringHelper.FinancialNumToChinese(1234);
```

---

### 5. ⚙️ 設定檔讀取：`CHMC.Config`

負責讀取 `Web.config`, `AppSettings.config`, `ConnectionStrings.config` 的安全通道。

#### 核心方法
```csharp
// 1. 讀取 AppSettings.config 內的 key 
string mySetting = CHMC.Config.appSettings("MyCustomKey");

// 2. 讀取連線字串 (但 DAL 初始化優先使用 Utility.SybaseConnectionString)
string connStr = CHMC.Config.ConnectionString(); // 預設 DB
string specificConn = CHMC.Config.ConnectionString("OtherDBName");

// 3. 取得 Log 目錄
string logPath = CHMC.Config.LogFolder(); 

// 4. 重新指定 Log 路徑與檔名
CHMC.Log.SetNewFloder("C:\\LogTemp\\UniqueTest\\", "host");
```


---

### 6. 🔢 全院唯一流水號產生器：`CHMC.LibLastID`

負責產生不重複的業務代碼（如病歷號、訂單號）。會存取 Sybase DB 鎖定資源以保證唯一性。

#### 核心方法
**⚠️ 執行完畢後必須呼叫 `Dispose()` 或使用 `using` 區塊釋放資料庫資源。**
```csharp
// 假設你在資料庫 Last_ID_Table 有註冊一個 TypeID 叫做 "ORDER_NO"
using (CHMC.LibLastID lastIdGen = new CHMC.LibLastID("ORDER_NO")) {
    
    // 取得下一個流水號字串
    string nextNo = lastIdGen.GetLastID("ORDER_NO"); 
    
    // 取得下一個流水號，並指定長度 (前面自動補 0)
    // 例如：GetLastID("ORDER_NO", 5) 回傳 "00042"
    string nextPaddedNo = lastIdGen.GetLastID("ORDER_NO", 5);
}
```

---

### 7. 📧 電子郵件發送器：`CHMC.MailClient`

封裝 SMTP 發信邏輯，支援附件與 CC/BCC 密件副本，並內建記錄狀態。

#### 標準發送流程
```csharp
// 1. 建立實體 (建議使用 using)
using(CHMC.MailClient mail = new CHMC.MailClient()) {
    
    // 2. 填寫主要資訊
    // fillMailInfo(寄件者名, 寄件者信箱, 信件主旨, 信件內容)
    mail.fillMailInfo("系統管理員", "admin@chgh.org.tw", "主旨", "<h1>內容</h1>");
    
    // 3. 設定格式
    mail.setBodyFormatHtml();	// 指定郵件格式為「Html」
	//mail.setBodyFormatText();	// 指定郵件格式為「文字」
    
    // 4. 加入收件人 (可多次呼叫加入多人)
    mail.addReceiver("user@example.com");
    mail.addCarbonCopy("boss@example.com"); // CC 副本
    
    // 5. 加入附件 (傳入 MemoryStream 或 Byte[])
    // mail.addAttachment(myMemoryStream, "Report.pdf");
    
    // 6. 執行發送
    bool isSuccess = mail.Send();
}
```

---

### 8. 🌐 靜態網頁與檔案下載工具：`CHMC.Web.FileHelper`

#### A. 讀取靜態 HTML 檔案內容
```csharp
// 讀取伺服器上的 HTML 檔作為字串 (常配合作為信件版型)
string htmlContent = CHMC.Web.FileHelper.GetHtmlContent(Server.MapPath("~/Template/Email.html"));
```

#### B. 觸發客戶端檔案下載 (Response Write)
**⚠️ 此方法會呼叫 `Response.End()` 阻斷後續生命週期，請放置於管線最後。**
```csharp
// 將字串內容轉為檔案讓前端下載
CHMC.Web.FileHelper.DownloadFile("Report.csv", "A,B,C\n1,2,3", System.Text.Encoding.UTF8);

// 或使用 byte[] 下載
// CHMC.Web.FileHelper.DownloadFile(fileName, MIME_Type, fileExtension, byte_array);
```

---

### 9. 🗂️ 交易管理：`CHMC.DB.AseClient.DbTransaction`

當跨多個資料表的新增/修改需要具備 ACID 特性時使用。

```csharp
/// <summary>
/// 變更員工姓名
/// </summary>
/// <param name="_employee_id"></param>
/// <param name="_employee_name"></param>
/// <param name="_Msg"></param>
/// <returns></returns>
/// <exception cref="Exception"></exception>
public Int32 UpdateEmployeeName(String _employee_id, String _employee_name, out String _Msg)
{
    Int32 intReturn = Enumeration.ReturnCode.FAILURE;
    List<string> lstMsg = new List<string>();

    BizUserPriority bizUserPriority = null;

    DbTransaction dbTransaction = null;

    DboEmployee dboemployee = null;
    DboUserPriority dboUserPriority = null;

    try
    {
        #region 使用 交易物件
        dbTransaction = new DbTransaction(Utility.SybaseConnectionString);
        dbTransaction.TransactionIsolationLevel = IsolationLevel.ReadCommitted;
        dbTransaction.BeginTransaction();

        dboemployee = new DboEmployee(dbTransaction);
        dboemployee.Update(_employee_id, _employee_name);

        // 假設 CheckPassword 可以獨立執行
        bizUserPriority = new BizUserPriority(dbTransaction);
        bizUserPriority.CheckPassword(_employee_id, null, out _Msg);
        lstMsg.Add(_Msg);

        dboUserPriority = new DboUserPriority(dbTransaction);
        dboUserPriority.Update(_employee_id, _employee_name, null, null, null, null);

        dbTransaction.CommitTransaction();
        #endregion 使用 交易物件

        lstMsg.Add("員工姓名變更成功");
        intReturn = Enumeration.ReturnCode.SUCCESS;
    }
    catch (Exception ex)
    {
        lstMsg.Add("員工姓名變更失敗，請洽資訊室！");
        if (dbTransaction != null)
        {
            dbTransaction.RollBackTransaction();
            dbTransaction.Dispose();
        }

        Log.WriteLog("Bizemployee.Update Error : " + ex.Message);
        throw new Exception("Bizemployee.Update Error : " + ex.Message, ex);
    }
    finally
    {
        _Msg = string.Join(Environment.NewLine, lstMsg);

        lstMsg.Clear();
        lstMsg = null;
        bizUserPriority = null;
        dbTransaction = null;
        dboemployee = null;
        dboUserPriority = null;
    }

    return intReturn;
}
```

必須包含 YAML frontmatter 的 name 與 description。

修改說明

取消