# 实施计划： [FEATURE]

**分支**：`[###-feature-name]` | **日期**： [DATE] | **规范**： [link]
**输入**：`/specs/[###-feature-name]/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（Ed25519）、Aster（EIP-191）、Binance（HMAC-SHA256）、OKX等平台的签名算法，提供统一的签名接口和配置热重载功能。

## 技术背景
**语言/版本**： TypeScript 5.1, Node.js 18.12+
**主要依赖**： bs58, tweetnacl, ethers, axios, winston, dotenv, ccxt
**存储**： 文件系统（外部配置）+ Redis（缓存）+ PostgreSQL（审计日志）
**测试框架**： Jest 29.7 + ts-jest
**目标平台**： Linux server（生产）+ macOS/Windows（开发）
**项目类型**： 单体后端服务（凭据管理器）
**性能目标**： 签名响应时间 <50ms，支持 <100 QPS 并发请求
**约束条件**： AES-256加密存储，99.95%可用性，配置热重载 <5秒
**规模/范围**： 多交易所（4+），多账户类型，可插拔签名适配器

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

### I. Delta-Neutral First
- ⚠️ **不适用**: 本功能为凭据管理服务，不涉及交易执行或敞口管理
- ✅ **符合**: 为交易系统提供底层支持，不破坏Delta中性策略
- ✅ **符合**: 提供统一签名服务，支持对冲交易的权限管理

### II. Deterministic Market Data Intake
- ⚠️ **不适用**: 本功能不涉及市场数据获取
- ✅ **符合**: 不干扰现有行情数据流，仅提供账户凭据支持
- ✅ **符合**: 签名服务响应时间<50ms，不影响交易延迟

### III. Capital Protection & Risk Controls
- ✅ **符合**: 提供平台级权限控制，防止未授权账户访问
- ✅ **符合**: 凭据加密存储（AES-256），防止私钥泄露风险
- ✅ **符合**: 审计日志记录所有签名操作，支持风险追踪
- ✅ **符合**: 支持账户状态监控和紧急禁用机制

### IV. Transparent Observability & Audit
- ✅ **符合**: 所有签名操作必须记录审计日志（24个月保留）
- ✅ **符合**: 提供结构化日志，包含签名请求、权限验证、账户使用
- ✅ **符合**: 支持凭据生命周期管理的完整追踪
- ✅ **符合**: 配置文件变化和热重载操作的监控记录

### V. Tested Execution Paths
- ✅ **符合**: 每个平台签名适配器必须通过单元测试和集成测试
- ✅ **符合**: 凭据注入和权限验证的自动化测试覆盖
- ✅ **符合**: 多环境隔离测试，防止开发/生产凭据混用
- ✅ **符合**: 新交易所接入前必须完成签名算法验证测试

**初步评估**: ✅ 通过 - 功能作为基础设施服务，与宪章原则兼容，为交易系统提供安全的凭据管理支持

### 设计后再次核对
*基于 Phase 1 完成后的数据模型和契约设计*

**评估结果**: ✅ 设计符合宪章要求
- **Delta-Neutral First**: 签名服务支持对冲交易的快速签名，不干扰Delta中性策略
- **Deterministic Market Data**: 不涉及市场数据，签名响应时间<50ms，不影响交易时效性
- **Capital Protection & Risk Controls**:
  - PlatformCredentialSchema 强制执行凭据格式验证
  - PermissionPolicy 实体确保权限控制和资源访问限制
  - AuditLog 实体提供完整的操作追踪和合规检查
- **Transparent Observability**:
  - 所有签名操作记录结构化审计日志
  - 权限验证过程完全可追踪
  - 配置变更和系统状态完整监控
- **Tested Execution Paths**:
  - quickstart.md 涵盖8个关键测试场景
  - 包含故障处理和恢复验证
  - 多平台签名算法的完整测试覆盖

**无新发现的违例或复杂度问题**

## 项目结构

### 文档（本功能）
```
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/
├── app/
│   └── main.ts              # 主入口点和HTTP服务器
├── core/
│   ├── credential-manager.ts # 凭据管理器（主服务）
│   ├── config-loader.ts     # 配置文件加载和热重载
│   └── signature-adapters/  # 签名适配器
│       ├── pacifica.ts      # Pacifica Ed25519签名
│       ├── aster.ts         # Aster EIP-191签名
│       ├── binance.ts       # Binance HMAC-SHA256签名
│       └── okx.ts           # OKX签名适配器
├── shared/
│   ├── types.ts             # 类型定义
│   ├── constants.ts         # 常量定义
│   └── utils.ts             # 工具函数
└── api/
    ├── routes.ts            # API路由定义
    └── handlers.ts          # 请求处理器

