makemd/docs/01_Architecture/02_System_Interoperability.md

# 系统互通架构（System Interoperability Architecture）

> 本文档定义 Crawlful Hub 系统各组件之间的互通机制和通信规范。

## 1. 互通架构总览

### 1.1 核心互通模型

```
┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│   前端控制台         │────▶│    后端服务          │────▶│   运营代理（Agent）   │
│  (Frontend Console) │◀────│  (Backend Service)  │◀────│  (Operation Agent)  │
└─────────────────────┘     └─────────────────────┘     └─────────────────────┘
                                    │
                                    ▼
                          ┌─────────────────────┐
                          │    平台适配器         │
                          │ (Platform Adapter)  │
                          └─────────────────────┘
                                    │
                                    ▼
                          ┌─────────────────────┐
                          │    第三方平台         │
                          │ (External Platform) │
                          └─────────────────────┘
```

### 1.2 互通层次

| 互通层次 | 通信协议 | 说明 |
|---------|---------|------|
| 前端与后端互通 | RESTful API、WebSocket | 前端控制台与后端服务的通信 |
| 后端与Agent互通 | WebSocket、消息队列（MQ） | 后端服务与运营代理的通信 |
| Agent与平台互通 | 平台API、浏览器自动化 | 运营代理与第三方平台的通信 |

## 2. 前端与后端互通

### 2.1 API通信

| 项目 | 规范 |
|------|------|
| **基础API** | RESTful风格，支持CRUD操作 |
| **认证机制** | JWT Token（JSON Web Token），支持Bearer认证 |
| **请求格式** | JSON格式，统一错误处理 |
| **响应格式** | 统一响应体结构 |

**标准响应格式**：
```json
{
  "code": 200,
  "message": "success",
  "data": { /* 业务数据 */ },
  "timestamp": "2026-03-21T10:30:00Z"
}
```

### 2.2 WebSocket通信

| 功能 | 说明 |
|------|------|
| **实时数据推送** | 店铺状态、任务进度、操作结果实时同步 |
| **事件通知** | 操作完成、异常告警、系统通知 |
| **心跳保活** | 保持连接活跃，支持断线重连机制 |

**WebSocket消息格式**：
```json
{
  "type": "event|data|heartbeat",
  "event": "task_completed|error|notification",
  "payload": { /* 消息内容 */ },
  "timestamp": "2026-03-21T10:30:00Z"
}
```

### 2.3 前端API调用示例
```typescript
// 绑定店铺
const bindStore = async (storeData) => {
  const response = await fetch('/api/operation-agent/stores', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(storeData)
  });
  return response.json();
};

// 同步商品
const syncProducts = async (storeId) => {
  const response = await fetch(`/api/operation-agent/stores/${storeId}/products/sync`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  return response.json();
};
```

## 3. 后端与运营代理（Agent）互通

### 3.1 WebSocket通信

| 特性 | 说明 |
|------|------|
| **双向通信** | 后端下发任务，Agent回传执行结果 |
| **加密传输** | TLS/SSL加密，确保通信安全 |
| **认证机制** | Agent注册时进行身份验证（Token-based） |
| **消息格式** | 统一JSON消息格式 |

**任务下发消息格式**：
```json
{
  "type": "task",
  "taskId": "task-123",
  "action": "syncProducts",
  "params": {
    "storeId": "store-123",
    "limit": 100
  },
  "priority": "high|normal|low",
  "timeout": 300000
}
```

### 3.2 消息队列（Message Queue）

| 特性 | 说明 | 技术选型 |
|------|------|---------|
| **任务分发** | 异步任务分发，解耦前后端 | RabbitMQ / Redis / BullMQ |
| **任务优先级** | 支持高、中、低优先级任务 | Priority Queue |
| **任务持久化** | 确保任务不丢失，支持故障恢复 | Persistent Storage |
| **失败重试** | 自动重试机制，支持指数退避（Exponential Backoff） | Retry Policy |

