// EnvReader：環境變數讀取器介面，統一管理 .env 或系統環境變數
type EnvReader interface {
	Get(key string) string
	GetOrDefault(key, fallback string) string
}

// ConfigManager：整合環境變數與設定檔管理
// 功能：
// - 統一管理環境變數和設定檔
// - 支援設定檔熱重載
// - 提供型別安全的配置讀取
// - 支援配置驗證
type ConfigManager interface {
	// 設定檔操作
	// Load：載入指定路徑的設定檔
	// GetConfig：取得指定 key 的設定值
	// Watch：註冊設定變更回調函數
	Load(path string) error
	GetConfig(key string) any
	Watch(callback func(key string, value any))
	
	// 驗證與轉換
	// Validate：驗證所有設定值是否符合規則
	// GetString/GetInt/GetBool：型別安全的配置讀取
	Validate() error
	GetString(key string) string
	GetInt(key string) int
	GetBool(key string) bool
}

// Logger：通用日誌介面，支援多級別與上下文
// 功能：
// - 支援多級別日誌（Debug/Info/Warn/Error）
// - 支援結構化日誌
// - 支援上下文追蹤
// - 支援錯誤鏈追蹤
type Logger interface {
	// 基本日誌方法
	// Debug：用於開發時期的詳細資訊
	// Info：用於一般資訊記錄
	// Warn：用於警告訊息
	// Error：用於錯誤訊息
	Debug(msg string, fields ...any)
	Info(msg string, fields ...any)
	Warn(msg string, fields ...any)
	Error(msg string, fields ...any)
	
	// 上下文擴充
	// With：新增固定欄位到日誌
	// WithContext：從 context 提取追蹤資訊
	// WithError：記錄錯誤資訊
	With(fields ...any) Logger
	WithContext(ctx context.Context) Logger
	WithError(err error) Logger
}

// Telemetry：整合追蹤與指標收集
// 功能：
// - 分散式追蹤
// - 指標收集
// - 取樣率控制
// - 自定義標籤
type Telemetry interface {
	// 追蹤相關
	// StartSpan：開始新的追蹤區間
	// GenerateTraceID：生成追蹤 ID
	// SetSamplingRate：設定取樣率
	StartSpan(ctx context.Context, name string) (context.Context, Span)
	GenerateTraceID() string
	SetSamplingRate(rate float64)
	
	// 指標相關
	// RecordCounter：記錄計數器
	// RecordGauge：記錄儀表值
	// RecordHistogram：記錄直方圖
	RecordCounter(name string, value int64, labels map[string]string)
	RecordGauge(name string, value float64, labels map[string]string)
	RecordHistogram(name string, value float64, labels map[string]string)
}

// Span：抽象化的 OTel span
// 功能：
// - 追蹤區間管理
// - 事件記錄
// - 屬性設定
type Span interface {
	// End：結束追蹤區間
	// AddEvent：新增事件
	// SetAttributes：設定屬性
	End()
	AddEvent(name string)
	SetAttributes(attrs map[string]any)
}

// RedisClient：Redis 操作介面
// 功能：
// - 鍵值操作
// - 發布訂閱
// - 集合操作
// - 事務支援
type RedisClient interface {
	// 基本操作
	// Set：設定鍵值，支援 TTL
	// Get：取得鍵值
	// Delete：刪除鍵值
	Set(key string, value any, ttl time.Duration) error
	Get(key string) (string, error)
	Delete(key string) error
	
	// 發布訂閱
	// Publish：發布訊息
	// Subscribe：訂閱訊息
	Publish(channel string, payload any) error
	Subscribe(channel string, handler func(payload string)) error
	
	// 集合操作
	// SAdd：新增集合成員
	// SMembers：取得集合成員
	SAdd(key string, members ...string) error
	SMembers(key string) ([]string, error)
	
	// 事務支援
	// Begin：開始事務
	Begin() (Transaction, error)
}

// Transaction：Redis 事務介面
// 功能：
// - 事務提交
// - 事務回滾
type Transaction interface {
	// Exec：提交事務
	// Rollback：回滾事務
	Exec() error
	Rollback() error
}

// InfluxWriter：InfluxDB 寫入介面
type InfluxWriter interface {
	WritePoint(measurement string, tags map[string]string, fields map[string]any, ts time.Time) error
}

