# 订单清理功能使用指南

本文档介绍如何使用订单清理功能来管理 Pacifica 平台上的开放订单。

## 功能概述

订单清理功能包含以下特性：

1. **自动清理** - 系统启动时自动清理历史订单
2. **停止清理** - 系统停止时自动取消所有活跃订单
3. **手动清理** - 通过脚本手动清理订单
4. **智能筛选** - 根据条件筛选需要清理的订单
5. **干运行模式** - 预览要清理的订单而不实际执行

## 自动清理（系统启动/停止时）

### 启动时清理

系统启动时会自动执行以下操作：

```typescript
// 从 Pacifica API 获取所有开放订单
// 清理所有非 reduce_only 的订单
// reduce_only 订单会被保留（通常是止损/止盈订单）
```

**清理选项：**
- ✅ 清理所有开放订单
- ⛔ 保留 reduce_only 订单（保护性订单）
- 📝 逐个取消订单以便更好地记录

**日志输出示例：**
```
🧹 开始清理历史订单

✅ 历史订单清理完成
==========================================
📊 账户数: 2
📋 总订单数: 15
✅ 成功取消: 14
❌ 取消失败: 1
==========================================
```

### 停止时清理

系统停止时会自动执行以下操作：

```typescript
// 停止所有活跃会话
// 取消所有开放订单（包括 reduce_only 订单）
// 确保账户干净停止
```

**清理选项：**
- ✅ 清理所有开放订单
- ✅ 包括 reduce_only 订单
- 🚀 强制清理模式（使用 cancelAllOrders API）

## 手动清理

### 使用脚本清理订单

#### 1. 查看要清理的订单（干运行模式）

```bash
npm run cleanup-orders:dry
# 或
npm run cleanup-orders -- --dry
```

这将：
- 从 Pacifica API 获取所有开放订单
- 显示将要清理的订单详情
- **不会实际取消任何订单**

**输出示例：**
```
🧹 Pacifica 订单清理工具
==========================================

⚠️  干运行模式：只显示要清理的订单，不实际执行

📊 找到 2 个活跃账户

✅ 账户已加载: 主账户 (account-1)
✅ 账户已加载: 副账户 (account-2)

------------------------------------------

📌 主账户 (account-1)
   开放订单: 8
   需要清理: 7
   将要取消: 7
   耗时: 245ms

📌 副账户 (account-2)
   开放订单: 7
   需要清理: 7
   将要取消: 7
   耗时: 198ms

==========================================
🎯 总计
==========================================
账户数: 2
总订单数: 15
将要取消: 14
总耗时: 443ms
==========================================

💡 提示: 移除 --dry 参数以实际执行清理
```

#### 2. 实际清理订单

```bash
npm run cleanup-orders
```

这将：
- 从 Pacifica API 获取所有开放订单
- 逐个取消订单
- 显示清理结果和统计信息

**输出示例：**
```
🧹 Pacifica 订单清理工具
==========================================

📊 找到 2 个活跃账户

✅ 账户已加载: 主账户 (account-1)
✅ 账户已加载: 副账户 (account-2)

------------------------------------------

🚀 开始清理订单...

==========================================
📊 清理结果汇总
==========================================

📌 主账户 (account-1)
   开放订单: 8
   需要清理: 7
   已取消: 7
   失败: 0
   耗时: 1245ms

📌 副账户 (account-2)
   开放订单: 7
   需要清理: 7
   已取消: 6
   失败: 1
   耗时: 1198ms

   ⚠️  错误详情:
      订单ID 12345: Order already filled

==========================================
🎯 总计
==========================================
账户数: 2
总订单数: 15
成功取消: 13
取消失败: 1
总耗时: 2443ms
==========================================

✅ 订单清理完成!
```

## 订单筛选规则

订单清理服务支持以下筛选选项：

### CleanupOptions 配置

```typescript
interface CleanupOptions {
  // 是否清理所有订单
  cleanAll?: boolean;

  // 只清理特定交易对的订单
  symbols?: string[];  // 例如: ['BTC-PERP', 'ETH-PERP']

  // 只清理特定方向的订单
  sides?: Array<'bid' | 'ask'>;  // 例如: ['bid']

  // 清理创建时间早于指定时间戳的订单（毫秒）
  olderThan?: number;  // 例如: Date.now() - 3600000 (1小时前)

  // 是否清理 reduce_only 订单
  includeReduceOnly?: boolean;

  // 清理模式：selective（逐个清理）或 force（批量清理）
  mode?: 'selective' | 'force';

  // 是否执行干运行
  dryRun?: boolean;
}
```

