```markdown
## Case #2: 單向傳遞 - MessageClient 介面與配置抽離

### Problem Statement（問題陳述）
**業務場景**：多個業務服務需要將工作提交給後端工作者（Worker），不需等待結果。每個專案各自處理 RabbitMQ 連線與佇列配置，導致重工與易錯。需要簡單 API 發送消息並統一配置管理。
**技術挑戰**：發送端要隱藏連線與佇列細節；支持 DI 注入 TrackContext 與 Options；保持泛型消息契約。
**影響範圍**：所有單向投遞的業務流程；可靠性與開發效率。
**複雜度評級**：中

### Root Cause Analysis（根因分析）
**直接原因**：
1. 每個團隊重複書寫連線/序列化/發佈。
2. 配置來源分散，變更需改碼。
3. 缺乏標準化 Headers/追蹤傳遞。

**深層原因**：
- 架構層面：缺少發送端 SDK 規範。
- 技術層面：未使用 Options 模式與 DI。
- 流程層面：未落實集中配置管理。

### Solution Design（解決方案設計）
**解決策略**：提供 MessageClient<T> 並以 MessageClientOptions 聚合配置；支援 DI 注入 TrackContext/ILogger；泛型消息自動 JSON 序列化；傳回 correlationId 便於追蹤。

**實施步驟**：
1. 設計 Options 與建構子注入
- 實作細節：MessageClientOptions（連線、佇列名、BusType）。
- 所需資源：Microsoft.Extensions.Options 或自定。
- 預估時間：0.5 天。

2. 實作 SendMessage 與 Headers 注入
- 實作細節：序列化、BasicProperties、CorrelationId。
- 所需資源：RabbitMQ.Client、Newtonsoft.Json。
- 預估時間：0.5 天。

**關鍵程式碼/設定**：
```csharp
public class MessageClient<TInputMessage> : MessageClientBase {
    public string SendMessage(string routing, TInputMessage input, Dictionary<string,string> headers) {
        string correlationId = Guid.NewGuid().ToString("N");
        // 建立 IBasicProperties，填入 headers、correlationId
        // channel.BasicPublish(...);
        return correlationId;
    }
}

// Demo
using (var client = new MessageClient<DemoMessage>(new MessageClientOptions{
    ConnectionName="benchmark-client", BusType=QUEUE, QueueName="benchmark-queue"
}, null, null)) {
    for(int i=0;i<50000;i++) client.SendMessage("", new DemoMessage(), null);
}

```markdown
## Case #3: 單向傳遞 - MessageWorker 與 BackgroundService 整合

### Problem Statement（問題陳述）
**業務場景**：後端背景服務需長時間消費佇列中的任務，並在系統啟停時正確管理生命週期。希望遵循 .NET Core 標準（IHostedService/BackgroundService），便於容器化與雲端部署。
**技術挑戰**：需正確啟動/停止；註冊事件；處理多執行緒；與 DI 整合；避免資源洩漏。
**影響範圍**：所有後端 Worker；部署與維運流程。
**複雜度評級**：中

### Root Cause Analysis
**直接原因**：
1. 自建啟停流程易遺漏資源釋放。
2. 沒有標準生命周期，難以對接 orchestrator。
3. 多執行緒與事件處理易出現同步問題。

**深層原因**：
- 架構層面：未採用 IHostedService 標準模型。
- 技術層面：對 RabbitMQ channel/consumer/thread 管理不足。
- 流程層面：啟停/部署流程未標準化。

### Solution Design
**解決策略**：MessageWorker<T> 繼承 BackgroundService；在 ExecuteAsync 初始化連線/通道/消費者；註冊 Received；Stop 時解除處理流程、等待未完成任務、釋放資源。

**實施步驟**：
1. 建立通道/消費者並註冊事件
- 實作細節：BasicQos/BasicConsume；多通道對應多 worker。
- 資源：RabbitMQ.Client。
- 時間：1 天。

2. Stop 時解除事件並等待
- 實作細節：移除 Received；等待 in-flight 完成再關閉。
- 資源：AutoResetEvent、Interlocked。
- 時間：0.5 天。

**關鍵程式碼/設定**：
```csharp
public abstract class MessageWorkerBase : BackgroundService {}
public class MessageWorker<T> : MessageWorkerBase {
    public delegate void MessageWorkerProcess(T msg, string cid, IServiceScope scope=null);
    public MessageWorkerProcess Process;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken) {
        // 建立多個 channel/consumer
        // await Task.Run(()=> stoppingToken.WaitHandle.WaitOne());
        // 移除 consumer handlers, 等待 _subscriber_received_count 歸零
        // 關閉 channel/connection
    }
}

