高階架構模式實戰：打造高效能系統的完整指南

import asyncio
import time
from typing import List, Any, Optional, Dict
from datetime import datetime

async def fetch_data_from_api(api_id: int, delay: float) -> Dict[str, Any]:
    """
    模擬從外部 API 獲取資料的非同步函式
    
    這個函式展示了非同步程式設計的核心概念：當遇到 I/O 操作時
    協程會主動讓出控制權，讓事件迴圈能夠調度其他協程執行
    
    Args:
        api_id: API 的識別編號，用於追蹤不同的資料來源
              在實際應用中可能對應不同的服務端點
        delay: 模擬網路延遲的秒數，代表實際 API 回應時間
              實際場景中這個時間由網路狀況和伺服器負載決定
    
    Returns:
        Dict[str, Any]: 包含 API 編號、資料內容和時間戳記的字典
                       實際應用中會包含真實的業務資料
    
    在生產環境中，這裡應該使用 aiohttp 等非同步 HTTP 客戶端
    來執行真實的網路請求，而不是使用 asyncio.sleep 模擬
    """
    print(f"[{datetime.now().strftime('%H:%M:%S.%f')[:-3]}] 開始查詢 API {api_id}")
    
    # asyncio.sleep 是非阻塞的等待操作
    # 在等待期間，事件迴圈可以調度其他協程執行
    # 這是非同步程式設計能夠提升效能的關鍵
    await asyncio.sleep(delay)
    
    print(f"[{datetime.now().strftime('%H:%M:%S.%f')[:-3]}] API {api_id} 查詢完成")
    
    # 返回模擬的 API 回應資料
    # 實際應用中會包含解析後的 JSON 資料、狀態碼等資訊
    return {
        "api_id": api_id,
        "data": f"來自 API {api_id} 的資料",
        "timestamp": time.time(),
        "status": "success"
    }

async def process_data(data: Dict[str, Any]) -> Dict[str, Any]:
    """
    對獲取的資料進行處理和轉換
    
    這個函式展示了非同步資料處理流程中的中間步驟
    在實際應用中可能包含資料驗證、格式轉換、業務邏輯計算等操作
    
    Args:
        data: 從 API 獲取的原始資料字典
             包含需要處理的業務資料
    
    Returns:
        Dict[str, Any]: 處理後的資料字典，包含額外的處理狀態資訊
                       標記為已處理並記錄處理時間
    
    即使是資料處理操作，在非同步程式設計中也應該是非同步的
    這樣可以避免長時間運算阻塞事件迴圈
    """
    # 模擬資料處理的運算時間
    # 實際應用中可能是資料驗證、格式轉換等操作
    await asyncio.sleep(0.1)
    
    # 在原始資料上添加處理狀態標記
    data['processed'] = True
    data['process_time'] = time.time()
    data['processor'] = 'async_processor_v1'
    
    return data

async def aggregate_api_results(api_count: int, max_delay: float) -> List[Dict[str, Any]]:
    """
    聚合多個 API 的查詢結果
    
    這個函式展示了如何使用 asyncio.gather 來並發執行多個非同步任務
    並收集所有任務的執行結果。這是非同步程式設計中最常見的模式之一
    
    Args:
        api_count: 需要查詢的 API 數量
                  在實際應用中可能對應不同的微服務或資料來源
        max_delay: 每個 API 查詢的最大延遲時間
                  用於模擬不同 API 的回應時間差異
    
    Returns:
        List[Dict[str, Any]]: 包含所有 API 查詢和處理結果的列表
                            只包含成功處理的結果，過濾掉失敗的請求
    
    asyncio.gather 的 return_exceptions=True 參數確保即使某些任務失敗
    其他任務仍能繼續執行，這對於提升系統的容錯能力非常重要
    """
    print(f"\n開始聚合 {api_count} 個 API 的資料...")
    
    # 建立多個非同步任務
    # 每個任務查詢不同的 API，具有不同的模擬延遲時間
    # 延遲時間按比例分配，模擬真實場景中不同 API 的回應速度差異
    tasks = [
        fetch_data_from_api(i, max_delay * (i + 1) / api_count)
        for i in range(api_count)
    ]
    
    # asyncio.gather 並發執行所有任務
    # 這是非同步程式設計的核心優勢：多個 I/O 操作可以同時進行
    # return_exceptions=True 表示即使某個任務拋出異常
    # 也會將異常作為結果返回，而不是中斷整個 gather 操作
    results = await asyncio.gather(*tasks, return_exceptions=True)
    
    # 過濾掉執行過程中產生的異常
    # 在生產環境中，應該記錄這些異常以便後續分析
    successful_results = [
        result for result in results
        if not isinstance(result, Exception)
    ]
    
    print(f"成功獲取 {len(successful_results)}/{api_count} 個 API 的資料")
    
    # 對成功獲取的資料進行後續處理
    # 這裡展示了如何鏈接多個非同步操作
    processed_results = await asyncio.gather(
        *[process_data(data) for data in successful_results],
        return_exceptions=True
    )
    
    # 再次過濾異常，確保返回的都是成功處理的資料
    final_results = [
        result for result in processed_results
        if not isinstance(result, Exception)
    ]
    
    print(f"成功處理 {len(final_results)} 筆資料\n")
    
    return final_results

async def main():
    """
    主程式入口點，展示非同步程式設計的完整流程
    
    這個函式協調整個非同步工作流程，包括任務的建立、執行、
    結果收集和效能統計。透過比較非同步執行和同步執行的時間差異
    可以清楚看到非同步程式設計帶來的效能提升
    """
    print("=" * 60)
    print("非同步資料聚合程序")
    print("=" * 60)
    
    # 記錄開始時間，用於計算總執行時間
    start_time = time.time()
    
    # 設定要查詢的 API 數量和最大延遲時間
    # 這些參數可以根據實際需求調整
    api_count = 10
    max_delay = 2.0
    
    # 執行資料聚合任務
    # 這裡使用 await 關鍵字等待非同步操作完成
    results = await aggregate_api_results(api_count, max_delay)
    
    # 計算總執行時間
    elapsed_time = time.time() - start_time
    
    # 輸出執行結果統計
    print("=" * 60)
    print("執行統計")
    print("=" * 60)
    print(f"成功處理的資料筆數: {len(results)}")
    print(f"實際執行時間: {elapsed_time:.2f} 秒")
    
    # 計算如果使用同步方式執行，預估需要的時間
    # 同步執行時，每個 API 查詢必須等待前一個完成才能開始
    estimated_sync_time = sum(
        max_delay * (i + 1) / api_count + 0.1  # 0.1 是處理時間
        for i in range(api_count)
    )
    
    print(f"同步執行預估時間: {estimated_sync_time:.2f} 秒")
    print(f"效能提升倍數: {estimated_sync_time / elapsed_time:.2f}x")
    print(f"平均每筆資料處理時間: {elapsed_time / len(results):.3f} 秒")
    print("=" * 60)

# 執行主程式
# asyncio.run() 是 Python 3.7+ 推薦的執行非同步程式碼的方式
# 它會自動建立事件迴圈、執行協程、並在完成後清理資源
if __name__ == "__main__":
    asyncio.run(main())

from abc import ABC, abstractmethod
from typing import Dict, Any, Optional, List
from datetime import datetime
import json