// AuthProvider：認證提供者介面（如：Keycloak）
type AuthProvider interface {
	Login(username, password string) (token string, err error)
	ValidateToken(token string) (bool, error)
}

// SQLClient：MySQL 操作封裝介面
// 功能：
// - SQL 查詢執行
// - 事務管理
// - 預處理語句
// - 連接池管理
type SQLClient interface {
	// 基本操作
	// Query：執行查詢
	// Exec：執行更新
	Query(query string, args ...any) ([]map[string]any, error)
	Exec(query string, args ...any) error
	
	// 事務支援
	// Begin：開始事務
	Begin() (Transaction, error)
	
	// 預處理語句
	// Prepare：準備預處理語句
	Prepare(query string) (Stmt, error)
	
	// 連接池管理
	// SetMaxOpenConns：設定最大連接數
	// SetMaxIdleConns：設定最大閒置連接數
	// SetConnMaxLifetime：設定連接生命週期
	SetMaxOpenConns(n int)
	SetMaxIdleConns(n int)
	SetConnMaxLifetime(d time.Duration)
}

// Transaction：SQL 事務介面
// 功能：
// - 事務提交
// - 事務回滾
type Transaction interface {
	// Commit：提交事務
	// Rollback：回滾事務
	Commit() error
	Rollback() error
}

// Stmt：預處理語句介面
// 功能：
// - 參數化查詢
// - 參數化更新
// - 資源釋放
type Stmt interface {
	// Query：執行參數化查詢
	// Exec：執行參數化更新
	// Close：釋放資源
	Query(args ...any) ([]map[string]any, error)
	Exec(args ...any) error
	Close() error
}

// EventBus：事件匯流排介面
// 功能：
// - 事件發布訂閱
// - 重試機制
// - 死信佇列
// - 訊息過期
type EventBus interface {
	// 基本操作
	// Publish：發布事件
	// Subscribe：訂閱事件
	Publish(stream string, payload map[string]any) error
	Subscribe(stream string, handler func(entry map[string]any)) error
	
	// 進階功能
	// PublishWithRetry：支援重試的發布
	// SubscribeWithDeadLetter：支援死信佇列的訂閱
	// SetMessageTTL：設定訊息過期時間
	PublishWithRetry(stream string, payload map[string]any, maxRetries int) error
	SubscribeWithDeadLetter(stream string, handler func(entry map[string]any), dlq string) error
	SetMessageTTL(stream string, ttl time.Duration) error
}

// FileStore：檔案操作介面
// 功能：
// - 檔案讀寫
// - 檔案鎖定
// - 版本控制
// - 元資料管理
type FileStore interface {
	// 基本操作
	// Read：讀取檔案
	// Write：寫入檔案
	// Delete：刪除檔案
	Read(path string) ([]byte, error)
	Write(path string, content []byte) error
	Delete(path string) error
	
	// 進階功能
	// Lock：檔案鎖定
	// Unlock：檔案解鎖
	// GetMetadata：取得檔案元資料
	// ListVersions：列出檔案版本
	Lock(path string) error
	Unlock(path string) error
	GetMetadata(path string) (FileMetadata, error)
	ListVersions(path string) ([]FileVersion, error)
}

// FileMetadata：檔案元資料
// 功能：記錄檔案的基本資訊
type FileMetadata struct {
	Size    int64     // 檔案大小
	ModTime time.Time // 修改時間
	Hash    string    // 檔案雜湊值
}

// FileVersion：檔案版本
// 功能：記錄檔案的版本資訊
type FileVersion struct {
	Version   string    // 版本號
	Timestamp time.Time // 版本時間
	Hash      string    // 版本雜湊值
}

