binance-api/specs/002-credential-manager/quickstart.md

Quickstart 测试指南：多平台账户凭据管理与签名服务

前置条件

1. 已安装 Node.js 18.12+ 和必要的依赖包
2. 准备测试用的配置文件 credentials.test.json
3. 已配置测试环境的API密钥和私钥
4. 服务运行在测试模式，不影响生产数据

---

场景 1：配置文件加载与账户注入

1.1 配置文件准备

创建测试配置文件 credentials.test.json：

{
  "pacifica": [
    {
      "accountId": "pac-test-001",
      "alias": "Pacifica测试账户",
      "privateKey": "test_base58_private_key_here",
      "environment": "development"
    }
  ],
  "aster": [
    {
      "accountId": "ast-test-001",
      "alias": "Aster测试账户",
      "ethPrivateKey": "0xtest_ethereum_private_key",
      "signerAddress": "0xtest_signer_address",
      "environment": "development"
    }
  ],
  "binance": [
    {
      "accountId": "bn-test-001",
      "alias": "Binance测试账户",
      "apiKey": "test_api_key",
      "secretKey": "test_secret_key",
      "environment": "development"
    }
  ]
}

1.2 启动服务并加载配置

# 启动签名服务
npm run start:credential-service -- --config ./credentials.test.json

# 验证服务状态
curl -X GET "http://localhost:3000/api/v1/status"

验证

• 日志显示 配置加载成功: 3个平台, 3个账户
• API响应中显示正确的账户数量
• 所有平台状态为 active

---

场景 2：Pacifica Ed25519 签名测试

2.1 执行Pacifica签名请求

curl -X POST "http://localhost:3000/api/v1/sign" \
  -H "Content-Type: application/json" \
  -d '{
    "platformId": "pacifica",
    "accountId": "pac-test-001",
    "data": {
      "instruction": {
        "type": "place_order",
        "market": "BTC-USD",
        "side": "bid",
        "amount": "0.001",
        "price": "65000"
      },
      "nonce": 1735390800000
    }
  }'

验证

• 响应包含 signature 字段，base58编码
• algorithm 字段为 "ed25519"
• publicKey 字段正确派生
• 签名时间 < 50ms

---

场景 3：Aster EIP-191 签名测试

3.1 执行Aster签名请求

curl -X POST "http://localhost:3000/api/v1/sign" \
  -H "Content-Type: application/json" \
  -d '{
    "platformId": "aster",
    "accountId": "ast-test-001",
    "data": {
      "message": {
        "action": "place_order",
        "symbol": "BTCUSDT",
        "price": "65000",
        "quantity": "0.001",
        "side": "buy",
        "timestamp": 1735390800000
      }
    }
  }'

验证

• 响应包含 signature 字段，0x开头的十六进制
• algorithm 字段为 "eip191"
• 可通过ethers.js验证签名者地址

---

场景 4：Binance HMAC 签名测试

4.1 执行Binance签名请求

curl -X POST "http://localhost:3000/api/v1/sign" \
  -H "Content-Type: application/json" \
  -d '{
    "platformId": "binance",
    "accountId": "bn-test-001",
    "data": {
      "method": "POST",
      "endpoint": "/api/v3/order",
      "params": {
        "symbol": "BTCUSDT",
        "side": "BUY",
        "type": "LIMIT",
        "quantity": "0.001",
        "price": "65000",
        "timestamp": 1735390800000
      }
    }
  }'

验证

• 响应包含 signature 字段，HMAC-SHA256哈希
• algorithm 字段为 "hmac-sha256"
• 签名可用于Binance API认证

---

场景 5：配置热重载测试

5.1 修改配置文件

在 credentials.test.json 中添加新账户：

{
  "okx": [
    {
      "accountId": "okx-test-001",
      "alias": "OKX测试账户",
      "apiKey": "test_okx_api_key",
      "secretKey": "test_okx_secret",
      "passphrase": "test_passphrase",
      "environment": "development"
    }
  ]
}

5.2 触发热重载

curl -X POST "http://localhost:3000/api/v1/config/reload"

验证

• 响应显示 changes.added = 1
• 新增的OKX账户可查询到
• 重载时间 < 5秒
• 服务无中断

---

场景 6：批量签名测试

6.1 执行批量签名请求

curl -X POST "http://localhost:3000/api/v1/sign/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "requestId": "req_001",
        "platformId": "pacifica",
        "accountId": "pac-test-001",
        "data": {"instruction": {"type": "place_order"}}
      },
      {
        "requestId": "req_002",
        "platformId": "aster",
        "accountId": "ast-test-001",
        "data": {"message": {"action": "cancel_order"}}
      }
    ]
  }'

验证

• 响应包含 results 数组，每个请求一个结果
• summary 显示成功/失败统计
• 批量处理时间 < 200ms

---

场景 7：故障恢复测试

7.1 模拟配置损坏

# 备份原配置
cp credentials.test.json credentials.backup.json

# 创建无效配置
echo "invalid json" > credentials.test.json

# 尝试重载
curl -X POST "http://localhost:3000/api/v1/config/reload"

7.2 验证错误处理

# 检查服务状态
curl -X GET "http://localhost:3000/api/v1/status"

# 尝试签名（应该仍可用，使用旧配置）
curl -X POST "http://localhost:3000/api/v1/sign" \
  -H "Content-Type: application/json" \
  -d '{
    "platformId": "pacifica",
    "accountId": "pac-test-001",
    "data": {"test": "data"}
  }'

7.3 恢复配置

# 恢复有效配置
cp credentials.backup.json credentials.test.json

# 重新加载
curl -X POST "http://localhost:3000/api/v1/config/reload"

验证

• 配置损坏时返回错误 CONFIG_LOAD_FAILED
• 服务保持运行，使用最后有效配置
• 恢复后正常工作

清理步骤

1. 停止服务

# 停止签名服务
pkill -f credential-service

# 或使用npm脚本
npm run stop

2. 清理测试数据

# 删除测试配置文件
rm credentials.test.json credentials.backup.json

# 清理日志文件
rm -rf logs/test_*

---

预期结果汇总

测试场景	成功标准	性能要求
配置加载	4个平台账户成功加载	< 1秒
Pacifica签名	Ed25519签名成功	< 50ms
Aster签名	EIP-191签名成功	< 50ms
Binance签名	HMAC-SHA256签名成功	< 50ms
配置热重载	新配置生效，服务无中断	< 5秒
批量签名	并发处理正确	< 200ms
故障恢复	错误处理正确，服务稳定	降级运行

总体验收标准：

• 所有测试场景通过率 100%
• 单次签名延迟 < 50ms
• 配置热重载无服务中断
• 错误处理机制完善
• 支持4个平台的签名算法