class Connection(ABC):
    """
    連線介面的抽象基礎類別
    
    定義了所有資料庫連線必須實作的基本操作介面
    這個抽象層讓客戶端程式碼不需要知道具體的資料庫類型
    就能執行資料庫操作，實現了依賴反轉原則
    
    在實際應用中，這個介面還可以包含交易管理、連線池管理等功能
    """
    
    @abstractmethod
    def connect(self) -> str:
        """
        建立與資料庫的連線
        
        這個方法負責初始化資料庫連線，包括網路連線建立、
        身分驗證、連線參數設定等操作
        
        Returns:
            str: 連線成功的訊息字串，包含連線狀態和基本資訊
        """
        pass
    
    @abstractmethod
    def execute_query(self, query: str) -> Dict[str, Any]:
        """
        執行資料庫查詢操作
        
        這個方法是資料存取的核心介面，負責執行各種資料庫操作
        包括查詢、插入、更新、刪除等 SQL 或 NoSQL 指令
        
        Args:
            query: 要執行的查詢語句，可能是 SQL 語句或 NoSQL 查詢
        
        Returns:
            Dict[str, Any]: 包含查詢結果和執行狀態的字典
                          包括資料內容、影響的記錄數、執行時間等資訊
        """
        pass
    
    @abstractmethod
    def close(self) -> None:
        """
        關閉資料庫連線，釋放系統資源
        
        這個方法確保資料庫連線被正確關閉，避免資源洩漏
        在使用連線池的場景中，這個方法會將連線返回連線池
        """
        pass
    
    @abstractmethod
    def get_connection_info(self) -> Dict[str, Any]:
        """
        獲取連線的詳細資訊
        
        提供連線的元資訊，用於監控、除錯和日誌記錄
        
        Returns:
            Dict[str, Any]: 包含連線狀態、類型、建立時間等資訊的字典
        """
        pass

class SQLConnection(Connection):
    """
    SQL 資料庫連線的具體實作
    
    實作了針對關聯式資料庫（如 MySQL、PostgreSQL）的連線邏輯
    這個類別封裝了 SQL 資料庫特有的連線管理和查詢執行方式
    
    在實際應用中，這裡會使用 SQLAlchemy、psycopg2 等資料庫驅動程式
    並整合連線池管理、查詢優化、錯誤處理等功能
    """
    
    def __init__(self, connection_string: str):
        """
        初始化 SQL 連線
        
        Args:
            connection_string: 資料庫連線字串
                             格式類似：mysql://user:pass@localhost:3306/mydb
                             包含資料庫類型、主機位址、埠號、使用者認證等資訊
        """
        self.connection_string = connection_string
        self.connected = False
        self.connection_time: Optional[datetime] = None
        self.query_count = 0  # 追蹤查詢次數，用於監控和除錯
    
    def connect(self) -> str:
        """
        建立 SQL 資料庫連線
        
        在實際應用中，這裡會執行真實的資料庫連線邏輯
        包括 TCP 連線建立、SSL 加密設定、連線池初始化等
        
        Returns:
            str: 連線成功訊息
        """
        # 模擬連線建立過程
        # 實際應用中會使用資料庫驅動程式建立真實連線
        self.connected = True
        self.connection_time = datetime.now()
        
        return f"已成功連線至 SQL 資料庫：{self.connection_string}"
    
    def execute_query(self, query: str) -> Dict[str, Any]:
        """
        執行 SQL 查詢
        
        Args:
            query: SQL 查詢語句
        
        Returns:
            Dict[str, Any]: 查詢結果字典
        
        實際應用中，這裡會進行：
        1. SQL 注入防護（使用參數化查詢）
        2. 查詢計畫分析和優化
        3. 結果集分頁處理
        4. 錯誤處理和重試機制
        """
        if not self.connected:
            raise ConnectionError("資料庫未連線，請先呼叫 connect() 方法")
        
        # 增加查詢計數器
        self.query_count += 1
        
        # 模擬 SQL 查詢執行
        # 實際應用中會使用資料庫游標執行真實的 SQL 語句
        result = {
            "status": "success",
            "query": query,
            "query_number": self.query_count,
            "data": [
                {"id": 1, "name": "使用者A", "email": "usera@example.com", "active": True},
                {"id": 2, "name": "使用者B", "email": "userb@example.com", "active": True}
            ],
            "row_count": 2,
            "execution_time_ms": 23,
            "database_type": "SQL"
        }
        
        return result
    
    def close(self) -> None:
        """
        關閉 SQL 連線
        
        在實際應用中，需要：
        1. 提交或回滾未完成的交易
        2. 釋放資料庫連線資源
        3. 將連線返回連線池（如果使用連線池）
        4. 清理相關的系統資源
        """
        if self.connected:
            self.connected = False
            print(f"SQL 資料庫連線已關閉（執行了 {self.query_count} 次查詢）")
    
    def get_connection_info(self) -> Dict[str, Any]:
        """
        獲取 SQL 連線的詳細資訊
        
        Returns:
            Dict[str, Any]: 連線資訊字典
        """
        return {
            "type": "SQL",
            "connected": self.connected,
            "connection_string": self.connection_string,
            "connection_time": self.connection_time.isoformat() if self.connection_time else None,
            "query_count": self.query_count
        }

class NoSQLConnection(Connection):
    """
    NoSQL 資料庫連線的具體實作
    
    實作了針對文件型資料庫（如 MongoDB）的連線邏輯
    NoSQL 資料庫通常使用不同於 SQL 的查詢語言和資料模型
    
    在實際應用中，會使用 PyMongo、Motor 等 NoSQL 資料庫驅動程式
    """
    
    def __init__(self, host: str, port: int, database: str):
        """
        初始化 NoSQL 連線
        
        Args:
            host: 資料庫伺服器主機位址
            port: 資料庫伺服器埠號
            database: 要連線的資料庫名稱
        """
        self.host = host
        self.port = port
        self.database = database
        self.connected = False
        self.connection_time: Optional[datetime] = None
        self.operation_count = 0
    
    def connect(self) -> str:
        """
        建立 NoSQL 資料庫連線
        
        Returns:
            str: 連線成功訊息
        """
        self.connected = True
        self.connection_time = datetime.now()
        
        return f"已成功連線至 NoSQL 資料庫：{self.host}:{self.port}/{self.database}"
    
    def execute_query(self, query: str) -> Dict[str, Any]:
        """
        執行 NoSQL 查詢
        
        Args:
            query: NoSQL 查詢語句（通常是 JSON 格式）
        
        Returns:
            Dict[str, Any]: 查詢結果字典
        
        NoSQL 資料庫通常使用 JSON 格式的查詢語言
        例如 MongoDB 的查詢文件語法
        """
        if not self.connected:
            raise ConnectionError("資料庫未連線，請先呼叫 connect() 方法")
        
        self.operation_count += 1
        
        # 模擬 NoSQL 查詢執行
        # 實際應用中會解析 JSON 查詢並執行對應的資料庫操作
        result = {
            "status": "success",
            "query": query,
            "operation_number": self.operation_count,
            "documents": [
                {
                    "_id": "507f1f77bcf86cd799439011",
                    "name": "產品A",
                    "category": "電子產品",
                    "price": 15000,
                    "in_stock": True,
                    "tags": ["熱門", "新品"]
                },
                {
                    "_id": "507f1f77bcf86cd799439012",
                    "name": "產品B",
                    "category": "家電",
                    "price": 8500,
                    "in_stock": False,
                    "tags": ["促銷"]
                }
            ],
            "document_count": 2,
            "execution_time_ms": 15,
            "database_type": "NoSQL"
        }
        
        return result
    
    def close(self) -> None:
        """
        關閉 NoSQL 連線
        """
        if self.connected:
            self.connected = False
            print(f"NoSQL 資料庫連線已關閉（執行了 {self.operation_count} 次操作）")
    
    def get_connection_info(self) -> Dict[str, Any]:
        """
        獲取 NoSQL 連線的詳細資訊
        
        Returns:
            Dict[str, Any]: 連線資訊字典
        """
        return {
            "type": "NoSQL",
            "connected": self.connected,
            "host": self.host,
            "port": self.port,
            "database": self.database,
            "connection_time": self.connection_time.isoformat() if self.connection_time else None,
            "operation_count": self.operation_count
        }

