pancakeswap-project-guide.mdc

---
description: 
globs: 
alwaysApply: false
---
# PancakeSwap V3 流动性管理系统 - 开发引导规则

## 🎯 项目概述

本项目是一个专业的 **PancakeSwap V3 流动性管理系统**，采用模块化架构设计，提供完整的流动性添加、头寸管理、钱包操作和策略执行功能。

### 核心设计理念
- **职责分离**: 每个服务专注单一核心功能
- **功能复现**: 100%复现参考脚本的所有逻辑和步骤  
- **用户友好**: 智能参数设计，简化用户输入
- **架构清晰**: 模块间界限清晰，不允许跨职责调用
- **代码简洁**: 单一文件不超过800行，单一方法不超过100行

## 🏗️ 系统架构

### 服务分层架构
```
┌─────────────────────────────────────────────────┐
│                  API 层                         │  
│        [routes.ts](mdc:src/api/routes.ts)        │
│     HTTP接口 & 参数验证 & 响应处理                │
└─────────────────┬───────────────────────────────┘
                  │
┌─────────────────┴───────────────────────────────┐
│                专用服务层                        │
├─────────────────┬───────────────┬───────────────┤
│ LiquidityManager│ PositionManager│ ContractService│
│   💧 流动性添加   │    🎯 头寸管理   │   🔧 基础合约   │
│ [LiquidityManager.ts](mdc:src/services/LiquidityManager.ts) │ [PositionManager.ts](mdc:src/services/PositionManager.ts) │ [ContractService.ts](mdc:src/services/ContractService.ts) │
└─────────────────┴───────────────┴───────────────┘
                  │
┌─────────────────┴───────────────────────────────┐
│                基础设施层                        │
├─────────────────┬───────────────┬───────────────┤
│   Web3Service   │  CryptoService │   EventBus    │
│  🌐 区块链连接   │  🔐 钱包加密    │  📡 事件通信   │
│ [Web3Service.ts](mdc:src/services/Web3Service.ts) │ [CryptoService.ts](mdc:src/services/CryptoService.ts) │               │
└─────────────────┴───────────────┴───────────────┘
```