### 3.3 状态同步

| 机制 | 说明 | 频率 |
|------|------|------|
| **心跳保活** | Agent定期发送心跳，报告运行状态 | 每30秒 |
| **状态回传** | 任务执行状态实时回传到后端 | 实时 |
| **健康检查** | 后端定期检查Agent健康状态 | 每60秒 |

### 3.4 后端API调用示例
```typescript
// 向Agent下发任务
const sendTaskToAgent = async (agentId, task) => {
  const ws = getAgentWebSocket(agentId);
  if (ws && ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({
      type: 'task',
      taskId: generateTaskId(),
      action: task.action,
      params: task.params
    }));
  } else {
    // 发送到消息队列
    await messageQueue.send('agent-tasks', {
      agentId,
      task
    });
  }
};

// 处理Agent回传
const handleAgentResponse = (message) => {
  const data = JSON.parse(message);
  switch (data.type) {
    case 'task_result':
      handleTaskResult(data.taskId, data.result);
      break;
    case 'heartbeat':
      updateAgentStatus(data.agentId, data.status);
      break;
    case 'error':
      handleAgentError(data.agentId, data.error);
      break;
  }
};
```

## 4. 运营代理与第三方平台互通

### 4.1 平台API调用

| 项目 | 说明 |
|------|------|
| **认证机制** | OAuth 2.0、API密钥（API Key）、签名认证等 |
| **请求格式** | 符合各平台API规范（RESTful/GraphQL） |
| **响应处理** | 统一解析和错误处理，标准化输出 |
| **速率限制** | 遵守平台API Rate Limit，实现限流保护 |

### 4.2 浏览器自动化（Browser Automation）

| 技术 | 说明 |
|------|------|
| **无界面浏览器** | Puppeteer / Playwright / Selenium |
| **操作模拟** | 点击、输入、滚动、表单提交等用户行为模拟 |
| **数据提取** | DOM解析、XPath/CSS选择器、数据抓取 |
| **异常处理** | 页面变化检测、验证码识别、反爬策略应对 |

### 4.3 适配器模式（Adapter Pattern）

| 组件 | 说明 |
|------|------|
| **统一接口** | `IPlatformAdapter` 接口定义标准操作 |
| **平台实现** | 每个平台独立实现适配器（Platform-specific Adapter） |
| **数据标准化** | 统一数据模型，标准化输出格式 |
| **错误处理** | 平台特定错误捕获、转换、上报 |

### 4.4 Agent平台调用示例
```typescript
// 使用平台适配器同步商品
async function syncProducts(storeId, platform) {
  const adapter = platformAdapterFactory.createAdapter(platform);
  try {
    // 授权
    await adapter.authorize(getAuthInfo(storeId));
    
    // 获取商品列表
    const products = await adapter.getProducts(100, 0);
    
    // 处理商品数据
    const processedProducts = processProducts(products);
    
    // 回传数据
    await sendToBackend({
      type: 'products_synced',
      storeId,
      products: processedProducts
    });
  } catch (error) {
    // 处理错误
    await sendToBackend({
      type: 'error',
      storeId,
      error: error.message
    });
  }
}
```

## 5. 远程人工交互互通

### 5.1 实时屏幕传输（Real-time Screen Streaming）

| 技术 | 说明 |
|------|------|
| **屏幕捕获** | 使用 Puppeteer / Playwright 捕获浏览器屏幕 |
| **编码压缩** | JPEG / WEBP / H.264 编码，降低传输带宽 |
| **实时传输** | WebSocket / WebRTC 实时传输屏幕数据 |
| **前端渲染** | Canvas / Video 元素渲染远程屏幕 |

### 5.2 操作指令传输（Remote Control）

| 环节 | 说明 |
|------|------|
| **操作捕获** | 前端捕获用户点击、输入、滚动等操作 |
| **坐标映射** | 将前端坐标转换为远程浏览器坐标（Resolution Mapping） |
| **指令传输** | WebSocket 传输操作指令到 Agent |
| **指令执行** | Agent 在远程浏览器执行操作指令 |