class ConnectionFactory(ABC):
    """
    連線工廠的抽象基礎類別
    
    定義了建立資料庫連線的介面
    具體的工廠類別負責建立對應類型的連線物件
    
    這個抽象層實現了開閉原則：
    對擴展開放（可以輕鬆添加新的工廠類別）
    對修改封閉（不需要修改現有程式碼）
    """
    
    @abstractmethod
    def create_connection(self) -> Connection:
        """
        建立資料庫連線物件
        
        這是工廠模式的核心方法，負責實例化具體的連線類別
        
        Returns:
            Connection: Connection 介面的具體實作物件
        """
        pass
    
    @abstractmethod
    def get_connection_type(self) -> str:
        """
        獲取工廠建立的連線類型
        
        提供工廠的元資訊，用於日誌記錄和監控
        
        Returns:
            str: 連線類型的字串描述
        """
        pass

class SQLConnectionFactory(ConnectionFactory):
    """
    SQL 資料庫連線工廠
    
    負責建立 SQL 資料庫連線物件
    封裝了 SQL 連線的建立邏輯和初始化參數
    """
    
    def __init__(self, connection_string: str):
        """
        初始化 SQL 連線工廠
        
        Args:
            connection_string: SQL 資料庫的連線字串
        """
        self.connection_string = connection_string
    
    def create_connection(self) -> Connection:
        """
        建立 SQL 連線物件
        
        Returns:
            Connection: SQL 連線的實例
        """
        return SQLConnection(self.connection_string)
    
    def get_connection_type(self) -> str:
        """
        返回連線類型
        
        Returns:
            str: 連線類型描述
        """
        return "SQL Database"

class NoSQLConnectionFactory(ConnectionFactory):
    """
    NoSQL 資料庫連線工廠
    
    負責建立 NoSQL 資料庫連線物件
    """
    
    def __init__(self, host: str, port: int, database: str):
        """
        初始化 NoSQL 連線工廠
        
        Args:
            host: NoSQL 資料庫伺服器主機位址
            port: NoSQL 資料庫伺服器埠號
            database: 要連線的資料庫名稱
        """
        self.host = host
        self.port = port
        self.database = database
    
    def create_connection(self) -> Connection:
        """
        建立 NoSQL 連線物件
        
        Returns:
            Connection: NoSQL 連線的實例
        """
        return NoSQLConnection(self.host, self.port, self.database)
    
    def get_connection_type(self) -> str:
        """
        返回連線類型
        
        Returns:
            str: 連線類型描述
        """
        return "NoSQL Database"

class DatabaseService:
    """
    資料庫服務類別
    
    這個類別展示了如何使用抽象工廠模式來建立
    與具體資料庫類型解耦的服務層
    
    透過依賴注入工廠物件，服務層可以在執行時
    動態切換不同的資料庫實作，而不需要修改業務邏輯程式碼
    """
    
    def __init__(self, factory: ConnectionFactory):
        """
        初始化資料庫服務
        
        Args:
            factory: 連線工廠物件，用於建立資料庫連線
        
        透過依賴注入的方式，服務層只依賴抽象工廠介面
        而不依賴具體的工廠實作，這是依賴反轉原則的實踐
        """
        self.factory = factory
        self.connection: Optional[Connection] = None
    
    def execute_operation(self, query: str) -> Dict[str, Any]:
        """
        執行資料庫操作
        
        Args:
            query: 要執行的查詢語句
        
        Returns:
            Dict[str, Any]: 操作結果字典
        
        這個方法展示了客戶端程式碼如何使用工廠模式
        整個過程不需要知道具體的資料庫實作細節
        """
        try:
            # 使用工廠建立連線
            # 這裡不需要知道建立的是 SQL 還是 NoSQL 連線
            self.connection = self.factory.create_connection()
            
            # 建立連線
            connect_msg = self.connection.connect()
            print(connect_msg)
            
            # 執行查詢
            # 無論是 SQL 還是 NoSQL，都使用相同的介面
            result = self.connection.execute_query(query)
            
            # 獲取連線資訊
            conn_info = self.connection.get_connection_info()
            print(f"連線類型：{conn_info['type']}")
            print(f"執行狀態：{result['status']}")
            
            return result
            
        finally:
            # 確保連線被正確關閉
            # 無論操作成功或失敗，都要釋放資源
            if self.connection:
                self.connection.close()

# 使用範例
def demonstrate_abstract_factory():
    """
    展示抽象工廠模式的使用方式
    
    這個函式展示了如何在執行時動態切換不同的資料庫實作
    而不需要修改業務邏輯程式碼，充分體現了抽象工廠模式的價值
    """
    print("=" * 70)
    print("抽象工廠模式示範：彈性的資料庫連線系統")
    print("=" * 70)
    
    # 場景一：使用 SQL 資料庫
    print("\n【場景一】使用 SQL 資料庫處理關聯式資料")
    print("-" * 70)
    
    sql_factory = SQLConnectionFactory("mysql://user:pass@localhost:3306/mydb")
    sql_service = DatabaseService(sql_factory)
    
    sql_result = sql_service.execute_operation(
        "SELECT * FROM users WHERE status = 'active' ORDER BY created_at DESC"
    )
    
    print(f"\nSQL 查詢結果：")
    print(json.dumps(sql_result, indent=2, ensure_ascii=False))
    
    # 場景二：使用 NoSQL 資料庫
    print("\n\n【場景二】使用 NoSQL 資料庫處理文件型資料")
    print("-" * 70)
    
    nosql_factory = NoSQLConnectionFactory("localhost", 27017, "mydb")
    nosql_service = DatabaseService(nosql_factory)
    
    nosql_result = nosql_service.execute_operation(
        '{"find": "products", "filter": {"in_stock": true}, "sort": {"price": -1}}'
    )
    
    print(f"\nNoSQL 查詢結果：")
    print(json.dumps(nosql_result, indent=2, ensure_ascii=False))
    
    print("\n" + "=" * 70)
    print("抽象工廠模式的優勢：")
    print("-" * 70)
    print("1. 業務邏輯程式碼與具體資料庫類型完全解耦")
    print("2. 可以在執行時動態切換資料庫實作")
    print("3. 新增資料庫類型不需要修改現有程式碼")
    print("4. 便於單元測試，可以輕鬆注入模擬物件")
    print("=" * 70)

if __name__ == "__main__":
    demonstrate_abstract_factory()

import rx
from rx import operators as ops
from rx.subject import Subject
from typing import Any, Callable, Dict, List
import time
from datetime import datetime
import statistics

