PolyHermes/docs/zh/DEVELOPMENT.md

PolyHermes 开发文档

本文档介绍 PolyHermes 项目的开发指南，包括项目结构、开发环境配置、代码规范、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. 克隆仓库

git clone https://github.com/WrBug/PolyHermes.git
cd PolyHermes

2. 配置数据库

创建 MySQL 数据库：

CREATE DATABASE polyhermes CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

3. 配置环境变量

编辑 backend/src/main/resources/application.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}

# JWT 密钥
jwt.secret=${JWT_SECRET:change-me-in-production}

# 加密密钥（用于加密存储私钥和 API Key）
crypto.secret.key=${CRYPTO_SECRET_KEY:change-me-in-production}

4. 启动后端服务

cd backend
./gradlew bootRun

后端服务将在 http://localhost:8000 启动。

前端开发环境

1. 安装依赖

cd frontend
npm install

2. 配置环境变量（可选）

创建 .env 文件：

VITE_API_URL=http://localhost:8000
VITE_WS_URL=ws://localhost:8000

3. 启动开发服务器

npm run dev

前端应用将在 http://localhost:3000 启动。

📝 代码规范

后端开发规范

详细规范请参考：后端开发规范

核心规范：

• 使用 Kotlin 编码规范
• Controller 方法禁止使用 suspend
• 实体类 ID 字段使用 Long? = null
• 所有时间字段使用 Long 时间戳（毫秒）
• 数值计算使用 BigDecimal
• 使用 ErrorCode 枚举定义错误码和消息
• 禁止在代码中添加 TODO 注释
• 禁止直接返回 mock 数据

前端开发规范

详细规范请参考：前端开发规范

核心规范：

• 使用 TypeScript 类型定义
• 使用函数式组件和 Hooks
• 禁止使用 any 类型
• 必须使用多语言（i18n）进行所有文本显示
• 必须使用 formatUSDC 函数格式化 USDC 金额
• 必须支持移动端和桌面端
• 禁止在代码中添加 TODO 注释

提交规范

遵循 Conventional Commits 规范：

• feat: 新功能
• fix: 修复 bug
• docs: 文档更新
• style: 代码格式调整
• refactor: 代码重构
• test: 测试相关
• chore: 构建/工具相关

示例：

git commit -m "feat: 添加版本号显示功能"
git commit -m "fix: 修复订单状态更新问题"

📡 API 接口文档

统一响应格式

所有 API 接口统一使用 POST 方法，响应格式如下：

{
  "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 接口文档请参考：跟单系统需求文档

🗄️ 数据库设计

主要数据表

• 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：

import { useTranslation } from 'react-i18next'

const MyComponent: React.FC = () => {
  const { t } = useTranslation()
  return <div>{t('key')}</div>
}

移动端适配

• 使用 react-responsive 检测设备类型
• 断点设置：移动端 < 768px，桌面端 >= 768px
• 使用响应式布局和组件

工具函数

USDC 金额格式化：

import { formatUSDC } from '../utils'

const balance = formatUSDC('1.23456')  // "1.2345"

以太坊地址验证：

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/ 目录）：

interface MyApi {
    @POST("/endpoint")
    suspend fun myMethod(@Body request: MyRequest): Response<MyResponse>
}

2. 创建 Service（在 service/ 目录）：

@Service
class MyService(
    private val myApi: MyApi
) {
    suspend fun doSomething(): Result<MyResponse> {
        // 业务逻辑
    }
}

3. 创建 Controller（在 controller/ 目录）：

@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：

@Repository
interface MyRepository : JpaRepository<MyEntity, Long> {
    fun findByCode(code: String): MyEntity?
    fun findByCategory(category: String): List<MyEntity>
}

加密存储

使用 CryptoUtils 加密敏感数据：

@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 或查看日志文件

📚 相关文档

• 部署文档 / English - 详细的部署指南
• 版本号管理文档 / English - 版本号管理和自动构建
• 开发文档 / English - 开发指南
• 跟单系统需求文档 - 后端 API 接口文档
• 前端需求文档 - 前端功能文档

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

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! 🚀