### 5.3 会话管理（Session Management）

| 功能 | 说明 |
|------|------|
| **会话创建** | 后端创建远程交互会话，分配资源 |
| **权限验证** | 验证用户权限，确保操作安全 |
| **状态跟踪** | 会话状态机：初始化 → 活跃 → 空闲 → 结束 |
| **资源清理** | 会话结束时清理资源，保存操作日志 |

### 5.4 远程交互示例
```typescript
// 前端捕获点击操作
const handleCanvasClick = (e) => {
  const rect = canvas.getBoundingClientRect();
  const x = e.clientX - rect.left;
  const y = e.clientY - rect.top;
  
  // 发送点击指令
  ws.send(JSON.stringify({
    type: 'user_action',
    action: {
      type: 'click',
      x,
      y
    }
  }));
};

// Agent执行操作指令
const handleUserAction = async (page, action) => {
  switch (action.type) {
    case 'click':
      await page.mouse.click(action.x, action.y);
      break;
    case 'type':
      await page.keyboard.type(action.text);
      break;
    case 'keypress':
      await page.keyboard.press(action.key);
      break;
  }
};
```

## 6. 多Agent互通

### 6.1 Agent管理服务（Agent Management Service）

| 功能 | 说明 |
|------|------|
| **Agent注册** | Agent启动时向管理服务注册，上报元数据 |
| **资源分配** | 根据店铺需求、任务类型分配Agent资源 |
| **负载均衡** | 基于负载的任务分发（Load Balancing） |
| **健康监控** | 实时监控Agent健康状态、性能指标 |

### 6.2 Agent间通信（Inter-Agent Communication）

| 场景 | 说明 |
|------|------|
| **任务协调** | 避免多Agent操作同一店铺产生冲突 |
| **资源共享** | 共享配置、状态信息、缓存数据 |
| **故障转移** | Agent故障时自动转移任务（Failover） |

### 6.3 多VPS部署（Multi-VPS Deployment）

| 功能 | 说明 |
|------|------|
| **VPS管理** | 管理多VPS资源池，动态分配 |
| **IP隔离** | 同平台店铺使用不同IP，避免关联 |
| **网络配置** | 配置VPS网络、防火墙、代理 |
| **自动化部署** | CI/CD自动化部署和配置Agent |

### 6.4 Agent管理示例
```typescript
// 分配任务到合适的Agent
function assignTask(task) {
  const store = getStoreById(task.storeId);
  
  if (store.requiresIpIsolation) {
    // 需要IP隔离的店铺，使用专用Agent
    return findDedicatedAgent(store);
  } else {
    // 不需要IP隔离的店铺，使用负载最低的Agent
    return findLeastLoadedAgent(store.platform);
  }
}

// 监控Agent健康状态
function monitorAgents() {
  setInterval(async () => {
    const agents = await getAllAgents();
    for (const agent of agents) {
      if (!agent.heartbeatReceived) {
        // Agent可能离线，触发故障转移
        await failoverAgent(agent.id);
      }
    }
  }, 30000); // 每30秒检查一次
}
```

## 7. 安全互通

### 7.1 认证与授权（Authentication & Authorization）

| 层级 | 机制 | 说明 |
|------|------|------|
| **API认证** | JWT Token + Refresh Token | 定期轮换，支持无感知续期 |
| **Agent认证** | API Key + HMAC签名 | 基于密钥的双向认证 |
| **权限控制** | RBAC（基于角色的访问控制） | 角色-权限-资源三级管控 |
| **操作审计** | Audit Log | 全链路操作记录，支持追溯 |

### 7.2 数据安全（Data Security）

