diff --git a/README.md b/README.md index 8a7467a..ab19216 100644 --- a/README.md +++ b/README.md @@ -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 < { + const { t } = useTranslation() + return
{t('key')}
+} +``` + +### 移动端适配 + +- 使用 `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 +} +``` + +2. **创建 Service**（在 `service/` 目录）： + +```kotlin +@Service +class MyService( + private val myApi: MyApi +) { + suspend fun doSomething(): Result { + // 业务逻辑 + } +} +``` + +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> { + 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 { + fun findByCode(code: String): MyEntity? + fun findByCategory(category: String): List +} +``` + +### 加密存储 + +使用 `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! 🚀** +