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

**分支**：`002-httpclient-http-api` | **日期**： 2025-09-29 | **规范**： [spec.md](./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：概述与调研
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]
- 每个用户故事 → 集成测试任务
- 实现任务遵循测试先行

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

### 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. 实现任务依赖顺序
1. **基础类型定义** [P] - 扩展现有types/httpClient.ts
2. **核心HTTP客户端** - 重构universalHttpClient.ts架构
3. **平台适配器** [P] - 增强现有adapters/目录实现
4. **认证集成** - 集成core/credential-manager/
5. **性能优化** [P] - 连接池、缓存、监控
6. **集成测试** - 多平台端到端测试

### 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 个项目] | [现实需求] | [为何前三个不足] |

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

**阶段状态**：
- [x] Phase 0：调研完成 (/plan) ✅
- [x] Phase 1：设计完成 (/plan) ✅
- [x] Phase 2：任务规划完成 (/plan，仅描述方法) ✅
- [ ] Phase 3：任务已生成 (/tasks)
- [ ] Phase 4：实现完成
- [ ] Phase 5：验证通过

**关卡状态**：
- [x] 初次宪章核对：通过 ✅
- [x] 设计后宪章核对：通过 ✅
- [x] 所有 NEEDS CLARIFICATION 已解决 ✅
- [x] 复杂度偏差已记录：无违例 ✅

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