### 完整目录结构
```
📦 项目根目录/
├── 📁 src/                          # 主程序源代码
│   ├── 📄 [app.ts](mdc:src/app.ts)                    # Express应用主文件  
│   ├── 📄 [index.ts](mdc:src/index.ts)                # 程序入口文件
│   ├── 📁 api/                      # API层
│   │   ├── 📄 [routes.ts](mdc:src/api/routes.ts)             # 统一路由配置
│   │   └── 📄 [okx-proxy-routes.ts](mdc:src/api/okx-proxy-routes.ts)   # OKX代理路由
│   ├── 📁 services/                 # 专用服务层
│   │   ├── 📄 [LiquidityManager.ts](mdc:src/services/LiquidityManager.ts)   # 流动性添加
│   │   ├── 📄 [PositionManager.ts](mdc:src/services/PositionManager.ts)    # 头寸管理  
│   │   ├── 📄 [ContractService.ts](mdc:src/services/ContractService.ts)    # 基础合约
│   │   ├── 📄 [Web3Service.ts](mdc:src/services/Web3Service.ts)        # 区块链连接
│   │   └── 📄 [CryptoService.ts](mdc:src/services/CryptoService.ts)      # 钱包加密
│   ├── 📁 types/                    # 类型定义
│   │   └── 📄 [interfaces.ts](mdc:src/types/interfaces.ts)         # 统一接口
│   ├── 📁 di/                       # 依赖注入
│   │   └── 📄 [container.ts](mdc:src/di/container.ts)          # DI容器
│   ├── 📁 constants/                # 常量定义
│   ├── 📁 adapters/                 # 外部适配器
│   ├── 📁 business/                 # 业务逻辑
│   ├── 📁 contracts/                # 合约相关
│   └── 📁 infrastructure/           # 基础设施
├── 📁 strategy-ui/                  # 策略管理前端 (端口: 5000)
│   ├── 📄 [server.js](mdc:strategy-ui/server.js)              # Express静态服务器
│   └── 📁 public/                   # 静态资源文件
├── 📁 web/                          # 主程序前端 (端口: 4001)  
│   ├── 📄 [server.js](mdc:web/server.js)                # Express静态服务器
│   └── 📁 public/                   # 静态资源文件
├── 📁 okx-proxy/                    # 🔄 OKX交换代理服务 (端口: 8001)
│   ├── 📄 [package.json](mdc:okx-proxy/package.json)            # 代理服务配置
│   ├── 📄 [proxy-server.js](mdc:okx-proxy/proxy-server.js)        # 核心代理逻辑
│   └── 📄 [README.md](mdc:okx-proxy/README.md)               # 代理服务文档
├── 📁 okx_dex_api/                  # OKX DEX API服务 (端口: 8000)
│   ├── 📄 [package.json](mdc:okx_dex_api/package.json)            # 依赖配置
│   └── 📁 src/                      # TypeScript源码
├── 📁 scripts/                      # 启动和管理脚本
│   ├── 📄 [simple-start.sh](mdc:scripts/simple-start.sh)          # 简化启动脚本
│   └── 📄 [stop-all-services.sh](mdc:scripts/stop-all-services.sh)    # 停止所有服务
├── 📁 test/                         # 测试脚本目录
├── 📁 docs/                         # 文档目录
├── 📁 data/                         # 数据文件
├── 📁 config/                       # 配置文件
├── 📁 examples/                     # 示例代码
├── 📄 [package.json](mdc:package.json)                 # 主程序依赖配置
├── 📄 [tsconfig.json](mdc:tsconfig.json)                # TypeScript配置
├── 📄 [README.md](mdc:README.md)                     # 项目说明文档
├── 📄 [pancakeswap-architecture.mdc](mdc:pancakeswap-architecture.mdc) # 架构规范
└── 📄 [env.example](mdc:env.example)                  # 环境变量示例
```

## 🚀 系统服务端口架构

### 🏠 主程序系统 (4xxx端口)
- **主程序后端API**: `http://localhost:4000/api`
  - 启动方式: `npm start` 或 `npm run dev`
  - 核心功能: 流动性管理、头寸操作、钱包管理、策略执行
  - WebSocket服务: `ws://localhost:4000`
  - 健康检查: `http://localhost:4000/health`
  - 测试页面: `http://localhost:4000/test/`
  - OKX路由: `http://localhost:4000/api/okx/*`

- **主程序前端**: `http://localhost:4001`  
  - 启动方式: `cd web && npm start`
  - 功能: 流动性操作主界面

### 📊 策略管理系统 (5xxx端口)
- **策略管理前端**: `http://localhost:5000`
  - 启动方式: `cd strategy-ui && npm start`
  - 功能: 策略配置和管理界面

### 🎮 OKX系统 (8xxx端口)
- **OKX DEX API**: `http://localhost:8000`
  - 启动方式: `cd okx_dex_api && npm run web`
  - 功能: OKX DEX独立Web界面服务

- **🔄 OKX交换代理**: `http://localhost:8001/api/okx`
  - 启动方式: `cd okx-proxy && npm start`
  - 功能: 为策略引擎提供8001端口的OKX API访问
  - 代理目标: 转发所有请求到 `http://localhost:4000/api/okx/*`
  - 健康检查: `http://localhost:8001/health`

### 🔄 服务依赖关系
```
策略引擎 → 8001端口 → OKX代理服务 → 转发到4000端口 → 主系统OKX路由
```

## 🛠️ 一键启动管理

### 完整系统启动
```bash
# 启动所有服务
./scripts/simple-start.sh

# 停止所有服务  
./scripts/stop-all-services.sh

# 检查端口状态
./scripts/check-ports.sh
```

