Главная Обзор Помощь
Регистрация Вход
Malone
/
binance-api
1
0
Ответвить 0
Файлы Задачи 0 Запросы на слияние 0 Вики
Дерево: 76b0987bb1
Ветки Метки
binance-api
/
specs
/
001-credential-manager
/
plan.md

plan.md 9.7 KB
История Исходник

实施计划：凭证管理模块

分支：001-credential-manager | 日期： 2025-09-28 | 规范： 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内)、智能识别Pacifica/Aster/Binance平台、统一签名接口(50ms内)、账户信息查询功能。技术方案将基于TypeScript+Node.js实现，采用模块化设计支持Ed25519、EIP-191、HMAC-SHA256等多种签名算法。

技术背景

语言/版本： TypeScript 5.1.0, Node.js 18.12+ 主要依赖： tweetnacl (Ed25519), ethers (EIP-191), crypto (HMAC-SHA256), winston (日志), fs/chokidar (文件监控) 存储： 文件系统 (JSON/YAML配置文件) 测试框架： Jest 29.7.0 目标平台： Node.js server环境 项目类型： 单体项目 (交易系统模块) 性能目标： 热加载<100ms, 签名操作<50ms 约束条件： 内存占用<50MB, 支持热重载, 零停机时间 规模/范围： 支持50+账户, 3个交易平台, 并发签名请求

宪章核对（Constitution Check）

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

一、集成优先架构与现实测试 ✅

  • 集成优先设计: 凭证管理模块设计为可与现有交易系统无缝集成，提供统一接口而非复杂抽象
  • 企业级性能: 热加载<100ms, 签名操作<50ms 满足性能要求
  • 统一接口: 支持Ed25519、EIP-191、HMAC-SHA256认证，符合多平台适配器要求
  • 现实测试: 使用Jest进行TDD开发，契约测试覆盖真实工作流

二、Delta中性优先 N/A

  • 凭证管理模块不直接涉及交易敞口，无Delta中性要求

三、确定性市场数据摄取 N/A

  • 凭证管理模块不直接处理市场数据，但为数据摄取模块提供认证支持

四、资金保护与风险控制 ✅

  • 凭证安全: 静态加密存储，支持季度轮换演练
  • 错误处理: 全面错误处理和自动重试机制
  • 审计追踪: 所有签名操作记录关联ID，支持端到端可追踪

五、透明可观测性与审计 ✅

  • 结构化日志: 使用winston记录凭证加载、签名操作等关键事件
  • 性能监控: 提供热加载和签名操作的性能指标
  • 健康检查: 实时监控凭证状态和平台连接健康度

运营约束检查 ✅

  • 高频评估: 支持8秒内快速账户查询和签名操作
  • 凭证安全: 配置文件加密存储，支持热重载无需重启
  • 数据保留: 操作日志满足90天重放要求

项目结构

文档（本功能）

specs/001-credential-manager/
├── 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/    # 新增：凭证管理核心模块
│   └── ...
├── adapters/
│   ├── pacifica/             # 现有：Pacifica平台适配器
│   ├── aster/                # 待实现：Aster平台适配器
│   └── binance/              # 待实现：Binance平台适配器
├── types/
│   ├── credential.ts         # 新增：凭证相关类型定义
│   ├── platformAdapter.ts    # 现有：平台适配器类型
│   └── ...
├── config/
│   ├── simpleEnv.ts          # 现有：环境配置
│   └── credential-config.ts  # 新增：凭证配置管理
└── utils/
    ├── logger.ts             # 现有：日志工具
    └── ...

tests/
├── contract/
│   └── credential-manager.contract.test.ts  # 新增：凭证管理契约测试
├── integration/
│   └── credential-manager.integration.test.ts # 新增：集成测试
└── unit/
    └── credential-manager.unit.test.ts      # 新增：单元测试

结构决策：采用方案1单体项目结构，在现有src/目录下新增core/credential-manager/模块，与现有adapters/、types/、utils/等目录协同工作。选择此结构因为：1）与现有代码库架构一致；2）便于与其他交易模块集成；3）符合模块化设计原则。

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：测试先行

具体任务类型：

  1. 类型定义任务 [P]: Platform, Account, Credentials, Signer接口
  2. 契约测试任务 [P]: ICredentialManager, ConfigLoader, SignerStrategy契约
  3. 核心实现任务: 凭证管理器、配置加载器、签名策略
  4. 平台适配任务 [P]: Pacifica, Binance, Aster签名器实现
  5. 集成测试任务: 热加载、多平台签名、性能测试
  6. 配置和文档任务: TypeScript配置、导出设置

排序策略：

  • TDD 顺序：契约测试 → 类型定义 → 核心实现 → 平台适配 → 集成测试
  • 依赖顺序：类型 → 接口 → 核心逻辑 → 平台特定 → 集成验证
  • [P] 标记可并行执行的任务组

预估输出：tasks.md，约 28-32 个有序任务，包含：

  • 8个类型定义任务
  • 6个契约测试任务
  • 8个核心实现任务
  • 6个平台适配任务
  • 4个集成测试任务

注意：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)
  • Phase 1：设计完成 (/plan)
  • Phase 2：任务规划完成 (/plan，仅描述方法)
  • Phase 3：任务已生成 (/tasks)
  • Phase 4：实现完成
  • Phase 5：验证通过

关卡状态：

  • 初次宪章核对：通过
  • 设计后宪章核对：通过
  • 所有 NEEDS CLARIFICATION 已解决
  • 复杂度偏差已记录 (无违例)

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