# Pacifica凭据管理服务

## 🎯 概述

专注于**Pacifica平台**的内部凭据管理系统，提供Ed25519签名服务供项目内部其他模块调用。

**核心特性**：
- ✅ **单一职责**: 专注于凭据分类管理和签名服务
- ✅ **内部调用**: 供项目内部模块使用，非HTTP API
- ✅ **高性能**: Ed25519签名 <50ms 响应时间
- ✅ **热重载**: 配置文件变化自动检测和重载
- ✅ **类型安全**: 完整的TypeScript类型定义

## 📦 快速开始

### 1. 配置文件设置

创建 `credentials.json` 配置文件：

```json
{
  "pacifica": [
    {
      "accountId": "pac-main-001",
      "alias": "Pacifica主账户",
      "privateKey": "your_base58_private_key_here",
      "environment": "production"
    },
    {
      "accountId": "pac-dev-001",
      "alias": "Pacifica开发账户",
      "privateKey": "your_development_private_key_here",
      "environment": "development"
    }
  ]
}
```

### 2. 基本使用

```typescript
import { signPacifica, hasPacificaAccount } from './src/services/index.js';

// 检查账户是否存在
if (hasPacificaAccount('pac-main-001')) {

  // 执行签名
  const result = await signPacifica('pac-main-001', {
    instruction: {
      type: 'place_order',
      market: 'BTC-USD',
      side: 'bid',
      amount: '0.001',
      price: '65000'
    },
    nonce: Date.now()
  });

  console.log('签名:', result.signature);
  console.log('公钥:', result.publicKey);
}
```

## 🔧 API 参考

### 便捷函数

#### `signPacifica(accountId, data)`
执行单次Pacifica签名

```typescript
import { signPacifica, PacificaSignData } from './src/services/index.js';

const signData: PacificaSignData = {
  instruction: {
    type: 'place_order',
    market: 'BTC-USD',
    side: 'bid',
    amount: '0.001',
    price: '65000'
  },
  nonce: Date.now()
};

const result = await signPacifica('pac-main-001', signData);
```

#### `signPacificaBatch(requests)`
执行批量Pacifica签名

```typescript
import { signPacificaBatch } from './src/services/index.js';

const requests = [
  {
    accountId: 'pac-main-001',
    requestId: 'order_1',
    data: { instruction: { type: 'place_order' } }
  },
  {
    accountId: 'pac-main-002',
    requestId: 'order_2',
    data: { instruction: { type: 'cancel_order' } }
  }
];

const results = await signPacificaBatch(requests);
```

#### `hasPacificaAccount(accountId)`
检查账户是否存在

```typescript
import { hasPacificaAccount } from './src/services/index.js';

if (hasPacificaAccount('pac-main-001')) {
  console.log('账户存在');
}
```

#### `getPacificaPublicKey(accountId)`
获取账户公钥

```typescript
import { getPacificaPublicKey } from './src/services/index.js';

const publicKey = getPacificaPublicKey('pac-main-001');
console.log('公钥:', publicKey);
```

### 高级用法

#### 直接使用服务实例

```typescript
import { getCredentialService } from './src/services/index.js';

const service = getCredentialService();

// 获取服务状态
const status = service.getStatus();
console.log('Pacifica账户数:', status.pacificaAccounts);

// 获取所有账户
const accounts = service.getPacificaAccounts();

// 监听事件
service.on('signature:success', (event) => {
  console.log(`签名成功: ${event.accountId}`);
});

service.on('signature:error', (event) => {
  console.log(`签名失败: ${event.accountId} - ${event.error}`);
});
```

## 🏗️ 在交易模块中的集成

### 示例：交易模块

```typescript
import { signPacifica, hasPacificaAccount } from './src/services/index.js';

class TradingModule {
  async placeOrder(accountId: string, market: string, side: 'bid' | 'ask', amount: string, price: string) {
    // 1. 检查账户
    if (!hasPacificaAccount(accountId)) {
      throw new Error(`账户 ${accountId} 不可用`);
    }

    // 2. 构建订单数据
    const orderData = {
      instruction: {
        type: 'place_order',
        market,
        side,
        amount,
        price
      },
      nonce: Date.now()
    };

    // 3. 执行签名
    const signatureResult = await signPacifica(accountId, orderData);

    // 4. 提交到Pacifica交易所
    return this.submitToPacifica(signatureResult);
  }
}
```

### 示例：对冲交易

```typescript
import { signPacificaBatch } from './src/services/index.js';

async function hedgeTrade(account1: string, account2: string, market: string, amount: string) {
  const requests = [
    {
      accountId: account1,
      requestId: 'long_position',
      data: {
        instruction: {
          type: 'place_order',
          market,
          side: 'bid',
          amount
        }
      }
    },
    {
      accountId: account2,
      requestId: 'short_position',
      data: {
        instruction: {
          type: 'place_order',
          market,
          side: 'ask',
          amount
        }
      }
    }
  ];

  const results = await signPacificaBatch(requests);

  // 处理结果...
}
```

## 📋 支持的订单类型

Pacifica签名适配器支持以下订单类型：

- `place_order` - 下单
- `cancel_order` - 撤单
- `modify_order` - 修改订单
- `close_position` - 平仓

## 🧪 测试

```bash
# 运行单元测试
npx jest __tests__/unit/pacifica-signature.test.ts
npx jest __tests__/unit/internal-credential-service.test.ts

# 运行使用示例
npx tsx examples/credential-usage.ts
```

## 📄 文件结构

```
src/
├── services/
│   ├── index.ts                    # 统一导出
│   └── credential-service.ts       # 内部凭据服务
├── core/
│   ├── config-loader.ts           # 配置加载器
│   └── signature-adapters/
│       └── pacifica.ts            # Pacifica签名适配器
└── shared/
    ├── credential-types.ts        # 类型定义
    ├── credential-constants.ts    # 常量
    └── credential-utils.ts        # 工具函数

examples/
└── credential-usage.ts           # 使用示例

__tests__/
├── unit/
│   ├── pacifica-signature.test.ts
│   └── internal-credential-service.test.ts
└── fixtures/
    └── test-credentials.json     # 测试配置
```

## 🚀 性能特性

- ✅ **单次签名**: <50ms 响应时间
- ✅ **批量签名**: 平均每个签名 <50ms
- ✅ **内存管理**: 自动清理敏感数据
- ✅ **热重载**: <5秒配置重载时间
- ✅ **并发安全**: 支持多线程并发调用

## 🔒 安全特性

- ✅ **私钥保护**: 内存中加密存储，自动清理
- ✅ **日志脱敏**: 敏感信息自动脱敏
- ✅ **类型验证**: 严格的输入验证和类型检查
- ✅ **错误隔离**: 详细的错误分类和处理

## 📝 注意事项

1. **配置文件**: 请确保 `credentials.json` 存在且包含有效的Pacifica账户
2. **私钥格式**: 必须是44字符的base58编码Ed25519私钥
3. **环境隔离**: development和production环境账户分离管理
4. **性能监控**: 建议监控签名执行时间，超过50ms时检查系统负载

## 🔗 相关文档

- [Pacifica API文档](docs/PACIFICA_API_REFERENCE.md)
- [技术设计文档](specs/002-/plan.md)
- [数据模型说明](specs/002-/data-model.md)