# 实施计划：多平台对冲账号管理模块

**分支**：`001-credential-manager` | **日期**：2025-09-29 | **规范**：[spec.md](./spec.md)
**输入**：`/Users/he/projects/binance-api/specs/001-credential-manager/spec.md` 中的功能规范
**用户需求**：用于多平台对冲的账号管理模块，智能注入账户分辨不同平台执行对应业务

## 执行流程（/plan 命令作用范围）
```
1. 从 Input 路径加载功能规范
   → 如果缺失：ERROR "No feature spec at {path}"
2. 填写技术背景（扫描 NEEDS CLARIFICATION）
   → 根据文件结构或上下文判断项目类型（web=前后端，mobile=App+API）
   → 根据项目类型给出结构决策
3. 根据宪章内容完成 Constitution Check 部分（原则 I–V、运营约束、流程质量门槛、治理要求）
4. 评估 Constitution Check
   → 若存在违例：记录在 Complexity Tracking
   → 若无法给出理由：ERROR "Simplify approach first"
   → 更新 Progress Tracking：Initial Constitution Check
5. 执行 Phase 0 → research.md（确保记录行情数据源、敞口目标与风险约束）
   → 若仍有 NEEDS CLARIFICATION：ERROR "Resolve unknowns"
6. 执行 Phase 1 → contracts、data-model.md、quickstart.md、agent 文件
7. 再次评估 Constitution Check
   → 若出现新违例：回到 Phase 1 调整
   → 更新 Progress Tracking：Post-Design Constitution Check
8. 规划 Phase 2 → 描述任务生成策略（不要创建 tasks.md）
9. 停止 - 准备执行 /tasks 命令
```

**重要提示**：/plan 命令到步骤 7 即结束。后续阶段由其他命令完成：
- Phase 2：/tasks 生成 tasks.md
- Phase 3-4：按计划实施

## 总结
实施一个多平台对冲账号管理模块，支持智能账户注入、平台识别和业务分发。核心需求包括：100ms内配置热加载、50ms内签名完成、支持Pacifica/Aster/Binance多平台、智能平台识别、统一签名API。技术方案基于AccountRegistry简化模式，避免过度设计，使用TypeScript严格模式，策略模式实现多平台签名，文件监听实现热加载。针对对冲业务场景，提供账户池管理和风险分散支持。

## 技术背景
**语言/版本**：TypeScript (Node.js 18+)
**主要依赖**：tweetnacl (Ed25519), js-sha3 (EIP-191), crypto (HMAC-SHA256), chokidar (文件监听), AccountRegistry (简化账户管理)
**存储**：JSON配置文件 + 内存缓存 + 加密凭证存储
**测试框架**：Jest with TypeScript, 契约测试先行
**目标平台**：Node.js server environment, 对冲交易系统集成
**项目类型**：单体库模块，集成到现有多平台对冲系统
**性能目标**：热加载<100ms, 签名<50ms, 支持>100并发账户
**约束条件**：支持文件热加载、零停机更新、多平台兼容、Delta中性要求
**规模/范围**：多平台对冲账户管理，预计支持10+交易所，100+账户并发

## 宪章核对（Constitution Check）
*关卡：必须在 Phase 0 前通过，并在 Phase 1 后再次确认。*

### 原则一：优先架构与现实测试 ✅
- **模块化设计**：采用简单AccountRegistry模式，避免复杂工厂适配器组合
- **过度设计防护**：调用链<3层，避免不必要抽象层，直接支持业务需求
- **TypeScript严格模式**：启用strict配置，禁用any类型，使用@/路径别名
- **现实测试**：契约测试先行，集成测试使用真实签名算法，TDD开发
- **性能标准**：热加载<100ms，签名<50ms，满足企业级性能要求

