实施计划：通用HTTP客户端模块化重构

分支：002-httpclient-http-api | 日期： 2025-09-29 | 规范： spec.md 输入：/specs/002-httpclient-http-api/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：按计划实施

总结

重构现有的HTTP客户端库，使其更加模块化并与credential模块紧密配合，支持多平台交易签名。基于功能规范，系统需要支持Pacifica、Aster、Binance三个平台的HTTP API调用，通过统一接口实现平台特定的认证和请求处理，确保高性能(<100ms响应时间)、高可用性(99.9%)和高并发(1000+请求)。技术方案将采用适配器模式重构现有UniversalHttpClient，深度集成credential-manager模块，实现智能重试、全面日志记录和分层代理支持。

技术背景

语言/版本： TypeScript 5.1+ with Node.js 18.12+ 主要依赖： axios, ethers, tweetnacl, @noble/secp256k1, https-proxy-agent, winston 存储：内存缓存 + 文件系统配置存储 测试框架： Jest 29.7+ with contract testing, integration testing 目标平台： Node.js 服务器环境 项目类型：单体项目，模块化库设计 性能目标： <100ms响应时间，99.9%可用性，1000+并发请求 约束条件： 5秒连接超时，30秒读取超时，15秒写入超时，支持HTTP代理 规模/范围： 3个交易平台适配器，统一HTTP客户端接口，credential-manager深度集成

技术架构决策：

采用适配器模式重构现有UniversalHttpClient
与credential-manager模块深度集成进行认证和签名
支持Ed25519(Pacifica)、EIP-191(Aster)、HMAC-SHA256(Binance)认证
实现智能重试策略：网络错误指数退避，认证错误立即失败
分层代理支持：全局代理+账户专用代理
完整的请求/响应日志记录，包含敏感数据(30天保留)

宪章核对（Constitution Check）

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

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

高内聚低耦合：采用适配器模式，各平台适配器独立，通过统一接口交互
企业级性能标准：目标<100ms响应时间，99.9%可用性，1000+并发请求
统一认证接口：支持Ed25519(Pacifica)、EIP-191(Aster)、HMAC-SHA256(Binance)
TypeScript代码质量：严格类型配置，无any类型，完整类型定义和导出接口
测试驱动开发：契约测试先行，集成测试覆盖真实工作流，TDD开发模式

原则二：Delta中性优先 ✅

支持交易操作：HTTP客户端为多平台交易提供基础通信能力
实时性要求：满足高频交易场景的低延迟要求

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

低延迟通信：WebSocket和HTTP回退支持，确保数据连续性
批量请求处理：支持并发请求管理和连接池优化

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

全面错误处理：智能重试机制、熔断器模式、自动故障转移
审计追踪：完整的请求/响应日志记录，包含敏感数据

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

凭证管理集成：与credential-manager深度集成，支持多平台热加载
安全存储：静态加密存储，传输时安全通道
性能监控：SLA跟踪、实时健康检查、性能基准测试
审计日志：记录所有凭证访问、签名操作和配置变更

运营约束检查 ✅

高频评估：支持≤8秒循环的高频信号评估
代理合规：支持地理合规、IP轮换和自动故障转移
凭证轮换：支持季度演练和零停机时间更新
数据保留：满足90天重放要求，30天日志保留

代码质量保障 ✅

ESLint配置：强制执行import/extensions、import/order、import/no-unresolved规则
TypeScript严格模式：禁用any类型，使用路径别名(@/)
自动格式化：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/     # 现有凭证管理模块
│   └── http-client/           # 重构后的HTTP客户端模块
├── adapters/                  # 平台适配器
│   ├── base/                  # 基础适配器
│   ├── pacifica/              # Pacifica适配器
│   ├── aster/                 # Aster适配器
│   └── binance/               # Binance适配器
├── types/                     # 类型定义
├── utils/                     # 工具函数
└── examples/                  # 示例代码

tests/
├── contract/                  # 契约测试
├── integration/               # 集成测试
└── unit/                      # 单元测试

