# Tools迁移计划

## 🎯 目标
将 `src/shared/libs/` 中的JS工具迁移到 `browser-automation-ts/src/tools/`，统一使用TypeScript和ITool规范。

---

## 📊 迁移清单

### 1. AccountGenerator ✅ (已创建)
- **源文件**: `src/shared/libs/account-generator.js`
- **目标**: `browser-automation-ts/src/tools/AccountGenerator.ts`
- **状态**: ✅ 完成（新实现符合ITool规范）
- **接口**: `IAccountGenerator`

### 2. CardGenerator
- **源文件**: `src/shared/libs/card-generator.js`
- **目标**: `browser-automation-ts/src/tools/CardGenerator.ts`
- **状态**: ⏳ 待迁移
- **接口**: `ICardGenerator`
- **依赖**: Database
- **功能**:
  - 从数据库获取未使用的卡
  - 标记卡为已使用
  - BIN去重逻辑

### 3. EmailHandler
- **源文件**: `src/shared/libs/email-handler.js` (如果存在)
- **目标**: `browser-automation-ts/src/tools/EmailHandler.ts`
- **状态**: ⏳ 待创建
- **接口**: `IEmailHandler`
- **功能**:
  - 连接邮箱服务
  - 获取验证码
  - 解析邮件内容

### 4. CaptchaSolver
- **源文件**: `src/shared/libs/captcha-solver.js`
- **目标**: `browser-automation-ts/src/tools/CaptchaSolver.ts`
- **状态**: ⏳ 待迁移
- **接口**: `ICaptchaHandler`
- **功能**:
  - Turnstile处理
  - hCaptcha处理
  - reCAPTCHA处理

### 5. DatabaseClient
- **源文件**: `src/shared/libs/database.js`
- **目标**: `browser-automation-ts/src/tools/DatabaseClient.ts`
- **状态**: ⏳ 待迁移
- **接口**: `IDatabaseClient`
- **功能**:
  - MySQL连接
  - 保存账号数据
  - 保存卡片数据
  - 查询操作

---

## 🏗️ 最终架构

```
browser-automation-ts/
├── src/
│   ├── core/                     # 核心（Provider、Action、WorkflowEngine）
│   ├── adapters/                 # 适配器接口
│   └── tools/                    # 业务工具（符合ITool规范）
│       ├── ITool.ts             # ✅ 工具接口规范
│       ├── AccountGenerator.ts   # ✅ 账号生成器
│       ├── CardGenerator.ts      # ⏳ 卡生成器
│       ├── EmailHandler.ts       # ⏳ 邮箱处理器
│       ├── CaptchaSolver.ts      # ⏳ 验证码处理器
│       └── DatabaseClient.ts     # ⏳ 数据库客户端
├── configs/
│   └── sites/
│       ├── windsurf.yaml         # 流程定义
│       └── windsurf-adapter.ts   # 业务逻辑（使用tools）
└── cli/
    └── run.ts                    # 通用执行器
```

---

## 💡 使用示例

### Windsurf Adapter示例

```typescript
import { WindsurfAdapter } from './windsurf-adapter';
import { AccountGenerator } from '../../src/tools/AccountGenerator';
import { CardGenerator } from '../../src/tools/CardGenerator';
import { DatabaseClient } from '../../src/tools/DatabaseClient';

class WindsurfAdapter implements ISiteAdapter {
  private accountGen: AccountGenerator;
  private cardGen: CardGenerator;
  private db: DatabaseClient;

  async initialize(context: any) {
    // 初始化工具
    this.accountGen = new AccountGenerator({
      emailDomain: 'tempmail.com'
    });
    await this.accountGen.initialize();

    this.db = new DatabaseClient({
      host: 'localhost',
      database: 'accounts'
    });
    await this.db.initialize();

    this.cardGen = new CardGenerator({
      database: this.db
    });
    await this.cardGen.initialize();

    // 生成账号（如果需要）
    if (!context.data.account.email) {
      context.data.account = await this.accountGen.generate();
    }
  }

  getHandlers() {
    return {
      generateCard: async () => {
        const card = await this.cardGen.generate();
        this.context.data.card = card;
        return { success: true, data: card };
      },
      
      saveToDatabase: async () => {
        await this.db.saveAccount(this.context.data.account);
        await this.db.saveCard(this.context.data.card);
        return { success: true };
      }
    };
  }
}
```

---

## ✅ 迁移优势

1. **类型安全** - 全TypeScript，编译时检查
2. **统一规范** - 所有工具实现ITool接口
3. **易测试** - 接口明确，方便mock
4. **可扩展** - 新工具遵循同样规范
5. **解耦** - 工具独立，adapter组合使用

---

## 📅 迁移计划

### 第一阶段：核心工具（当前）
- [x] ITool接口规范
- [x] AccountGenerator
- [ ] DatabaseClient（优先）
- [ ] CardGenerator

### 第二阶段：扩展工具
- [ ] EmailHandler
- [ ] CaptchaSolver

### 第三阶段：测试和优化
- [ ] 单元测试
- [ ] 集成测试
- [ ] 性能优化

---

## 🚀 开始使用

当前可以直接使用：
```bash
# 只需设置AdsPower ID
export ADSPOWER_USER_ID="your-id"

# 运行（会自动生成账号）
pnpm run run -- windsurf
```

账号数据完全由 `AccountGenerator` 自动生成！