```markdown
## Case #4: 多執行緒平行處理與多 Channel/Consumer 設計

### Problem Statement
**業務場景**：高吞吐工作隊列需要同時處理多則消息，提高處理速度。RabbitMQ 官方不建議跨執行緒共享 channel，需找最佳並行結構。
**技術挑戰**：並行處理與順序控制；每個 channel/consumer 的資源成本與效能平衡；公平調度。
**影響範圍**：吞吐量、資源使用、穩定性。
**複雜度評級**：高

### Root Cause Analysis
**直接原因**：
1. 共享 channel 會強制順序造成阻塞。
2. 單 channel 多 consumer 仍有序列化處理。
3. 不當並行造成競態與 ack 問題。

**深層原因**：
- 架構層面：未建立「每執行緒一 channel」策略。
- 技術層面：缺乏對 BasicQos、prefetch 的理解。
- 流程層面：並行度未納入配置與校正。

### Solution Design
**解決策略**：每個 worker thread 對應一個 channel + consumer；透過 Options 曝露 WorkerThreadsCount、PrefetchCount；在 ExecuteAsync 迴圈建立對應數量資源，Stop 時逐一釋放。

**實施步驟**：
1. 初始化多通道與消費者
- 細節：第一個通道負責 QueueDeclare；其餘只消費。
- 資源：RabbitMQ.Client。
- 時間：0.5 天。

2. 設定 Prefetch 與調整並行度
- 細節：BasicQos；測試不同並行/預取的吞吐。
- 資源：性能測試工具。
- 時間：1 天。

**關鍵程式碼/設定**：
```csharp
for (int i=0; i<options.WorkerThreadsCount; i++) {
    var channel = connection.CreateModel();
    if (i==0) channel.QueueDeclare(queue: options.QueueName, durable: options.QueueDurable, exclusive:false, autoDelete:false, arguments:null);
    var consumer = new EventingBasicConsumer(channel);
    consumer.Received += (s,e)=> Subscriber_Received(s,e,channel);
    channel.BasicQos(0, options.PrefetchCount, true);
    channel.BasicConsume(options.QueueName, false, consumer);
}

```markdown
## Case #5: Graceful Shutdown 與在途任務收斂

### Problem Statement
**業務場景**：自動擴縮或部署關閉時，Worker 不應丟失處理中的消息，需要等待在途任務完成再關閉，避免半成品與資料不一致。
**技術挑戰**：正確停止接收新消息；追蹤在途數量；等待完成再關閉連線；避免死鎖。
**影響範圍**：資料一致性、可靠性與維運可信度。
**複雜度評級**：高

### Root Cause Analysis
**直接原因**：
1. 立即中止會造成未 ack 消息丟失或重複。
2. 無在途計數與等待機制。
3. 提前關閉連線導致 ack 失敗。

**深層原因**：
- 架構層面：生命週期未設計為可維運。
- 技術層面：缺乏 WaitHandle/Interlocked 的使用。
- 流程層面：部署/擴縮未要求優雅關閉。

### Solution Design
**解決策略**：Stop 時解除 Received handler 阻止新消息；使用 _subscriber_received_count 計數在途；每次處理完成 Set AutoResetEvent 喚醒等待；直到計數歸零再釋放資源。

**實施步驟**：
1. 停止接收新消息
- 細節：Received -= handler。
- 資源：RabbitMQ.Client。
- 時間：0.5 天。

2. 在途計數與等待
- 細節：Interlocked.Increment/Decrement；AutoResetEvent 協調。
- 資源：System.Threading。
- 時間：1 天。

**關鍵程式碼/設定**：
```csharp
// Stop: 移除 handlers
for(int i=0;i<options.WorkerThreadsCount;i++){
    consumers[i].Received -= handlers[i]; handlers[i]=null;
}
// 等待在途處理完成
while(_subscriber_received_count>0) _subscriber_received_wait.WaitOne();

// 在處理委派前後
Interlocked.Increment(ref _subscriber_received_count);
// ...處理...
Interlocked.Decrement(ref _subscriber_received_count);
_subscriber_received_wait.Set();

