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 渲染分離

## 啟動方式

```bash
python app.py
```

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

## 環境需求

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

## 開發注意事項

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