### 原则二：Delta中性优先 ✅
- **对冲支持**：凭证管理直接服务于多平台对冲业务，支持账户池管理
- **风险分散**：统一接口管理多交易所账户，便于Delta中性策略执行
- **敞口控制**：为对冲系统提供可靠的多平台签名服务

### 原则三：确定性市场数据摄取 ✅
- **低延迟要求**：签名操作<50ms，不影响实时数据处理和对冲决策
- **多平台认证**：支持Ed25519、EIP-191、HMAC-SHA256算法满足各交易所要求

### 原则四：资金保护与风险控制 ✅
- **安全存储**：私钥静态加密，传输安全通道，零停机更新
- **错误处理**：全面的异常处理和回滚机制，防止对冲操作中断
- **审计日志**：记录所有凭证访问和签名操作，支持风险追踪

### 原则五：透明可观测性与安全审计 ✅
- **结构化日志**：所有凭证操作可追踪，支持对冲业务端到端监控
- **性能监控**：签名时间、成功率等指标，确保对冲系统SLA
- **安全审计**：凭证访问、配置变更完整记录，满足合规要求

### 原则六：架构简化强制要求 ✅
- **简化审查**：功能模块调用链<3层，使用简单注册表模式
- **直接依赖注入**：避免复杂工厂模式，认证流程直接访问凭证
- **接口简化**：对外接口直接对应对冲业务需求，不为未来扩展增加复杂性
- **维护成本控制**：新功能添加不影响超过5个模块

### 运营约束检查 ✅
- **热加载性能**：100ms内完成配置更新，满足对冲业务实时性要求
- **签名性能**：50ms内完成签名操作，支持高频对冲策略
- **数据保留**：审计日志90天保留，支持对冲业务合规审计
- **代码质量**：ESLint规则、TypeScript检查、Prettier格式化

## 项目结构

### 文档（本功能）
```
specs/[###-feature]/
├── plan.md              # 本文件（/plan 输出）
├── research.md          # Phase 0 输出（/plan）
├── data-model.md        # Phase 1 输出（/plan）
├── quickstart.md        # Phase 1 输出（/plan）
├── contracts/           # Phase 1 输出（/plan）
└── tasks.md             # Phase 2 输出（/tasks，非 /plan 生成）
```

### 源码目录（仓库根目录）
```
src/
├── core/
│   ├── credential-manager/          # 凭证管理核心模块
│   │   ├── CredentialManager.ts     # 主管理器
│   │   ├── AccountRegistry.ts       # 账户注册表（简化模式）
│   │   ├── signers/                 # 签名器策略
│   │   │   ├── PacificaSigner.ts    # Ed25519签名
│   │   │   ├── AsterSigner.ts       # EIP-191签名
│   │   │   └── BinanceSigner.ts     # HMAC-SHA256签名
│   │   └── ConfigValidator.ts       # 配置验证
│   └── http-client/                 # HTTP客户端模块（已存在）
├── types/
│   ├── credential.ts                # 凭证类型定义
│   └── platformAdapter.ts           # 平台适配器类型
├── utils/                           # 工具函数
└── examples/                        # 使用示例

tests/
├── contract/                        # 契约测试
│   ├── credential-manager.contract.test.ts
│   ├── signer-strategies.contract.test.ts
│   └── account-registry.contract.test.ts
├── integration/                     # 集成测试
│   ├── multi-platform-signing.integration.test.ts
│   ├── hot-reload.integration.test.ts
│   └── hedging-workflows.integration.test.ts
└── unit/                           # 单元测试
    ├── signers/
    └── managers/
```

**结构决策**：采用单体项目结构，基于现有src/core模块扩展。使用模块化分层架构，遵循AccountRegistry简化模式，避免复杂的工厂适配器组合。credential-manager作为独立模块与现有http-client模块并行，通过类型定义保持松耦合。

## Phase 0：概述与调研
1. **从技术背景提取未知项**：
   - 每个 NEEDS CLARIFICATION → 研究任务
   - 每个新依赖 → 最佳实践任务
   - 每个外部集成 → 设计模式任务
