# openPosition 方法使用指南

## 方法签名

```typescript
async openPosition(
    symbol: string,
    side: DerivativesTradingUsdsFuturesRestAPI.NewOrderSideEnum,
    quantity: number,
    price: number,
    options?: {
        // 所有可选参数...
    }
)
```

## 必需参数

### symbol

- **类型**: `string`
- **说明**: 交易对符号
- **示例**: `'BTCUSDT'`, `'ETHUSDT'`

### side

- **类型**: `DerivativesTradingUsdsFuturesRestAPI.NewOrderSideEnum`
- **说明**: 买卖方向
- **可选值**:
  - `BUY` - 买入
  - `SELL` - 卖出

### quantity

- **类型**: `number`
- **说明**: 订单数量
- **示例**: `0.001`, `1.5`

### price

- **类型**: `number`
- **说明**: 订单价格
- **示例**: `50000`, `3000.5`

## 可选参数

### type

- **类型**: `string`
- **默认值**: `'LIMIT'`
- **说明**: 订单类型
- **可选值**:
  - `LIMIT` - 限价单
  - `MARKET` - 市价单
  - `STOP` - 止损单
  - `STOP_MARKET` - 止损市价单
  - `TAKE_PROFIT` - 止盈单
  - `TAKE_PROFIT_MARKET` - 止盈市价单
  - `TRAILING_STOP_MARKET` - 追踪止损单

### timeInForce

- **类型**: `DerivativesTradingUsdsFuturesRestAPI.NewOrderTimeInForceEnum`
- **默认值**: `GTC`
- **说明**: 订单有效期
- **可选值**:
  - `GTC` - Good Till Cancel (一直有效直到取消)
    - 订单会一直有效，直到被手动取消或完全成交
    - 最常见的订单类型，适合长期挂单
  - `IOC` - Immediate or Cancel (立即成交或取消)
    - 订单必须立即成交，未成交的部分会被取消
    - 适合希望立即成交的场景
  - `FOK` - Fill or Kill (全部成交或取消)
    - 订单必须全部成交，否则整个订单会被取消
    - 适合不希望部分成交的大额订单
  - `GTX` - Good Till Crossing (有效直到穿越)
    - 订单在价格穿越指定价格时生效
    - 适合条件订单，如止损单
  - `GTD` - Good Till Date (有效直到指定日期)
    - 订单在指定日期前有效，过期后自动取消
    - 适合有时间限制的订单

### positionSide

- **类型**: `DerivativesTradingUsdsFuturesRestAPI.NewOrderPositionSideEnum`
- **说明**: 仓位方向
- **可选值**:
  - `BOTH` - 双向模式（默认）
  - `LONG` - 多头
  - `SHORT` - 空头

### reduceOnly

- **类型**: `string`
- **默认值**: `'false'`
- **说明**: 是否仅减仓
- **可选值**:
  - `'true'` - 仅减仓
  - `'false'` - 允许开仓和减仓

### closePosition

- **类型**: `string`
- **说明**: 是否平仓
- **可选值**:
  - `'true'` - 平仓
  - `'false'` - 不开仓也不平仓

### activationPrice

- **类型**: `number`
- **说明**: 激活价格（用于追踪止损单等）
- **示例**: `50000`

### callbackRate

- **类型**: `number`
- **说明**: 回调价格（用于追踪止损单等）
- **示例**: `0.1` (10%)

### workingType

- **类型**: `DerivativesTradingUsdsFuturesRestAPI.NewOrderWorkingTypeEnum`
- **说明**: 工作类型（用于追踪止损单等）
- **可选值**:
  - `MARK_PRICE` - 标记价格
  - `CONTRACT_PRICE` - 合约价格

### priceProtect

- **类型**: `string`
- **说明**: 价格保护
- **可选值**:
  - `'TRUE'` - 启用价格保护
  - `'FALSE'` - 禁用价格保护

### newOrderRespType

- **类型**: `DerivativesTradingUsdsFuturesRestAPI.NewOrderNewOrderRespTypeEnum`
- **说明**: 订单响应类型
- **可选值**:
  - `ACK` - 仅确认
  - `RESULT` - 返回结果
  - `FULL` - 返回完整信息

### newClientOrderId

- **类型**: `string`
- **说明**: 客户端订单ID（可选）
- **示例**: `'my_order_123'`

### stopPrice

- **类型**: `number`
- **说明**: 止损价格
- **示例**: `48000`

### icebergQty

- **类型**: `number`
- **说明**: 冰山订单显示数量
- **示例**: `0.1`

### orderTag

- **类型**: `string`
- **说明**: 订单标签
- **示例**: `'test_order'`

## 使用示例

### 基础限价单

```typescript
const result = await futureConnector.openPosition(
  'BTCUSDT',
  DerivativesTradingUsdsFuturesRestAPI.NewOrderSideEnum.BUY,
  0.001,
  50000,
)
```

### 市价单

```typescript
const result = await futureConnector.openPosition(
  'ETHUSDT',
  DerivativesTradingUsdsFuturesRestAPI.NewOrderSideEnum.SELL,
  0.01,
  0, // 市价单价格为0
  {
    type: 'MARKET',
  },
)
```

### 止损单

```typescript
const result = await futureConnector.openPosition(
  'BTCUSDT',
  DerivativesTradingUsdsFuturesRestAPI.NewOrderSideEnum.SELL,
  0.001,
  48000,
  {
    type: 'STOP_MARKET',
    stopPrice: 48000,
    reduceOnly: 'true',
  },
)
```

### 追踪止损单

```typescript
const result = await futureConnector.openPosition(
  'BTCUSDT',
  DerivativesTradingUsdsFuturesRestAPI.NewOrderSideEnum.SELL,
  0.001,
  0,
  {
    type: 'TRAILING_STOP_MARKET',
    activationPrice: 50000,
    callbackRate: 0.1,
    workingType: DerivativesTradingUsdsFuturesRestAPI.NewOrderWorkingTypeEnum.MARK_PRICE,
  },
)
```

### 带完整参数的单子

```typescript
const result = await futureConnector.openPosition(
  'BTCUSDT',
  DerivativesTradingUsdsFuturesRestAPI.NewOrderSideEnum.BUY,
  0.001,
  50000,
  {
    type: 'LIMIT',
    timeInForce: DerivativesTradingUsdsFuturesRestAPI.NewOrderTimeInForceEnum.GTC,
    positionSide: DerivativesTradingUsdsFuturesRestAPI.NewOrderPositionSideEnum.BOTH,
    reduceOnly: 'false',
    newOrderRespType: DerivativesTradingUsdsFuturesRestAPI.NewOrderNewOrderRespTypeEnum.RESULT,
    newClientOrderId: `order_${Date.now()}`,
    orderTag: 'my_order',
  },
)
```

## 注意事项

1. **API密钥**: 确保已正确设置 API_KEY 和 API_SECRET
2. **余额检查**: 下单前请确保账户有足够余额
3. **价格精度**: 注意交易对的价格精度要求
4. **数量精度**: 注意交易对的数量精度要求
5. **风险控制**: 建议在测试环境中先测试
6. **错误处理**: 方法会返回 null 如果下单失败

## 错误处理

方法内部已包含错误处理，如果下单失败会：

1. 在控制台输出错误信息
2. 返回 `null`
3. 不会抛出异常

建议在使用时添加额外的错误处理逻辑。