```markdown
## Case #6: RPC over RabbitMQ（reply_to + correlationId 雙向封裝）

### Problem Statement
**業務場景**：某些服務需同步獲得結果（請求/回應）。希望以 MQ 實作 RPC 模式，避免 REST 直連耦合，同時保留 MQ 的可靠性與解耦。
**技術挑戰**：回應路徑設計；關聯請求/回應；每 Client 的回覆佇列；低延遲回傳。
**影響範圍**：跨服務同步流程；效能與可靠性。
**複雜度評級**：高

### Root Cause Analysis
**直接原因**：
1. 回應消息與請求配對困難。
2. 共用回覆佇列會造成排隊與干擾。
3. 客戶端離線後回覆資源未釋放。

**深層原因**：
- 架構層面：無通用 RPC 模式與契約。
- 技術層面：對 reply_to/correlationId/專用回覆佇列掌握不足。
- 流程層面：缺少封裝，重複樣板碼。

### Solution Design
**解決策略**：MessageClient<TIn,TOut> 支援 RPC；每 Client 產生專屬 ReplyQueue；發送訊息附帶 correlationId/reply_to；Worker 回傳時按標頭傳回；Client 端監聽回覆佇列，快速對應並回傳結果。

**實施步驟**：
1. 擴充泛型與介面
- 細節：SendMessageAsync<TIn,TOut>()。
- 資源：C# 泛型/Task。
- 時間：0.5 天。

2. 建立專屬回覆佇列
- 細節：QueueDeclare() 無名臨時佇列；BasicConsume。
- 資源：RabbitMQ.Client。
- 時間：0.5 天。

**關鍵程式碼/設定**：
```csharp
public class MessageClient<TIn,TOut> : MessageClientBase {
    public MessageClient(...){
        ReplyQueueName = channel.QueueDeclare().QueueName;
        ReplyQueueConsumer = new EventingBasicConsumer(channel);
        ReplyQueueConsumer.Received += ReplyQueue_Received;
        channel.BasicConsume(ReplyQueueName, false, ReplyQueueConsumer);
    }
    protected override void SetupMessageProperties(IBasicProperties props){
        props.ReplyTo = ReplyQueueName;
    }
}

```markdown
## Case #7: Async/await 封裝：AutoResetEvent 與 await 橋接

### Problem Statement
**業務場景**：Client 發送 RPC 後需非同步等待結果，避免阻塞主執行緒，並能同時等待多個回應（Task.WaitAll）。
**技術挑戰**：以事件驅動回應（Received）轉為 awaitable；正確對應 correlationId；避免競態。
**影響範圍**：RPC 易用性、效能與可靠性。
**複雜度評級**：高

### Root Cause Analysis
**直接原因**：
1. Received 是事件回呼，難以直接 await。
2. 多請求併發需對應各自回應。
3. 同步阻塞可能造成 thread pool 壓力。

**深層原因**：
- 架構層面：非同步模型未抽象。
- 技術層面：WaitHandle 與 Task 橋接技巧不足。
- 流程層面：缺乏統一非同步封裝。

### Solution Design
**解決策略**：為每個 correlationId 建立 AutoResetEvent 與回應緩存字典；Send 後等待 WaitOne 包裝成 Task.Run 供 await；Received 事件到達時 Set 對應事件並寫入緩存。

**實施步驟**：
1. 建立 waitlist/buffer 字典
- 細節：lock 保護；key=correlationId。
- 時間：0.5 天。

2. 將 WaitOne 包裝成 Task
- 細節：await Task.Run(()=> wait.WaitOne())。
- 時間：0.5 天。

**關鍵程式碼/設定**：
```csharp
private Dictionary<string, TOut> buffer = new();
private Dictionary<string, AutoResetEvent> waitlist = new();
public async Task<TOut> SendMessageAsync(...){
    string cid = PublishMessage(...);
    var wait = new AutoResetEvent(false);
    lock(_sync){ waitlist[cid]=wait; }
    await Task.Run(()=> wait.WaitOne());
    lock(_sync){
        var output = buffer[cid]; buffer.Remove(cid); waitlist.Remove(cid);
        return output;
    }
}
private void ReplyQueue_Received(...){
    var cid = props.CorrelationId; var output = Deserialize<TOut>(body);
    lock(_sync){ buffer[cid]=output; waitlist[cid].Set(); }
    channel.BasicAck(e.DeliveryTag, false);
}

```markdown
## Case #8: MessageClient 回覆消費設計：專屬 ReplyQueue 與共用 Channel

### Problem Statement
**業務場景**：單個 Client 可能同時發多筆 RPC，應降低資源成本且避免回覆的隊列擁塞，並在 Client 離線時釋放資源。
**技術挑戰**：回覆佇列生命周期；回覆消費者的事件處理；與發送端共用連線/通道。
**影響範圍**：資源使用、延遲與穩定性。
**複雜度評級**：中

### Root Cause Analysis
**直接原因**：
1. 共用回覆佇列造成排隊與干擾。
2. 為回覆再開 Worker 過重。
3. Client 離線時未清除回覆資源。

**深層原因**：
- 架構層面：回覆佇列與通道共用策略未定。
- 技術層面：回覆消費事件的同步處理。
- 流程層面：資源管理無生命周期對應。

### Solution Design
**解決策略**：每個 MessageClient 建立一次臨時 ReplyQueue（QueueDeclare 無名）；回覆消費使用與發送同一個 channel；Dispose 時移除事件並刪除回覆佇列。

**實施步驟**：
1. 建立回覆佇列與消費者
- 細節：ReplyQueueConsumer.Received += handler。
- 時間：0.5 天。

2. 正確釋放
- 細節：Received -= handler；QueueDelete。
- 時間：0.5 天。

**關鍵程式碼/設定**：
```csharp
public override void Dispose(){
    ReplyQueueConsumer.Received -= ReplyQueue_Received;
    channel.QueueDelete(ReplyQueueName);
    base.Dispose();
}