### 单独服务启动
```bash
# 主程序后端 (4000端口)
npm run dev

# 主程序前端 (4001端口) 
cd web && npm start

# 策略管理前端 (5000端口)
cd strategy-ui && npm start

# OKX DEX API (8000端口)
cd okx_dex_api && npm run web

# OKX交换代理 (8001端口)
cd okx-proxy && npm start
```

## 💧 核心服务功能详解

### LiquidityManager - 流动性添加专用服务
**职责**: 100%复现 `real_multicall_direct_test_fixed_v5.js` 的完整流动性添加流程

**核心功能**:
- ✅ 智能参数处理 (用户友好的百分比输入)
- ✅ 实时状态获取和重新计算 (`getRealTimeStateAndRecalculate`)
- ✅ 动态滑点计算 (`calculateDynamicSlippage`)
- ✅ 完整执行流程 (`executeWithRealTimeRecalculation`)
- ✅ Tick范围计算 (`calculateTickRange`)
- ✅ 流动性数量计算 (`calculateLiquidityFromAmount`)

**智能参数示例**:
```typescript
const params = {
  inputAmount: "0.1",           // 0.1 WBNB (用户友好)
  inputToken: "WBNB",           // 简化代币选择
  lowerPercent: -5,             // 当前价格-5%
  upperPercent: 5,              // 当前价格+5%  
  baseSlippagePercent: 1        // 1%基础滑点
};
```

### PositionManager - 头寸管理专用服务  
**职责**: 100%复现 `position_management.js` 的完整头寸管理功能

**核心功能**:
- ✅ 获取用户头寸 (`getUserPositions`) - 包含完整代币信息
- ✅ 关闭单个头寸 (`closeSinglePosition`) - Multicall一步完成
- ✅ 批量关闭所有头寸 (`closeAllPositions`) - 自动处理所有类型
- ✅ 完整的错误处理和状态管理
- ✅ 自动NFT销毁和手续费收集

**Multicall优势**: 一次交易完成移除流动性 + 收集手续费 + 销毁NFT

### ContractService - 基础合约交互服务
**职责**: 提供基础合约交互功能，支持其他专用服务

**核心功能**:
- ✅ 代币授权管理 (`approveToken`, `checkAllowance`)
- ✅ 池子信息查询 (`getPoolAddress`, `getPoolState`)  
- ✅ 代币信息查询 (`getTokenInfo`)
- ✅ Tick工具方法 (`getTickSpacing`, `nearestUsableTick`)

## 📊 完整API接口

### 💧 流动性操作 (1个核心接口)
- `POST /api/add-liquidity` - 智能流动性添加 ⭐⭐⭐
  - 参数: inputAmount, inputToken, lowerPercent, upperPercent, baseSlippagePercent
  - 返回: 交易哈希、流动性Token ID、实际添加数量

### 🎯 头寸管理 (3个接口)  
- `GET /api/positions/:userAddress` - 获取用户所有头寸 ⭐
- `DELETE /api/positions/:tokenId` - 关闭单个头寸 
- `DELETE /api/positions/batch/:userAddress` - 批量关闭所有头寸 ⭐

### 🔐 钱包管理 (8个接口)
- `GET /api/wallet/status` - 获取钱包状态
- `POST /api/wallet/create` - 创建钱包
- `POST /api/wallet/unlock` - 解锁钱包 ⭐
- `POST /api/wallet/lock` - 锁定钱包
- `DELETE /api/wallet/delete` - 删除钱包
- `GET /api/wallet/info` - 获取钱包信息
- `POST /api/wallet/connect-web3` - 连接Web3
- `GET /api/wallet/balance/:address` - 获取BNB余额

### 🔄 OKX交换API (6个接口)
- `GET /api/okx/health` - OKX服务健康检查 ⭐
- `POST /api/okx/quote` - 获取交换报价
- `POST /api/okx/swap` - 执行代币交换
- `POST /api/okx/approve` - 代币授权
- `GET /api/okx/track/:orderId` - 追踪交易状态
- `GET /api/okx/tokens` - 获取支持的代币列表