| 措施 | 说明 |
|------|------|
| **传输加密** | TLS 1.3 / SSL，端到端加密 |
| **存储加密** | AES-256-GCM 加密敏感数据 |
| **凭证管理** | 使用密钥管理服务（KMS），禁止明文存储 |
| **数据脱敏** | API返回数据按需脱敏（PII保护） |
| **访问控制** | 细粒度权限控制，最小权限原则 |

### 7.3 网络安全（Network Security）

| 措施 | 说明 |
|------|------|
| **TLS加密** | 所有通信强制使用TLS 1.3 |
| **防火墙** | VPS防火墙 + 云防火墙双层防护 |
| **速率限制** | API限流（Rate Limiting），防止滥用 |
| **DDoS防护** | 云厂商DDoS防护 + 应用层限流 |
| **IP白名单** | 关键接口限制访问IP范围 |

### 7.4 安全最佳实践

| 实践 | 说明 |
|------|------|
| **最小权限原则** | Agent仅获取执行任务所需的最小权限 |
| **安全审计** | 定期安全审计，检查配置和代码 |
| **漏洞扫描** | 自动化漏洞扫描（SAST/DAST） |
| **依赖管理** | 及时更新依赖，修复安全漏洞 |
| **密钥轮换** | 定期轮换API密钥和证书 |

## 8. 性能优化

### 8.1 通信优化

| 优化手段 | 说明 |
|---------|------|
| **消息压缩** | Gzip / Brotli 压缩传输数据，减少带宽使用 |
| **批量处理** | 批量发送和处理数据，减少请求次数（Batch Processing） |
| **缓存策略** | Redis 缓存常用数据，减少重复请求 |
| **异步处理** | 非关键操作异步处理，提高响应速度（Async/Await） |
| **长连接** | WebSocket 长连接，减少连接建立开销 |

### 8.2 资源优化

| 资源类型 | 优化措施 |
|---------|---------|
| **连接池** | 数据库连接池、HTTP连接池，复用连接 |
| **内存管理** | 优化内存使用，避免内存泄漏，定期GC |
| **CPU优化** | 减少CPU密集型操作，使用Worker线程 |
| **磁盘I/O** | 减少磁盘I/O，使用内存缓存和SSD |
| **网络I/O** | 合并请求，使用HTTP/2或HTTP/3 |

### 8.3 监控与调优

| 环节 | 说明 |
|------|------|
| **性能监控** | APM工具（如Prometheus + Grafana）实时监控系统性能指标 |
| **瓶颈分析** | 识别性能瓶颈（CPU/内存/网络/磁盘），进行针对性优化 |
| **负载测试** | 使用JMeter/k6模拟高负载场景，测试系统性能 |
| **自动调优** | 根据负载自动调整系统参数（Auto-scaling） |

## 9. 容错与灾备（Fault Tolerance & Disaster Recovery）

### 9.1 错误处理（Error Handling）

| 机制 | 说明 |
|------|------|
| **异常捕获** | 全局异常捕获，统一错误处理（Try-Catch + Global Handler） |
| **错误重试** | 自动重试失败操作，支持指数退避（Exponential Backoff） |
| **降级策略** | 服务降级（Degradation），保障核心功能可用 |
| **错误通知** | 实时告警通知（钉钉/飞书/邮件），及时响应 |

### 9.2 故障恢复（Fault Recovery）

| 措施 | 说明 |
|------|------|
| **数据备份** | 定期全量+增量备份，异地多副本存储 |
| **灾难恢复** | 制定DR计划，RPO<1小时，RTO<4小时 |
| **高可用性** | 多Agent部署，无单点故障（HA Architecture） |
| **自动恢复** | Agent故障自动重启，任务自动重分配 |

### 9.3 容灾方案（Disaster Recovery）

| 方案 | 说明 |
|------|------|
| **多区域部署** | 多可用区（AZ）部署，避免单点故障 |
| **数据同步** | 跨区域数据实时同步，确保数据一致性 |
| **故障转移** | 自动故障转移（Automatic Failover） |
| **业务连续性** | 确保业务持续运行（Business Continuity） |

