# 账户注入系统

## 概述

账户注入系统提供了多种灵活的方式来动态配置和管理多个交易所账户，支持配置文件、命令行参数、环境变量等多种配置源。

## 支持的注入方式

### 1. JSON 配置文件注入 (推荐)

最灵活和结构化的账户配置方式。

#### 配置文件格式

创建 `accounts.config.json` 文件：

```json
{
  "metadata": {
    "version": "1.0",
    "description": "多交易所账户配置",
    "lastUpdated": "2024-01-01T00:00:00Z"
  },
  "defaults": {
    "maxPositionUsd": 1000,
    "maxDailyVolumeUsd": 10000,
    "tradingEnabled": true,
    "hedgingEnabled": true
  },
  "accounts": [
    {
      "name": "pacifica-main",
      "exchange": "pacifica",
      "accountId": "main-account-1",
      "alias": "Pacifica主账户",
      "enabled": true,
      "priority": 1,
      "tradingEnabled": true,
      "hedgingEnabled": true,
      "maxPositionUsd": 10000,
      "maxDailyVolumeUsd": 100000,
      "auth": {
        "privateKeyEnv": "PACIFICA_PRIVATE_KEY_1",
        "accountIdEnv": "PACIFICA_ACCOUNT_1"
      },
      "riskLimits": {
        "maxDrawdownPercent": 10,
        "maxConsecutiveLosses": 5,
        "dailyLossLimitUsd": 1000
      }
    },
    {
      "name": "aster-hedge",
      "exchange": "aster",
      "accountId": "hedge-account-1",
      "alias": "Aster对冲账户",
      "enabled": true,
      "priority": 2,
      "tradingEnabled": true,
      "hedgingEnabled": true,
      "maxPositionUsd": 20000,
      "maxDailyVolumeUsd": 200000,
      "auth": {
        "userEnv": "ASTER_ORDER_USER_1",
        "signerEnv": "ASTER_ORDER_SIGNER_1",
        "privateKeyEnv": "ASTER_PRIVATE_KEY_1"
      }
    },
    {
      "name": "binance-spot",
      "exchange": "binance",
      "accountId": "spot-account-1",
      "alias": "Binance现货账户",
      "enabled": false,
      "priority": 3,
      "tradingEnabled": false,
      "hedgingEnabled": false,
      "auth": {
        "apiKeyEnv": "BINANCE_API_KEY_1",
        "apiSecretEnv": "BINANCE_SECRET_KEY_1"
      }
    }
  ],
  "hedgingGroups": [
    {
      "name": "cross-dex-hedge",
      "strategy": "delta-neutral",
      "accounts": ["pacifica-main", "aster-hedge"],
      "maxExposureUsd": 50000,
      "enabled": true,
      "rebalanceIntervalMs": 30000,
      "minHedgeRatio": 0.8,
      "maxHedgeRatio": 1.2
    }
  ],
  "tradingRules": [
    {
      "name": "conservative-trading",
      "accounts": ["pacifica-main"],
      "symbols": ["BTC-PERP", "ETH-PERP"],
      "enabled": true,
      "minOrderSizeUsd": 10,
      "maxOrderSizeUsd": 1000,
      "maxSlippage": 0.005,
      "cooldownMs": 5000
    }
  ]
}
```

#### 使用方法

```bash
# 运行配置文件演示
yarn demo:config-accounts

# 查看配置文件格式帮助
yarn demo:config-accounts --help
```

#### 代码示例

```typescript
import { AccountConfigLoader } from '../src/accounts/AccountConfigLoader'

// 1. 创建配置加载器
const configLoader = new AccountConfigLoader('./accounts.config.json')

// 2. 加载配置
const config = configLoader.load()

// 3. 获取启用的账户
const enabledAccounts = configLoader.getEnabledAccounts()

// 4. 转换为账户配置格式
const accountConfigs = configLoader.convertToAccountConfigs(enabledAccounts)

// 5. 监听配置文件变更 (可选)
configLoader.on('config_changed', (newConfig, oldConfig) => {
  console.log('配置文件已更新')
  // 重新加载账户
})

configLoader.startWatching()
```

### 2. 命令行参数注入

适合快速测试和单个账户场景。

#### 参数说明

| 参数             | 简写 | 说明              | 默认值           |
| ---------------- | ---- | ----------------- | ---------------- |
| `--exchange`     | `-e` | 交易所类型 (必需) | -                |
| `--account`      | `-a` | 账户ID            | `cli-account`    |
| `--alias`        | -    | 账户别名          | `CLI-<exchange>` |
| `--priority`     | `-p` | 优先级            | `999`            |
| `--trading`      | -    | 是否启用交易      | `true`           |
| `--hedging`      | -    | 是否启用对冲      | `true`           |
| `--max-position` | -    | 最大仓位USD       | `1000`           |
| `--config`       | `-c` | 配置文件路径      | -                |
| `--dry-run`      | -    | 干运行模式        | `false`          |

#### 使用示例

```bash
# 基本账户注入
tsx examples/cli_account_injection.ts --exchange pacifica

# 完整参数注入
tsx examples/cli_account_injection.ts \
  --exchange pacifica \
  --account main-account \
  --alias "我的Pacifica账户" \
  --priority 1 \
  --trading true \
  --hedging true \
  --max-position 5000 \
  --verbose

# 干运行模式 (不实际连接)
tsx examples/cli_account_injection.ts \
  --exchange aster \
  --dry-run
```

#### 代码示例

```typescript
import { CLIAccountInjector } from '../src/accounts/CLIAccountInjector'

// 1. 解析命令行参数
const cliOptions = CLIAccountInjector.parseArgs()

// 2. 创建账户配置
const accountConfig = CLIAccountInjector.createQuickAccount()

// 3. 使用配置
console.log('生成的账户配置:', accountConfig)
```

