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！**