__tests__/
├── unit/                    # 单元测试
├── integration/             # 集成测试
└── fixtures/               # 测试数据
```

**结构决策**：采用简化的单体服务架构，专注于核心功能。credential-manager.ts 作为主服务，集成配置加载、账户管理和签名调度。signature-adapters/ 目录包含各平台的签名实现，保持良好的扩展性。

## 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 cursor`
   - 仅添加本轮新增技术信息
   - 保留手工补充内容
   - 记录最近 3 次变更
   - 保持文件在 150 行以内

**产出**：data-model.md、/contracts/*、失败的契约测试、quickstart.md、更新后的 agent 文件

## Phase 2：任务规划方法
*说明 /tasks 命令的工作方式（本阶段不执行）*

**任务生成策略**：
基于简化设计文档生成实现任务：

### 核心模块任务（基于 data-model.md）
1. **数据模型层** [P]：
   - PlatformAccount 实体实现
   - SignatureAdapter 接口定义
   - ConfigManager 配置管理器

2. **签名适配器** [P]：
   - PacificaAdapter: Ed25519 签名实现
   - AsterAdapter: EIP-191 签名实现
   - BinanceAdapter: HMAC-SHA256 签名实现
   - OkxAdapter: OKX 特有签名实现

### 契约测试任务（基于 contracts/）
1. **签名服务契约** [P]: signature-service.md → 测试多平台签名和批量操作
2. **配置管理契约** [P]: 配置加载、热重载、状态查询测试

### 集成测试任务（基于 quickstart.md）
1. **配置文件加载**: 多平台账户注入测试
2. **Pacifica签名**: Ed25519 签名流程测试
3. **Aster签名**: EIP-191 签名验证测试
4. **Binance签名**: HMAC-SHA256 签名测试
5. **配置热重载**: 文件监控和动态更新测试
6. **批量签名性能**: 并发处理性能测试
7. **故障恢复**: 错误处理和降级运行测试

### 实现顺序策略
**Phase A - 核心功能** [2周]：
- 配置加载和数据模型
- 4个平台的签名适配器
- 主服务和API接口

**Phase B - 集成测试** [1周]：
- 契约测试覆盖
- 端到端集成测试
- 性能验证和调优

**预估输出**：
- tasks.md：约 15-18 个有序任务
- 总工期：3周，简化实现
- 关键路径：配置加载 → 签名适配器 → API集成

**质量门控**：
- 签名适配器单元测试覆盖率 >90%
- Quickstart 场景 100% 通过
- 签名性能 <50ms 要求

**注意**：Phase 2 具体任务由 /tasks 命令生成，此处仅描述生成策略

## Phase 3+：后续实施
*超出 /plan 命令范围*

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

## 复杂度追踪
*仅在 Constitution Check 有违例时填写*

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

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

**阶段状态**：
- [x] Phase 0：调研完成 (/plan) - 2025-09-28 ✅
- [x] Phase 1：设计完成 (/plan) - 简化设计文档完成 ✅
- [x] Phase 2：任务规划完成 (/plan，仅描述方法) - 简化策略已制定 ✅
- [ ] Phase 3：任务已生成 (/tasks) - 待执行
- [ ] Phase 4：实现完成 - 预计3周（简化）
- [ ] Phase 5：验证通过 - 依赖实现完成

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

**简化成果**:
- 数据模型：从7个实体简化为3个核心实体
- API契约：从3个复杂契约简化为1个签名服务契约
- 测试场景：从8个复杂场景简化为7个核心场景
- 实施周期：从8周简化为3周

**当前状态**: ✅ /plan 阶段完成（简化版），准备执行 /tasks 命令生成具体实现任务

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