# Examples 使用指南

## 📋 可用示例文件

### 🏦 账户管理示例

| 文件                               | 命令                         | 功能描述                           |
| ---------------------------------- | ---------------------------- | ---------------------------------- |
| `account_manager_smoke.ts`         | `npx tsx examples/account_manager_smoke.ts` | 多平台账户管理器功能测试 |
| `config_file_account_injection.ts` | `npx tsx examples/config_file_account_injection.ts` | JSON配置文件账户注入演示 |
| `fluent_account_injection.ts`      | `npx tsx examples/fluent_account_injection.ts` | 流畅式API账户管理演示 ⭐ |
| `cli_account_injection.ts`         | `npx tsx examples/cli_account_injection.ts` | 命令行参数账户注入演示   |
| `elegant_account_injection.ts`     | `npx tsx examples/elegant_account_injection.ts` | 优雅账户注入系统演示     |

### 🎯 Aster DEX 示例

| 文件                      | 命令                        | 功能描述                 |
| ------------------------- | --------------------------- | ------------------------ |
| `aster_adapter_smoke.ts`  | `npx tsx examples/aster_adapter_smoke.ts` | Aster 适配器基础功能测试 |
| `aster_listenkey_test.ts` | `npx tsx examples/aster_listenkey_test.ts` | ListenKey 管理和用户认证 |
| `aster_order_test.ts`     | `npx tsx examples/aster_order_test.ts` | 订单下单和管理测试       |
| `aster_user_ws_test.ts`   | `npx tsx examples/aster_user_ws_test.ts` | 用户 WebSocket 流测试    |
| `aster_ws_example.ts`     | `npx tsx examples/aster_ws_example.ts` | 市场数据 WebSocket 订阅  |

### 🌊 Pacifica DEX 示例

| 文件                     | 命令                        | 功能描述                 |
| ------------------------ | --------------------------- | ------------------------ |
| `pacifica_smoke.ts`      | `npx tsx examples/pacifica_smoke.ts` | Pacifica 基础连接测试    |
| `pacifica_test.ts`       | `npx tsx examples/pacifica_test.ts` | 完整的 Pacifica 功能测试 |
| `pacifica_ws_example.ts` | `npx tsx examples/pacifica_ws_example.ts` | WebSocket 实时数据订阅   |

### 🔄 对冲和高级交易示例

| 文件                       | 命令                         | 功能描述             |
| -------------------------- | ---------------------------- | -------------------- |
| `same_platform_hedging_demo.ts` | `npx tsx examples/same_platform_hedging_demo.ts` | 同平台对冲系统演示   |
| `enhanced_hedging_example.ts` | `npx tsx examples/enhanced_hedging_example.ts` | 增强对冲功能演示 |
| `bidirectional_profit_trading_demo.ts` | `npx tsx examples/bidirectional_profit_trading_demo.ts` | 双向盈利交易演示 ⭐ |
| `real_trading_test.ts` | `npx tsx examples/real_trading_test.ts` | 实际交易测试（谨慎使用）|

### 🛠️ 系统配置和工具示例

| 文件                       | 命令                         | 功能描述             |
| -------------------------- | ---------------------------- | -------------------- |
| `proxy_demo.ts` | `npx tsx examples/proxy_demo.ts` | 代理配置和测试演示 |

## 🚀 快速开始

### 推荐学习路径

1. **基础连接测试**：`npx tsx examples/pacifica_smoke.ts`
2. **账户管理**：`npx tsx examples/fluent_account_injection.ts` ⭐
3. **WebSocket数据**：`npx tsx examples/pacifica_ws_example.ts`
4. **完整功能测试**：`npx tsx examples/pacifica_test.ts`
5. **对冲系统**：`npx tsx examples/same_platform_hedging_demo.ts`
6. **高级交易**：`npx tsx examples/bidirectional_profit_trading_demo.ts` ⭐

### 1. 环境配置