// DataSource：通用資料來源介面
// 功能：
// - CRUD 操作
// - 分頁查詢
// - 排序功能
// - 批量操作
// - 資料驗證
type DataSource interface {
	// 基本操作
	// List：列出資料
	// Create：新增資料
	// Update：更新資料
	// Delete：刪除資料
	List(filter map[string]any) ([]map[string]any, error)
	Create(record map[string]any) error
	Update(id string, record map[string]any) error
	Delete(id string) error
	
	// 進階功能
	// ListWithPagination：分頁查詢
	// ListWithSort：排序查詢
	// BatchCreate：批量新增
	// BatchUpdate：批量更新
	// Validate：資料驗證
	ListWithPagination(filter map[string]any, page, size int) ([]map[string]any, int64, error)
	ListWithSort(filter map[string]any, sortBy string, ascending bool) ([]map[string]any, error)
	BatchCreate(records []map[string]any) error
	BatchUpdate(records []map[string]any) error
	Validate(record map[string]any) error
}

// AuthProvider：認證提供者介面
// 功能：
// - 使用者認證
// - 令牌管理
// - 權限檢查
// - 角色管理
type AuthProvider interface {
	// 基本操作
	// Login：使用者登入
	// ValidateToken：驗證令牌
	// Logout：使用者登出
	Login(username, password string) (token string, err error)
	ValidateToken(token string) (bool, error)
	Logout(token string) error
	
	// 進階功能
	// RefreshToken：更新令牌
	// GetUserInfo：取得使用者資訊
	// CheckPermission：檢查權限
	// ListRoles：列出角色
	RefreshToken(token string) (string, error)
	GetUserInfo(token string) (UserInfo, error)
	CheckPermission(token string, resource string, action string) (bool, error)
	ListRoles() ([]Role, error)
}

// UserInfo：使用者資訊
// 功能：記錄使用者的基本資訊
type UserInfo struct {
	ID       string   // 使用者 ID
	Username string   // 使用者名稱
	Email    string   // 電子郵件
	Roles    []string // 角色列表
}

// Role：角色資訊
// 功能：記錄角色的權限資訊
type Role struct {
	ID          string       // 角色 ID
	Name        string       // 角色名稱
	Permissions []Permission // 權限列表
}

// CacheManager：快取管理介面
// 功能：
// - 快取存取
// - TTL 管理
// - 批量操作
// - 快取回填
type CacheManager interface {
	// 基本操作
	// Get：取得快取
	// Set：設定快取
	// Delete：刪除快取
	// Clear：清除所有快取
	Get(key string) (any, error)
	Set(key string, value any, ttl time.Duration) error
	Delete(key string) error
	Clear() error
	
	// 進階功能
	// GetOrSet：取得或設定快取
	// GetMulti：批量取得快取
	// SetMulti：批量設定快取
	GetOrSet(key string, ttl time.Duration, getter func() (any, error)) (any, error)
	GetMulti(keys []string) (map[string]any, error)
	SetMulti(items map[string]any, ttl time.Duration) error
}

// JobScheduler：任務排程介面
// 功能：
// - 任務排程
// - 任務管理
// - 執行記錄
// - 重試機制
type JobScheduler interface {
	// 基本操作
	// Schedule：排程任務
	// Cancel：取消任務
	// ListJobs：列出任務
	// GetJobStatus：取得任務狀態
	Schedule(job Job) error
	Cancel(jobID string) error
	ListJobs() ([]Job, error)
	GetJobStatus(jobID string) (JobStatus, error)
	
	// 進階功能
	// PauseJob：暫停任務
	// ResumeJob：恢復任務
	// UpdateJob：更新任務
	// GetJobHistory：取得任務歷史
	PauseJob(jobID string) error
	ResumeJob(jobID string) error
	UpdateJob(job Job) error
	GetJobHistory(jobID string) ([]JobExecution, error)
}

// Job：任務定義
// 功能：定義任務的基本資訊
type Job struct {
	ID          string       // 任務 ID
	Name        string       // 任務名稱
	Cron        string       // Cron 表達式
	Handler     func() error // 處理函數
	RetryPolicy RetryPolicy  // 重試策略
}

// JobStatus：任務狀態
// 功能：記錄任務的執行狀態
type JobStatus struct {
	Status     string    // 狀態
	LastRun    time.Time // 上次執行時間
	NextRun    time.Time // 下次執行時間
	Error      error     // 錯誤資訊
	RetryCount int       // 重試次數
}

// JobExecution：任務執行記錄
// 功能：記錄任務的執行歷史
type JobExecution struct {
	StartTime time.Time // 開始時間
	EndTime   time.Time // 結束時間
	Status    string    // 狀態
	Error     error     // 錯誤資訊
	Output    string    // 輸出資訊
}