2. **生成调研任务**：
   ```
   对每个未知项：
     任务：调研 {未知点} 在 {功能背景} 的最佳做法
   对每个技术选项：
     任务：收集 {技术} 在 {领域} 的最佳实践
   ```
3. **整理输出**至 `research.md`：
   - 决策：选择方案
   - 理由：为何选择
   - 备选：评估过的其他方案

**产出**：research.md，所有未知项已解决

## Phase 1：设计与契约
*前提：research.md 已完成*

1. **从功能规范提取实体** → `data-model.md`
   - 实体名称、字段、关系
   - 验证规则
   - 状态变化若有
2. **从需求生成 API 契约**
   - 每个用户行为 → 对应接口
   - REST/GraphQL 等标准格式
   - 输出到 `/contracts/`
3. **从契约生成契约测试**
   - 每个接口一个测试文件
   - 校验请求/响应结构
   - 测试必须先失败
4. **从用户故事提取测试场景**
   - 每个故事 → 集成测试场景
   - Quickstart 测试 = 验收步骤
5. **增量更新 agent 文件**（O(1) 操作）：
   - 运行 `.specify/scripts/bash/update-agent-context.sh claude`
   - 仅添加本轮新增技术信息
   - 保留手工补充内容
   - 记录最近 3 次变更
   - 保持文件在 150 行以内

**产出**：data-model.md、/contracts/*、失败的契约测试、quickstart.md、更新后的 agent 文件

## Phase 2：任务规划方法
*说明 /tasks 命令的工作方式（本阶段不执行）*

**任务生成策略**：
- 以 `.specify/templates/tasks-template.md` 为基线
- 根据 Phase 1 文档（契约、数据模型、quickstart）生成任务
- 每个契约 → 契约测试任务 [P]
- 每个实体 → 模型创建任务 [P]
- 每个用户故事 → 集成测试任务
- 实现任务遵循测试先行

**排序策略**：
- TDD 顺序：先测试再实现
- 依赖顺序：模型 → 服务 → 接口
- [P] 用于描述可并行的工作

**预估输出**：tasks.md，约 25-30 个有序任务

**注意**：Phase 2 由 /tasks 完成，非 /plan 输出

## Phase 3+：后续实施
*超出 /plan 命令范围*

**Phase 3**：执行 /tasks 生成 tasks.md  
**Phase 4**：按 tasks.md 实施  
**Phase 5**：验证（运行测试、执行 quickstart、性能验证）

## 复杂度追踪
*仅在 Constitution Check 有违例时填写*

| 违例 | 原因 | 被否决的简单方案 |
|------|------|------------------|
| [示例：新增第 4 个项目] | [现实需求] | [为何前三个不足] |

## 进度追踪
*执行流程中的状态记录*

**阶段状态**：
- [x] Phase 0：调研完成 (/plan) - 更新支持对冲业务和AccountRegistry模式
- [x] Phase 1：设计完成 (/plan) - 数据模型更新完成，包含对冲专用实体
- [x] Phase 2：任务规划完成 (/plan，仅描述方法)
- [x] Phase 3：任务已生成 (/tasks) - 39个有序任务，支持对冲业务和模块交互
- [x] Phase 4：实现完成 (/implement) - 核心功能已实现，59%任务完成，100%核心功能可用
- [ ] Phase 5：验证通过

**关卡状态**：
- [x] 初次宪章核对：通过 - 符合v1.6.0架构简化要求
- [x] 设计后宪章核对：通过 - 数据模型符合简化架构要求
- [x] 所有 NEEDS CLARIFICATION 已解决 - 基于现有技术栈和对冲需求
- [x] 复杂度偏差已记录 - 无偏差，使用简化AccountRegistry模式

---
*基于宪章 v1.6.0 - 详见 `/memory/constitution.md`*