README_REFACTOR.md

數位保鏢系統 - 重構版本

此專案已將原本的單一 app.py 檔案重構成多個模組化的檔案，以提高程式碼的可維護性和可讀性。

檔案結構說明

主要模組

app.py - 主程式

• 用途: 系統啟動點，整合所有模組
• 功能:
  • 初始化系統設定（字型、警告抑制）
  • 載入機器學習模型和歷史資料
  • 設定 CORS 中介軟體
  • 啟動 FastAPI + Gradio 整合服務

config.py - 配置管理

• 用途: 集中管理系統配置、環境變數和常數
• 包含:
  • SMTP 設定
  • 系統權重設定
  • 動作映射表
  • 用戶資料庫
  • 伺服器設定
  • 模型檔案路徑

utils.py - 工具函數

• 用途: 通用工具函數和輔助功能
• 功能:
  • 中文字型下載和設定
  • 警告抑制
  • IP 分類和地理等級判斷
  • 系統權重更新
  • 時間格式驗證

models.py - 機器學習模型

• 用途: 處理 AI 模型載入、資料處理和異常偵測
• 功能:
  • 載入標籤編碼器和歷史資料
  • HDBSCAN 異常偵測演算法
  • 日誌記錄和統計更新
  • 特徵工程和資料預處理

auth.py - 身份驗證

• 用途: 處理用戶登入、驗證和會話管理
• 功能:
  • 登入處理邏輯
  • 快速登入功能
  • 角色切換
  • 登出處理
  • 模擬點擊操作

security.py - 安全功能

• 用途: 安全警報和身份驗證機制
• 功能:
  • 安全郵件發送
  • 身份驗證觸發
  • 異常日誌分析（使用 Groq AI）
  • 郵件鏈接驗證

api.py - API 端點

• 用途: 定義所有 REST API 端點
• 功能:
  • 統計資料 API
  • 日誌查詢 API
  • 圖表資料 API
  • 身份驗證 API
  • Vue 前端整合 API

plotting.py - 圖表繪製

• 用途: 處理所有圖表生成和可視化功能
• 功能:
  • 統計儀表板 HTML 生成
  • Matplotlib/Seaborn 圖表繪製
  • Base64 圖片編碼
  • 定時更新功能

ui.py - 用戶界面

• 用途: Gradio 用戶界面設計和事件處理
• 功能:
  • 登入界面
  • 儀表板界面
  • 管理員界面
  • 學生操作界面
  • 事件綁定和狀態管理

程式碼組織原則

1. 單一責任原則: 每個模組負責特定的功能領域
2. 依賴注入: 通過 import 清晰地展示模組間的依賴關係
3. 配置集中化: 所有配置項集中在 config.py
4. 工具抽象化: 通用功能抽取到 utils.py
5. 關注點分離: 將業務邏輯、資料處理、UI 渲染分離

啟動方式

python app.py

系統將自動：

1. 載入所有模組
2. 初始化機器學習模型
3. 設定網路服務
4. 啟動整合的 FastAPI + Gradio 應用

環境需求

• Python 3.8+
• 必要的套件（見 requirements.txt）
• 模型檔案（le_action.pkl, baseline_logs.csv）
• 環境變數配置（.env 檔案）

開發注意事項

• 修改配置時，請在 config.py 中進行
• 新增功能時，請考慮將其放入適當的模組
• 保持模組間的低耦合和高內聚
• 測試時請確保所有模組都能正常載入