```markdown
## Case #9: 避免過度重用：不在 MessageClient 內嵌 MessageWorker

### Problem Statement
**業務場景**：最初嘗試在 MessageClient 內嵌 Worker 來接收回覆，但 RPC 的回覆消費特性與 Worker 的高可靠長期運行不同，導致過度複雜與資源浪費。
**技術挑戰**：找出回覆處理的最小設計；避免多餘的通道/執行緒與關閉負擔。
**影響範圍**：Client 資源占用與簡潔性。
**複雜度評級**：中

### Root Cause Analysis
**直接原因**：
1. 內嵌 Worker 會帶進多執行緒、關閉流程等不必要負擔。
2. 回覆處理需要的是輕量事件消費即可。
3. 過度抽象讓錯誤定位與維運更難。

**深層原因**：
- 架構層面：對角色責任界線不清。
- 技術層面：未針對情境最小化設計。
- 流程層面：重用導致複雜度上升。

### Solution Design
**解決策略**：移除 Client 內嵌 Worker，改為在 MessageClient 以 EventingBasicConsumer 監聽回覆佇列；維持單通道、單事件處理的輕量模型。

**實施步驟**：
1. 重構 Client 回覆處理
- 細節：僅保留事件處理與等待的字典。
- 時間：0.5 天。

2. 測試資源使用與關閉
- 細節：確保 Dispose 即可移除回覆資源。
- 時間：0.5 天。

**關鍵程式碼/設定**：
```csharp
ReplyQueueConsumer = new EventingBasicConsumer(channel);
ReplyQueueConsumer.Received += ReplyQueue_Received;
channel.BasicConsume(ReplyQueueName, false, ReplyQueueConsumer);

```markdown
## Case #10: TrackContext 跨服務傳遞（Headers）

### Problem Statement
**業務場景**：跨多服務的請求需可追蹤（如 RequestId），方便在大量日誌中定位單筆交易。需確保透過 MQ 的請求也能傳遞追蹤資訊。
**技術挑戰**：將追蹤資訊從發送端帶至消費端；避免與消息體耦合；標準化字段。
**影響範圍**：可觀測性、稽核、除錯。
**複雜度評級**：中

### Root Cause Analysis
**直接原因**：
1. 未統一傳遞 request-id，跨服務追蹤困難。
2. 將追蹤放進 message body 容易與業務耦合。
3. 每處自行處理易遺漏。

**深層原因**：
- 架構層面：缺乏跨服務追蹤基礎設施。
- 技術層面：Headers 介面未抽象。
- 流程層面：未將追蹤納入 SDK 規範。

### Solution Design
**解決策略**：定義 TrackContext（如 RequestId）；由 MessageClient 於 Send 時寫入 Headers；Worker 收到消息時讀取 Headers 還原 TrackContext；與 DI 整合讓使用者透明取得。

**實施步驟**：
1. 設計 TrackContext 與序列化
- 細節：字典型式 Headers，或 JSON 放入特定欄位。
- 時間：0.5 天。

2. 在 Send/Receive 兩端抽象
- 細節：SetupMessageProperties/ExtractHeaders。
- 時間：0.5 天。

**關鍵程式碼/設定**：
```csharp
// Client
protected override void SetupMessageProperties(IBasicProperties props){
    base.SetupMessageProperties(props);
    // 將 TrackContext 注入到 props.Headers
}

// Worker
TrackContext.InitScope(scope, GetHeaders(props));
Process(request, props.CorrelationId, scope);

```markdown
## Case #11: TrackContext 與 DI Scope：每訊息隔離注入

### Problem Statement
**業務場景**：Worker 同時處理多訊息，每則訊息的追蹤資訊應在該處理上下文內可用，且不應互相污染。需採用 DI Scope 隔離每條處理。
**技術挑戰**：為每次 Process 建立 Scope；在 Scope 中註冊 TrackContext；避免跨訊息污染。
**影響範圍**：正確性、可維運與安全性。
**複雜度評級**：中

### Root Cause Analysis
**直接原因**：
1. 共用全域狀態導致追蹤錯亂。
2. Worker 並行處理缺乏上下文隔離。
3. 無 DI Scope 管理。

**深層原因**：
- 架構層面：缺乏 per-message scope 概念。
- 技術層面：對 Microsoft DI Scope 應用不足。
- 流程層面：未規範 Handler 解析方式。

### Solution Design
**解決策略**：在 Received 中使用 _services.CreateScope() 建立 Scope；從 Headers 還原 TrackContext 並注入該 Scope；將 Process 委派在此 Scope 執行，處理完即釋放。

**實施步驟**：
1. 每次收到消息建立 Scope
- 細節：using scope 包裹 Process。
- 時間：0.5 天。

2. 在 Scope 注入追蹤
- 細節：TrackContext.InitScope(scope, headers)。
- 時間：0.5 天。

**關鍵程式碼/設定**：
```csharp
using (var scope = _services.CreateScope()){
    TrackContext.InitScope(scope, GetHeaders(props));
    Process(request, props.CorrelationId, scope);
}