// SecretManager：密鑰管理介面
// 功能：
// - 密鑰存取
// - 版本控制
// - 密鑰輪換
// - 元資料管理
type SecretManager interface {
	// 基本操作
	// GetSecret：取得密鑰
	// SetSecret：設定密鑰
	// DeleteSecret：刪除密鑰
	// ListSecrets：列出密鑰
	GetSecret(key string) (string, error)
	SetSecret(key string, value string) error
	DeleteSecret(key string) error
	ListSecrets() ([]string, error)
	
	// 進階功能
	// GetSecretWithVersion：取得指定版本的密鑰
	// RotateSecret：輪換密鑰
	// GetSecretMetadata：取得密鑰元資料
	GetSecretWithVersion(key string, version string) (string, error)
	RotateSecret(key string) error
	GetSecretMetadata(key string) (SecretMetadata, error)
}

// SecretMetadata：密鑰元資料
// 功能：記錄密鑰的基本資訊
type SecretMetadata struct {
	CreatedAt  time.Time // 建立時間
	UpdatedAt  time.Time // 更新時間
	Version    string    // 版本號
	ExpiresAt  time.Time // 過期時間
}

// ErrorHandler：錯誤處理介面
// 功能：
// - 錯誤處理
// - 錯誤分類
// - 錯誤追蹤
// - 錯誤上下文
type ErrorHandler interface {
	// 基本操作
	// HandleError：處理錯誤
	// IsRetryable：判斷是否可重試
	// GetErrorCode：取得錯誤代碼
	// GetErrorDetails：取得錯誤詳情
	HandleError(err error) error
	IsRetryable(err error) bool
	GetErrorCode(err error) string
	GetErrorDetails(err error) map[string]any
	
	// 進階功能
	// WrapError：包裝錯誤
	// UnwrapError：解包錯誤
	// GetErrorStack：取得錯誤堆疊
	// GetErrorContext：取得錯誤上下文
	WrapError(err error, message string) error
	UnwrapError(err error) error
	GetErrorStack(err error) []string
	GetErrorContext(err error) map[string]any
}

// AnalyzerPlugin：異常分析插件介面
// 功能：
// - 異常檢測
// - 模型訓練
// - 模型資訊管理
// - 配置更新
type AnalyzerPlugin interface {
	// 基本操作
	// Detect：執行異常檢測
	Detect(metricSet any) (AnomalyResult, error)
	
	// 進階功能
	// Train：訓練模型
	// GetModelInfo：取得模型資訊
	// UpdateConfig：更新配置
	Train(data []any) error
	GetModelInfo() ModelInfo
	UpdateConfig(config map[string]any) error
}

// ModelInfo：模型資訊
// 功能：記錄模型的基本資訊和效能指標
type ModelInfo struct {
	Name        string             // 模型名稱
	Version     string             // 模型版本
	LastUpdated time.Time          // 最後更新時間
	Metrics     map[string]float64 // 效能指標
}

// AnomalyResult：異常分析結果
// 功能：記錄異常檢測的結果和詳情
type AnomalyResult struct {
	IsAnomaly bool              // 是否為異常
	Score     float64           // 異常分數
	Reason    string            // 異常原因
	Details   map[string]any    // 詳細資訊
}

// LLMPlugin：自然語言處理插件介面
// 功能：
// - 文字摘要
// - 文本分析
// - 文本生成
// - 向量嵌入
type LLMPlugin interface {
	// 基本操作
	// Summarize：生成文字摘要
	Summarize(input LLMInput) (string, error)
	
	// 進階功能
	// Analyze：分析文本內容
	// Generate：生成文本內容
	// GetEmbedding：取得文本向量
	Analyze(input LLMInput) (AnalysisResult, error)
	Generate(input LLMInput) (string, error)
	GetEmbedding(text string) ([]float64, error)
}

// LLMInput：LLM 輸入資料結構
// 功能：定義 LLM 處理所需的輸入參數
type LLMInput struct {
	Context    string         // 上下文資訊
	Prompt     string         // 提示詞
	Parameters map[string]any // 模型參數
}