结构决策：采用单体项目模块化设计，基于现有src/目录结构，新增core/http-client/模块，重构现有utils/httpClient.ts和utils/universalHttpClient.ts到模块化架构。充分利用现有adapters/目录和core/credential-manager/集成。

Phase 0：概述与调研

从技术背景提取未知项：
- 每个 NEEDS CLARIFICATION → 研究任务
- 每个新依赖 → 最佳实践任务
- 每个外部集成 → 设计模式任务

生成调研任务：

对每个未知项：
 任务：调研 {未知点} 在 {功能背景} 的最佳做法
对每个技术选项：
 任务：收集 {技术} 在 {领域} 的最佳实践

整理输出至 research.md：
- 决策：选择方案
- 理由：为何选择
- 备选：评估过的其他方案

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

Phase 1：设计与契约

前提：research.md 已完成

从功能规范提取实体 → data-model.md
- 实体名称、字段、关系
- 验证规则
- 状态变化若有
从需求生成 API 契约
- 每个用户行为 → 对应接口
- REST/GraphQL 等标准格式
- 输出到 /contracts/
从契约生成契约测试
- 每个接口一个测试文件
- 校验请求/响应结构
- 测试必须先失败
从用户故事提取测试场景
- 每个故事 → 集成测试场景
- Quickstart 测试 = 验收步骤
增量更新 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]
每个用户故事 → 集成测试任务
实现任务遵循测试先行

基于现有分析的任务规划策略：

1. 核心架构任务

HttpClientCore重构：基于research.md中的分层架构设计
平台适配器工厂：完善universalHttpClient.ts中未实现的createPlatformAdapter
CredentialManager集成：建立HTTPClient与credential-manager的深度集成

2. 契约测试优先策略

HTTP客户端契约：基于contracts/http-client.contract.md生成TDD测试
平台适配器契约：基于contracts/platform-adapter.contract.md生成适配器测试
认证集成契约：验证与credential-manager的签名接口

3. 实现任务依赖顺序

基础类型定义 [P] - 扩展现有types/httpClient.ts
核心HTTP客户端 - 重构universalHttpClient.ts架构
平台适配器 [P] - 增强现有adapters/目录实现
认证集成 - 集成core/credential-manager/
性能优化 [P] - 连接池、缓存、监控
集成测试 - 多平台端到端测试

4. 质量保障任务

ESLint规则验证：确保符合宪章的代码质量要求
TypeScript严格模式：移除any类型，完善类型定义
性能基准测试：验证<100ms响应时间，1000+并发支持

排序策略：

TDD 顺序：先测试再实现
依赖顺序：类型 → 核心 → 适配器 → 集成
[P] 用于描述可并行的工作
优先处理现有代码重构，后增加新功能

预估输出：tasks.md，约 28-32 个有序任务，重点关注模块化重构和credential集成

注意：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.5.0 - 详见 /memory/constitution.md

plan.md 11 KB

History Raw

实施计划：通用HTTP客户端模块化重构

执行流程（/plan 命令作用范围）

总结

技术背景

宪章核对（Constitution Check）

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

原则二：Delta中性优先 ✅

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

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

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

运营约束检查 ✅

代码质量保障 ✅

项目结构

文档（本功能）

源码目录（仓库根目录）

Phase 0：概述与调研

Phase 1：设计与契约

Phase 2：任务规划方法

1. 核心架构任务

2. 契约测试优先策略

3. 实现任务依赖顺序

4. 质量保障任务

Phase 3+：后续实施

复杂度追踪

进度追踪

plan.md 11 KB History Raw

实施计划：通用HTTP客户端模块化重构

执行流程（/plan 命令作用范围）

总结

技术背景

宪章核对（Constitution Check）

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

原则二：Delta中性优先 ✅

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

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

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

运营约束检查 ✅

代码质量保障 ✅

项目结构

文档（本功能）

源码目录（仓库根目录）

Phase 0：概述与调研

Phase 1：设计与契约

Phase 2：任务规划方法

1. 核心架构任务

2. 契约测试优先策略

3. 实现任务依赖顺序

4. 质量保障任务

Phase 3+：后续实施

复杂度追踪

进度追踪

plan.md 11 KB

History Raw