```markdown
## Case #12: 並行與吞吐調參：PrefetchCount 與 WorkerThreadsCount

### Problem Statement
**業務場景**：不同負載有不同最佳並行組合。需透過配置調整線程數與預取數來最佳化吞吐與公平性，避免飢餓與壓垮消費端。
**技術挑戰**：找到合適的 WorkerThreadsCount 與 PrefetchCount 組合；避免單一大任務阻塞。
**影響範圍**：效能、穩定性與資源使用。
**複雜度評級**：中

### Root Cause Analysis
**直接原因**：
1. 預取過大導致不公平；過小吞吐不足。
2. 線程不足無法利用 CPU；過多造成切換開銷。
3. 單 channel 限制並行。

**深層原因**：
- 架構層面：並行度未參數化。
- 技術層面：對 Qos 與併發模型理解不足。
- 流程層面：缺少壓測與調參流程。

### Solution Design
**解決策略**：以 Options 提供參數；以每執行緒一 channel 實作；建立壓測腳本驗證不同組合，形成準則。

**實施步驟**：
1. 參數化 Options
- 細節：WorkerThreadsCount、PrefetchCount。
- 時間：0.5 天。

2. 壓測與準則沉澱
- 細節：不同消息大小/耗時評估。
- 時間：1-2 天。

**關鍵程式碼/設定**：
```csharp
channel.BasicQos(0, options.PrefetchCount, true);
// options.WorkerThreadsCount 控制通道/消費者數量

```markdown
## Case #13: ACK 正確性與停止流程：先移除事件後等待完成

### Problem Statement
**業務場景**：停止 Worker 時需確保不再開始新任務，避免未 ack 任務被吞或重送，導致資料不一致。
**技術挑戰**：正確時間點移除事件；計數完成後再關閉；避免提早關閉連線。
**影響範圍**：資料一致性、可靠性。
**複雜度評級**：中

### Root Cause Analysis
**直接原因**：
1. 直接關閉連線造成 ack 失敗。
2. 停止後仍有新任務開始處理。
3. 缺乏分段停止流程。

**深層原因**：
- 架構層面：停止流程不完整。
- 技術層面：事件與 ack 機制理解不足。
- 流程層面：未定義標準關閉步驟。

### Solution Design
**解決策略**：分段關閉：先等 Stop 信號 -> 移除 Received handler -> 等待在途清空 -> 關閉 channel -> 關閉 connection。

**實施步驟**：
1. 分段點控制
- 細節：stoppingToken.WaitHandle.WaitOne()。
- 時間：0.5 天。

2. 正確關閉順序
- 細節：handlers=null -> 計數為 0 -> Close。
- 時間：0.5 天。

**關鍵程式碼/設定**：
```csharp
await Task.Run(()=> stoppingToken.WaitHandle.WaitOne());
// stop receive new messages
consumers[i].Received -= handlers[i]; handlers[i]=null;
// wait inflight -> close channels -> connection.Close()

```markdown
## Case #14: IHostedService 啟停與 ExecuteAsync 中的阻塞處理

### Problem Statement
**業務場景**：BackgroundService 的 ExecuteAsync 需以 await 結束初始化，使宿主能繼續其他任務，同時能在收到停機訊號後返回，以配合 orchestrator。
**技術挑戰**：在 ExecuteAsync 中等待停止訊號但不阻塞宿主；符合 async/await 契約。
**影響範圍**：服務啟動可用性、關閉一致性。
**複雜度評級**：中

### Root Cause Analysis
**直接原因**：
1. 直接 WaitOne 會阻塞，違反 async 契約。
2. 宿主等待鏈無法釋放。
3. 停止訊號無法正確傳遞。

**深層原因**：
- 架構層面：非同步生命週期掌握不足。
- 技術層面：阻塞呼叫需以 Task 包裝。
- 流程層面：缺乏標準樣板。

### Solution Design
**解決策略**：將 WaitHandle.WaitOne 包裝在 Task.Run 內，讓 ExecuteAsync 可 await 並返回 Task；保持非同步模型一致。

**實施步驟**：
1. 包裝阻塞等待
- 細節：await Task.Run(()=> wait.WaitOne())。
- 時間：0.5 天。

2. 驗證啟停行為
- 細節：Start 後立刻返回；Stop 後結束。
- 時間：0.5 天。

**關鍵程式碼/設定**：
```csharp
await Task.Run(() => { stoppingToken.WaitHandle.WaitOne(); });
// 之後進入停止流程

