# 数据模型设计：凭证管理模块

**特性**：001-credential-manager
**日期**：2025-09-28
**状态**：Phase 1 - 数据模型设计

## 核心实体模型

### 1. Platform（平台）

**描述**：代表不同的交易平台，定义了特定的签名和认证规则。

**属性**：
- `id`: string - 平台唯一标识符
- `name`: string - 平台显示名称
- `signatureType`: SignatureType - 签名算法类型

**枚举值**：
```typescript
enum Platform {
  PACIFICA = 'pacifica',
  ASTER = 'aster',
  BINANCE = 'binance'
}

enum SignatureType {
  ED25519 = 'ed25519',
  ECDSA_ETHEREUM = 'ecdsa-ethereum',
  HMAC_SHA256 = 'hmac-sha256'
}
```

**验证规则**：
- id必须是有效的平台枚举值
- name不能为空
- signatureType必须与平台匹配

---

### 2. Account（账户）

**描述**：包含账户ID、平台类型、凭证信息的基本数据结构。

**属性**：
```typescript
interface Account {
  id: string;                    // 账户唯一ID
  platform: Platform;           // 所属平台
  credentials: Credentials;      // 凭证信息
  metadata?: {                   // 可选元数据
    alias?: string;              // 账户别名
    description?: string;        // 账户描述
    [key: string]: any;         // 其他自定义字段
  };
}
```

**凭证结构**：
```typescript
type Credentials = PacificaCredentials | AsterCredentials | BinanceCredentials;

interface PacificaCredentials {
  type: 'pacifica';
  privateKey: string;            // 64字符十六进制Ed25519私钥
}

interface AsterCredentials {
  type: 'aster';
  privateKey: string;            // 以太坊格式私钥
}

interface BinanceCredentials {
  type: 'binance';
  apiKey: string;               // API密钥
  secretKey: string;            // 密钥对
}
```

**验证规则**：
- id在所有账户中必须唯一
- platform必须是有效的Platform枚举值
- credentials类型必须与platform匹配
- Pacifica私钥必须是64字符十六进制字符串
- Aster私钥必须是以太坊格式（0x前缀）
- Binance API密钥不能为空

---

### 3. Signer（签名器）

**描述**：提供统一签名接口的组件，内部根据平台类型调用对应算法。

**接口定义**：
```typescript
interface Signer {
  // 统一签名接口
  sign(accountId: string, message: Uint8Array): Promise<SignResult>;

  // 验证签名
  verify(accountId: string, message: Uint8Array, signature: string): Promise<boolean>;

  // 获取账户信息
  getAccount(accountId: string): Account | null;

  // 列出所有账户
  listAccounts(): Account[];
}

interface SignResult {
  success: boolean;
  signature?: string;           // Base64编码的签名
  algorithm: string;           // 使用的签名算法
  timestamp: Date;             // 签名时间戳
  error?: string;              // 错误信息
}
```

**平台特定签名策略**：
```typescript
interface SignerStrategy {
  platform: Platform;
  sign(message: Uint8Array, credentials: Credentials): Promise<string>;
  verify(message: Uint8Array, signature: string, publicKey: string): Promise<boolean>;
}
```

---

### 4. ConfigLoader（配置加载器）

**描述**：负责从配置文件加载账户信息并监听文件变更。

**接口定义**：
```typescript
interface ConfigLoader {
  // 加载配置文件
  loadConfig(filePath: string): Promise<LoadResult>;

  // 开始监听文件变更
  watchConfig(filePath: string, callback: (accounts: Account[]) => void): void;

  // 停止监听
  stopWatching(): void;
}

interface LoadResult {
  success: boolean;
  accounts: Account[];
  errors?: string[];
  loadTime: number;            // 加载耗时（毫秒）
}
```

**配置文件格式**：
```typescript
interface ConfigFile {
  version: string;             // 配置文件版本
  accounts: AccountConfig[];
}

interface AccountConfig {
  id: string;
  platform: Platform;
  credentials: Credentials;
  metadata?: Record<string, any>;
}
```

---

## 实体关系图

```
ConfigLoader (1) ←→ (N) Account
    ↓
Account (N) ←→ (1) Signer
    ↓
Signer (1) ←→ (N) SignerStrategy
    ↓
SignerStrategy (N) ←→ (1) Platform
```

