rust_raidguardx/GC_3.8.0_ANALYSIS.md

# GC_3.8.0 專案分析文件

## 1. 專案概述

GC_3.8.0 是 Accusys 的 RAID 儲存管理系統解決方案，包含一個完整的桌面應用程式用於管理和監控 RAID 儲存系統。該專案採用混合技術架構，結合了傳統的 Java Swing 應用程式和現代的 Rust GUI 客戶端。

**專案位置**: `/Users/accusys/GC_3.8.0`

---

## 2. 專案架構

```
GC_3.8.0/
├── RAIDGuardX/                 # Java 17 Swing 桌面應用程式
├── raidguard_x_gui_client/     # Rust Slint GUI 客戶端 (新開發)
├── raidguard_x_gui_server/     # Rust 後端伺服器
├── AGENTS.md                   # Agent 開發指南
├── README_GUI.md              # GUI 架構說明
├── Cargo.toml                 # Rust Workspace 配置
├── build.sh                   # 編譯腳本
└── test_client.rs             # 測試客戶端
```

---

## 3. 主要元件分析

### 3.1 RAIDGuardX (Java 17)

**技術棧**:
- Java 17
- Maven build system
- Swing UI framework

**主要功能**:
- RAID 控制器管理
- RAID 陣列配置
- 磁碟監控
- 事件日誌
- In-Band API 通訊 (port 8922)
- SNMP trap 支援

**專案結構**:
```
src/main/java/raidguard_x/
├── AppMain.java              # 主入口點
├── frmMain.java              # 主應用視窗
├── InBandAPI/                # RAID 控制器通訊
│   ├── SendCmd.java          # 命令發送與協議處理
│   ├── BasePage.java
│   └── ...
├── SNMP/                     # SNMP trap 實現
├── Exception/                # 自定義異常
├── frm*.java                 # 表單類別
├── dlg*.java                 # 對話框類別
└── jp*.java                  # JPanel 類別
```

**關鍵協議** (In-Band API - Port 8922):
| OpCode | 功能 |
|--------|------|
| 0x01 | GET_PAGE |
| 0x1D | SEND_PASSWORD |
| 0xBC | Unlock |
| 0x1B | Erase RAID |
| 0xCC | Create RAID |
| 0xCE | Set Global Config |
| 0x26 | Commit Configuration |

### 3.2 raidguard_x_gui_client (Rust)

**技術棧**:
- Rust
- Slint UI framework
- TCP JSON 協議

**功能**:
- 跨平台 GUI (macOS, Windows, Linux)
- 連接後端伺服器
- 即時資料顯示

**專案結構**:
```
raidguard_x_gui_client/
├── Cargo.toml
├── build.rs                 # Slint build script
├── src/
│   ├── main.rs              # 入口點
│   ├── lib.rs
│   ├── app.rs               # 狀態管理
│   ├── models/              # 資料模型
│   └── protocol/            # 用戶端協議
└── ui/
    └── main_window.slint   # Slint UI 定義
```

### 3.3 raidguard_x_gui_server (Rust)

**技術棧**:
- Rust
- TCP 伺服器
- JSON 協議
- Mock 資料提供者

**功能**:
- 提供 RAID 控制器資料
- 目前提供 Mock 資料
- 未來計劃: 連接真實 RAID 系統

**專案結構**:
```
raidguard_x_gui_server/
├── Cargo.toml
└── src/
    ├── main.rs
    ├── lib.rs
    ├── server.rs            # TCP 伺服器
    ├── protocol/            # JSON 消息協議
    ├── handlers/            # 請求處理
    └── mock/                # Mock 資料
```

---

## 4. 通訊協議

### 請求格式
```json
{
  "id": "uuid-v4",
  "type": "request",
  "action": "get_controllers",
  "params": {}
}
```

### 回應格式
```json
{
  "id": "uuid-v4",
  "type": "response",
  "status": "success",
  "data": { ... },
  "error": null
}
```

### 可用操作

| Action | Description |
|--------|-------------|
| `get_controllers` | 取得所有控制器 |
| `get_raids` | 取得 RAID 陣列 |
| `get_disks` | 取得實體磁碟 |
| `get_events` | 取得事件日誌 |
| `ping` | 健康檢查 |

---

## 5. 編譯與執行

### 5.1 RAIDGuardX (Java)

```bash
cd RAIDGuardX
mvn compile                    # 編譯
mvn exec:java -Dexec.mainClass="raidguard_x.AppMain"  # 執行
mvn clean package              # 打包 macOS app
```

### 5.2 Rust GUI (Client + Server)

```bash
# 編譯整個 workspace
cargo build --release

# 分別編譯
cd raidguard_x_gui_server
cargo build --release

cd raidguard_x_gui_client
cargo build --release

# 執行伺服器 (預設 port 8923)
cd raidguard_x_gui_server
cargo run --release

# 自訂 port
SERVER_ADDR=127.0.0.1:8923 cargo run --release

# 執行客戶端
cd raidguard_x_gui_client
cargo run --release
```

---

## 6. 依賴管理

### Java 依賴
- JUnit 3.8.1 (測試)
- javax.mail 1.6.2 (郵件功能)
- org.json (JSON 解析)

### Rust 依賴
- slint (UI framework)
- tokio (非同步 runtime)
- serde (序列化)
- 詳細請參考各元件的 Cargo.toml

---

## 7. 測試

### Rust 測試
```bash
# 測試伺服器
nc localhost 8923
{"id":"test","type":"request","action":"get_controllers","params":{}}

# 預期回應
{"id":"test","type":"response","status":"success","data":{"controllers":[...]}}
```

### Java 測試
```bash
cd RAIDGuardX
mvn test                      # 執行所有測試
mvn test -Dtest=TestClassName # 執行特定測試
```

---

## 8. 開發指南

### 代碼風格

**Java (RAIDGuardX)**:
- 縮排: 4 spaces
- 命名: PascalCase (類別), camelCase (方法/變數)
- 前綴: `s` (String), `i` (int), `b/byte` (byte arrays)

**Rust**:
- 遵循 standard Rust idioms
- 使用 `rustfmt` 格式化
- 使用 `clippy` 進行 lint

### 調試

使用 `Debug` 類別進行日誌記錄:
```java
Debug.Log(">>> [Protocol] GET_PAGE: 0x%02X (%s)", pageCode, pageName);
Debug.HexDump("RAW RECEIVED DATA", actualRead);
```

---

## 9. 版本資訊

- **Version**: 3.8.0
- **License**: Proprietary - Accusys Inc.
- **Platform**: macOS, Windows, Linux (Rust), Java 17

---

## 10. 發展歷程

| 版本 | 日期 | 描述 |
|------|------|------|
| 3.8.0 | 2026-03 | 新增 Rust GUI 客戶端/伺服器 |
| 3.7.x | 早期 | Java Swing 版本 |

---

## 11. 建議與展望

1. **統一協議**: 確保 Java 和 Rust 客戶端使用一致的 API 協議
2. **Mock 數據**: 目前 GUI 伺服器使用 Mock 數據，建議連接真實 In-Band API
3. **Web 介面**: 可考慮開發 Web 版本的 RAID 管理介面
4. **容器化**: 考慮使用 Docker 部署 Rust 伺服器元件

---

*文件建立時間: 2026-03-26*
*Author: Accusys Development Team*