### 使用示例

```typescript
// 1. 只清理 BTC-PERP 的订单
const options: CleanupOptions = {
  symbols: ['BTC-PERP'],
  includeReduceOnly: false
};

// 2. 只清理 1 小时前的订单
const options: CleanupOptions = {
  olderThan: Date.now() - 3600000,
  includeReduceOnly: false
};

// 3. 清理所有卖单
const options: CleanupOptions = {
  sides: ['ask'],
  includeReduceOnly: false
};

// 4. 强制清理所有订单（包括 reduce_only）
const options: CleanupOptions = {
  cleanAll: true,
  includeReduceOnly: true,
  mode: 'force'
};
```

## API 集成

订单清理服务使用 Pacifica API 的以下端点：

### 1. 获取开放订单

```
GET /api/v1/orders
```

从此端点获取所有开放订单，然后根据筛选条件决定哪些订单需要清理。

### 2. 取消单个订单

```
POST /api/v1/orders/cancel
Body: { order_id: "12345" }
```

在 `selective` 模式下使用，逐个取消订单。

### 3. 取消所有订单

```
POST /api/v1/orders/cancel_all
```

在 `force` 模式下使用，批量取消所有订单。

## 错误处理

### 常见错误

1. **Order already filled**
   - 订单已成交，无法取消
   - 这是正常情况，不影响其他订单清理

2. **Order not found**
   - 订单已被取消或不存在
   - 这是正常情况，继续清理其他订单

3. **API rate limit**
   - API 请求频率过高
   - 清理服务会在每次取消订单后延迟 100ms

4. **Network timeout**
   - 网络连接超时
   - 重试当前订单或跳过

### 错误日志

所有错误都会记录到日志中，包括：

```typescript
{
  orderId: 12345,
  error: 'Order already filled',
  accountId: 'account-1',
  timestamp: '2025-09-30T10:30:00Z'
}
```

## 最佳实践

### 1. 系统启动前

```bash
# 先查看有哪些订单
npm run cleanup-orders:dry

# 确认后再清理
npm run cleanup-orders
```

### 2. 定期清理

如果系统长时间运行，建议：
- 每天定期检查开放订单
- 清理意外未取消的订单

### 3. 保护性订单

如果有重要的止损/止盈订单：
- 使用 `includeReduceOnly: false` 选项
- 或使用 `symbols` 和 `sides` 精确筛选

### 4. 多账户管理

对于多个账户：
- 系统会自动并行清理所有账户
- 每个账户的结果独立记录
- 可以查看每个账户的详细情况

## 安全考虑

1. **谨慎使用 force 模式**
   - force 模式会取消所有订单（包括 reduce_only）
   - 只在系统停止时使用

2. **干运行模式优先**
   - 先使用 `--dry` 参数预览
   - 确认无误后再实际执行

3. **备份重要配置**
   - 清理前确认账户配置正确
   - 保存重要的订单策略参数

4. **监控清理结果**
   - 检查日志中的错误信息
   - 确认清理数量符合预期

## 故障排除

### 问题：清理失败率过高

**原因：**
- API 连接问题
- 账户权限不足
- 订单状态异常

**解决方案：**
```bash
# 1. 检查账户配置
npm run test:basic

# 2. 检查 API 连接
npm run test:advanced

# 3. 查看详细日志
tail -f logs/system.log
```

### 问题：某些订单无法取消

**原因：**
- 订单已成交或已取消
- 订单类型不支持取消
- 账户余额不足

**解决方案：**
- 检查订单状态
- 使用干运行模式查看订单详情
- 手动在 Pacifica 平台上检查

### 问题：清理速度慢

**原因：**
- 订单数量过多
- API 限流
- 网络延迟

**解决方案：**
- 使用 `force` 模式批量取消
- 分批次清理（按交易对或时间）
- 优化网络连接

## 总结

订单清理功能提供了灵活的方式来管理 Pacifica 平台上的订单：

✅ **自动化** - 系统启动/停止时自动清理
✅ **可控性** - 支持干运行模式和条件筛选
✅ **可靠性** - 错误处理和详细日志
✅ **安全性** - 保护重要订单，避免误操作

正确使用订单清理功能可以：
- 避免遗留订单造成资金占用
- 保持账户状态整洁
- 减少意外成交风险
- 提高系统管理效率