# 实施计划： 凭证管理模块

**分支**：`001-credential-manager` | **日期**： 2025-09-28 | **规范**： [spec.md](./spec.md)
**输入**：`/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：按计划实施

## 总结
基于现有的交易系统实现，需要构建一个凭证管理模块，支持多平台账户（Pacifica、Aster、Binance）的热加载、智能平台识别和统一签名接口。该模块将作为独立库提供给其他交易模块使用，确保符合库优先架构原则。

**关键需求**：
- FR-001: 配置文件热加载（<100ms）
- FR-002: 智能平台识别
- FR-003: 统一签名接口（<50ms）
- FR-004: 账户信息查询

**技术方案**：基于现有TypeScript 5.1+基础架构，使用@noble/ed25519实现Ed25519签名，Node.js fs.watch实现热加载，策略模式支持多平台扩展。

## 技术背景
**语言/版本**： TypeScript 5.1+，Node.js 18+
**主要依赖**： @noble/ed25519，@noble/hashes，Jest
**存储**： JSON配置文件，内存缓存
**测试框架**： Jest，ts-jest
**目标平台**： Node.js服务端，Linux/macOS
**项目类型**： 独立库模块（支持其他交易模块）
**性能目标**： 文件加载<100ms，签名操作<50ms
**约束条件**： 热加载支持，多平台兼容，类型安全
**规模/范围**： 支持数百个账户，3个主要平台（可扩展）

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

### 原则一：库优先架构与现实测试
- ✅ **库优先**：凭证管理器将作为独立npm库实现于`libs/credential-manager/`
- ✅ **现实测试**：使用真实Ed25519签名算法和实际文件系统监听，避免模拟
- ✅ **契约测试**：实施前编写失败的契约测试确保接口正确性

### 原则二：Delta中性优先
- ✅ **适用性**：凭证管理模块不直接涉及交易执行，但为交易模块提供安全签名服务
- ✅ **风险控制**：确保私钥安全存储和签名操作的正确性，防止签名错误导致意外交易

### 原则三：确定性市场数据摄取
- N/A：凭证管理模块不涉及市场数据

### 原则四：资金保护与风险控制
- ✅ **账户安全**：实施严格的凭证验证和错误处理，防止无效签名
- ✅ **操作审计**：记录所有签名操作和账户管理操作

### 原则五：透明可观测性与审计
- ✅ **结构化日志**：记录账户加载、签名操作、错误处理的详细日志
- ✅ **性能监控**：追踪文件加载和签名操作性能指标
- ✅ **端到端追踪**：为每个操作提供关联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 生成）
```

### 源码目录（仓库根目录）
```
libs/credential-manager/          # 独立库目录
├── src/
│   ├── core/                    # 核心组件
│   │   ├── types.ts            # 类型定义
│   │   ├── CredentialManager.ts # 主管理器
│   │   ├── Signer.ts           # 统一签名器
│   │   └── PlatformDetector.ts # 平台检测器
│   ├── platforms/              # 平台特定实现
│   │   ├── pacifica/           # Pacifica平台
│   │   ├── aster/              # Aster平台
│   │   └── binance/            # Binance平台
│   ├── loaders/                # 配置加载器
│   │   └── ConfigLoader.ts     # 文件加载和热监听
│   └── index.ts                # 库导出入口
├── tests/
│   ├── contract/               # 契约测试
│   ├── integration/            # 集成测试
│   └── unit/                   # 单元测试
├── examples/                   # 使用示例
├── package.json                # 独立包配置
└── tsconfig.json               # TypeScript配置
```

**结构决策**：采用独立库架构，符合宪章的库优先原则。该库可以被主项目和其他模块独立引用，提供完整的凭证管理功能。

## 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]（必须先失败）
- ICredentialManager → credential-manager契约测试
- IConfigLoader → config-loader契约测试
- ISigner → signer契约测试
- IPlatformDetector → platform-detector契约测试

**从数据模型生成的任务**：
- 每个核心实体 → 模型创建任务 [P]
- Platform、Account、Credentials → types.ts实现
- SignResult、LoadResult → 结果类型实现
- CredentialManagerError → 错误处理实现

**从quickstart生成的任务**：
- 每个示例场景 → 集成测试任务
- 基础使用 → 基础功能集成测试
- 签名操作 → 签名流程集成测试
- 热加载监听 → 文件监听集成测试
- 多平台签名 → 平台策略集成测试

**库优先架构任务**：
- 独立库结构创建
- package.json配置
- TypeScript配置
- Jest测试配置
- 构建和发布配置

**TDD实现顺序**：
1. 测试先行：所有契约测试必须先失败
2. 核心模型：types → Account → Signer
3. 平台策略：PacificaSigner → AsterSigner → BinanceSigner
4. 服务层：ConfigLoader → PlatformDetector → CredentialManager
5. 工厂和集成：CredentialManagerFactory → 全局管理器
6. 验证和优化：性能测试 → 错误处理 → 生产优化

**依赖关系管理**：
- [P] 标记并行任务（不同文件，无依赖）
- 严格按照 types → 实现 → 集成 → 验证 顺序
- Ed25519库集成必须在Pacifica实现之前
- 配置文件监听必须在热加载测试之前

**预估输出**：
- tasks.md：约30-35个有序任务
- 5个主要阶段：Setup → Tests → Core → Integration → Polish
- 符合库优先架构和现实测试原则

**性能验证任务**：
- 文件加载<100ms验证
- 签名操作<50ms验证
- 内存使用监控
- 并发操作测试

**注意**：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) - data-model.md、contracts/、quickstart.md已生成
- [x] Phase 2：任务规划完成 (/plan，仅描述方法) - 策略已详细描述
- [x] Phase 3：任务已生成 (/tasks) - tasks.md已生成
- [ ] Phase 4：实现完成
- [ ] Phase 5：验证通过

**关卡状态**：
- [x] 初次宪章核对：通过 - 符合库优先架构和现实测试原则
- [x] 设计后宪章核对：通过 - 所有设计符合宪章要求
- [x] 所有 NEEDS CLARIFICATION 已解决 - 技术选型已确定
- [x] 复杂度偏差已记录 - 无违例情况

**产出清单**：
- ✅ plan.md - 完整实施计划（本文件）
- ✅ research.md - 技术调研报告
- ✅ data-model.md - 数据模型设计
- ✅ contracts/ - API契约定义
  - ✅ credential-manager.ts - 主接口契约
  - ✅ pacifica-signer.ts - Pacifica签名契约
- ✅ quickstart.md - 快速开始指南
- ✅ tasks.md - 详细任务列表（44个任务，5个阶段）
- ✅ 更新了CLAUDE.md agent context

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