### 📊 策略管理 (7个接口)
- `POST /api/strategy/create` - 创建策略配置 ⭐
- `POST /api/strategy/:instanceId/start` - 启动策略实例
- `POST /api/strategy/:instanceId/stop` - 停止策略实例
- `DELETE /api/strategy/:instanceId` - 删除策略实例
- `GET /api/strategy/:instanceId/status` - 获取策略状态
- `GET /api/strategy/instances` - 获取所有策略实例
- `GET /api/strategy/ws/status` - WebSocket状态查询

### 🔧 系统工具 (5个接口)
- `GET /api/health` - 系统健康检查
- `GET /api/metrics` - 系统指标
- `GET /api/pool/:token0/:token1/:fee` - 池子信息查询
- `POST /api/approve` - 代币授权
- `GET /api/allowance/:token/:owner` - 查询授权额度

## 🛠️ 开发规范和约束

### 架构保护规则
1. **✅ LiquidityManager 只处理流动性添加**
2. **✅ PositionManager 只处理头寸管理**  
3. **✅ ContractService 只提供基础合约交互**
4. **✅ OKX代理服务只负责8001端口的透明转发**
5. **✅ 必须100%复现参考脚本功能和步骤**
6. **❌ 禁止跨职责调用，严格分层**

### 代码质量要求
- **功能复现**: 100%复现参考脚本，不允许删减步骤
- **智能参数**: 用户友好的参数设计，避免复杂计算
- **代理透明**: OKX代理服务对策略引擎完全透明

### 错误处理规范
- 完善的异常捕获和错误信息
- 详细的日志记录和调试信息
- 用户友好的错误提示
- 自动重试机制（适当场景）
- 代理服务的连接状态监控

### 测试和文档要求
- 所有测试脚本创建在 `test/` 目录下
- 所有说明文档保存在 `docs/` 目录下
- 保持代码简洁、结构清晰、容易扩展
- 模块化架构设计

## 🎯 开发建议

### 新功能开发流程  
1. **确认职责归属**: 明确功能属于哪个专用服务
2. **参考已有规范**: 查看 [pancakeswap-architecture.mdc](mdc:pancakeswap-architecture.mdc)  
3. **遵循代码规范**: 保持简洁和模块化
4. **完善错误处理**: 添加详细的异常处理
5. **编写测试用例**: 在 `test/` 目录创建测试

### 常见开发场景
- **添加新API**: 在 [routes.ts](mdc:src/api/routes.ts) 添加路由，调用对应专用服务
- **扩展流动性功能**: 在 [LiquidityManager.ts](mdc:src/services/LiquidityManager.ts) 中扩展
- **增强头寸管理**: 在 [PositionManager.ts](mdc:src/services/PositionManager.ts) 中完善
- **基础功能支持**: 在 [ContractService.ts](mdc:src/services/ContractService.ts) 中添加
- **OKX功能扩展**: 在 [okx-proxy-routes.ts](mdc:src/api/okx-proxy-routes.ts) 中添加新路由

### OKX代理服务使用指南
- **策略引擎调用**: 直接访问 `http://localhost:8001/api/okx/*`
- **健康检查**: `curl http://localhost:8001/health`
- **日志监控**: `tail -f logs/okx-proxy.log`
- **服务管理**: 使用统一启动脚本或独立启动

### 故障排查指南
- **健康检查**: 访问 `http://localhost:4000/health`
- **OKX代理检查**: 访问 `http://localhost:8001/health`
- **日志查看**: 检查控制台输出和日志文件  
- **接口测试**: 使用 `http://localhost:4000/test/` 页面
- **架构文档**: 参考 [pancakeswap-architecture.mdc](mdc:pancakeswap-architecture.mdc)
- **端口状态**: 运行 `./scripts/check-ports.sh`

---

**记住**: 本项目采用严格的模块化架构，每个服务专注单一职责。新增的OKX代理服务通过透明转发的方式，实现了策略引擎与主系统的解耦，保持了架构的独立性和可扩展性。开发时请严格遵循架构规范和代码质量要求。