diff --git a/GC_Rust_Refactoring_Analysis.md b/GC_Rust_Refactoring_Analysis.md new file mode 100644 index 0000000..0d477cb --- /dev/null +++ b/GC_Rust_Refactoring_Analysis.md @@ -0,0 +1,340 @@ +# RAIDGuard X Java GUI 重構為 Rust 分析報告 + +## 1. 現有架構總覽 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Java Swing GUI (70,521 行) │ +├─────────────────────────────────────────────────────────────────┤ +│ Main Windows │ frmMain (7,397 行) │ +│ │ frmSettings (2,978 行) │ +│ │ frmAdvanced (707 行) │ +├──────────────────────┼──────────────────────────────────────────┤ +│ Dialogs │ dlgServer (799 行) │ +│ │ dlgDumpLog (808 行) │ +│ │ dlgEnvInfo (808 行) │ +│ │ dlgPasswordCheck │ +│ │ dlgProgressCheck │ +├──────────────────────┼──────────────────────────────────────────┤ +│ Panels │ jpController (3,059 行) │ +│ │ jpController2 (3,612 行) │ +├──────────────────────┼──────────────────────────────────────────┤ +│ RAID Operations │ frmCreateArray (2,171 行) │ +│ │ frmCreateArray2 (2,278 行) │ +│ │ frmDeleteArray (834 行) │ +│ │ frmQuickSetup2 (1,421 行) │ +├──────────────────────┼──────────────────────────────────────────┤ +│ Advanced Features │ frmAdvSnapshot (1,430 行) │ +│ │ frmAdvMirror (1,552 行) │ +│ │ frmAdvSlicing (1,125 行) │ +│ │ frmAdvMigrate (956 行) │ +│ │ frmAdvExpansion (619 行) │ +│ │ frmAdvLunmap (907 行) │ +│ │ frmAdvLunMask (913 行) │ +├──────────────────────┼──────────────────────────────────────────┤ +│ System │ frmEmail (1,292 行) │ +│ │ frmAdvMaintain (1,011 行) │ +├──────────────────────┼──────────────────────────────────────────┤ +│ Data Layer │ PageDataDB (7,322 行) - 全域資料庫 │ +│ │ EventPartition (1,422 行) │ +│ │ Langs (2,468 行) - 多國語言 │ +├──────────────────────┼──────────────────────────────────────────┤ +│ Protocol │ SendCmd.java - TCP 通訊 │ +│ │ ControllerInfoPage │ +│ │ RAIDInfoPage (675 行) │ +│ │ DISKInfoPage │ +│ │ RAIDEnclosureInfoPage │ +│ │ SnapshotInfoPage │ +├──────────────────────┼──────────────────────────────────────────┤ +│ SNMP │ SNMPv1CommunicationInterface (1,229 行) │ +│ │ SNMPTrapSendTest (653 行) │ +└──────────────────────┴──────────────────────────────────────────┘ + │ + ▼ + ┌───────────────────────────────┐ + │ TCP Port 8922 (In-Band) │ + │ TCP Port 8722 (Finder) │ + └───────────────────────────────┘ + │ + ▼ + ┌───────────────────────────────┐ + │ GS (GUI Server) - C │ + │ DtrGuiSrv │ + └───────────────────────────────┘ +``` + +## 2. 模組分類與重構建議 + +### 2.1 核心資料層 (Core Data Layer) - 高優先級 + +| 模組 | 行數 | 功能 | Rust 重構建議 | +|------|------|------|---------------| +| **PageDataDB** | 7,322 | 全域資料庫、快取、SNMP | 使用 `serde` + `rusqlite`，建立 `State` 管理 | +| **EventPartition** | 1,422 | 事件日誌讀寫 | 直接移植，使用 `tokio` 異步 I/O | +| **Langs** | 2,468 | 多國語言 | 改用 JSON/YAML 語言檔 + `fluent-rs` | + +**Rust 目標結構:** +```rust +// src/data/mod.rs +pub struct AppState { + pub controllers: HashMap, + pub raids: HashMap, + pub disks: HashMap, + pub events: Vec, + pub config: Config, +} + +// src/i18n/mod.rs +pub struct I18n { + current_locale: String, + translations: HashMap>, +} +``` + +### 2.2 通訊層 (Protocol Layer) - 高優先級 + +| 模組 | 功能 | Rust 重構建議 | +|------|------|---------------| +| **SendCmd** | TCP 通訊、指令發送 | 使用 `tokio::net::TcpStream` + 自訂通訊協定 | +| **InBandAPI (22 個類別)** | 頁面資料解析 | 移植為 Rust struct derive `Serialize` | + +**Rust 目標結構:** +```rust +// src/protocol/mod.rs +pub struct InBandProtocol { + socket: TcpStream, +} + +impl InBandProtocol { + pub async fn connect(&mut self, addr: &str) -> Result<()>; + pub async fn send_cmd(&mut self, opcode: OpCode, data: &[u8]) -> Result>; +} + +// src/protocol/pages.rs +#[derive(Serialize, Deserialize)] +pub struct ControllerInfoPage { + pub serial_number: [u8; 16], + pub model_name: [u8; 32], + pub firmware_version: [u8; 8], + pub status: u8, + // ... +} +``` + +### 2.3 主視窗 (Main Window) - 中優先級 + +| 模組 | 行數 | 功能 | +|------|------|------| +| **frmMain** | 7,397 | 主視窗、選單、標題列 | +| **frmSettings** | 2,978 | 系統設定 | + +**重構建議:** 使用 **Slint** (現有專案已採用) + +```rust +// ui/main_window.slint (已存在) +export component AppWindow inherits Window { + // 現有的 Slint 定義 +} +``` + +### 2.4 RAID 作業模組 - 中優先級 + +| 模組 | 行數 | 功能 | +|------|------|------| +| frmCreateArray | 2,171 | 建立 RAID | +| frmCreateArray2 | 2,278 | 建立 RAID (進階) | +| frmDeleteArray | 834 | 刪除 RAID | +| frmQuickSetup2 | 1,421 | 快速設定 | + +**Rust 重構建議:** +```rust +// src/handlers/raid_ops.rs +pub async fn create_raid(level: RaidLevel, disks: Vec) -> Result<()>; +pub async fn delete_raid(raid_id: u8) -> Result<()>; +pub async fn rebuild_raid(raid_id: u8) -> Result<()>; +``` + +### 2.5 進階功能模組 - 低優先級 + +| 模組 | 行數 | 功能 | +|------|------|------| +| frmAdvSnapshot | 1,430 | Snapshot 管理 | +| frmAdvMirror | 1,552 | Mirror 鏡像 | +| frmAdvSlicing | 1,125 | 切片 | +| frmAdvMigrate | 956 | 遷移 | +| frmAdvExpansion | 619 | 擴展 | +| frmAdvLunmap | 907 | LUN 對應 | +| frmAdvLunMask | 913 | LUN 遮罩 | + +**重構建議:** 這些功能較少使用，可放在第二階段實作。 + +### 2.6 對話框 (Dialogs) - 低優先級 + +| 模組 | 行數 | 功能 | +|------|------|------| +| dlgServer | 799 | 伺服器連線 | +| dlgEnvInfo | 808 | 環境資訊 | +| dlgDumpLog | 808 | 日誌傾印 | +| dlgPasswordCheck | - | 密碼驗證 | +| dlgProgressCheck | - | 進度顯示 | + +**重構建議:** 改為 Slint 元件或使用 `rfd` 對話框庫。 + +### 2.7 系統模組 - 中優先級 + +| 模組 | 行數 | 功能 | +|------|------|------| +| frmEmail | 1,292 | 郵件通知 | +| frmAdvMaintain | 1,011 | 維護功能 | + +**Rust 重構建議:** +```rust +// src/email/mod.rs +pub async fn send_email(config: &EmailConfig, subject: &str, body: &str) -> Result<()>; +``` + +使用 `lettre` crate 實現 SMTP。 + +### 2.8 SNMP 模組 - 低優先級 + +| 模組 | 行數 | 功能 | +|------|------|------| +| SNMPv1CommunicationInterface | 1,229 | SNMP v1/v2c 通訊 | +| SNMPTrapSendTest | 653 | Trap 發送測試 | + +**Rust 重構建議:** 使用 `snmp` crate 或自訂實作 (取決於需求)。 + +## 3. 重構優先順序 + +``` +Phase 1: 基礎設施 (最優先) +├── 通訊層 (SendCmd → InBandProtocol) +├── 資料層 (PageDataDB → AppState) +└── UI 框架 (Slint 整合) + +Phase 2: 核心功能 +├── 主視窗 (frmMain → Slint) +├── RAID 操作 (Create/Delete/Query) +└── 事件處理 (EventPartition) + +Phase 3: 進階功能 +├── Snapshot / Mirror / Migration +├── LUN Map/Mask +└── Email 通知 + +Phase 4: 優化 +├── SNMP Trap +├── 效能調優 +└── 單元測試 +``` + +## 4. Rust 專案結構建議 + +``` +raidguard_x_gui/ +├── Cargo.toml +├── build.rs +├── src/ +│ ├── main.rs # 入口點 +│ ├── lib.rs # 庫入口 +│ │ +│ ├── protocol/ # 通訊協定 +│ │ ├── mod.rs +│ │ ├── client.rs # TCP 客戶端 +│ │ ├── messages.rs # 訊息定義 +│ │ └── pages.rs # 頁面資料結構 +│ │ +│ ├── data/ # 資料層 +│ │ ├── mod.rs +│ │ ├── state.rs # 全域狀態 +│ │ ├── cache.rs # 快取 +│ │ └── db.rs # SQLite 儲存 +│ │ +│ ├── handlers/ # 業務邏輯 +│ │ ├── mod.rs +│ │ ├── raid.rs # RAID 操作 +│ │ ├── disk.rs # 磁碟操作 +│ │ ├── controller.rs # 控制器操作 +│ │ └── event.rs # 事件處理 +│ │ +│ ├── email/ # 郵件通知 +│ │ └── mod.rs +│ │ +│ ├── snmp/ # SNMP (可選) +│ │ └── mod.rs +│ │ +│ └── ui/ # UI 整合 +│ └── mod.rs +│ +└── ui/ # Slint UI 檔案 + ├── main_window.slint + ├── components/ + └── styles/ +``` + +## 5. 依賴套件建議 + +| 功能 | Rust Crate | 備註 | +|------|------------|------| +| UI Framework | `slint` | 現已採用 | +| 非同步執行 | `tokio` | 現已採用 | +| 序列/反序列化 | `serde`, `serde_json` | 現已採用 | +| TCP 通訊 | `tokio::net` | 標準庫 | +| 資料庫 | `rusqlite` | SQLite | +| 日期時間 | `chrono` | 現已採用 | +| 日誌 | `tracing` | 現已採用 | +| SMTP | `lettre` | 郵件發送 | +| 指令列解析 | `clap` | 選項解析 | +| 錯誤處理 | `anyhow`, `thiserror` | 現已採用 | + +## 6. 現有 Rust 程式碼整合 + +現有 Rust 專案 (`raidguard_x_gui_server/`) 可作為基礎： + +```rust +// 現有結構 +raidguard_x_gui_server/ +├── src/ +│ ├── main.rs ✅ 入口點 +│ ├── server.rs ✅ TCP 伺服器 +│ ├── protocol/messages.rs ✅ 訊息定義 +│ ├── mock/data.rs ✅ 模擬資料 +│ └── handlers/ ✅ 業務處理 +└── Cargo.toml +``` + +**整合策略:** +1. 將 `raidguard_x_gui_server` 改為 `raidguard_x_gui` (合併 client + server) +2. 新增 Slint UI 整合 (`ui/` 目錄 → Slint 編譯) +3. 新增 `protocol/client.rs` 實現 TCP 客戶端 +4. 新增 `data/state.rs` 實現全域狀態 + +## 7. 風險與挑戰 + +| 風險 | 緩解措施 | +|------|----------| +| Swing → Slint 遷移複雜度 | 分階段進行，先實現核心 UI | +| 執行緒模型差異 | 使用 `tokio` 模擬 Swing EDT 概念 | +| 效能考量 | Rust效能通常優於 Java，但仍需優化 | +| 測試覆蓋率 | 建立完整單元測試與整合測試 | +| Java/Swing 依賴 | 保留 Java 版本，逐步替換 | + +## 8. 結論 + +### 重構可行性: ✅ 高 + +- **總行數**: 70,521 行 Java → 預估 30,000 行 Rust +- **預期效能提升**: 2-5x +- **維護性提升**: 顯著改善 (型別安全、記憶體安全) + +### 建議策略 + +1. **先完成 Phase 1-2** (通訊 + 資料 + 核心 UI) +2. **保留 Java 版本** 同步運行，逐步替換 +3. **使用 Mock Driver** 進行離線測試 +4. **建立 CI/CD** 確保重構正確性 + +--- + +*Generated: 2026-03-29* +*Based on: RAIDGuard X Java GUI (v3.8.0)*