```markdown
## Case #15: Windows OS Shutdown 處理：WindowsHostExtensions + SetConsoleCtrlHandler

### Problem Statement
**業務場景**：在 Windows/.NET Framework 或 Windows 容器中，需正確捕捉 OS 關機訊號來優雅關閉 Worker。部分版本無法靠內建機制捕捉，需要替代方案。
**技術挑戰**：在 Windows 環境捕捉 shutdown；與 IHost 整合；避免容器無法停止。
**影響範圍**：Windows 環境的可維運性與可靠性。
**複雜度評級**：高

### Root Cause Analysis
**直接原因**：
1. 舊版需建立隱藏視窗才能接收訊號。
2. .NET Core/Windows 容器某些組合捕捉失敗。
3. 容器在 LCOW/特定版本有停止異常。

**深層原因**：
- 架構層面：跨平台啟停差異未抽象。
- 技術層面：Win32 API 與 Host 契約整合不足。
- 流程層面：未針對 Windows 撰寫替代封裝。

### Solution Design
**解決策略**：實作 WindowsHostExtensions，使用 SetConsoleCtrlHandler 註冊處理關機信號；在 WaitForWinShutdownAsync 中與 IHost.StopAsync 協同，確保優雅關閉。

**實施步驟**：
1. Win32 處理程序
- 細節：SetConsoleCtrlHandler；ManualResetEvent 同步。
- 時間：1 天。

2. 與 IHost 整合
- 細節：WinStart/WaitForWinShutdown 擴充方法。
- 時間：0.5 天。

**關鍵程式碼/設定**：
```csharp
[DllImport("Kernel32")] static extern bool SetConsoleCtrlHandler(EventHandler handler, bool add);
private static bool ShutdownHandler(CtrlType sig) { close.Set(); close_ack.WaitOne(); return true; }

public static void WinStart(this IHost host){
    SetConsoleCtrlHandler(ShutdownHandler, true);
    host.StartAsync().GetAwaiter().GetResult();
}
public static async Task WaitForWinShutdownAsync(this IHost host,...){
    int index = Task.WaitAny(host.WaitForShutdownAsync(), Task.Run(()=> close.WaitOne()));
    if(index==1){ await host.StopAsync(); close_ack.Set(); SetConsoleCtrlHandler(ShutdownHandler, false); }
}

```markdown
## Case #16: Auto Scaling 與 docker-compose --scale 驗證

### Problem Statement
**業務場景**：運維需以基礎設施工具（如 docker-compose 或 K8s）調整 Worker 數量，期望只操作 --scale 即可自動優雅啟停，而無需進入應用程式內部。
**技術挑戰**：Worker 必須優雅關閉；啟動/停止流程對接 orchestrator；消息不掉不重。
**影響範圍**：可運維性、擴縮效率與穩定性。
**複雜度評級**：中

### Root Cause Analysis
**直接原因**：
1. 應用程式無優雅關閉，導致擴縮風險。
2. 需要自建工具才能擴縮，成本高。
3. 操作複雜依賴 Dev 介入。

**深層原因**：
- 架構層面：未設計 for operation。
- 技術層面：未對接 OS shutdown 與 orchestrator 事件。
- 流程層面：維運與開發分離，缺少回饋循環。

### Solution Design
**解決策略**：完成 Worker 優雅關閉與啟動流程，容器化部署；運維只需 docker-compose --scale consumer=N 操作，即可平滑擴縮；從 logs 驗證處理完成才退出。

**實施步驟**：
1. 容器化部署
- 細節：Dockerfile/compose；環境變數 MQURL。
- 時間：0.5 天。

2. 擴縮驗證
- 細節：logs 觀察 stop 不再接新訊息，處理完退出。
- 時間：0.5 天。

**關鍵程式碼/設定**：
```yaml
# docker-compose (windows)
producer:
  image: demorpc_client
  environment: [ MQURL="amqp://guest:guest@rabbitmq:5672/" ]
consumer:
  image: demorpc_server
  environment: [ MQURL="amqp://guest:guest@rabbitmq:5672/" ]
# 擴縮指令
# docker-compose up -d --scale consumer=2