class SensorDataProcessor:
    """
    感測器資料處理器
    
    使用反應式程式設計模式處理來自多個感測器的即時資料流
    展示如何組合多個操作符來建立複雜的資料處理管道
    
    這個類別展示了反應式程式設計的核心概念：
    1. 將資料流視為一等公民
    2. 使用聲明式的方式定義資料處理邏輯
    3. 透過組合操作符來建立複雜的處理流程
    4. 優雅地處理錯誤和異常情況
    """
    
    def __init__(self):
        """
        初始化資料處理器
        
        建立 Subject 物件作為資料流的來源
        Subject 既是 Observable 也是 Observer
        可以手動推送資料，也可以被訂閱
        """
        # 建立資料流的來源
        # Subject 允許我們手動推送資料到流中
        self.sensor_stream = Subject()
        
        # 統計資訊
        self.processed_count = 0  # 成功處理的資料筆數
        self.error_count = 0      # 錯誤筆數
        self.total_values = []    # 儲存所有處理過的值，用於統計
    
    def setup_processing_pipeline(self):
        """
        設定資料處理管道
        
        這個方法展示了如何使用 RxPY 的操作符來建立一個
        複雜的資料處理流程，包含過濾、轉換、聚合、錯誤處理等步驟
        
        管道處理流程：
        1. 過濾：移除無效的感測器讀數
        2. 標準化：將原始資料轉換為統一格式
        3. 視窗聚合：使用滑動視窗計算移動平均值
        4. 閾值過濾：只處理超過特定閾值的資料
        5. 分析：執行進階的資料分析
        6. 錯誤處理：捕獲並處理異常
        """
        # 建立資料處理管道
        # 使用 pipe 方法串連多個操作符
        pipeline = self.sensor_stream.pipe(
            # 步驟 1: 過濾掉無效的感測器讀數
            # filter 操作符只讓符合條件的資料通過
            ops.filter(lambda data: self._is_valid_reading(data)),
            
            # 步驟 2: 將原始感測器資料轉換為標準化格式
            # map 操作符對每個資料項進行轉換
            ops.map(lambda data: self._normalize_data(data)),
            
            # 步驟 3: 使用滑動視窗計算移動平均值
            # buffer_with_count 建立一個大小為 5 的滑動視窗
            # 每次滑動 1 個位置（重疊視窗）
            ops.buffer_with_count(5, 1),
            
            # 步驟 4: 計算視窗內的移動平均值
            ops.map(lambda buffer: self._calculate_moving_average(buffer)),
            
            # 步驟 5: 只處理移動平均值超過閾值的資料
            # 這可以用來觸發警報或特殊處理
            ops.filter(lambda avg_data: avg_data.get('moving_average', 0) > 50),
            
            # 步驟 6: 執行進階分析
            # 根據資料特徵進行狀態判斷和建議生成
            ops.map(lambda data: self._perform_analysis(data)),
            
            # 步驟 7: 錯誤處理
            # catch 操作符捕獲處理過程中的任何錯誤
            # 確保錯誤不會導致整個資料流中斷
            ops.catch(lambda error, source: self._handle_error(error, source))
        )
        
        # 訂閱處理管道
        # 定義當資料到達、發生錯誤、或流結束時的處理邏輯
        pipeline.subscribe(
            on_next=self._on_data_processed,      # 資料處理完成時的回呼
            on_error=self._on_error,              # 發生錯誤時的回呼
            on_completed=self._on_completed       # 資料流結束時的回呼
        )
    
    def _is_valid_reading(self, data: Dict[str, Any]) -> bool:
        """
        驗證感測器讀數是否有效
        
        Args:
            data: 感測器資料字典
        
        Returns:
            bool: 資料是否有效
        
        驗證規則：
        1. 資料必須是字典類型
        2. 必須包含 value 和 sensor_id 欄位
        3. value 必須在合理範圍內（0-100）
        """
        # 檢查資料類型
        if not isinstance(data, dict):
            return False
        
        # 檢查必要欄位
        if 'value' not in data or 'sensor_id' not in data:
            return False
        
        # 檢查數值範圍
        # 假設感測器讀數應在 0-100 之間
        value = data.get('value', 0)
        return 0 <= value <= 100
    
    def _normalize_data(self, data: Dict[str, Any]) -> Dict[str, Any]:
        """
        標準化感測器資料
        
        Args:
            data: 原始感測器資料
        
        Returns:
            Dict[str, Any]: 標準化後的資料字典
        
        標準化步驟：
        1. 添加時間戳記
        2. 補充預設值（單位、位置等）
        3. 統一資料格式
        """
        return {
            'sensor_id': data['sensor_id'],
            'value': data['value'],
            'timestamp': datetime.now().isoformat(),
            'unit': data.get('unit', '未知單位'),
            'location': data.get('location', '未知位置'),
            'raw_data': data  # 保留原始資料供除錯使用
        }
    
    def _calculate_moving_average(self, buffer: List[Dict[str, Any]]) -> Dict[str, Any]:
        """
        計算移動平均值
        
        Args:
            buffer: 包含多個資料點的列表（視窗）
        
        Returns:
            Dict[str, Any]: 包含移動平均值的資料字典
        
        移動平均值的作用：
        1. 平滑感測器資料中的雜訊
        2. 識別趨勢變化
        3. 減少誤報（避免因瞬間波動觸發警報）
        """
        if not buffer:
            return {
                'moving_average': 0,
                'data_points': 0,
                'error': 'Empty buffer'
            }
        
        # 提取所有資料點的數值
        values = [point['value'] for point in buffer]
        
        # 計算移動平均值
        moving_average = statistics.mean(values)
        
        # 計算標準差，用於判斷資料的穩定性
        std_dev = statistics.stdev(values) if len(values) > 1 else 0
        
        # 返回最新的資料點，並添加統計資訊
        latest_point = buffer[-1].copy()
        latest_point['moving_average'] = moving_average
        latest_point['std_dev'] = std_dev
        latest_point['data_points_count'] = len(buffer)
        latest_point['min_value'] = min(values)
        latest_point['max_value'] = max(values)
        
        return latest_point
    
    def _perform_analysis(self, data: Dict[str, Any]) -> Dict[str, Any]:
        """
        執行進階資料分析
        
        Args:
            data: 經過預處理的感測器資料
        
        Returns:
            Dict[str, Any]: 包含分析結果的資料字典
        
        分析內容：
        1. 根據移動平均值判斷狀態
        2. 根據標準差判斷穩定性
        3. 生成相應的警報和建議
        """
        moving_avg = data.get('moving_average', 0)
        std_dev = data.get('std_dev', 0)
        
        # 根據移動平均值判斷狀態
        if moving_avg > 80:
            status = '警告'
            severity = 'high'
            recommendation = '感測器讀數異常偏高，建議立即檢查設備狀態'
        elif moving_avg > 65:
            status = '注意'
            severity = 'medium'
            recommendation = '感測器讀數偏高，建議密切監控並檢查是否需要調整'
        else:
            status = '正常'
            severity = 'low'
            recommendation = '感測器運作正常，繼續監控'
        
        # 根據標準差判斷穩定性
        if std_dev > 10:
            stability = '不穩定'
            recommendation += '；資料波動較大，建議檢查感測器連線'
        else:
            stability = '穩定'
        
        # 添加分析結果到資料中
        data['status'] = status
        data['severity'] = severity
        data['stability'] = stability
        data['recommendation'] = recommendation
        data['analysis_time'] = datetime.now().isoformat()
        
        return data
    
    def _handle_error(self, error: Exception, source: rx.Observable) -> rx.Observable:
        """
        處理資料處理過程中的錯誤
        
        Args:
            error: 捕獲到的異常
            source: 原始資料流
        
        Returns:
            rx.Observable: 用於恢復的 Observable
        
        錯誤處理策略：
        1. 記錄錯誤資訊
        2. 更新錯誤計數器
        3. 返回空的 Observable 以繼續處理後續資料
        """
        self.error_count += 1
        print(f"\n[錯誤] 資料處理異常：{str(error)}")
        print(f"錯誤類型：{type(error).__name__}")
        print(f"累計錯誤次數：{self.error_count}")
        
        # 返回空的 Observable 以繼續處理後續資料
        # 這確保了一個錯誤不會中斷整個資料流
        return rx.empty()
    
    def _on_data_processed(self, data: Dict[str, Any]):
        """
        資料處理完成時的回呼函式
        
        Args:
            data: 處理完成的資料
        
        這個函式會在每個資料點成功處理後被呼叫
        用於輸出處理結果和更新統計資訊
        """
        self.processed_count += 1
        self.total_values.append(data['value'])
        
        print(f"\n{'='*60}")
        print(f"[處理完成 #{self.processed_count}] 感測器：{data['sensor_id']}")
        print(f"{'='*60}")
        print(f"位置：{data['location']}")
        print(f"原始值：{data['value']:.2f} {data['unit']}")
        print(f"移動平均：{data['moving_average']:.2f}")
        print(f"標準差：{data['std_dev']:.2f}")
        print(f"穩定性：{data['stability']}")
        print(f"狀態：{data['status']} (嚴重程度：{data['severity']})")
        print(f"建議：{data['recommendation']}")
    
    def _on_error(self, error: Exception):
        """
        發生無法恢復的錯誤時的回呼函式
        
        Args:
            error: 錯誤異常物件
        
        這個函式處理嚴重的、無法恢復的錯誤
        """
        print(f"\n[嚴重錯誤] 資料流處理失敗：{str(error)}")
        print(f"錯誤類型：{type(error).__name__}")
    
    def _on_completed(self):
        """
        資料流完成時的回呼函式
        
        當資料流正常結束時被呼叫
        執行清理工作和輸出統計報告
        """
        print(f"\n{'='*60}")
        print("資料流處理完成")
        print(f"{'='*60}")
        print(f"總處理筆數：{self.processed_count}")
        print(f"錯誤筆數：{self.error_count}")
        
        if self.total_values:
            print(f"平均值：{statistics.mean(self.total_values):.2f}")
            print(f"最大值：{max(self.total_values):.2f}")
            print(f"最小值：{min(self.total_values):.2f}")
        
        print(f"{'='*60}")
    
    def push_sensor_data(self, sensor_id: str, value: float, **kwargs):
        """
        推送感測器資料到處理管道
        
        Args:
            sensor_id: 感測器識別碼
            value: 感測器讀數
            **kwargs: 其他選用的感測器屬性
        
        這個方法模擬了感測器資料的產生
        在實際應用中，資料可能來自 MQTT、WebSocket 或其他即時資料來源
        """
        data = {
            'sensor_id': sensor_id,
            'value': value,
            **kwargs
        }
        self.sensor_stream.on_next(data)