## 10. 总结

系统互通是 Crawlful Hub 的核心设计之一，通过标准化的通信机制和接口，实现了前端控制台、后端服务、运营代理（Agent）和第三方平台之间的无缝互通。这种设计不仅提高了系统的可扩展性和可维护性，也为 100% AI 开发测试落地提供了坚实的技术基础。

在实际部署中，需要根据具体的业务需求和技术环境，选择合适的互通方案，并不断优化和改进，以适应不断变化的业务需求和技术发展。

---

## 11. 互通规范

### 11.1 接口命名规范

| 项目 | 规范 |
|------|------|
| **API路径** | RESTful风格，小写字母，单词间用连字符（kebab-case）<br>示例：`/api/v1/product-management/products` |
| **方法命名** | 驼峰命名法（camelCase），动词+名词格式<br>示例：`getProductList`、`createOrder` |
| **参数命名** | 驼峰命名法（camelCase），清晰表达参数含义<br>示例：`pageSize`、`sortBy` |

### 11.2 消息格式规范

| 项目 | 规范 |
|------|------|
| **数据格式** | 所有通信使用 JSON 格式（application/json） |
| **消息结构** | 统一包含 `type`、`data`、`timestamp`、`traceId` 等字段 |
| **错误处理** | 统一错误码和错误消息格式，支持国际化（i18n） |

**标准消息格式示例**：
```json
{
  "type": "event|data|error|heartbeat",
  "event": "task_completed|error|notification",
  "data": { /* 业务数据 */ },
  "timestamp": "2026-03-21T10:30:00Z",
  "traceId": "trace-123456",
  "code": 200,
  "message": "success"
}
```

### 11.3 安全规范
- **认证**：所有API调用必须进行身份认证
- **授权**：基于角色的访问控制
- **加密**：所有传输数据必须加密
- **审计**：所有操作必须记录审计日志

### 11.4 性能规范
- **响应时间**：API响应时间不超过500ms
- **并发处理**：支持高并发请求
- **缓存策略**：合理使用缓存减少响应时间
- **批量处理**：支持批量操作减少请求次数

## 12. 互通示例

### 12.1 完整业务流程示例

#### 商品采集流程
1. **前端**：用户选择平台，设置采集参数
2. **后端**：`ProductController`接收请求，调用`ProductService`
3. **后端**：`ProductService`生成采集任务，发送到消息队列
4. **Agent**：接收任务，调用对应平台Adapter执行采集
5. **Agent**：回传采集结果到后端
6. **后端**：`ProductService`处理采集结果，存储到数据库
7. **后端**：通过WebSocket推送采集结果到前端
8. **前端**：展示采集结果，提供后续操作入口

#### 自动上架流程
1. **前端**：用户设置上架参数，触发自动上架
2. **后端**：`AutoListingController`接收请求，调用`AutoListingService`
3. **后端**：`AutoListingService`生成上架任务，发送到消息队列
4. **Agent**：接收任务，调用平台Adapter执行上架
5. **Agent**：回传上架结果和截图到后端
6. **后端**：`AutoListingService`更新任务状态，存储上架结果
7. **后端**：通过WebSocket推送上架结果到前端
8. **前端**：展示上架状态，提供效果分析

## 13. 未来扩展

### 13.1 微服务架构
- **服务拆分**：将核心服务拆分为独立的微服务
- **服务发现**：使用服务发现机制管理服务实例
- **负载均衡**：自动负载均衡提高系统可用性
- **容错机制**：服务降级和熔断保护

### 13.2 事件驱动架构
- **事件总线**：使用消息队列实现事件驱动
- **事件溯源**：通过事件记录系统状态变更
- **CQRS**：命令查询责任分离，提高系统性能

### 13.3 边缘计算
- **边缘Agent**：在边缘节点部署Agent，减少延迟
- **本地处理**：部分计算在本地完成，减少网络传输
- **智能调度**：根据网络状况和负载自动调度任务