wails-epic/README.md

# 装备数据导出工具

一个基于Go + Wails + React的桌面应用程序，用于抓取游戏TCP包并解析装备数据。

## 功能特性

- 🎯 **TCP包抓取** - 实时抓取游戏客户端的TCP通信数据
- 🔍 **数据解析** - 自动解析十六进制数据为可读的装备信息
- 📊 **数据可视化** - 现代化的React界面展示装备数据
- 💾 **数据持久化** - 基于SQLite的本地数据存储，支持装备数据的增删改查
- 📤 **数据导出** - 支持导出为JSON格式
- 🔍 **数据搜索** - 支持装备数据的模糊搜索和筛选
- 📈 **数据统计** - 提供装备数据的统计分析功能
- ⚙️ **设置管理** - 应用设置的本地持久化存储
- 🚀 **高性能** - 基于Go语言的高性能网络处理

## 技术栈

### 后端
- **Go 1.21+** - 主要开发语言
- **Wails v2** - 桌面应用框架
- **gopacket** - 网络包抓取
- **zap** - 结构化日志
- **SQLite** - 本地数据存储

### 前端
- **React 18** - 用户界面框架
- **TypeScript** - 类型安全
- **Vite** - 构建工具
- **Ant Design** - UI组件库

## 快速开始

### 环境要求

- Go 1.21+
- Node.js 18+
- npm 或 yarn

### 安装步骤

1. **克隆项目**
```bash
git clone <repository-url>
cd equipment-analyzer
```

2. **安装后端依赖**
```bash
go install github.com/wailsapp/wails/v2/cmd/wails@latest
go mod tidy
```

3. **安装前端依赖**
```bash
cd frontend
npm install
cd ..
```

4. **开发模式运行**
```bash
make dev
```

5. **构建发布版本**
```bash
make release
```

## 使用说明

### 1. 启动应用
运行应用后，会看到主界面。

### 2. 选择网络接口
- 点击"刷新接口"获取可用的网络接口
- 选择包含游戏流量的网络接口（通常是192.168开头的IP）

### 3. 开始抓包
- 点击"开始抓包"按钮
- 启动游戏并登录
- 在游戏中查看装备数据

### 4. 停止抓包
- 点击"停止抓包"按钮
- 等待数据处理完成

### 5. 导出数据
- 点击"导出数据"按钮
- 选择保存位置

## 项目结构

```
equipment-analyzer/
├── cmd/                    # 应用程序入口
├── internal/               # 内部包
│   ├── capture/           # 抓包模块
│   ├── parser/            # 数据解析
│   ├── model/             # 数据模型
│   ├── service/           # 业务逻辑
│   ├── config/            # 配置管理
│   └── utils/             # 工具函数
├── frontend/              # React前端
│   ├── src/               # 源代码
│   ├── dist/              # 构建输出
│   └── package.json       # 前端依赖
├── build/                 # 构建产物
├── go.mod                 # Go模块
├── wails.json             # Wails配置
└── Makefile               # 构建脚本
```

## 开发指南

### 常见问题解决

#### 1. React严格模式导致的重复调用
在开发模式下，React严格模式会导致组件渲染两次，这可能导致：
- useEffect被重复执行
- 异步操作被重复调用
- 用户提示消息重复显示

**解决方案：**
- **全局消息去重配置**：在`frontend/src/utils/messageConfig.ts`中配置Antd message的全局设置
- **防重复机制**：使用缓存机制防止2秒内相同消息重复显示
- **最大显示数量限制**：设置`maxCount: 1`确保同时只显示一个消息