# 使用範例
def demonstrate_reactive_programming():
    """
    展示反應式程式設計的實際應用
    
    模擬一個即時感測器監控系統
    展示如何使用反應式程式設計來處理連續的資料流
    """
    print("=" * 70)
    print("反應式程式設計示範：即時感測器監控系統")
    print("=" * 70)
    
    # 建立資料處理器並設定處理管道
    processor = SensorDataProcessor()
    processor.setup_processing_pipeline()
    
    # 模擬感測器資料流
    # 在實際應用中，這些資料可能來自 MQTT、WebSocket 或其他即時資料來源
    sensors_data = [
        {'sensor_id': 'TEMP-001', 'value': 45.5, 'unit': '°C', 'location': '機房A'},
        {'sensor_id': 'TEMP-001', 'value': 52.3, 'unit': '°C', 'location': '機房A'},
        {'sensor_id': 'TEMP-001', 'value': 58.7, 'unit': '°C', 'location': '機房A'},
        {'sensor_id': 'TEMP-001', 'value': 65.2, 'unit': '°C', 'location': '機房A'},
        {'sensor_id': 'TEMP-001', 'value': 71.8, 'unit': '°C', 'location': '機房A'},
        {'sensor_id': 'TEMP-001', 'value': 68.5, 'unit': '°C', 'location': '機房A'},
        {'sensor_id': 'TEMP-001', 'value': 75.3, 'unit': '°C', 'location': '機房A'},
        {'sensor_id': 'HUMID-002', 'value': 82.1, 'unit': '%', 'location': '機房B'},
        {'sensor_id': 'HUMID-002', 'value': 85.7, 'unit': '%', 'location': '機房B'},
        {'sensor_id': 'HUMID-002', 'value': 88.3, 'unit': '%', 'location': '機房B'},
    ]
    
    # 推送感測器資料到處理管道
    for data in sensors_data:
        processor.push_sensor_data(**data)
        time.sleep(0.2)  # 模擬資料產生的時間間隔
    
    # 完成資料流
    processor.sensor_stream.on_completed()
    
    print("\n反應式程式設計的優勢：")
    print("-" * 70)
    print("1. 聲明式的程式設計風格，程式碼更易讀易維護")
    print("2. 透過組合操作符建立複雜的資料處理邏輯")
    print("3. 優雅的錯誤處理機制，不會中斷整個資料流")
    print("4. 適合處理連續的非同步事件序列")
    print("=" * 70)

if __name__ == "__main__":
    demonstrate_reactive_programming()

import cProfile
import pstats
import io
from functools import lru_cache
import time
from typing import List, Dict, Any
import statistics

class PerformanceAnalyzer:
    """
    效能分析器
    
    提供一套完整的效能分析和優化工具
    幫助開發者識別和解決效能瓶頸
    
    這個類別封裝了 Python 的 cProfile 模組
    提供更友善的介面來進行效能分析
    """
    
    def __init__(self):
        """
        初始化效能分析器
        
        建立 cProfile.Profile 實例和相關的資料結構
        """
        self.profiler = cProfile.Profile()
        self.stats = None
    
    def profile_function(self, func, *args, **kwargs):
        """
        分析指定函式的效能
        
        Args:
            func: 要分析的函式
            *args: 函式的位置參數
            **kwargs: 函式的關鍵字參數
        
        Returns:
            函式的執行結果
        
        這個方法會記錄函式執行過程中的詳細效能資訊
        包括每個函式的呼叫次數和執行時間
        """
        # 啟動效能分析器
        self.profiler.enable()
        
        # 執行目標函式
        result = func(*args, **kwargs)
        
        # 停止效能分析器
        self.profiler.disable()
        
        return result
    
    def get_stats(self, sort_by: str = 'cumulative', top_n: int = 20) -> str:
        """
        獲取效能分析統計資訊
        
        Args:
            sort_by: 排序方式
                    'cumulative' - 累積時間（包含子函式）
                    'time' - 函式自身時間（不包含子函式）
                    'calls' - 呼叫次數
            top_n: 顯示前 N 個最耗時的函式
        
        Returns:
            str: 格式化的效能統計字串
        
        這個方法將效能資料轉換為易讀的格式
        幫助開發者快速識別效能瓶頸
        """
        # 建立字串緩衝區來儲存統計輸出
        s = io.StringIO()
        
        # 將效能資料載入到 Stats 物件中
        stats = pstats.Stats(self.profiler, stream=s)
        
        # 去除檔案路徑，只保留檔案名稱
        # 這讓輸出更簡潔易讀
        stats.strip_dirs()
        
        # 按指定方式排序
        stats.sort_stats(sort_by)
        
        # 列印前 N 個最耗時的函式
        stats.print_stats(top_n)
        
        return s.getvalue()
    
    def print_analysis(self, sort_by: str = 'cumulative'):
        """
        列印詳細的效能分析報告
        
        Args:
            sort_by: 排序方式
        
        這個方法會輸出格式化的效能分析結果
        包括函式呼叫次數、總時間、平均時間等資訊
        """
        print("\n" + "=" * 80)
        print("效能分析報告")
        print("=" * 80)
        print(self.get_stats(sort_by=sort_by))

# 示範程式碼：效能問題案例

def inefficient_fibonacci(n: int) -> int:
    """
    低效率的費波那契數列計算（遞迴實作）
    
    Args:
        n: 要計算的費波那契數列項數
    
    Returns:
        int: 第 n 項費波那契數
    
    這個實作方式會進行大量重複計算
    時間複雜度為 O(2^n)，效能極差
    
    例如計算 fibonacci(5)：
    - fibonacci(5) 呼叫 fibonacci(4) 和 fibonacci(3)
    - fibonacci(4) 呼叫 fibonacci(3) 和 fibonacci(2)
    - 可以看到 fibonacci(3) 被計算了兩次
    - 隨著 n 增大，重複計算呈指數級增長
    """
    if n <= 1:
        return n
    return inefficient_fibonacci(n - 1) + inefficient_fibonacci(n - 2)

