gavindiaz/PolyHermes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 重新整理 README 并创建开发文档

Browse Source 
- 重新组织 README 为三个部分：产品功能说明、如何部署、开发文档
- 创建 DEVELOPMENT.md 开发文档，包含完整的开发指南
- 优化文档结构和内容，提升可读性
This commit is contained in:
WrBug
2025-12-07 16:53:59 +08:00
parent b069e54b89
commit c114241ffb
2 changed files with 710 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+197 -130
View File
@@ -5,28 +5,82 @@
一个功能强大的 Polymarket 预测市场跟单交易系统，支持自动化跟单、多账户管理、实时订单推送和统计分析。
## ✨ 功能特性
---
### 核心功能
- 🔐 **多账户管理**：支持通过私钥导入多个钱包账户，统一管理
- 👥 **Leader 管理**：添加和管理被跟单者（Leader），支持分类筛选（sports/crypto）
- 📊 **跟单配置**：灵活的跟单模板配置，支持比例跟单和固定金额跟单
- 🔄 **自动跟单**：实时监控 Leader 交易，自动复制订单（支持买入和卖出）
- 📈 **订单跟踪**：完整的订单生命周期跟踪，包括买入、卖出和匹配记录
- 📊 **统计分析**：全局统计、Leader 统计、分类统计，支持时间范围筛选
- 💼 **仓位管理**：实时查看和管理持仓，支持仓位推送
- ⚙️ **系统管理**：代理配置、API 健康检查、实时状态监控
## 📋 目录
### 技术特性
- 🌐 **WebSocket 实时推送**：订单和仓位数据实时推送
- 🔒 **安全存储**：私钥和 API 凭证加密存储
- 📱 **响应式设计**：完美支持移动端和桌面端
- 🚀 **高性能**：异步处理、并发优化
- 🛡️ **风险控制**：每日亏损限制、订单数限制、价格容忍度等
- [第一部分：产品功能说明](#第一部分产品功能说明)
- [第二部分：如何部署](#第二部分如何部署)
- [第三部分：开发文档](#第三部分开发文档)
## 🏗️ 技术栈
---
### 后端
## 第一部分：产品功能说明
### ✨ 核心功能
#### 🔐 账户管理
- **多账户支持**：通过私钥导入多个钱包账户，统一管理
- **安全存储**：私钥和 API 凭证加密存储，确保数据安全
- **账户信息**：查看账户余额、持仓、交易记录等详细信息
- **账户编辑**：支持修改账户名称、设置默认账户等
#### 👥 Leader 管理
- **添加 Leader**：添加被跟单者（Leader）的钱包地址
- **分类筛选**：支持按分类筛选（sports/crypto）
- **Leader 信息**：查看 Leader 的交易历史、统计信息
- **备注管理**：为 Leader 添加备注，方便识别和管理
#### 📊 跟单模板
- **灵活配置**：创建跟单模板，配置跟单参数
- **跟单方式**：支持比例跟单和固定金额跟单
- **风险控制**：配置每日亏损限制、订单数限制、价格容忍度等
- **模板复用**：一个模板可以用于多个跟单关系
#### 🔄 跟单配置
- **关系管理**：将账户、模板和 Leader 关联，创建跟单关系
- **启用/禁用**：灵活控制跟单关系的启用状态
- **自动跟单**：实时监控 Leader 交易，自动复制订单（支持买入和卖出）
- **订单跟踪**：完整的订单生命周期跟踪，包括买入、卖出和匹配记录
#### 📈 订单管理
- **买入订单**：查看所有买入订单的详细信息
- **卖出订单**：查看所有卖出订单的详细信息
- **匹配订单**：查看已匹配的订单记录
- **订单筛选**：支持按账户、Leader、时间范围等条件筛选
#### 💼 仓位管理
- **实时持仓**：实时查看和管理所有账户的持仓
- **仓位推送**：通过 WebSocket 实时推送仓位变化
- **卖出仓位**：支持市价和限价卖出仓位
- **赎回仓位**：支持批量赎回已结算的仓位
#### 📊 统计分析
- **全局统计**：查看所有跟单关系的汇总统计
- **Leader 统计**：查看特定 Leader 的统计信息
- **分类统计**：按分类（sports/crypto）查看统计
- **跟单关系统计**：查看单个跟单关系的详细统计
- **时间筛选**：支持按时间范围筛选统计数据
#### ⚙️ 系统管理
- **代理配置**：通过 Web UI 配置 HTTP 代理，无需修改环境变量
- **API 健康检查**：实时监控 Polymarket API 的健康状态
- **用户管理**：管理系统用户，支持添加、编辑、删除用户
- **公告管理**：查看系统公告和更新信息
### 🚀 技术特性
- **WebSocket 实时推送**：订单和仓位数据实时推送，无需手动刷新
- **安全存储**：私钥和 API 凭证使用 AES 加密存储
- **响应式设计**：完美支持移动端和桌面端，提供一致的用户体验
- **高性能**：异步处理、并发优化，支持大量订单处理
- **风险控制**：每日亏损限制、订单数限制、价格容忍度等多重风险控制机制
- **多语言支持**：支持中文（简体/繁体）和英文
- **版本管理**：自动版本号显示和管理，支持 GitHub Releases 自动构建
### 🏗️ 技术栈
#### 后端
- **框架**: Spring Boot 3.2.0
- **语言**: Kotlin 1.9.20
- **数据库**: MySQL 8.2.0
@@ -35,7 +89,7 @@
- **HTTP 客户端**: Retrofit 2.9.0 + OkHttp 4.12.0
- **WebSocket**: Spring WebSocket
### 前端
#### 前端
- **框架**: React 18 + TypeScript
- **构建工具**: Vite
- **UI 库**: Ant Design 5.12.0
@@ -43,108 +97,100 @@
- **状态管理**: Zustand
- **路由**: React Router 6
- **以太坊库**: ethers.js 6.9.0
- **多语言**: react-i18next
## 📦 项目结构
---
```
polyhermes/
├── backend/ # 后端服务
│ ├── src/main/kotlin/ # Kotlin 源代码
│ │ ├── api/ # Polymarket API 接口定义
│ │ ├── controller/ # REST 控制器
│ │ ├── service/ # 业务逻辑服务
│ │ ├── entity/ # 数据库实体
│ │ ├── repository/ # 数据访问层
│ │ ├── dto/ # 数据传输对象
│ │ ├── websocket/ # WebSocket 处理
│ │ └── util/ # 工具类
│ └── src/main/resources/
│ ├── application.properties
│ └── db/migration/ # 数据库迁移脚本
├── frontend/ # 前端应用
│ ├── src/
│ │ ├── components/ # 公共组件
│ │ ├── pages/ # 页面组件
│ │ ├── services/ # API 服务
│ │ ├── types/ # TypeScript 类型
│ │ └── utils/ # 工具函数
│ └── package.json
├── docs/ # 文档
└── README.md
```
## 第二部分：如何部署
## 🚀 快速开始
### 🚀 快速部署
### 前置要求
#### 一体化部署（推荐）
- JDK 17+
- Node.js 18+
- MySQL 8.0+
- Gradle 7.5+（或使用 Gradle Wrapper）
将前后端一起部署到一个 Docker 容器中，使用 Nginx 提供前端静态文件并代理后端 API。
### 开发环境
**前置要求**：
- Docker 20.10+
- Docker Compose 2.0+
1. **克隆仓库**
**部署步骤**：
```bash
git clone https://github.com/WrBug/PolyHermes.git
cd PolyHermes
```
1. **使用部署脚本（推荐）**
2. **配置数据库**
创建 MySQL 数据库：
```sql
CREATE DATABASE polyhermes CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
3. **启动后端**
```bash
cd backend
./gradlew bootRun
```
后端服务将在 `http://localhost:8000` 启动（开发环境）。
4. **启动前端**
```bash
cd frontend
npm install
npm run dev
```
前端应用将在 `http://localhost:3000` 启动。
### 生产部署
详细的部署文档请参考：[部署文档](docs/DEPLOYMENT.md)
#### 快速部署
**一体化部署（推荐）** - 前后端一起部署到一个容器：
```bash
# 在项目根目录
./deploy.sh
```
**分别部署**:
脚本会自动：
- 检查 Docker 环境
- 创建 `.env` 配置文件（如果不存在）
- 构建 Docker 镜像（包含前后端）
- 启动服务（应用 + MySQL）
2. **手动部署**
```bash
# 创建 .env 文件
cat > .env <<EOF
DB_URL=jdbc:mysql://mysql:3306/polyhermes?useSSL=false&serverTimezone=UTC&characterEncoding=utf8&allowPublicKeyRetrieval=true
DB_USERNAME=root
DB_PASSWORD=your_password_here
SPRING_PROFILES_ACTIVE=prod
SERVER_PORT=80
POLYGON_RPC_URL=https://polygon-rpc.com
JWT_SECRET=your-jwt-secret-key-change-in-production
ADMIN_RESET_PASSWORD_KEY=your-admin-reset-key-change-in-production
EOF
# 构建并启动
docker-compose build
docker-compose up -d
# 查看日志
docker-compose logs -f
# 停止服务
docker-compose down
```
3. **使用 Docker Hub 镜像（生产环境推荐）**
```bash
# 使用部署脚本
./deploy.sh --use-docker-hub
# 或修改 docker-compose.yml，取消注释：
# image: wrbug/polyhermes:latest
```
**访问应用**：
- 前端和后端统一访问：`http://localhost:80`
- Nginx 自动处理：
- `/api/*` → 后端 API（`localhost:8000`）
- `/ws` → 后端 WebSocket（`localhost:8000`）
- 其他路径 → 前端静态文件
### 📦 分别部署
#### 后端部署
**Java 直接部署**：
后端（Java 方式）:
```bash
cd backend
./deploy.sh java
```
后端（Docker 方式）:
**Docker 部署**：
```bash
cd backend
./deploy.sh docker
```
前端:
#### 前端部署
```bash
cd frontend
# 使用默认后端地址（相对路径）
@@ -154,33 +200,9 @@ cd frontend
./build.sh --api-url http://your-backend-server.com:8000
```
## 📖 使用指南
### ⚙️ 环境配置
### 账户管理
1. 进入"账户管理"页面
2. 点击"导入账户"
3. 输入私钥（支持私钥字符串、助记词或 Keystore 文件）
4. 系统自动推导钱包地址并验证
5. 配置账户名称和是否默认账户
### 跟单配置
1. 进入"Leader 管理"，添加被跟单者（Leader）地址
2. 进入"跟单模板"，创建跟单模板（配置跟单比例、风险控制等）
3. 进入"跟单配置"，将账户、模板和 Leader 关联
4. 启用跟单关系，系统将自动开始跟单
### 查看统计
- **全局统计**：查看所有跟单关系的汇总统计
- **Leader 统计**：查看特定 Leader 的统计信息
- **分类统计**：按分类（sports/crypto）查看统计
- **跟单关系统计**：查看单个跟单关系的详细统计
## 🔧 配置说明
### 环境变量
#### 必需的环境变量
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
@@ -189,8 +211,10 @@ cd frontend
| `SERVER_PORT` | 后端服务端口 | `8000` |
| `POLYGON_RPC_URL` | Polygon RPC 地址 | `https://polygon-rpc.com` |
| `JWT_SECRET` | JWT 密钥 | - |
| `ADMIN_RESET_PASSWORD_KEY` | 管理员密码重置密钥 | - |
| `CRYPTO_SECRET_KEY` | 加密密钥（用于加密存储私钥和 API Key） | - |
### 代理配置
#### 代理配置
系统支持通过 Web UI 配置 HTTP 代理，无需修改环境变量：
@@ -199,23 +223,65 @@ cd frontend
3. 启用代理并测试连接
4. 配置实时生效，无需重启服务
## 📚 文档
### 📚 详细部署文档
更多部署选项和详细说明，请参考：[部署文档](docs/DEPLOYMENT.md)
包括：
- 一体化部署详细步骤
- 后端部署（Java/Docker）
- 前端部署
- 环境配置说明
- 常见问题解答
### 🔄 版本管理
项目支持自动版本号管理和 Docker 镜像构建：
- **自动构建**：通过 GitHub Releases 页面创建 release 时自动构建 Docker 镜像
- **自动删除**：删除 release 时自动删除对应的 Docker 镜像标签
- **版本号显示**：前端自动显示当前版本号
详细说明请参考：[版本号管理文档](docs/VERSION_MANAGEMENT.md)
---
## 第三部分：开发文档
详细的开发指南、API 接口文档、代码规范等，请参考：
### 📖 [开发文档](docs/DEVELOPMENT.md)
开发文档包含以下内容：
- **项目结构**：详细的目录结构说明
- **开发环境配置**：如何搭建开发环境
- **代码规范**：后端和前端开发规范
- **API 接口文档**：所有 API 接口的详细说明
- **数据库设计**：数据库表结构说明
- **前端开发指南**：前端开发最佳实践
- **后端开发指南**：后端开发最佳实践
- **常见问题**：开发过程中常见问题的解答
### 📚 其他文档
- [部署文档](docs/DEPLOYMENT.md) - 详细的部署指南（Java/Docker）
- [版本号管理文档](docs/VERSION_MANAGEMENT.md) - 版本号管理和自动构建
- [跟单系统需求文档](docs/copy-trading-requirements.md) - 后端 API 接口文档
- [前端需求文档](docs/copy-trading-frontend-requirements.md) - 前端功能文档
## 🤝 贡献
### 🤝 贡献指南
欢迎贡献代码！请遵循以下步骤：
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request
3. 遵循代码规范（参考开发文档）
4. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
5. 推送到分支 (`git push origin feature/AmazingFeature`)
6. 开启 Pull Request
## 📝 开发规范
### 📝 开发规范
- **后端**: 遵循 Kotlin 编码规范，使用 Spring Boot 最佳实践
- **前端**: 遵循 TypeScript 和 React 最佳实践
@@ -225,6 +291,8 @@ cd frontend
- [后端开发规范](.cursor/rules/backend.mdc)
- [前端开发规范](.cursor/rules/frontend.mdc)
---
## ⚠️ 免责声明
本软件仅供学习和研究使用。使用本软件进行交易的风险由用户自行承担。作者不对任何交易损失负责。
@@ -247,4 +315,3 @@ cd frontend
---
**⭐ 如果这个项目对你有帮助，请给个 Star！**
docs/DEVELOPMENT.md
+513
View File
@@ -0,0 +1,513 @@
# PolyHermes 开发文档
本文档介绍 PolyHermes 项目的开发指南，包括项目结构、开发环境配置、代码规范、API 接口等。
## 📋 目录
- [项目结构](#项目结构)
- [开发环境配置](#开发环境配置)
- [代码规范](#代码规范)
- [API 接口文档](#api-接口文档)
- [数据库设计](#数据库设计)
- [前端开发指南](#前端开发指南)
- [后端开发指南](#后端开发指南)
- [常见问题](#常见问题)
## 📦 项目结构
```
polyhermes/
├── backend/ # 后端服务
│ ├── src/main/kotlin/
│ │ └── com/wrbug/polymarketbot/
│ │ ├── api/ # API 接口定义（Retrofit）
│ │ ├── config/ # 配置类
│ │ ├── controller/ # REST 控制器
│ │ ├── dto/ # 数据传输对象
│ │ ├── entity/ # 数据库实体
│ │ ├── repository/ # 数据访问层
│ │ ├── service/ # 业务逻辑服务
│ │ ├── util/ # 工具类
│ │ └── websocket/ # WebSocket 处理
│ └── src/main/resources/
│ ├── application.properties
│ └── db/migration/ # Flyway 数据库迁移脚本
├── frontend/ # 前端应用
│ ├── src/
│ │ ├── components/ # 公共组件
│ │ ├── pages/ # 页面组件
│ │ ├── services/ # API 服务
│ │ ├── store/ # 状态管理（Zustand）
│ │ ├── types/ # TypeScript 类型定义
│ │ ├── utils/ # 工具函数
│ │ ├── hooks/ # React Hooks
│ │ ├── locales/ # 多语言资源
│ │ └── styles/ # 样式文件
│ └── public/ # 静态资源
├── docs/ # 文档
│ ├── DEPLOYMENT.md # 部署文档
│ ├── VERSION_MANAGEMENT.md # 版本号管理文档
│ ├── copy-trading-requirements.md # 跟单系统需求文档
│ └── ... # 其他文档
├── .github/workflows/ # GitHub Actions 工作流
└── README.md # 项目说明
```
## 🛠️ 开发环境配置
### 前置要求
- **JDK**: 17+
- **Node.js**: 18+
- **MySQL**: 8.0+
- **Gradle**: 7.5+（或使用 Gradle Wrapper）
- **Docker**: 20.10+（可选，用于容器化部署）
### 后端开发环境
1. **克隆仓库**
```bash
git clone https://github.com/WrBug/PolyHermes.git
cd PolyHermes
```
2. **配置数据库**
创建 MySQL 数据库：
```sql
CREATE DATABASE polyhermes CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
3. **配置环境变量**
编辑 `backend/src/main/resources/application.properties` 或使用环境变量：
```properties
# 数据库配置
spring.datasource.url=jdbc:mysql://localhost:3306/polyhermes?useSSL=false&serverTimezone=UTC&characterEncoding=utf8mb4
spring.datasource.username=${DB_USERNAME:root}
spring.datasource.password=${DB_PASSWORD:password}
# 服务器端口
server.port=${SERVER_PORT:8000}
# Polygon RPC
polygon.rpc.url=${POLYGON_RPC_URL:https://polygon-rpc.com}
# JWT 密钥
jwt.secret=${JWT_SECRET:change-me-in-production}
# 加密密钥（用于加密存储私钥和 API Key）
crypto.secret.key=${CRYPTO_SECRET_KEY:change-me-in-production}
```
4. **启动后端服务**
```bash
cd backend
./gradlew bootRun
```
后端服务将在 `http://localhost:8000` 启动。
### 前端开发环境
1. **安装依赖**
```bash
cd frontend
npm install
```
2. **配置环境变量（可选）**
创建 `.env` 文件：
```env
VITE_API_URL=http://localhost:8000
VITE_WS_URL=ws://localhost:8000
```
3. **启动开发服务器**
```bash
npm run dev
```
前端应用将在 `http://localhost:3000` 启动。
## 📝 代码规范
### 后端开发规范
详细规范请参考：[后端开发规范](.cursor/rules/backend.mdc)
**核心规范**：
- 使用 Kotlin 编码规范
- Controller 方法**禁止**使用 `suspend`
- 实体类 ID 字段使用 `Long? = null`
- 所有时间字段使用 `Long` 时间戳（毫秒）
- 数值计算使用 `BigDecimal`
- 使用 `ErrorCode` 枚举定义错误码和消息
- **禁止**在代码中添加 TODO 注释
- **禁止**直接返回 mock 数据
### 前端开发规范
详细规范请参考：[前端开发规范](.cursor/rules/frontend.mdc)
**核心规范**：
- 使用 TypeScript 类型定义
- 使用函数式组件和 Hooks
- **禁止**使用 `any` 类型
- **必须**使用多语言（i18n）进行所有文本显示
- **必须**使用 `formatUSDC` 函数格式化 USDC 金额
- **必须**支持移动端和桌面端
- **禁止**在代码中添加 TODO 注释
### 提交规范
遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建/工具相关
示例：
```bash
git commit -m "feat: 添加版本号显示功能"
git commit -m "fix: 修复订单状态更新问题"
```
## 📡 API 接口文档
### 统一响应格式
所有 API 接口统一使用 POST 方法，响应格式如下：
```json
{
"code": 0,
"data": {},
"msg": ""
}
```
- `code`: 响应码，0 表示成功，非 0 表示失败
- `data`: 响应数据，可以是任意类型
- `msg`: 响应消息，成功时通常为空，失败时包含错误提示
### 错误码规范
- `0`: 成功
- `1001-1999`: 参数错误
- `2001-2999`: 认证/权限错误
- `3001-3999`: 资源不存在
- `4001-4999`: 业务逻辑错误
- `5001-5999`: 服务器内部错误
### 主要 API 接口
#### 账户管理
- `POST /api/accounts/list` - 获取账户列表
- `POST /api/accounts/import` - 导入账户（通过私钥）
- `POST /api/accounts/detail` - 获取账户详情
- `POST /api/accounts/edit` - 编辑账户
- `POST /api/accounts/delete` - 删除账户
- `POST /api/accounts/balance` - 获取账户余额
#### Leader 管理
- `POST /api/leaders/list` - 获取 Leader 列表
- `POST /api/leaders/add` - 添加 Leader
- `POST /api/leaders/edit` - 编辑 Leader
- `POST /api/leaders/delete` - 删除 Leader
#### 跟单模板
- `POST /api/templates/list` - 获取模板列表
- `POST /api/templates/add` - 添加模板
- `POST /api/templates/edit` - 编辑模板
- `POST /api/templates/delete` - 删除模板
#### 跟单配置
- `POST /api/copy-trading/list` - 获取跟单配置列表
- `POST /api/copy-trading/add` - 添加跟单配置
- `POST /api/copy-trading/edit` - 编辑跟单配置
- `POST /api/copy-trading/delete` - 删除跟单配置
- `POST /api/copy-trading/enable` - 启用跟单
- `POST /api/copy-trading/disable` - 禁用跟单
#### 订单管理
- `POST /api/copy-trading/orders/buy` - 获取买入订单列表
- `POST /api/copy-trading/orders/sell` - 获取卖出订单列表
- `POST /api/copy-trading/orders/matched` - 获取匹配订单列表
#### 统计分析
- `POST /api/statistics/global` - 获取全局统计
- `POST /api/statistics/leader` - 获取 Leader 统计
- `POST /api/statistics/category` - 获取分类统计
- `POST /api/copy-trading/statistics` - 获取跟单关系统计
#### 仓位管理
- `POST /api/positions/list` - 获取仓位列表
- `POST /api/positions/sell` - 卖出仓位
- `POST /api/positions/redeem` - 赎回仓位
#### 系统管理
- `POST /api/system-settings/proxy` - 配置代理
- `POST /api/system-settings/api-health` - 获取 API 健康状态
- `POST /api/users/list` - 获取用户列表
- `POST /api/users/add` - 添加用户
- `POST /api/users/edit` - 编辑用户
- `POST /api/users/delete` - 删除用户
详细 API 接口文档请参考：[跟单系统需求文档](copy-trading-requirements.md)
## 🗄️ 数据库设计
### 主要数据表
- `accounts` - 账户表
- `leaders` - Leader 表
- `templates` - 跟单模板表
- `copy_trading` - 跟单配置表
- `copy_orders` - 跟单订单表
- `positions` - 仓位表
- `users` - 用户表
- `system_settings` - 系统设置表
数据库迁移脚本位于 `backend/src/main/resources/db/migration/`，使用 Flyway 管理。
## 🎨 前端开发指南
### 项目结构
```
frontend/src/
├── components/ # 公共组件
│ ├── Layout.tsx # 布局组件（支持移动端）
│ └── Logo.tsx # Logo 组件
├── pages/ # 页面组件
│ ├── AccountList.tsx
│ ├── LeaderList.tsx
│ ├── CopyTradingList.tsx
│ └── ...
├── services/ # API 服务
│ ├── api.ts # API 服务定义
│ └── websocket.ts # WebSocket 服务
├── store/ # 状态管理（Zustand）
├── types/ # TypeScript 类型定义
├── utils/ # 工具函数
│ ├── index.ts # 统一导出
│ ├── ethers.ts # 以太坊相关工具
│ ├── auth.ts # 认证相关工具
│ └── version.ts # 版本号工具
├── hooks/ # React Hooks
├── locales/ # 多语言资源
│ ├── zh-CN/
│ ├── zh-TW/
│ └── en/
└── styles/ # 样式文件
```
### 多语言支持
项目支持多语言（中文简体、中文繁体、英文），使用 `react-i18next`。
**添加新翻译**：
1. 在 `src/locales/{locale}/common.json` 中添加翻译
2. 在组件中使用 `useTranslation` Hook：
```typescript
import { useTranslation } from 'react-i18next'
const MyComponent: React.FC = () => {
const { t } = useTranslation()
return <div>{t('key')}</div>
}
```
### 移动端适配
- 使用 `react-responsive` 检测设备类型
- 断点设置：移动端 < 768px，桌面端 >= 768px
- 使用响应式布局和组件
### 工具函数
**USDC 金额格式化**：
```typescript
import { formatUSDC } from '../utils'
const balance = formatUSDC('1.23456') // "1.2345"
```
**以太坊地址验证**：
```typescript
import { isValidWalletAddress } from '../utils'
if (isValidWalletAddress(address)) {
// 地址有效
}
```
## ⚙️ 后端开发指南
### 项目结构
```
backend/src/main/kotlin/com/wrbug/polymarketbot/
├── api/ # API 接口定义（Retrofit）
│ ├── PolymarketClobApi.kt
│ ├── PolymarketGammaApi.kt
│ └── GitHubApi.kt
├── controller/ # REST 控制器
├── service/ # 业务逻辑服务
├── entity/ # 数据库实体
├── repository/ # 数据访问层
├── dto/ # 数据传输对象
├── util/ # 工具类
│ ├── CryptoUtils.kt # 加密工具
│ ├── RetrofitFactory.kt # Retrofit 工厂
│ └── ...
└── websocket/ # WebSocket 处理
```
### 创建新 API 接口
1. **定义 Retrofit 接口**（在 `api/` 目录）：
```kotlin
interface MyApi {
@POST("/endpoint")
suspend fun myMethod(@Body request: MyRequest): Response<MyResponse>
}
```
2. **创建 Service**（在 `service/` 目录）：
```kotlin
@Service
class MyService(
private val myApi: MyApi
) {
suspend fun doSomething(): Result<MyResponse> {
// 业务逻辑
}
}
```
3. **创建 Controller**（在 `controller/` 目录）：
```kotlin
@RestController
@RequestMapping("/api/my")
class MyController(
private val myService: MyService,
private val messageSource: MessageSource
) {
@PostMapping("/list")
fun list(@RequestBody request: MyListRequest): ResponseEntity<ApiResponse<MyListResponse>> {
return try {
val data = runBlocking { myService.getList(request) }
ResponseEntity.ok(ApiResponse.success(data))
} catch (e: Exception) {
logger.error("获取列表失败", e)
ResponseEntity.ok(ApiResponse.error(ErrorCode.SERVER_ERROR, messageSource = messageSource))
}
}
}
```
### 数据库操作
使用 Spring Data JPA：
```kotlin
@Repository
interface MyRepository : JpaRepository<MyEntity, Long> {
fun findByCode(code: String): MyEntity?
fun findByCategory(category: String): List<MyEntity>
}
```
### 加密存储
使用 `CryptoUtils` 加密敏感数据：
```kotlin
@Autowired
private lateinit var cryptoUtils: CryptoUtils
// 加密
val encrypted = cryptoUtils.encrypt("sensitive-data")
// 解密
val decrypted = cryptoUtils.decrypt(encrypted)
```
## 🔧 常见问题
### Q1: 如何添加新的页面？
1. 在 `frontend/src/pages/` 创建页面组件
2. 在 `frontend/src/App.tsx` 添加路由
3. 在 `frontend/src/components/Layout.tsx` 添加菜单项（如需要）
### Q2: 如何添加新的 API 接口？
1. 在 `backend/src/main/kotlin/.../controller/` 创建 Controller
2. 在 `backend/src/main/kotlin/.../service/` 创建 Service
3. 在 `frontend/src/services/api.ts` 添加 API 调用方法
### Q3: 如何添加数据库表？
1. 创建 Entity 类（在 `entity/` 目录）
2. 创建 Repository 接口（在 `repository/` 目录）
3. 创建 Flyway 迁移脚本（在 `resources/db/migration/`）
### Q4: 如何测试 WebSocket？
使用浏览器控制台或 WebSocket 客户端工具连接到 `ws://localhost:8000/ws`
### Q5: 如何调试后端代码？
1. 使用 IDE 的调试功能（IntelliJ IDEA、VS Code 等）
2. 在代码中添加日志：`logger.debug("调试信息")`
3. 查看日志输出：`./gradlew bootRun` 或查看日志文件
## 📚 相关文档
- [部署文档](DEPLOYMENT.md) - 详细的部署指南
- [版本号管理文档](VERSION_MANAGEMENT.md) - 版本号管理和自动构建
- [跟单系统需求文档](copy-trading-requirements.md) - 后端 API 接口文档
- [前端需求文档](copy-trading-frontend-requirements.md) - 前端功能文档
## 🤝 贡献指南
欢迎贡献代码！请遵循以下步骤：
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 遵循代码规范
4. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
5. 推送到分支 (`git push origin feature/AmazingFeature`)
6. 开启 Pull Request
---
**Happy Coding! 🚀**