### 3. 环境变量注入

通过环境变量直接注入账户信息。

#### 环境变量格式

```bash
# 基础配置
ACCOUNT_INJECTION_METHOD=env
DEFAULT_EXCHANGE=pacifica
DEFAULT_ACCOUNT_ID=main-1

# Pacifica 账户
PACIFICA_PRIVATE_KEY_1=base58_private_key_1
PACIFICA_ACCOUNT_1=account_id_1
PACIFICA_PRIVATE_KEY_2=base58_private_key_2
PACIFICA_ACCOUNT_2=account_id_2

# Aster 账户
ASTER_ORDER_USER_1=0x...
ASTER_ORDER_SIGNER_1=0x...
ASTER_PRIVATE_KEY_1=0x...

# Binance 账户
BINANCE_API_KEY_1=api_key_1
BINANCE_SECRET_KEY_1=secret_key_1
```

### 4. 自动发现注入

系统自动扫描环境变量并发现可用账户。

```typescript
import { AutoDiscoveryProvider } from '../src/accounts/providers/AutoDiscoveryProvider'

// 自动发现账户
const discoveryProvider = new AutoDiscoveryProvider()
const discoveredAccounts = await discoveryProvider.discoverAccounts()

console.log(`发现 ${discoveredAccounts.length} 个账户`)
```

## 注入器类详解

### AccountConfigLoader

负责JSON配置文件的加载和监控。

```typescript
export class AccountConfigLoader extends EventEmitter {
  // 检查配置文件是否存在
  exists(): boolean

  // 加载配置文件
  load(): AccountConfig

  // 获取启用的账户
  getEnabledAccounts(): AccountEntry[]

  // 转换为统一账户配置格式
  convertToAccountConfigs(accounts: AccountEntry[]): UnifiedAccountConfig[]

  // 启动文件监控
  startWatching(): void

  // 停止文件监控
  stopWatching(): void
}
```

### CLIAccountInjector

处理命令行参数解析和账户配置生成。

```typescript
export class CLIAccountInjector {
  // 解析命令行参数
  static parseArgs(): CLIAccountOptions

  // 创建快速账户配置
  static createQuickAccount(): QuickAccountConfig
}
```

### AutoDiscoveryProvider

自动发现环境中可用的账户配置。

```typescript
export class AutoDiscoveryProvider {
  // 发现可用账户
  async discoverAccounts(): Promise<DiscoveredAccount[]>

  // 验证账户配置
  validateAccountConfig(account: DiscoveredAccount): ValidationResult
}
```

## 最佳实践

### 1. 生产环境配置

```json
{
  "accounts": [
    {
      "name": "prod-pacifica-main",
      "exchange": "pacifica",
      "enabled": true,
      "priority": 1,
      "maxPositionUsd": 50000,
      "riskLimits": {
        "maxDrawdownPercent": 5,
        "dailyLossLimitUsd": 5000
      }
    }
  ],
  "hedgingGroups": [
    {
      "name": "prod-hedge-group",
      "enabled": true,
      "maxExposureUsd": 100000
    }
  ]
}
```

### 2. 开发环境配置

```json
{
  "accounts": [
    {
      "name": "dev-pacifica-test",
      "exchange": "pacifica",
      "enabled": true,
      "maxPositionUsd": 100,
      "tradingEnabled": false
    }
  ]
}
```

### 3. 安全考虑

- **环境变量隔离**: 不同环境使用不同的环境变量后缀
- **最小权限**: 只给必需的账户启用交易权限
- **监控审计**: 记录所有账户配置变更
- **密钥轮换**: 定期更新API密钥和私钥

### 4. 错误处理

```typescript
try {
  const configLoader = new AccountConfigLoader('./accounts.config.json')
  const config = configLoader.load()
} catch (error) {
  if (error.code === 'ENOENT') {
    console.error('配置文件不存在')
  } else if (error instanceof SyntaxError) {
    console.error('配置文件格式错误')
  } else {
    console.error('未知错误:', error)
  }
}
```

### 5. 配置验证

```typescript
import { validateAccountConfig } from '../src/accounts/validators'

const validation = validateAccountConfig(accountConfig)
if (!validation.isValid) {
  console.error('配置验证失败:', validation.errors)
  return
}

if (validation.warnings.length > 0) {
  console.warn('配置警告:', validation.warnings)
}
```

## 故障排除

### 常见问题

1. **配置文件不存在**

   - 确保 `accounts.config.json` 文件存在
   - 检查文件路径是否正确

2. **环境变量未设置**

   - 检查 `.env` 文件
   - 确认环境变量名称正确

3. **权限不足**

   - 检查账户是否启用了交易权限
   - 确认API密钥有足够权限

4. **网络连接问题**
   - 检查交易所API端点是否可访问
   - 确认防火墙设置

### 调试模式

```bash
# 启用详细日志
LOG_LEVEL=debug tsx examples/config_file_account_injection.ts

# 干运行模式
tsx examples/cli_account_injection.ts --exchange pacifica --dry-run --verbose
```

## 示例文件

系统提供了完整的示例文件：

- `examples/config_file_account_injection.ts` - 配置文件注入演示
- `examples/cli_account_injection.ts` - 命令行注入演示
- `examples/elegant_account_injection.ts` - 优雅账户注入演示
- `examples/unified_account_manager_demo.ts` - 统一账户管理演示

运行示例：

```bash
# 配置文件演示
yarn demo:config-accounts

# CLI 注入演示
tsx examples/cli_account_injection.ts --help

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