# 快速开始：凭证管理模块

**特性**：001-credential-manager
**版本**：v1.0.0
**状态**：Phase 1 - 快速开始指南

## 概述

凭证管理模块提供简化的多平台账户管理，支持配置文件热加载、智能平台识别和统一签名接口。

## 安装和配置

### 1. 模块集成

```bash
# 凭证管理模块已集成到现有代码库
# 无需单独安装，直接在 src/core/credential-manager/ 目录下实现
```

### 2. 基础配置

创建账户配置文件 `config/accounts.json`：

```json
{
  "version": "1.0",
  "accounts": [
    {
      "id": "pacifica-main-001",
      "platform": "pacifica",
      "credentials": {
        "type": "pacifica",
        "privateKey": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab"
      },
      "metadata": {
        "alias": "Pacifica主账户",
        "description": "用于Pacifica交易的主要账户"
      }
    },
    {
      "id": "binance-api-001",
      "platform": "binance",
      "credentials": {
        "type": "binance",
        "apiKey": "your_binance_api_key",
        "secretKey": "your_binance_secret_key"
      },
      "metadata": {
        "alias": "Binance API账户"
      }
    }
  ]
}
```

## 快速开始示例

### 示例1：基础使用

```typescript
import { CredentialManagerFactory } from '@/core/credential-manager';

async function basicUsage() {
  // 1. 创建凭证管理器
  const factory = new CredentialManagerFactory();
  const manager = await factory.create({
    enableFileWatching: true,
    enableLogging: true
  });

  // 2. 加载配置文件
  const result = await manager.loadConfig('./config/accounts.json');
  console.log(`加载成功: ${result.accounts.length} 个账户`);

  // 3. 列出所有账户
  const accounts = manager.listAccounts();
  accounts.forEach(account => {
    console.log(`账户: ${account.id} (${account.platform})`);
  });

  // 4. 获取特定账户
  const account = manager.getAccount('pacifica-main-001');
  if (account) {
    console.log(`找到账户: ${account.metadata?.alias}`);
  }

  return manager;
}
```

### 示例2：签名操作

```typescript
async function signingExample(manager) {
  // 1. 准备要签名的消息
  const message = new TextEncoder().encode('Hello, Pacifica!');

  // 2. 执行签名 (系统自动识别平台类型)
  const signResult = await manager.sign('pacifica-main-001', message);

  if (signResult.success) {
    console.log('签名成功:', {
      signature: signResult.signature,
      algorithm: signResult.algorithm,
      timestamp: signResult.timestamp
    });

    // 3. 验证签名
    const isValid = await manager.verify('pacifica-main-001', message, signResult.signature!);
    console.log('签名验证:', isValid ? '通过' : '失败');
  } else {
    console.error('签名失败:', signResult.error);
  }

  return signResult;
}
```

### 示例3：热加载监听

```typescript
async function hotReloadExample(manager) {
  // 1. 开始监听配置文件变更
  manager.watchConfig('./config/accounts.json', (accounts) => {
    console.log(`配置文件已更新，重新加载了 ${accounts.length} 个账户`);

    accounts.forEach(account => {
      console.log(`- ${account.id}: ${account.platform} (${account.status})`);
    });
  });

  console.log('开始监听配置文件变更...');
  console.log('现在可以修改 accounts.json 文件来测试热加载功能');

  // 2. 模拟运行一段时间
  await new Promise(resolve => setTimeout(resolve, 30000));

  // 3. 停止监听
  manager.stopWatching();
  console.log('停止监听配置文件变更');
}
```

### 示例4：多平台签名

```typescript
async function multiPlatformExample(manager) {
  const testMessage = new TextEncoder().encode('多平台测试消息');

  // 获取所有账户并按平台分组
  const accounts = manager.listAccounts();
  const platformGroups = accounts.reduce((groups, account) => {
    if (!groups[account.platform]) {
      groups[account.platform] = [];
    }
    groups[account.platform].push(account);
    return groups;
  }, {} as Record<string, any[]>);

  // 为每个平台的每个账户执行签名
  for (const [platform, platformAccounts] of Object.entries(platformGroups)) {
    console.log(`\n=== ${platform.toUpperCase()} 平台签名测试 ===`);

    for (const account of platformAccounts) {
      try {
        const startTime = Date.now();
        const result = await manager.sign(account.id, testMessage);
        const duration = Date.now() - startTime;

        if (result.success) {
          console.log(`✅ ${account.id}: 签名成功 (${duration}ms)`);
          console.log(`   算法: ${result.algorithm}`);
          console.log(`   签名: ${result.signature?.substring(0, 20)}...`);
        } else {
          console.log(`❌ ${account.id}: 签名失败 - ${result.error}`);
        }
      } catch (error) {
        console.log(`💥 ${account.id}: 签名异常 - ${error.message}`);
      }
    }
  }
}
```

## 完整集成测试

### 集成测试脚本

创建 `test-credential-manager.ts` 文件：