@lru_cache(maxsize=None)
def efficient_fibonacci(n: int) -> int:
    """
    高效率的費波那契數列計算（帶快取的遞迴實作）
    
    Args:
        n: 要計算的費波那契數列項數
    
    Returns:
        int: 第 n 項費波那契數
    
    使用 lru_cache 裝飾器來快取計算結果
    避免重複計算，時間複雜度降低到 O(n)
    
    lru_cache 工作原理：
    - 第一次呼叫 fibonacci(n) 時計算並儲存結果
    - 後續相同的呼叫直接返回快取的結果
    - maxsize=None 表示快取大小無限制
    """
    if n <= 1:
        return n
    return efficient_fibonacci(n - 1) + efficient_fibonacci(n - 2)

def process_large_dataset_inefficient(data: List[int]) -> Dict[str, Any]:
    """
    低效率的大型資料集處理
    
    Args:
        data: 要處理的整數列表
    
    Returns:
        Dict[str, Any]: 包含處理結果的字典
    
    這個實作使用了多次完整遍歷，效能較差
    每次呼叫 sum()、max()、min() 都會遍歷整個列表
    總共遍歷了 5 次，時間複雜度為 O(5n) = O(n)
    但常數係數較大，實際執行時間長
    """
    # 第一次遍歷：計算總和
    total = sum(data)
    
    # 第二次遍歷：再次計算總和來算平均值
    # 這裡重複計算了總和，浪費了運算資源
    average = sum(data) / len(data)
    
    # 第三次遍歷：找出最大值
    maximum = max(data)
    
    # 第四次遍歷：找出最小值
    minimum = min(data)
    
    # 第五次遍歷：計算標準差
    variance = sum((x - average) ** 2 for x in data) / len(data)
    std_dev = variance ** 0.5
    
    return {
        'total': total,
        'average': average,
        'max': maximum,
        'min': minimum,
        'std_dev': std_dev
    }

def process_large_dataset_efficient(data: List[int]) -> Dict[str, Any]:
    """
    高效率的大型資料集處理
    
    Args:
        data: 要處理的整數列表
    
    Returns:
        Dict[str, Any]: 包含處理結果的字典
    
    這個實作只進行兩次遍歷，大幅提升效能
    第一次遍歷同時計算總和、最大值、最小值
    第二次遍歷計算標準差
    時間複雜度仍為 O(n)，但常數係數更小
    """
    # 第一次遍歷：同時計算多個統計量
    # 這樣避免了重複遍歷，提升效能
    total = 0
    maximum = float('-inf')
    minimum = float('inf')
    
    for value in data:
        total += value
        maximum = max(maximum, value)
        minimum = min(minimum, value)
    
    # 計算平均值
    average = total / len(data)
    
    # 第二次遍歷：計算標準差
    # 這次遍歷無法避免，因為需要用到平均值
    variance = sum((x - average) ** 2 for x in data) / len(data)
    std_dev = variance ** 0.5
    
    return {
        'total': total,
        'average': average,
        'max': maximum,
        'min': minimum,
        'std_dev': std_dev
    }

def demonstrate_performance_analysis():
    """
    展示效能分析和優化的完整流程
    
    這個函式比較低效率和高效率實作的效能差異
    展示如何使用效能分析工具來驗證優化效果
    """
    print("=" * 80)
    print("效能分析與優化示範")
    print("=" * 80)
    
    # ===== 案例 1：費波那契數列計算 =====
    print("\n【案例一】費波那契數列計算優化")
    print("-" * 80)
    
    n = 30
    
    # 分析低效率實作
    print(f"\n1. 低效率實作（遞迴無快取）")
    analyzer_inefficient = PerformanceAnalyzer()
    start_time = time.time()
    result_inefficient = analyzer_inefficient.profile_function(inefficient_fibonacci, n)
    inefficient_time = time.time() - start_time
    
    print(f"   結果：fibonacci({n}) = {result_inefficient}")
    print(f"   執行時間：{inefficient_time:.4f} 秒")
    
    # 分析高效率實作
    print(f"\n2. 高效率實作（遞迴帶快取）")
    efficient_fibonacci.cache_clear()  # 清除快取確保公平比較
    analyzer_efficient = PerformanceAnalyzer()
    start_time = time.time()
    result_efficient = analyzer_efficient.profile_function(efficient_fibonacci, n)
    efficient_time = time.time() - start_time
    
    print(f"   結果：fibonacci({n}) = {result_efficient}")
    print(f"   執行時間：{efficient_time:.4f} 秒")
    print(f"   效能提升：{inefficient_time / efficient_time:.2f} 倍")
    
    # 列印詳細的效能分析報告
    print("\n   低效率實作的效能分析：")
    analyzer_inefficient.print_analysis()
    
    print("\n   高效率實作的效能分析：")
    analyzer_efficient.print_analysis()
    
    # ===== 案例 2：大型資料集處理 =====
    print("\n\n【案例二】大型資料集處理優化")
    print("-" * 80)
    
    large_dataset = list(range(1000000))
    
    # 分析低效率實作
    print(f"\n1. 低效率實作（多次遍歷）")
    analyzer_dataset_inefficient = PerformanceAnalyzer()
    start_time = time.time()
    result_dataset_inefficient = analyzer_dataset_inefficient.profile_function(
        process_large_dataset_inefficient, large_dataset
    )
    dataset_inefficient_time = time.time() - start_time
    
    print(f"   執行時間：{dataset_inefficient_time:.4f} 秒")
    print(f"   結果統計：平均值 = {result_dataset_inefficient['average']:.2f}")
    
    # 分析高效率實作
    print(f"\n2. 高效率實作（減少遍歷）")
    analyzer_dataset_efficient = PerformanceAnalyzer()
    start_time = time.time()
    result_dataset_efficient = analyzer_dataset_efficient.profile_function(
        process_large_dataset_efficient, large_dataset
    )
    dataset_efficient_time = time.time() - start_time
    
    print(f"   執行時間：{dataset_efficient_time:.4f} 秒")
    print(f"   結果統計：平均值 = {result_dataset_efficient['average']:.2f}")
    print(f"   效能提升：{dataset_inefficient_time / dataset_efficient_time:.2f} 倍")
    
    # 列印詳細的效能分析報告
    print("\n   低效率實作的效能分析：")
    analyzer_dataset_inefficient.print_analysis()
    
    print("\n   高效率實作的效能分析：")
    analyzer_dataset_efficient.print_analysis()
    
    # 總結
    print("\n" + "=" * 80)
    print("效能優化總結")
    print("=" * 80)
    print("1. 費波那契計算：透過快取避免重複計算，效能提升數百倍")
    print("2. 資料集處理：減少遍歷次數，降低時間複雜度的常數係數")
    print("3. 使用效能分析工具可以精準定位瓶頸，避免盲目優化")
    print("4. 優化應該基於實際測量資料，而非主觀猜測")
    print("=" * 80)

if __name__ == "__main__":
    demonstrate_performance_analysis()

from abc import ABC, abstractmethod
from typing import Dict, List, Optional, Any
from datetime import datetime
from enum import Enum
import json

# ============ 資料存取層 Data Access Layer ============

