pacifica/docs/ORDER_CLEANUP_GUIDE.md

订单清理功能使用指南

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

功能概述

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

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

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

启动时清理

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

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

清理选项：

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

日志输出示例：

🧹 开始清理历史订单

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

停止时清理

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

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

清理选项：

• ✅ 清理所有开放订单
• ✅ 包括 reduce_only 订单
• 🚀 强制清理模式（使用 cancelAllOrders API）

手动清理

使用脚本清理订单

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

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. 实际清理订单

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 配置

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;
}

使用示例

// 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

   • 网络连接超时
   • 重试当前订单或跳过

错误日志

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

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

最佳实践

1. 系统启动前

# 先查看有哪些订单
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 连接问题
• 账户权限不足
• 订单状态异常

解决方案：

# 1. 检查账户配置
npm run test:basic

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

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

问题：某些订单无法取消

原因：

• 订单已成交或已取消
• 订单类型不支持取消
• 账户余额不足

解决方案：

• 检查订单状态
• 使用干运行模式查看订单详情
• 手动在 Pacifica 平台上检查

问题：清理速度慢

原因：

• 订单数量过多
• API 限流
• 网络延迟

解决方案：

• 使用 force 模式批量取消
• 分批次清理（按交易对或时间）
• 优化网络连接

总结

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

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

正确使用订单清理功能可以：

• 避免遗留订单造成资金占用
• 保持账户状态整洁
• 减少意外成交风险
• 提高系统管理效率