**关系说明**：
1. ConfigLoader加载多个Account
2. Signer管理多个Account
3. Signer使用多个SignerStrategy（按平台）
4. 每个SignerStrategy对应一个Platform

---

## 状态变化流程

### 配置文件生命周期
```
[文件创建] → [首次加载] → [监听变更] → [热重载] → [验证] → [更新内存]
     ↓         ↓          ↓         ↓        ↓         ↓
   CREATED → LOADING → WATCHING → RELOADING → VALIDATED → UPDATED
```

### 账户状态管理
```typescript
enum AccountStatus {
  LOADING = 'loading',      // 正在加载
  ACTIVE = 'active',        // 活跃可用
  ERROR = 'error',          // 错误状态
  REMOVED = 'removed'       // 已移除
}
```

**状态转换规则**：
- LOADING → ACTIVE：凭证验证成功
- ACTIVE → ERROR：签名失败或凭证无效
- ANY → REMOVED：从配置文件中删除
- ERROR → ACTIVE：问题解决后重新验证

---

## JSON配置格式

### 账户配置文件结构
```json
{
  "version": "1.0",
  "accounts": [
    {
      "id": "pacifica-main-001",
      "platform": "pacifica",
      "credentials": {
        "type": "pacifica",
        "privateKey": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab"
      },
      "metadata": {
        "alias": "Pacifica主账户",
        "description": "用于Pacifica交易的主要账户",
        "environment": "production"
      }
    },
    {
      "id": "binance-api-001",
      "platform": "binance",
      "credentials": {
        "type": "binance",
        "apiKey": "your_binance_api_key",
        "secretKey": "your_binance_secret_key"
      },
      "metadata": {
        "alias": "Binance API账户",
        "testnet": false
      }
    }
  ]
}
```

### JSON Schema验证
```typescript
const accountConfigSchema = {
  type: "object",
  properties: {
    version: { type: "string", pattern: "^\\d+\\.\\d+$" },
    accounts: {
      type: "array",
      items: {
        type: "object",
        properties: {
          id: { type: "string", minLength: 1 },
          platform: { enum: ["pacifica", "aster", "binance"] },
          credentials: {
            oneOf: [
              {
                properties: {
                  type: { const: "pacifica" },
                  privateKey: {
                    type: "string",
                    pattern: "^[0-9a-fA-F]{64}$"
                  }
                },
                required: ["type", "privateKey"]
              },
              {
                properties: {
                  type: { const: "binance" },
                  apiKey: { type: "string", minLength: 1 },
                  secretKey: { type: "string", minLength: 1 }
                },
                required: ["type", "apiKey", "secretKey"]
              }
              // 其他平台schema...
            ]
          }
        },
        required: ["id", "platform", "credentials"]
      }
    }
  },
  required: ["version", "accounts"]
};
```

---

## 性能要求映射

| 实体 | 性能要求 | 实现策略 |
|------|----------|----------|
| ConfigLoader | 加载<100ms | 异步文件读取 + JSON解析优化 |
| Signer | 签名<50ms | 内存缓存凭证 + 高性能签名库 |
| Account | 查询<10ms | 内存索引 + HashMap查找 |
| Platform识别 | 识别<1ms | 正则表达式预编译 + 优先级队列 |

---

## 错误处理模型

### 错误分类
```typescript
enum ErrorType {
  CONFIG_LOAD_ERROR = 'config_load_error',
  VALIDATION_ERROR = 'validation_error',
  SIGNATURE_ERROR = 'signature_error',
  PLATFORM_DETECTION_ERROR = 'platform_detection_error'
}

interface CredentialError {
  type: ErrorType;
  message: string;
  accountId?: string;
  timestamp: Date;
  details?: any;
}
```

### 错误处理策略
- **配置加载错误**：记录错误，跳过无效账户，继续加载其他账户
- **验证错误**：标记账户为ERROR状态，不影响其他账户
- **签名错误**：返回错误结果，记录日志，不影响后续操作
- **平台识别错误**：使用默认策略或手动指定平台

---

**Phase 1.1 状态**：✅ 数据模型设计完成
**下一步**：生成API契约定义