```typescript
import { CredentialManagerFactory } from '@/core/credential-manager';

async function runIntegrationTests() {
  console.log('🚀 开始凭证管理模块集成测试...\n');

  try {
    // 测试1: 基础使用
    console.log('📋 测试1: 基础使用');
    const manager = await basicUsage();
    console.log('✅ 基础使用测试通过\n');

    // 测试2: 签名操作
    console.log('🔐 测试2: 签名操作');
    const signResult = await signingExample(manager);
    console.log('✅ 签名操作测试通过\n');

    // 测试3: 多平台签名
    console.log('🌐 测试3: 多平台签名');
    await multiPlatformExample(manager);
    console.log('✅ 多平台签名测试通过\n');

    // 测试4: 性能测试
    console.log('⚡ 测试4: 性能测试');
    await performanceTest(manager);
    console.log('✅ 性能测试通过\n');

    console.log('🎉 所有集成测试通过！');

  } catch (error) {
    console.error('❌ 集成测试失败:', error);
    process.exit(1);
  }
}

async function performanceTest(manager) {
  const message = new TextEncoder().encode('性能测试消息');
  const iterations = 10;

  // 测试签名性能
  console.log(`执行 ${iterations} 次签名操作...`);
  const startTime = Date.now();

  const promises = Array.from({ length: iterations }, async (_, i) => {
    const result = await manager.sign('pacifica-main-001', message);
    return {
      iteration: i + 1,
      success: result.success,
      duration: Date.now() - startTime
    };
  });

  const results = await Promise.all(promises);
  const totalTime = Date.now() - startTime;
  const averageTime = totalTime / iterations;

  console.log(`性能测试结果:`);
  console.log(`- 总时间: ${totalTime}ms`);
  console.log(`- 平均时间: ${averageTime.toFixed(2)}ms`);
  console.log(`- 成功率: ${results.filter(r => r.success).length}/${iterations}`);

  // 验证性能要求
  if (averageTime > 50) {
    throw new Error(`签名性能不满足要求: ${averageTime}ms > 50ms`);
  }
}

// 运行测试
if (require.main === module) {
  runIntegrationTests();
}

export { runIntegrationTests };
```

## 运行测试

```bash
# 运行集成测试
npx tsx test-credential-manager.ts

# 使用Jest运行测试套件
npm test -- --testPathPattern=credential-manager

# 运行性能测试
npm run test:performance
```

## 配置文件示例

### 完整配置示例

```json
{
  "version": "1.0",
  "accounts": [
    {
      "id": "pacifica-main-001",
      "platform": "pacifica",
      "credentials": {
        "type": "pacifica",
        "privateKey": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
      },
      "metadata": {
        "alias": "Pacifica主账户",
        "description": "主要用于Pacifica交易",
        "environment": "production",
        "maxDailyVolume": 100000
      }
    },
    {
      "id": "aster-test-001",
      "platform": "aster",
      "credentials": {
        "type": "aster",
        "privateKey": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12"
      },
      "metadata": {
        "alias": "Aster测试账户",
        "testnet": true
      }
    },
    {
      "id": "binance-api-001",
      "platform": "binance",
      "credentials": {
        "type": "binance",
        "apiKey": "your_binance_api_key_here",
        "secretKey": "your_binance_secret_key_here"
      },
      "metadata": {
        "alias": "Binance现货账户",
        "testnet": false,
        "permissions": ["SPOT"]
      }
    }
  ]
}
```

## 故障排除

### 常见问题

**问题1: 配置文件加载失败**
```
错误: CONFIG_LOAD_ERROR - 无法读取配置文件
解决: 检查文件路径和权限，确保JSON格式正确
```

**问题2: 平台识别失败**
```
错误: PLATFORM_DETECTION_ERROR - 无法识别平台类型
解决: 检查credentials格式，确保符合平台要求
```

**问题3: 签名操作超时**
```
错误: SIGNATURE_ERROR - 签名操作超时
解决: 增加签名超时时间或检查凭证有效性
```

### 调试模式

启用详细日志：

```typescript
const manager = await factory.create({
  enableLogging: true,
  logLevel: 'debug'
});
```

## API参考

### 主要接口

- `ICredentialManager`: 主要凭证管理接口
- `loadConfig(path)`: 加载配置文件
- `watchConfig(path, callback)`: 监听文件变更
- `sign(accountId, message)`: 执行签名
- `verify(accountId, message, signature)`: 验证签名
- `getAccount(accountId)`: 获取账户信息
- `listAccounts()`: 列出所有账户

### 配置选项

- `enableFileWatching`: 启用文件监听（默认: true）
- `signTimeout`: 签名超时时间（默认: 30000ms）
- `enableLogging`: 启用日志记录（默认: true）
- `logLevel`: 日志级别（默认: 'info'）

## 下一步

1. **集成到主系统**: 将凭证管理器集成到您的交易系统中
2. **添加更多平台**: 根据需要实现其他平台支持
3. **监控和日志**: 设置日志分析和监控
4. **性能优化**: 根据实际使用情况调整性能参数

---

**开发状态**: ✅ Phase 1 完成 - 快速开始指南
**下一阶段**: Phase 2 - 任务生成 (运行 `/tasks` 命令)