class OrderStatus(Enum):
    """
    訂單狀態列舉
    
    定義訂單在系統中可能的各種狀態
    這些狀態代表了訂單的生命週期
    """
    PENDING = "pending"          # 待確認
    CONFIRMED = "confirmed"      # 已確認
    PROCESSING = "processing"    # 處理中
    SHIPPED = "shipped"          # 已出貨
    DELIVERED = "delivered"      # 已送達
    CANCELLED = "cancelled"      # 已取消

class IRepository(ABC):
    """
    資料存取介面
    
    定義所有資料存取層必須實作的基本操作
    這個介面讓業務邏輯層與具體的資料存取實作解耦
    遵循依賴反轉原則：高層模組不依賴低層模組，兩者都依賴抽象
    
    在實際應用中，這個介面還可以包含：
    - 交易管理方法
    - 批次操作方法
    - 複雜查詢方法
    """
    
    @abstractmethod
    def find_by_id(self, entity_id: str) -> Optional[Dict[str, Any]]:
        """
        根據 ID 查詢實體
        
        Args:
            entity_id: 實體的唯一識別碼
        
        Returns:
            Optional[Dict[str, Any]]: 實體資料字典，如果不存在則返回 None
        """
        pass
    
    @abstractmethod
    def find_all(self) -> List[Dict[str, Any]]:
        """
        查詢所有實體
        
        Returns:
            List[Dict[str, Any]]: 包含所有實體的列表
        """
        pass
    
    @abstractmethod
    def save(self, entity: Dict[str, Any]) -> bool:
        """
        儲存實體
        
        Args:
            entity: 要儲存的實體資料
        
        Returns:
            bool: 儲存是否成功
        """
        pass
    
    @abstractmethod
    def delete(self, entity_id: str) -> bool:
        """
        刪除實體
        
        Args:
            entity_id: 要刪除的實體 ID
        
        Returns:
            bool: 刪除是否成功
        """
        pass

class OrderRepository(IRepository):
    """
    訂單資料存取實作
    
    實作訂單相關的資料庫操作
    在實際應用中，這裡會使用 SQLAlchemy 等 ORM 框架
    或直接使用資料庫驅動程式
    
    這個類別封裝了所有與資料庫互動的細節
    業務邏輯層不需要知道資料是如何儲存的
    """
    
    def __init__(self):
        """
        初始化訂單儲存庫
        
        在記憶體中模擬資料庫
        實際應用中應該連線到真實的資料庫
        """
        self._storage: Dict[str, Dict[str, Any]] = {}
        self._id_counter = 1
    
    def find_by_id(self, entity_id: str) -> Optional[Dict[str, Any]]:
        """
        根據 ID 查詢訂單
        
        Args:
            entity_id: 訂單 ID
        
        Returns:
            Optional[Dict[str, Any]]: 訂單資料或 None
        """
        return self._storage.get(entity_id)
    
    def find_all(self) -> List[Dict[str, Any]]:
        """
        查詢所有訂單
        
        Returns:
            List[Dict[str, Any]]: 所有訂單的列表
        """
        return list(self._storage.values())
    
    def find_by_status(self, status: OrderStatus) -> List[Dict[str, Any]]:
        """
        根據狀態查詢訂單
        
        Args:
            status: 訂單狀態
        
        Returns:
            List[Dict[str, Any]]: 符合條件的訂單列表
        
        這是一個自定義的查詢方法
        展示了如何擴展基本的 CRUD 操作
        """
        return [
            order for order in self._storage.values()
            if order['status'] == status.value
        ]
    
    def save(self, entity: Dict[str, Any]) -> bool:
        """
        儲存訂單
        
        如果訂單 ID 不存在，則建立新訂單並分配 ID
        如果訂單 ID 已存在，則更新現有訂單
        
        Args:
            entity: 訂單資料
        
        Returns:
            bool: 儲存是否成功
        """
        try:
            # 如果沒有 ID 或 ID 為空，分配新 ID
            if 'id' not in entity or not entity['id']:
                entity['id'] = f"ORD-{self._id_counter:06d}"
                self._id_counter += 1
            
            # 更新時間戳記
            entity['updated_at'] = datetime.now().isoformat()
            
            # 儲存到記憶體
            self._storage[entity['id']] = entity
            
            return True
            
        except Exception as e:
            print(f"儲存訂單失敗：{str(e)}")
            return False
    
    def delete(self, entity_id: str) -> bool:
        """
        刪除訂單
        
        Args:
            entity_id: 訂單 ID
        
        Returns:
            bool: 刪除是否成功
        """
        try:
            if entity_id in self._storage:
                del self._storage[entity_id]
                return True
            return False
            
        except Exception as e:
            print(f"刪除訂單失敗：{str(e)}")
            return False

# ============ 業務邏輯層 Business Logic Layer ============

class OrderService:
    """
    訂單業務邏輯服務
    
    包含訂單處理的核心業務規則和流程
    透過依賴注入的方式使用資料存取層
    
    這一層是系統的核心，包含所有的業務邏輯：
    - 訂單建立和驗證
    - 折扣計算
    - 狀態管理
    - 業務規則執行
    """
    
    def __init__(self, repository: IRepository):
        """
        初始化訂單服務
        
        Args:
            repository: 資料存取層的實作物件
        
        透過依賴介面而非具體實作
        這是依賴反轉原則的實踐
        讓服務層可以與任何實作 IRepository 介面的類別協作
        """
        self.repository = repository
    
    def create_order(self, customer_id: str, items: List[Dict[str, Any]]) -> Dict[str, Any]:
        """
        建立新訂單
        
        Args:
            customer_id: 客戶 ID
            items: 訂單項目列表
        
        Returns:
            Dict[str, Any]: 建立的訂單資料
        
        這個方法包含完整的訂單建立業務邏輯：
        1. 資料驗證
        2. 金額計算
        3. 折扣應用
        4. 狀態初始化
        5. 資料持久化
        """
        # 驗證輸入資料
        if not customer_id:
            raise ValueError("客戶 ID 不能為空")
        
        if not items or len(items) == 0:
            raise ValueError("訂單必須至少包含一個項目")
        
        # 計算訂單總金額
        total_amount = self._calculate_total_amount(items)
        
        # 應用折扣規則
        discount = self._apply_discount_rules(total_amount, items)
        final_amount = total_amount - discount
        
        # 建立訂單物件
        order = {
            'id': '',  # 由資料存取層分配
            'customer_id': customer_id,
            'items': items,
            'subtotal': total_amount,
            'discount': discount,
            'total': final_amount,
            'status': OrderStatus.PENDING.value,
            'created_at': datetime.now().isoformat(),
            'updated_at': datetime.now().isoformat()
        }
        
        # 儲存訂單
        if self.repository.save(order):
            print(f"訂單建立成功：{order['id']}")
            return order
        else:
            raise RuntimeError("訂單儲存失敗")
    
    def _calculate_total_amount(self, items: List[Dict[str, Any]]) -> float:
        """
        計算訂單總金額
        
        Args:
            items: 訂單項目列表
        
        Returns:
            float: 總金額
        
        這是一個私有方法，只在服務內部使用
        封裝了金額計算的具體邏輯
        """
        total = 0.0
        for item in items:
            quantity = item.get('quantity', 0)
            price = item.get('price', 0.0)
            total += quantity * price
        
        return round(total, 2)
    
    def _apply_discount_rules(self, total_amount: float, items: List[Dict[str, Any]]) -> float:
        """
        應用折扣規則
        
        Args:
            total_amount: 訂單原始總金額
            items: 訂單項目列表
        
        Returns:
            float: 折扣金額
        
        實作各種折扣邏輯：
        - 滿額折扣
        - 數量折扣
        - 會員折扣（未實作）
        - 促銷活動折扣（未實作）
        """
        discount = 0.0
        
        # 規則 1：訂單金額超過 10000 元，折扣 5%
        if total_amount > 10000:
            discount += total_amount * 0.05
        
        # 規則 2：購買 3 件以上商品，額外折扣 100 元
        total_quantity = sum(item.get('quantity', 0) for item in items)
        if total_quantity >= 3:
            discount += 100
        
        return round(discount, 2)
    
    def confirm_order(self, order_id: str) -> bool:
        """
        確認訂單
        
        Args:
            order_id: 訂單 ID
        
        Returns:
            bool: 確認是否成功
        
        將訂單狀態從 PENDING 變更為 CONFIRMED
        這通常發生在付款完成或庫存確認後
        """
        order = self.repository.find_by_id(order_id)
        
        if not order:
            raise ValueError(f"訂單不存在：{order_id}")
        
        if order['status'] != OrderStatus.PENDING.value:
            raise ValueError(
                f"訂單狀態不正確，無法確認：當前狀態為 {order['status']}"
            )
        
        order['status'] = OrderStatus.CONFIRMED.value
        return self.repository.save(order)
    
    def cancel_order(self, order_id: str, reason: str) -> bool:
        """
        取消訂單
        
        Args:
            order_id: 訂單 ID
            reason: 取消原因
        
        Returns:
            bool: 取消是否成功
        
        實作訂單取消的業務邏輯：
        - 驗證訂單狀態
        - 檢查是否可以取消
        - 更新訂單狀態
        - 記錄取消原因
        """
        order = self.repository.find_by_id(order_id)
        
        if not order:
            raise ValueError(f"訂單不存在：{order_id}")
        
        # 已出貨的訂單不能取消
        if order['status'] in [OrderStatus.SHIPPED.value, OrderStatus.DELIVERED.value]:
            raise ValueError(f"訂單已出貨，無法取消")
        
        order['status'] = OrderStatus.CANCELLED.value
        order['cancellation_reason'] = reason
        order['cancelled_at'] = datetime.now().isoformat()
        
        return self.repository.save(order)
    
    def get_order_details(self, order_id: str) -> Dict[str, Any]:
        """
        獲取訂單詳細資訊
        
        Args:
            order_id: 訂單 ID
        
        Returns:
            Dict[str, Any]: 訂單詳細資訊
        """
        order = self.repository.find_by_id(order_id)
        
        if not order:
            raise ValueError(f"訂單不存在：{order_id}")
        
        return order

