binance-api/specs/001-credential-manager/data-model.md

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

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

核心实体模型

1. Platform（平台）

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

属性：

• id: string - 平台唯一标识符
• name: string - 平台显示名称
• signatureType: SignatureType - 签名算法类型

枚举值：

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、平台类型、凭证信息的基本数据结构。

属性：

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

凭证结构：

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（签名器）

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

接口定义：

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;              // 错误信息
}

平台特定签名策略：

interface SignerStrategy {
  platform: Platform;
  sign(message: Uint8Array, credentials: Credentials): Promise<string>;
  verify(message: Uint8Array, signature: string, publicKey: string): Promise<boolean>;
}

---

4. ConfigLoader（配置加载器）

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

接口定义：

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;            // 加载耗时（毫秒）
}

配置文件格式：

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

账户状态管理

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

状态转换规则：

• LOADING → ACTIVE：凭证验证成功
• ACTIVE → ERROR：签名失败或凭证无效
• ANY → REMOVED：从配置文件中删除
• ERROR → ACTIVE：问题解决后重新验证

---

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验证

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	正则表达式预编译 + 优先级队列

---

错误处理模型

错误分类

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契约定义