```markdown
## Case #17: 容器化與部署：Dockerfile、docker-compose、環境變數

### Problem Statement
**業務場景**：需要將 Client/Server 容器化，透過環境變數注入 RabbitMQ 連線，快速部署於雲端或本機。
**技術挑戰**：Windows 容器鏡像選擇；與 MQ 服務連線；Compose 服務間網路。
**影響範圍**：交付速度、環境一致性與可重現性。
**複雜度評級**：低

### Root Cause Analysis
**直接原因**：
1. 手動部署易出錯，環境不一致。
2. 連線字串寫死在程式碼。
3. 本機/雲端建立 MQ 依賴繁瑣。

**深層原因**：
- 架構層面：缺乏容器化標準。
- 技術層面：未抽離配置至環境變數。
- 流程層面：CI/CD 缺乏 artifacts 管理。

### Solution Design
**解決策略**：撰寫 Dockerfile（Windows ltsc2019 基底）；以環境變數 MQURL 注入連線；Compose 定義 rabbitmq、producer、consumer；以 nat 網路互通。

**實施步驟**：
1. Dockerfile 撰寫
- 細節：COPY、ENV、CMD。
- 時間：0.5 天。

2. Compose 定義與啟動
- 細節：depends_on；--scale 擴縮。
- 時間：0.5 天。

**關鍵程式碼/設定**：
```dockerfile
FROM mcr.microsoft.com/windows/servercore:ltsc2019
WORKDIR c:/demorpc_server
COPY . .
ENV MQURL=amqp://guest:guest@rabbitmq:5672/
CMD demorpc_server.exe %MQURL%

```markdown
## Case #18: 設計面治理：Design for Operation 與用 Infra 工具取代自建管控

### Problem Statement
**業務場景**：DevOps 實踐需要服務能以標準工具維運（K8s/Compose/Swarm），避免自建管理平台與腳本。開發需在設計階段內建可維運性。
**技術挑戰**：將啟停、配置、註冊、追蹤、擴縮以標準化方式整合；降低運維複雜度。
**影響範圍**：整體交付效率與穩定性。
**複雜度評級**：高

### Root Cause Analysis
**直接原因**：
1. 把複雜步驟自動化但未標準化，仍難維運。
2. 擴縮需開發者介入，效率低。
3. 配置分散，無集中管理。

**深層原因**：
- 架構層面：缺乏面向運維的設計原則。
- 技術層面：未與 orchestrator/配置中心對接。
- 流程層面：Dev 與 Ops 缺少閉環。

### Solution Design
**解決策略**：以「設計可被維運」為原則：Worker 優雅關閉、配置集中化（環境變數/配置服務）、容器化、追蹤內建、用 orchestrator 做擴縮。避免自建管理平台，最大限度使用成熟工具。

**實施步驟**：
1. 定義設計準則與範本
- 細節：啟停規範、配置策略、追蹤標準。
- 時間：1 天。

2. 植入到 SDK 與樣板專案
- 細節：封裝通用行為；文檔化。
- 時間：2-3 天。

**關鍵程式碼/設定**：
```text
Implementation Example（實作範例）
- IHostedService/BackgroundService 樣板
- TrackContext/Headers 規範
- Dockerfile/Compose 模板
- 擴縮操作說明 (--scale / HPA)

```markdown
## Case #19: 觀測性：以 RequestId 串接跨服務日誌

### Problem Statement
**業務場景**：每秒大量請求分散多服務，需快速追蹤單筆交易的全鏈路日誌，支援故障診斷與稽核。
**技術挑戰**：跨協定（HTTP/MQ）一致傳遞；日誌標準化；追蹤與權限隔離。
**影響範圍**：除錯效率、可靠性、合規。
**複雜度評級**：中

### Root Cause Analysis
**直接原因**：
1. 無關聯 ID，難以串接跨服務日誌。
2. 每服務自訂欄位，不一致。
3. MQ 場景常被忽略。

**深層原因**：
- 架構層面：缺少全域追蹤策略。
- 技術層面：Headers 傳遞與 DI 注入未到位。
- 流程層面：日誌規範未統一。

### Solution Design
**解決策略**：以 TrackContext.RequestId 作為全域追蹤鍵；SDK 自動在 Headers 寫入/讀取；日誌中固定欄位輸出；並與集中式日誌平台對接。

**實施步驟**：
1. 追蹤欄位標準化
- 細節：RequestId/CorrelationId/UserId。
- 時間：0.5 天。

2. 日誌輸出與平台對接
- 細節：ILogger scope；集中式日誌。
- 時間：1 天。

**關鍵程式碼/設定**：
```csharp
// 在 Process 內以 DI 解析 TrackContext，將 RequestId 帶入 Logger Scope
using(logger.BeginScope(new Dictionary<string,object> { ["RequestId"]=track.RequestId })) {
    // 業務處理與日誌
}