// AnalysisResult：分析結果
// 功能：記錄文本分析的結果
type AnalysisResult struct {
	Summary    string   // 摘要
	Keywords   []string // 關鍵詞
	Sentiment  float64  // 情感分數
	Categories []string // 分類結果
}

// NotifierPlugin：通知插件介面
// 功能：
// - 事件通知
// - 模板通知
// - 重試機制
// - 狀態追蹤
type NotifierPlugin interface {
	// 基本操作
	// Notify：發送通知
	Notify(event AlertEvent) error
	
	// 進階功能
	// NotifyWithTemplate：使用模板發送通知
	// NotifyWithRetry：支援重試的通知
	// GetNotificationStatus：取得通知狀態
	NotifyWithTemplate(event AlertEvent, template string) error
	NotifyWithRetry(event AlertEvent, maxRetries int) error
	GetNotificationStatus(eventID string) (NotificationStatus, error)
}

// NotificationStatus：通知狀態
// 功能：記錄通知的發送狀態
type NotificationStatus struct {
	EventID    string    // 事件 ID
	Status     string    // 通知狀態
	SentAt     time.Time // 發送時間
	RetryCount int       // 重試次數
	Error      error     // 錯誤資訊
}

// AutomationPlugin：自動化執行動作的介面
// 功能：
// - 動作執行
// - 超時控制
// - 重試機制
// - 執行記錄
type AutomationPlugin interface {
	// 基本操作
	// Execute：執行自動化動作
	Execute(action AutomationAction) (AutomationResult, error)
	
	// 進階功能
	// ExecuteWithTimeout：支援超時控制的執行
	// ExecuteWithRetry：支援重試的執行
	// GetExecutionHistory：取得執行歷史
	ExecuteWithTimeout(action AutomationAction, timeout time.Duration) (AutomationResult, error)
	ExecuteWithRetry(action AutomationAction, maxRetries int) (AutomationResult, error)
	GetExecutionHistory(actionID string) ([]ExecutionRecord, error)
}

// AutomationAction：自動化動作定義
// 功能：定義自動化動作的參數
type AutomationAction struct {
	ID          string            // 動作 ID
	Name        string            // 動作名稱
	Type        string            // 動作類型
	Parameters  map[string]string // 動作參數
	RetryPolicy RetryPolicy       // 重試策略
}

// AutomationResult：自動化執行結果
// 功能：記錄自動化執行的結果
type AutomationResult struct {
	ActionID  string    // 動作 ID
	Success   bool      // 是否成功
	Output    string    // 輸出結果
	StartTime time.Time // 開始時間
	EndTime   time.Time // 結束時間
	Error     error     // 錯誤資訊
}

// ExecutionRecord：執行記錄
// 功能：記錄執行的詳細資訊
type ExecutionRecord struct {
	ActionID  string    // 動作 ID
	Status    string    // 執行狀態
	StartTime time.Time // 開始時間
	EndTime   time.Time // 結束時間
	Output    string    // 輸出結果
	Error     error     // 錯誤資訊
}

// SchedulerService：排程服務介面
// 功能：
// - 任務排程
// - 任務管理
// - 狀態追蹤
// - 歷史記錄
type SchedulerService interface {
	// 基本操作
	// ScheduleJob：排程任務
	// CancelJob：取消任務
	// GetJobStatus：取得任務狀態
	ScheduleJob(job JobDefinition) error
	CancelJob(jobID string) error
	GetJobStatus(jobID string) (JobStatus, error)
	
	// 進階功能
	// PauseJob：暫停任務
	// ResumeJob：恢復任務
	// UpdateJobSchedule：更新任務排程
	// GetJobHistory：取得任務歷史
	PauseJob(jobID string) error
	ResumeJob(jobID string) error
	UpdateJobSchedule(jobID string, schedule string) error
	GetJobHistory(jobID string) ([]JobExecution, error)
}

// JobDefinition：任務定義
// 功能：定義任務的基本資訊
type JobDefinition struct {
	ID          string        // 任務 ID
	Name        string        // 任務名稱
	Schedule    string        // 排程設定
	Handler     func() error  // 處理函數
	RetryPolicy RetryPolicy   // 重試策略
	Timeout     time.Duration // 超時設定
}

