binance-api/specs/001-credential-manager/plan.md

实施计划： 凭证管理模块

分支：001-credential-manager | 日期： 2025-09-28 | 规范： spec.md 输入：/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：按计划实施

总结

基于现有的交易系统实现，需要构建一个凭证管理模块，支持多平台账户（Pacifica、Aster、Binance）的热加载、智能平台识别和统一签名接口。该模块将作为独立库提供给其他交易模块使用，确保符合库优先架构原则。

关键需求：

• FR-001: 配置文件热加载（<100ms）
• FR-002: 智能平台识别
• FR-003: 统一签名接口（<50ms）
• FR-004: 账户信息查询

技术方案：基于现有TypeScript 5.1+基础架构，使用@noble/ed25519实现Ed25519签名，Node.js fs.watch实现热加载，策略模式支持多平台扩展。

技术背景

语言/版本： TypeScript 5.1+，Node.js 18+ 主要依赖： @noble/ed25519，@noble/hashes，Jest 存储： JSON配置文件，内存缓存 测试框架： Jest，ts-jest 目标平台： Node.js服务端，Linux/macOS 项目类型： 独立库模块（支持其他交易模块） 性能目标： 文件加载<100ms，签名操作<50ms 约束条件： 热加载支持，多平台兼容，类型安全 规模/范围： 支持数百个账户，3个主要平台（可扩展）

宪章核对（Constitution Check）

关卡：必须在 Phase 0 前通过，并在 Phase 1 后再次确认。

原则一：库优先架构与现实测试

• ✅ 库优先：凭证管理器将作为独立npm库实现于libs/credential-manager/
• ✅ 现实测试：使用真实Ed25519签名算法和实际文件系统监听，避免模拟
• ✅ 契约测试：实施前编写失败的契约测试确保接口正确性

原则二：Delta中性优先

• ✅ 适用性：凭证管理模块不直接涉及交易执行，但为交易模块提供安全签名服务
• ✅ 风险控制：确保私钥安全存储和签名操作的正确性，防止签名错误导致意外交易

原则三：确定性市场数据摄取

• N/A：凭证管理模块不涉及市场数据

原则四：资金保护与风险控制

• ✅ 账户安全：实施严格的凭证验证和错误处理，防止无效签名
• ✅ 操作审计：记录所有签名操作和账户管理操作

原则五：透明可观测性与审计

• ✅ 结构化日志：记录账户加载、签名操作、错误处理的详细日志
• ✅ 性能监控：追踪文件加载和签名操作性能指标
• ✅ 端到端追踪：为每个操作提供关联ID

项目结构

文档（本功能）

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 生成）

源码目录（仓库根目录）

libs/credential-manager/          # 独立库目录
├── src/
│   ├── core/                    # 核心组件
│   │   ├── types.ts            # 类型定义
│   │   ├── CredentialManager.ts # 主管理器
│   │   ├── Signer.ts           # 统一签名器
│   │   └── PlatformDetector.ts # 平台检测器
│   ├── platforms/              # 平台特定实现
│   │   ├── pacifica/           # Pacifica平台
│   │   ├── aster/              # Aster平台
│   │   └── binance/            # Binance平台
│   ├── loaders/                # 配置加载器
│   │   └── ConfigLoader.ts     # 文件加载和热监听
│   └── index.ts                # 库导出入口
├── tests/
│   ├── contract/               # 契约测试
│   ├── integration/            # 集成测试
│   └── unit/                   # 单元测试
├── examples/                   # 使用示例
├── package.json                # 独立包配置
└── tsconfig.json               # TypeScript配置

结构决策：采用独立库架构，符合宪章的库优先原则。该库可以被主项目和其他模块独立引用，提供完整的凭证管理功能。

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]（必须先失败）
• ICredentialManager → credential-manager契约测试
• IConfigLoader → config-loader契约测试
• ISigner → signer契约测试
• IPlatformDetector → platform-detector契约测试

从数据模型生成的任务：

• 每个核心实体 → 模型创建任务 [P]
• Platform、Account、Credentials → types.ts实现
• SignResult、LoadResult → 结果类型实现
• CredentialManagerError → 错误处理实现

从quickstart生成的任务：

• 每个示例场景 → 集成测试任务
• 基础使用 → 基础功能集成测试
• 签名操作 → 签名流程集成测试
• 热加载监听 → 文件监听集成测试
• 多平台签名 → 平台策略集成测试

库优先架构任务：

• 独立库结构创建
• package.json配置
• TypeScript配置
• Jest测试配置
• 构建和发布配置

TDD实现顺序：

1. 测试先行：所有契约测试必须先失败
2. 核心模型：types → Account → Signer
3. 平台策略：PacificaSigner → AsterSigner → BinanceSigner
4. 服务层：ConfigLoader → PlatformDetector → CredentialManager
5. 工厂和集成：CredentialManagerFactory → 全局管理器
6. 验证和优化：性能测试 → 错误处理 → 生产优化

依赖关系管理：

• [P] 标记并行任务（不同文件，无依赖）
• 严格按照 types → 实现 → 集成 → 验证 顺序
• Ed25519库集成必须在Pacifica实现之前
• 配置文件监听必须在热加载测试之前

预估输出：

• tasks.md：约30-35个有序任务
• 5个主要阶段：Setup → Tests → Core → Integration → Polish
• 符合库优先架构和现实测试原则

性能验证任务：

• 文件加载<100ms验证
• 签名操作<50ms验证
• 内存使用监控
• 并发操作测试

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

Phase 3+：后续实施

超出 /plan 命令范围

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

复杂度追踪

仅在 Constitution Check 有违例时填写

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

进度追踪

执行流程中的状态记录

阶段状态：

• Phase 0：调研完成 (/plan) - research.md已生成
• Phase 1：设计完成 (/plan) - data-model.md、contracts/、quickstart.md已生成
• Phase 2：任务规划完成 (/plan，仅描述方法) - 策略已详细描述
• Phase 3：任务已生成 (/tasks) - tasks.md已生成
• Phase 4：实现完成
• Phase 5：验证通过

关卡状态：

• 初次宪章核对：通过 - 符合库优先架构和现实测试原则
• 设计后宪章核对：通过 - 所有设计符合宪章要求
• 所有 NEEDS CLARIFICATION 已解决 - 技术选型已确定
• 复杂度偏差已记录 - 无违例情况

产出清单：

• ✅ plan.md - 完整实施计划（本文件）
• ✅ research.md - 技术调研报告
• ✅ data-model.md - 数据模型设计
• ✅ contracts/ - API契约定义
  • ✅ credential-manager.ts - 主接口契约
  • ✅ pacifica-signer.ts - Pacifica签名契约
• ✅ quickstart.md - 快速开始指南
• ✅ tasks.md - 详细任务列表（44个任务，5个阶段）
• ✅ 更新了CLAUDE.md agent context

---

基于宪章 v1.0.0 - 详见 /memory/constitution.md