```markdown
## Case #20: 專案治理：抽象與重用的邊界（避免過度抽象）

### Problem Statement
**業務場景**：為提升重用，容易傾向把所有功能抽象為通用元件，但不同情境（如 RPC 回覆）需要最小可行設計，過度抽象反而降低效能與可維運性。
**技術挑戰**：判斷抽象邊界；避免引入不需要的成本。
**影響範圍**：效能、可維護性與團隊效率。
**複雜度評級**：中

### Root Cause Analysis
**直接原因**：
1. 追求重用導致內嵌 Worker 到 Client。
2. 引入多餘的執行緒/通道與關閉流程。
3. 錯誤更難定位。

**深層原因**：
- 架構層面：缺乏設計準則。
- 技術層面：忽略場景特性（回覆輕量）。
- 流程層面：缺少設計審查。

### Solution Design
**解決策略**：建立「場景化」抽象準則：RPC 回覆以事件消費最小化；長時間消費才使用 Worker。以 ADR（Architecture Decision Record）保存決策，避免走回頭路。

**實施步驟**：
1. 撰寫準則與 ADR
- 細節：何時重用、何時分離。
- 時間：0.5 天。

2. 重構與範本發佈
- 細節：提供兩種樣板。
- 時間：1 天。

**關鍵程式碼/設定**：
```text
Implementation Example（實作範例）
- ADR: RPC 回覆不使用 Worker，改事件回覆
- 樣板：Client-Reply 模板 vs Worker 模板

--------------------------------
案例分類

1. 按難度分類
- 入門級（適合初學者）
  - Case #2 單向 MessageClient
  - Case #3 單向 MessageWorker + BackgroundService
  - Case #17 容器化與部署
- 中級（需要一定基礎）
  - Case #10 TrackContext 跨服務傳遞
  - Case #11 TrackContext 與 DI Scope
  - Case #12 並行調參
  - Case #13 ACK 與停止流程
  - Case #14 IHostedService 啟停阻塞處理
  - Case #16 Auto Scaling 驗證
  - Case #19 觀測性（RequestId）
  - Case #20 抽象與重用邊界
- 高級（需要深厚經驗）
  - Case #1 團隊專屬 SDK 抽象
  - Case #4 多執行緒與多通道設計
  - Case #5 Graceful Shutdown 收斂
  - Case #6 RPC 封裝
  - Case #7 Async/await 橋接
  - Case #8 回覆佇列與共用通道
  - Case #9 避免過度重用
  - Case #15 Windows OS Shutdown 擴充
  - Case #18 Design for Operation

2. 按技術領域分類
- 架構設計類
  - Case #1, #6, #8, #9, #18, #20
- 效能優化類
  - Case #4, #7, #12, #13, #14
- 整合開發類
  - Case #2, #3, #10, #11, #17
- 除錯診斷類
  - Case #5, #13, #15, #19
- 安全防護類
  -（本文未著重，但 #10/#11 涉及上下文與權限傳遞可延伸）

3. 按學習目標分類
- 概念理解型
  - Case #1, #18, #20
- 技能練習型
  - Case #2, #3, #17
- 問題解決型
  - Case #4, #5, #6, #7, #10, #11, #12, #13, #14, #15, #16, #19
- 創新應用型
  - Case #8, #9, #18

--------------------------------
案例關聯圖（學習路徑建議）
- 起步階段（基礎抽象與單向通訊）
  - 先學：Case #2（MessageClient 基礎）→ Case #3（MessageWorker 基礎）
  - 依賴：Case #2/#3 依賴 Case #1 的抽象理念（可並行閱讀概念）
- 併發與關閉（效能與可靠）
  - 接續：Case #4（多通道/多執行緒）→ Case #12（調參）→ Case #13（ACK/停止）→ Case #5（Graceful Shutdown 完整）
  - 依賴：Case #3 是前置；Case #14（async 契約）為共通基礎
- 雙向 RPC 與非同步橋接
  - 接續：Case #6（RPC）→ Case #7（AutoResetEvent/await）→ Case #8（回覆佇列最佳化）→ Case #9（避免過度重用）
  - 依賴：Case #2 基礎；Case #14 對 async 行為的理解
- 追蹤與上下文
  - 接續：Case #10（TrackContext Headers）→ Case #11（DI Scope）→ Case #19（觀測性）
  - 依賴：Case #2/#3 基礎
- 部署與運維（Design for Operation）
  - 接續：Case #17（容器化）→ Case #16（Auto Scaling）→ Case #15（Windows Shutdown 特化）→ Case #18（設計準則）
  - 依賴：Case #5（優雅關閉）、Case #14（啟停契約）

完整學習路徑建議：
1) 讀 Case #1（概念總覽）→ 2) 完成單向（#2、#3）→ 3) 強化並行與關閉（#4、#12、#13、#5、#14）→ 4) 進入 RPC 與非同步（#6、#7、#8、#9）→ 5) 佈建追蹤（#10、#11、#19）→ 6) 容器化與擴縮（#17、#16、#15）→ 7) 以設計治理收尾（#18、#20）。此路徑由易到難、由內而外（從程式內部到運維外部），最終達成可維運、可擴展且高可靠的微服務通訊體系。