// JobStatus：任務狀態
// 功能：記錄任務的執行狀態
type JobStatus struct {
	ID         string    // 任務 ID
	Status     string    // 執行狀態
	LastRun    time.Time // 上次執行時間
	NextRun    time.Time // 下次執行時間
	Error      error     // 錯誤資訊
	RetryCount int       // 重試次數
}

// HealthChecker：健康檢查介面
// 功能：
// - 健康狀態檢查
// - 檢查項目管理
// - 詳細狀態查詢
type HealthChecker interface {
	// 基本操作
	// CheckHealth：執行健康檢查
	CheckHealth() (HealthStatus, error)
	
	// 進階功能
	// RegisterCheck：註冊檢查項目
	// UnregisterCheck：取消註冊檢查項目
	// GetDetailedStatus：取得詳細狀態
	RegisterCheck(name string, check func() error)
	UnregisterCheck(name string)
	GetDetailedStatus() map[string]ComponentStatus
}

// HealthStatus：健康狀態
// 功能：記錄系統的健康狀態
type HealthStatus struct {
	Status    string                    // 整體狀態
	Timestamp time.Time                 // 檢查時間
	Details   map[string]ComponentStatus // 元件狀態
}

// ComponentStatus：元件狀態
// 功能：記錄個別元件的狀態
type ComponentStatus struct {
	Status    string    // 元件狀態
	Message   string    // 狀態訊息
	LastCheck time.Time // 最後檢查時間
}

// RuleManager：規則管理介面
// 功能：
// - 規則 CRUD
// - 規則啟用/停用
// - 規則驗證
// - 規則過濾
type RuleManager interface {
	// 基本操作
	// CreateRule：建立規則
	// UpdateRule：更新規則
	// DeleteRule：刪除規則
	// GetRule：取得規則
	CreateRule(rule Rule) error
	UpdateRule(rule Rule) error
	DeleteRule(ruleID string) error
	GetRule(ruleID string) (Rule, error)
	
	// 進階功能
	// ListRules：列出規則
	// EnableRule：啟用規則
	// DisableRule：停用規則
	// ValidateRule：驗證規則
	ListRules(filter RuleFilter) ([]Rule, error)
	EnableRule(ruleID string) error
	DisableRule(ruleID string) error
	ValidateRule(rule Rule) error
}

// Rule：規則定義
// 功能：定義規則的基本資訊
type Rule struct {
	ID          string   // 規則 ID
	Name        string   // 規則名稱
	Description string   // 規則描述
	Condition   string   // 條件表達式
	Actions     []Action // 動作列表
	Enabled     bool     // 是否啟用
	Priority    int      // 優先級
}

// RuleFilter：規則過濾條件
// 功能：定義規則查詢的過濾條件
type RuleFilter struct {
	Enabled  *bool    // 啟用狀態
	Priority *int     // 優先級
	Tags     []string // 標籤列表
}

// ContactManager：聯絡人管理介面
// 功能：
// - 聯絡人 CRUD
// - 群組管理
// - 通知管道管理
type ContactManager interface {
	// 基本操作
	// CreateContact：建立聯絡人
	// UpdateContact：更新聯絡人
	// DeleteContact：刪除聯絡人
	// GetContact：取得聯絡人
	CreateContact(contact Contact) error
	UpdateContact(contact Contact) error
	DeleteContact(contactID string) error
	GetContact(contactID string) (Contact, error)
	
	// 進階功能
	// ListContacts：列出聯絡人
	// AddToGroup：加入群組
	// RemoveFromGroup：從群組移除
	ListContacts(filter ContactFilter) ([]Contact, error)
	AddToGroup(contactID string, groupID string) error
	RemoveFromGroup(contactID string, groupID string) error
}

// Contact：聯絡人定義
// 功能：定義聯絡人的基本資訊
type Contact struct {
	ID        string              // 聯絡人 ID
	Name      string              // 聯絡人名稱
	Email     string              // 電子郵件
	Phone     string              // 電話號碼
	Groups    []string            // 群組列表
	Channels  []NotificationChannel // 通知管道
}

// ContactFilter：聯絡人過濾條件
// 功能：定義聯絡人查詢的過濾條件
type ContactFilter struct {
	Groups    []string // 群組列表
	Channels  []string // 通知管道
	Active    *bool    // 是否啟用
}