Initial commit: RAIDGuard X Rust/Slint GUI client and server

This commit is contained in:
accusys
2026-03-27 15:57:32 +08:00
commit 06e1cffae7
7 changed files with 7237 additions and 0 deletions
+234
View File
@@ -0,0 +1,234 @@
# AGENTS.md - RAIDGuard X Development Guide
## Project Overview
RAIDGuard X is a Java 17 Swing desktop application for managing and monitoring RAID storage systems (by Accusys).
**Location:** `RAIDGuardX/`
**Main Entry Point:** `raidguard_x.AppMain`
**Java Version:** 17
---
## Build Commands
```bash
# Navigate to project directory
cd RAIDGuardX
# Compile the project
mvn compile
# Run the application
mvn compile exec:java -Dexec.mainClass="raidguard_x.AppMain"
# Run with log output
mvn compile exec:java -Dexec.mainClass="raidguard_x.AppMain" 2>&1 | tee RAIDGuardX_$(date +%Y%m%d_%H%M).log
# Quick run (if already compiled)
mvn exec:java -Dexec.mainClass="raidguard_x.AppMain"
# Full clean build with packaging (creates macOS app)
mvn clean package
# Create JAR file only
mvn jar:jar
# Copy dependencies to target/dependency-libs
mvn dependency:copy-dependencies
# Run JAR directly
java -cp "target/raidguard_x-1.0.562.jar:target/dependency-libs/*" raidguard_x.AppMain
```
### Running Single Tests
This project uses **JUnit 3.8.1** for testing. Test files are in `src/test/java/`.
```bash
# Run all tests
mvn test
# Run a specific test class
mvn test -Dtest=TestClassName
# Run a specific test method
mvn test -Dtest=TestClassName#testMethodName
```
---
## Project Structure
```
src/main/java/raidguard_x/
├── AppMain.java # Main entry point (applet/application)
├── frmMain.java # Main application window
├── InBandAPI/ # RAID controller communication (port 8922)
│ ├── SendCmd.java # Command sending and protocol handling
│ ├── BasePage.java # Base class for info pages
│ ├── ControllerInfoPage.java
│ ├── RAIDInfoPage.java
│ └── ...
├── SNMP/ # SNMP trap implementation
│ ├── SNMPSender.java
│ ├── SNMPTrapSenderInterface.java
│ ├── SNMPv1TrapPDU.java
│ └── ...
├── Exception/ # Custom exceptions
│ ├── AMEException.java
│ └── ErrMsg.java
├── frm*.java # Form/dialog classes (JFrame)
├── dlg*.java # Dialog classes
├── jp*.java # JPanel classes
├── PageDataDB.java # Global data store
├── Langs.java # Localization support
└── Debug.java # Logging utility
```
---
## Code Style Guidelines
### General Conventions
1. **Indentation:** 4 spaces (no tabs)
2. **Braces:** Same-line style (K&R variant)
```java
public class Example {
public void method() {
if (condition) {
// code
}
}
}
```
3. **Line length:** No strict limit, but avoid excessive wrapping
### Naming Conventions
| Element | Convention | Example |
|---------|------------|---------|
| Classes | PascalCase | `AppMain`, `SendCmd` |
| Methods | camelCase | `sendPassword()`, `convetToAMEReplyFrame()` |
| Variables | camelCase | `sIP`, `replyBuf`, `pageCode` |
| Constants | UPPER_SNAKE | (rarely used) |
| Packages | lowercase | `raidguard_x`, `exception` |
**Prefix conventions observed in codebase:**
- `s` prefix for Strings: `sIP`, `sSN`, `sVMVer`
- `i` prefix for integers: `iCmdLen`, `iR`
- `b`/`byte` for byte arrays: `byte[] replyBuf`
### Import Organization
```java
package raidguard_x;
import java.io.*;
import java.net.*;
import raidguard_x.*;
import raidguard_x.Exception.*;
```
- Standard library imports first
- Third-party imports second
- Project imports last
- Use wildcard imports for related packages (`java.io.*`, `java.net.*`)
### Error Handling
- Use custom `AMEException` for protocol errors
- Use `try-catch` blocks for I/O and network operations
- Catch specific exceptions before generic ones
- Always close resources in `finally` blocks
```java
try {
// network I/O code
} catch (UnknownHostException ex) {
System.err.println("Unknown host: " + ex.getMessage());
} catch (IOException ex) {
System.err.println("IO error: " + ex.getMessage());
} catch (AMEException ex) {
throw ex;
} finally {
try {
if (socket != null) socket.close();
} catch (Exception e) { /* ignore */ }
}
```
### Logging/Debugging
Use the `Debug` class for structured logging:
```java
Debug.Log(">>> [Protocol] GET_PAGE: 0x%02X (%s)", pageCode, pageName);
Debug.HexDump("RAW RECEIVED DATA", actualRead);
```
Avoid `System.out.println` for debug output (existing code may still use it).
### Swing/GUI Conventions
1. **EDT Compliance:** Use `SwingUtilities.invokeLater()` for UI updates
```java
SwingUtilities.invokeLater(new Runnable() {
public void run() {
// UI code
}
});
```
2. **Platform Detection:** Use `AppMain.MAC_OS_X` and `AppMain.WIN` flags
3. **Font Settings:** Apply via `UIManager.put()` in `initGlobalFontSetting()`
### Comments
- Use Javadoc for public classes and methods
- Inline comments for non-obvious logic
- Chinese comments present in original code for debugging sections
### Type Annotations
- Use raw types sparingly (legacy codebase)
- Avoid generic warnings when possible
- Prefer `List<E>`, `Map<K,V>` over raw `ArrayList`, `HashMap`
---
## Dependencies
| Library | Version | Purpose |
|---------|---------|---------|
| JUnit | 3.8.1 | Testing |
| javax.mail | 1.6.2 | Email functionality |
| org.json | 20231013 | JSON parsing |
---
## Key Protocols
### In-Band API (Port 8922)
Protocol for communicating with RAID controllers:
- OpCode 0x01: GET_PAGE (read info pages)
- OpCode 0x1D: SEND_PASSWORD
- OpCode 0xBC: Unlock
- OpCode 0x1B: Erase RAID
- OpCode 0xCC: Create RAID
- OpCode 0xCE: Set Global Config
- OpCode 0x26: Commit Configuration
### SNMP
Custom SNMP implementation supporting v1 and v2 traps for event notification.
---
## Development Notes
1. **Java 17 Required:** Set `<maven.compiler.release>17</maven.compiler.release>` in pom.xml
2. **macOS Considerations:** Set `apple.laf.useScreenMenuBar=true` for menu bar
3. **Socket Timeout:** Default 3 seconds (prevent hangs on network issues)
4. **DEXT Service:** C++ service must be running on port 8922 for full functionality
Generated
+6503
View File
File diff suppressed because it is too large Load Diff
+6
View File
@@ -0,0 +1,6 @@
[workspace]
members = [
"raidguard_x_gui_server",
"raidguard_x_gui_client",
]
resolver = "2"
+286
View File
@@ -0,0 +1,286 @@
# 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*
+139
View File
@@ -0,0 +1,139 @@
# RAIDGuard X - GUI Client/Server Architecture
A modern Rust-based GUI application for managing RAID storage systems.
## Architecture
```
┌─────────────────────────────────────────────────────────────────────┐
│ raidguard_x_gui_client (Slint GUI) │
│ - Cross-platform UI (macOS, Windows, Linux) │
│ - TCP connection to server │
│ - Real-time data display │
└─────────────────────────┬───────────────────────────────────────────┘
│ TCP JSON Protocol (:8923)
┌─────────────────────────────────────────────────────────────────────┐
│ raidguard_x_gui_server (Mock/Real Backend) │
│ - Provides RAID controller data │
│ - Currently serves mock data │
│ - Future: In-Band API to real RAID systems │
└─────────────────────────────────────────────────────────────────────┘
```
## Project Structure
```
raidguard_x_gui_server/ # Data server
├── Cargo.toml
├── src/
│ ├── main.rs # Entry point
│ ├── lib.rs
│ ├── server.rs # TCP server
│ ├── protocol/ # JSON message protocol
│ ├── handlers/ # Request handlers
│ └── mock/ # Mock data provider
raidguard_x_gui_client/ # GUI client
├── Cargo.toml
├── build.rs # Slint build script
├── src/
│ ├── main.rs # Entry point + Slint integration
│ ├── lib.rs
│ ├── app.rs # App state management
│ ├── models/ # Data models
│ └── protocol/ # Client protocol
└── ui/
└── main_window.slint # Slint UI definition
```
## Build Requirements
- Rust 1.70+
- For GUI client: `xcode-select` (macOS) or equivalent
## Build Instructions
### Server
```bash
cd raidguard_x_gui_server
cargo build --release
```
Run:
```bash
# Default port 8923
cargo run --release
# Custom port
SERVER_ADDR=127.0.0.1:8923 cargo run --release
```
### Client
```bash
cd raidguard_x_gui_client
cargo build --release
```
Run:
```bash
cargo run --release
```
## Protocol
### Request Format
```json
{
"id": "uuid-v4",
"type": "request",
"action": "get_controllers",
"params": {}
}
```
### Response Format
```json
{
"id": "uuid-v4",
"type": "response",
"status": "success",
"data": { ... },
"error": null
}
```
### Available Actions
| Action | Description |
|--------|-------------|
| `get_controllers` | Get all controllers |
| `get_raids` | Get RAID arrays |
| `get_disks` | Get physical disks |
| `get_events` | Get event log |
| `ping` | Health check |
## Development
### Testing the Server
```bash
# Terminal 1: Start server
cd raidguard_x_gui_server
cargo run --release
# Terminal 2: Connect with netcat
nc localhost 8923
# Send request:
{"id":"test","type":"request","action":"get_controllers","params":{}}
# Response:
{"id":"test","type":"response","status":"success","data":{"controllers":[...]}}
```
## License
Proprietary - Accusys Inc.
Executable
+43
View File
@@ -0,0 +1,43 @@
#!/bin/bash
# Build script for RAIDGuard X
set -e
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
echo "=== RAIDGuard X Build Script ==="
echo ""
# Check Rust
if ! command -v rustc &> /dev/null; then
echo "ERROR: Rust is not installed"
echo "Install from: https://rustup.rs"
exit 1
fi
echo "Rust version: $(rustc --version)"
echo ""
# Build server
echo "=== Building Server ==="
cd "$SCRIPT_DIR/raidguard_x_gui_server"
cargo build --release
echo "Server built successfully!"
# Build client
echo ""
echo "=== Building Client ==="
cd "$SCRIPT_DIR/raidguard_x_gui_client"
cargo build --release
echo "Client built successfully!"
echo ""
echo "=== Build Complete ==="
echo ""
echo "Executables:"
echo " Server: raidguard_x_gui_server/target/release/raidguard-server"
echo " Client: raidguard_x_gui_client/target/release/raidguard-client"
echo ""
echo "Run:"
echo " Terminal 1: ./raidguard_x_gui_server/target/release/raidguard-server"
echo " Terminal 2: ./raidguard_x_gui_client/target/release/raidguard-client"
+26
View File
@@ -0,0 +1,26 @@
//! Simple test client
use std::io::{Read, Write};
use std::net::TcpStream;
fn main() {
println!("Connecting to 127.0.0.1:8923...");
match TcpStream::connect("127.0.0.1:8923") {
Ok(mut stream) => {
println!("Connected! Sending ping...");
let msg = r#"{"id":"test","type":"request","action":"ping","params":{}}"#;
stream.write_all(msg.as_bytes()).unwrap();
stream.write_all(b"\n").unwrap();
let mut buf = [0u8; 1024];
match stream.read(&mut buf) {
Ok(n) => {
let response = String::from_utf8_lossy(&buf[..n]);
println!("Response: {}", response);
}
Err(e) => println!("Read error: {}", e),
}
}
Err(e) => println!("Connection failed: {}", e),
}
}