**全局配置：**
```typescript
// frontend/src/utils/messageConfig.ts
import { message } from 'antd';

// 配置全局消息设置，防止重复显示
message.config({
  maxCount: 1, // 最多同时显示1个消息
  duration: 3, // 消息显示3秒
  top: 24, // 距离顶部24px
});

// 防重复消息函数
const messageCache = new Map<string, number>();
const DEBOUNCE_TIME = 2000; // 2秒内相同消息不重复显示

export const showMessage = (type: 'success' | 'error' | 'warning' | 'info', content: string) => {
  const messageId = `${type}:${content}`;
  const now = Date.now();
  
  // 检查是否在防抖时间内
  const lastTime = messageCache.get(messageId);
  if (lastTime && now - lastTime < DEBOUNCE_TIME) {
    return; // 跳过重复消息
  }
  
  // 更新缓存并显示消息
  messageCache.set(messageId, now);
  message[type](content);
};
```

**使用方法：**
- 在`main.tsx`中导入配置：`import './utils/messageConfig'`
- 在组件中正常使用`message.success()`、`message.error()`等
- 全局配置会自动防止重复消息显示

### 添加新功能

1. **后端功能**
    - 在`internal/`目录下创建相应的模块
    - 在`service/`中实现业务逻辑
    - 在`main.go`中绑定到前端

2. **前端功能**
    - 在`frontend/src/`下创建React组件
    - 使用TypeScript确保类型安全
    - 遵循Ant Design设计规范

### 数据库操作

1. **添加新的数据表**
    - 在`internal/model/database.go`的`initTables()`方法中添加表结构
    - 在`Database`结构体中添加相应的CRUD方法
    - 在`DatabaseService`中添加业务逻辑方法
    - 在`App`中添加API接口方法

2. **数据迁移**
    - 数据库结构变更时，在`initTables()`方法中处理版本升级
    - 使用事务确保数据一致性

3. **性能优化**
    - 为常用查询字段添加索引
    - 使用批量操作减少数据库交互
    - 合理使用连接池和事务

### 测试

```bash
# 运行单元测试
make test

# 运行集成测试
make test-integration

# 代码检查
make lint
```

### 构建

```bash
# 开发构建
make build

# 发布构建
make release

# 清理构建文件
make clean
```

## 数据存储

### 数据库存储
应用使用SQLite数据库进行本地数据持久化，数据库文件位置：`~/.equipment-analyzer/equipment_analyzer.db`

#### 数据库表结构
- **equipment** - 装备基本信息表
- **equipment_operations** - 装备操作属性表
- **capture_sessions** - 抓包会话记录表
- **raw_packet_data** - 原始数据包表
- **app_settings** - 应用设置表

#### 数据库功能
- ✅ 装备数据的增删改查
- ✅ 批量数据导入导出
- ✅ 装备数据搜索和筛选
- ✅ 数据统计分析
- ✅ 应用设置持久化
- ✅ 抓包会话历史记录

### 配置文件
应用会在用户目录下创建配置文件：`~/.equipment-analyzer/config.json`

```json
{
  "app": {
    "name": "equipment-analyzer",
    "version": "1.0.0",
    "debug": false
  },
  "capture": {
    "default_filter": "tcp and ( port 5222 or port 3333 )",
    "default_timeout": 3000,
    "buffer_size": 1600,
    "max_packet_size": 65535
  },
  "parser": {
    "max_data_size": 1048576,
    "enable_validation": true
  },
  "log": {
    "level": "info",
    "file": "equipment-analyzer.log",
    "max_size": 100,
    "max_backups": 3,
    "max_age": 28,
    "compress": true
  }
}
```

## 故障排除

### 常见问题

1. **无法获取网络接口**
    - 确保以管理员权限运行
    - 检查WinPcap/Npcap是否正确安装

2. **抓包失败**
    - 检查防火墙设置
    - 确认网络接口选择正确
    - 查看日志文件获取详细错误信息

3. **数据解析失败**
    - 确认游戏协议格式
    - 检查十六进制数据格式
    - 查看控制台错误信息

### 日志文件

应用日志保存在：`logs/equipment-analyzer.log`

## 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 联系方式

- 项目主页：[GitHub Repository]
- 问题反馈：[Issues]
- 邮箱：team@equipment-analyzer.com

---

**注意**: 本工具仅用于学习和研究目的，请遵守相关法律法规和游戏服务条款。