确保设置了必要的环境变量：

```bash
# Pacifica DEX
PACIFICA_ACCOUNT=your_account_id
PACIFICA_ACCOUNT_PRIVATE_KEY=your_private_key
PACIFICA_BASE_URL=https://api.pacifica.fi
PACIFICA_WS_URL=wss://ws.pacifica.fi/ws

# Aster DEX
ASTER_ORDER_USER=your_user_address
ASTER_API_KEY=your_api_key
ASTER_API_SECRET=your_api_secret
ASTER_HTTP_BASE=https://fapi.asterdex.com
ASTER_WS_BASE=wss://fstream.asterdex.com
```

### 2. 运行基础测试

```bash
# 测试连接性
yarn smoke:pacifica
yarn test:aster:adapter

# 测试 WebSocket 功能
yarn test:pacifica:ws
yarn test:aster:ws

# 测试账户管理
yarn test:accounts:smoke
```

### 3. 运行集成演示

```bash
# 统一账户管理演示
yarn demo:unified-account

# 对冲系统演示
yarn demo:unified-hedge

# 完整集成测试
yarn test:integration:full
```

## 📊 示例文件架构

### 核心功能分层

```
examples/
├── 🏦 账户管理层
│   ├── account_manager_smoke.ts        # 多平台账户管理
│   └── unified_account_manager_demo.ts # 统一账户管理演示
├── 📡 交易所适配层
│   ├── aster_*.ts                      # Aster DEX 系列
│   └── pacifica_*.ts                   # Pacifica DEX 系列
├── 🔄 业务逻辑层
│   ├── unified_hedge_demo.ts           # 对冲执行演示
│   └── full_integration_test.ts        # 端到端测试
└── 📈 数据流层
    ├── *_ws_*.ts                       # WebSocket 实时数据
    └── *_order_*.ts                    # 订单执行流程
```

## 🔧 开发指南

### 添加新的示例

1. **命名规范**: `{exchange}_{function}_{type}.ts`

   - `exchange`: pacifica, aster, binance
   - `function`: order, ws, adapter, smoke
   - `type`: test, demo, example

2. **添加npm脚本**: 在 `package.json` 中添加对应命令

3. **文档更新**: 在本文档中添加说明

### 示例代码结构

```typescript
// 标准示例模板
import 'dotenv/config'
import { SomeAdapter } from '../src/exchanges/...'

async function main() {
  console.log('🚀 开始 [功能] 示例...')

  try {
    // 1. 环境检查
    // 2. 创建适配器
    // 3. 执行功能演示
    // 4. 结果展示
  } catch (error) {
    console.error('❌ 示例执行失败:', error)
    process.exit(1)
  }
}

main().catch(console.error)
```

## 🧪 测试策略

### 按功能分类测试

1. **连接测试**: `smoke` 系列 - 验证基础连接
2. **功能测试**: `test` 系列 - 验证核心功能
3. **集成测试**: `demo` 系列 - 验证业务流程
4. **压力测试**: `integration` 系列 - 验证系统稳定性

### 测试环境

- **开发环境**: 使用测试网络和模拟数据
- **演示模式**: 不执行真实交易，仅展示功能
- **集成测试**: 真实环境但小额测试

## 📝 最佳实践

### 安全原则

1. 使用环境变量存储敏感信息
2. 测试时使用小额资金
3. 启用演示模式避免意外交易
4. 实时监控测试结果

### 代码质量

1. 每个示例都要有错误处理
2. 提供详细的日志输出
3. 包含环境变量检查
4. 支持优雅退出

### 文档维护

1. 示例代码要与API保持同步
2. 及时更新环境变量说明
3. 添加故障排除指南
4. 提供性能优化建议

---

📚 **相关文档**:

- `docs/PACIFICA_API_REFERENCE.md` - Pacifica API 完整参考
- `CLAUDE.md` - 项目开发指南
- `TEST_RESULTS.md` - 集成测试报告