# ============ 展示層 Presentation Layer ============

class OrderController:
    """
    訂單控制器
    
    處理來自使用者介面的請求
    並呼叫業務邏輯層的服務來完成操作
    
    這一層負責：
    - 請求驗證
    - 格式轉換
    - 錯誤處理
    - 回應格式化
    """
    
    def __init__(self, order_service: OrderService):
        """
        初始化訂單控制器
        
        Args:
            order_service: 訂單業務邏輯服務
        
        展示層依賴業務邏輯層
        但不直接存取資料存取層
        """
        self.order_service = order_service
    
    def handle_create_order_request(self, request_data: Dict[str, Any]) -> Dict[str, Any]:
        """
        處理建立訂單請求
        
        Args:
            request_data: 請求資料
        
        Returns:
            Dict[str, Any]: 回應資料
        
        這個方法負責：
        1. 解析請求資料
        2. 呼叫業務邏輯服務
        3. 處理異常
        4. 格式化回應
        """
        try:
            customer_id = request_data.get('customer_id')
            items = request_data.get('items', [])
            
            # 呼叫業務邏輯層建立訂單
            order = self.order_service.create_order(customer_id, items)
            
            # 格式化成功回應
            return {
                'success': True,
                'message': '訂單建立成功',
                'data': order
            }
            
        except ValueError as e:
            # 處理業務邏輯驗證錯誤
            return {
                'success': False,
                'message': f'輸入資料驗證失敗：{str(e)}',
                'data': None
            }
            
        except Exception as e:
            # 處理其他錯誤
            return {
                'success': False,
                'message': f'系統錯誤：{str(e)}',
                'data': None
            }
    
    def handle_get_order_request(self, order_id: str) -> Dict[str, Any]:
        """
        處理查詢訂單請求
        
        Args:
            order_id: 訂單 ID
        
        Returns:
            Dict[str, Any]: 回應資料
        """
        try:
            order = self.order_service.get_order_details(order_id)
            
            return {
                'success': True,
                'message': '查詢成功',
                'data': order
            }
            
        except ValueError as e:
            return {
                'success': False,
                'message': str(e),
                'data': None
            }
    
    def handle_confirm_order_request(self, order_id: str) -> Dict[str, Any]:
        """
        處理確認訂單請求
        
        Args:
            order_id: 訂單 ID
        
        Returns:
            Dict[str, Any]: 回應資料
        """
        try:
            success = self.order_service.confirm_order(order_id)
            
            return {
                'success': success,
                'message': '訂單確認成功' if success else '訂單確認失敗',
                'data': None
            }
            
        except ValueError as e:
            return {
                'success': False,
                'message': str(e),
                'data': None
            }

# ============ 使用範例 ============

def demonstrate_layered_architecture():
    """
    展示分層架構的實際應用
    
    這個函式模擬了一個完整的訂單處理流程
    展示各個層級如何協作完成業務功能
    """
    print("=" * 80)
    print("分層架構示範：訂單管理系統")
    print("=" * 80)
    
    # 初始化各層級
    # 從底層向上層建立，體現了依賴關係
    
    # 資料存取層
    order_repository = OrderRepository()
    
    # 業務邏輯層（依賴資料存取層）
    order_service = OrderService(order_repository)
    
    # 展示層（依賴業務邏輯層）
    order_controller = OrderController(order_service)
    
    # 模擬使用者請求 1：建立訂單
    print("\n【步驟一】建立訂單")
    print("-" * 80)
    
    create_request = {
        'customer_id': 'CUST-001',
        'items': [
            {'product_id': 'PROD-101', 'name': '筆記型電腦', 'quantity': 1, 'price': 35000},
            {'product_id': 'PROD-102', 'name': '滑鼠', 'quantity': 2, 'price': 500},
            {'product_id': 'PROD-103', 'name': '鍵盤', 'quantity': 1, 'price': 2000}
        ]
    }
    
    response = order_controller.handle_create_order_request(create_request)
    print(json.dumps(response, indent=2, ensure_ascii=False))
    
    if response['success']:
        order_id = response['data']['id']
        
        # 模擬使用者請求 2：查詢訂單
        print("\n【步驟二】查詢訂單")
        print("-" * 80)
        
        get_response = order_controller.handle_get_order_request(order_id)
        print(json.dumps(get_response, indent=2, ensure_ascii=False))
        
        # 模擬使用者請求 3：確認訂單
        print("\n【步驟三】確認訂單")
        print("-" * 80)
        
        confirm_response = order_controller.handle_confirm_order_request(order_id)
        print(json.dumps(confirm_response, indent=2, ensure_ascii=False))
        
        # 再次查詢以確認狀態變更
        print("\n【步驟四】確認後查詢訂單")
        print("-" * 80)
        
        final_response = order_controller.handle_get_order_request(order_id)
        print(json.dumps(final_response, indent=2, ensure_ascii=False))
    
    # 總結
    print("\n" + "=" * 80)
    print("分層架構的優勢")
    print("=" * 80)
    print("1. 職責分離：每一層都有明確的職責，易於理解和維護")
    print("2. 可測試性：每一層可以獨立進行單元測試")
    print("3. 可替換性：透過介面依賴，實作可以輕鬆替換")
    print("4. 團隊協作：不同團隊可以並行開發不同層級")
    print("5. 技術演進：可以逐步升級某一層的技術，不影響其他層")
    print("=" * 80)

if __name__ == "__main__":
    demonstrate_layered_architecture()