# 实施计划：通用HTTP客户端多平台账户管理

**分支**：`002-httpclient-http-api` | **日期**：2025-09-28 | **规范**：[spec.md](./spec.md)
**输入**：`/Users/he/projects/binance-api/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：按计划实施

## 总结
为多平台交易账户（Pacifica、Aster、Binance）提供统一的HTTP API调用客户端。核心要求包括：
- 高性能：<100ms响应时间，99.9%可用性，1000+并发请求
- 集成现有凭证管理库进行平台特定认证
- 智能重试逻辑：网络错误重试，认证错误立即失败
- 完整日志记录：30天保留期，包含敏感数据
- 分层超时：连接5s，读取30s，写入15s，支持HTTP代理
- 集成架构：集成到现有代码库，支持多账户并发调用

## 技术背景
**语言/版本**： TypeScript + Node.js 18.12+，ESNext模块
**主要依赖**： 现有httpClient.ts，credential-manager库，https-proxy-agent，winston日志
**存储**： 无持久化存储需求，内存缓存
**测试框架**： Jest (已配置在credential-manager)
**目标平台**： Node.js服务器环境，Linux/macOS
**项目类型**： 单体项目，集成到现有代码库
**性能目标**： <100ms响应时间，99.9%可用性，1000+并发请求
**约束条件**： 分层超时（连接5s，读取30s，写入15s），代理支持
**规模/范围**： 3个交易平台（Pacifica、Aster、Binance），多账户并发

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

### 一、库优先架构与现实测试
- ✅ **模块化架构**：HTTP客户端将实现为高内聚低耦合的模块，集成到现有代码库
- ✅ **现实测试**：将使用真实HTTP端点测试（Pacifica、Aster、Binance API），实施契约测试验证接口
- ✅ **TDD开发**：HTTP客户端库必须通过测试先行开发，确保代码质量

### 二、Delta中性优先
- ✅ **适用性**：HTTP客户端作为基础设施组件，直接支持交易操作，符合Delta中性要求
- ✅ **实时性**：<100ms响应时间确保快速订单执行和头寸调整
- ✅ **多账户支持**：支持同时处理多个账户的请求，保证账户间隔离

### 三、确定性市场数据摄取
- ✅ **适用性**：HTTP客户端将支持市场数据API调用的HTTP回退机制
- ✅ **延迟要求**：<100ms响应时间满足低延迟数据获取需求
- ✅ **健康检查**：实现超时和重试机制，确保数据源可用性

### 四、资金保护与风险控制
- ✅ **认证安全**：集成credential-manager确保安全的账户认证
- ✅ **请求隔离**：多账户并发不会导致凭据混合或认证冲突
- ✅ **幂等性**：HTTP请求支持幂等标识符，防止重复执行

### 五、透明可观测性与审计
- ✅ **完整日志**：记录所有请求/响应内容，包含敏感数据，30天保留
- ✅ **结构化日志**：集成winston日志系统，支持关联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 生成）
```

### 源码目录（仓库根目录）
```
src/
├── utils/
│   ├── httpClient.ts           # 现有实现（待增强）
│   └── universalHttpClient.ts  # 新建：通用HTTP客户端
├── adapters/                   # 新建：平台适配器
│   ├── base/
│   │   └── BaseAdapter.ts      # 基础适配器抽象类
│   ├── pacifica/
│   │   └── PacificaAdapter.ts  # Pacifica平台适配器
│   ├── aster/
│   │   └── AsterAdapter.ts     # Aster平台适配器
│   └── binance/
│       └── BinanceAdapter.ts   # Binance平台适配器
├── types/                      # 新建：类型定义
│   ├── httpClient.ts           # HTTP客户端类型
│   ├── platformAdapter.ts      # 平台适配器类型
│   └── common.ts               # 通用类型
└── core/                       # 现有核心模块
    ├── hedging/
    ├── market/
    └── ...

tests/
├── contract/                   # 契约测试
│   ├── httpClient.test.ts
│   └── platformAdapters.test.ts
├── integration/               # 集成测试
│   ├── multiPlatform.test.ts
│   └── authentication.test.ts
└── unit/                      # 单元测试
    ├── adapters/
    └── utils/

libs/                          # 现有库目录
└── credential-manager/        # 现有凭证管理库
```

**结构决策**：采用单体项目结构，HTTP客户端集成到现有src/目录下。新增src/adapters/目录用于平台适配器，src/types/目录用于类型定义。利用现有的libs/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]
- 每个用户故事 → 集成测试任务
- 实现任务遵循测试先行

**排序策略**：
- 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) - research.md已生成
- [x] Phase 1：设计完成 (/plan) - contracts/、data-model.md、quickstart.md已生成
- [x] Phase 2：任务规划完成 (/plan，仅描述方法) - 详细任务生成策略已制定
- [ ] Phase 3：任务已生成 (/tasks) - 待执行/tasks命令
- [ ] Phase 4：实现完成
- [ ] Phase 5：验证通过

**关卡状态**：
- [x] 初次宪章核对：通过
- [x] 设计后宪章核对：通过 - 所有设计组件保持宪章一致性
- [x] 所有 NEEDS CLARIFICATION 已解决（从规格说明澄清会话）
- [x] 复杂度偏差已记录（无违例）

**设计后宪章确认**：
- ✅ **模块化架构维持**：contracts定义的接口保持高内聚低耦合，支持动态平台注册
- ✅ **扩展性增强**：platform adapter factory和平台配置模板确保轻松添加新平台
- ✅ **性能目标保持**：所有设计组件支持<100ms响应时间和1000+并发要求
- ✅ **安全性强化**：详细认证契约和错误处理确保资金安全
- ✅ **可观测性完整**：日志记录、健康检查、性能监控全面覆盖

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