refactor: 重构项目结构并优化类型定义
- 移除extension模块，将功能迁移至node-agent - 修复类型导出问题，使用export type明确类型导出 - 统一数据库连接方式，从直接导入改为使用config/database - 更新文档中的项目结构描述 - 添加多个服务的实用方法，如getForecast、getBalances等 - 修复类型错误和TS1205警告 - 优化RedisService调用方式 - 添加新的实体类型定义 - 更新审计日志格式，统一字段命名
This commit is contained in:
@@ -179,3 +179,202 @@
|
||||
| 跨店订单量 | 跨店铺订单数量 | TOC + TOB |
|
||||
| 数据隔离有效性 | 数据隔离的成功率 | TOC + TOB |
|
||||
| 报表生成效率 | 报表生成的平均时间 | TOC + TOB |
|
||||
|
||||
***
|
||||
|
||||
## 7️⃣7️⃣ Node Agent 任务执行闭环（Node Agent Task Execution Loop）
|
||||
|
||||
- **目标**：通过 Playwright 自动化代理执行无 API 平台的操作任务，实现采集、刊登、订单处理等自动化。
|
||||
- **架构**：
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ Server │◄────►│ Hub │◄────►│ Node-Agent │
|
||||
│ (主控端) │ │ (任务调度) │ │ (Playwright)│
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
│
|
||||
┌──────▼──────┐
|
||||
│ Chromium │
|
||||
│ (无API平台) │
|
||||
└─────────────┘
|
||||
```
|
||||
- **流程**：
|
||||
1. **节点注册**：
|
||||
- Node Agent 启动时向 Hub 注册
|
||||
- 上报节点 ID、版本、操作系统、主机名
|
||||
- 加载本地店铺配置
|
||||
2. **心跳维持**：
|
||||
- 定时向 Hub 发送心跳（默认 30 秒）
|
||||
- 维持节点在线状态
|
||||
- 检测连接异常并自动重连
|
||||
3. **任务轮询**：
|
||||
- 定时从 Hub 拉取任务（默认 10 秒）
|
||||
- 获取待执行的任务队列
|
||||
- 按优先级和店铺隔离规则执行
|
||||
4. **任务执行**：
|
||||
- 启动 Playwright 浏览器实例
|
||||
- 配置代理 IP 和浏览器指纹
|
||||
- 执行具体任务（采集/刊登/订单处理）
|
||||
- 收集执行结果和截图
|
||||
5. **结果上报**：
|
||||
- 向 Hub 上报任务执行结果
|
||||
- 包含状态、数据、错误信息
|
||||
- 支持重试机制
|
||||
- **任务类型**：
|
||||
| 任务类型 | 说明 | 适用平台 |
|
||||
|---------|------|---------|
|
||||
| `COLLECT_PRODUCT` | 商品数据采集 | TikTok Shop, Temu, 1688 |
|
||||
| `COLLECT_ORDER` | 订单数据采集 | TikTok Shop, Temu |
|
||||
| `PUBLISH_PRODUCT` | 商品刊登 | TikTok Shop, Temu |
|
||||
| `PROCESS_ORDER` | 订单处理（发货、取消） | TikTok Shop, Temu |
|
||||
| `SYNC_INVENTORY` | 库存同步 | TikTok Shop, Temu |
|
||||
| `MANAGE_AD` | 广告管理 | TikTok Shop |
|
||||
- **店铺隔离策略**：
|
||||
- **一店一上下文**：每个店铺独立的 profileDir、proxy、fingerprintPolicy
|
||||
- **同店任务串行**：同一店铺的任务严格串行执行
|
||||
- **跨店任务并行**：不同店铺的任务可并行执行
|
||||
- **反检测策略**：
|
||||
| 策略 | 说明 |
|
||||
|------|------|
|
||||
| **指纹隔离** | 每个店铺独立浏览器指纹 |
|
||||
| **代理 IP** | 每个店铺独立代理 |
|
||||
| **行为模拟** | 随机延迟、鼠标轨迹 |
|
||||
| **User-Agent** | 随机 UA 轮换 |
|
||||
- **决策点**：
|
||||
- 任务优先级排序
|
||||
- 浏览器实例数量控制
|
||||
- 失败重试策略
|
||||
- 异常处理机制
|
||||
- **输入**：任务配置、店铺信息、代理配置、指纹策略
|
||||
- **输出**：执行结果、采集数据、截图日志
|
||||
- **状态机**：
|
||||
- 节点：`OFFLINE` → `REGISTERING` → `ONLINE` → `BUSY` → `OFFLINE`
|
||||
- 任务：`PENDING` → `PULLED` → `EXECUTING` → `SUCCESS` / `FAILED`
|
||||
|
||||
***
|
||||
|
||||
## 7️⃣8️⃣ 前端-后端-Node Agent 调用链路闭环（Frontend-Backend-NodeAgent Call Chain Loop）
|
||||
|
||||
- **目标**：定义从前端操作到 Node Agent 执行的完整调用链路，确保数据流和状态同步。
|
||||
- **架构层次**：
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 用户操作层 │
|
||||
│ Dashboard (React) → 用户点击"采集商品"按钮 │
|
||||
└──────────────────────────┬──────────────────────────────────┘
|
||||
│ HTTP Request
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ API 网关层 │
|
||||
│ Server Controller → 权限校验 → 参数验证 → 调用 Service │
|
||||
└──────────────────────────┬──────────────────────────────────┘
|
||||
│ Service Call
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 业务逻辑层 │
|
||||
│ Service → 创建任务 → 存入数据库 → 推送到 Hub 队列 │
|
||||
└──────────────────────────┬──────────────────────────────────┘
|
||||
│ Queue Push
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 任务调度层 │
|
||||
│ Hub → 任务队列 → 分配给 Node Agent → 监控执行状态 │
|
||||
└──────────────────────────┬──────────────────────────────────┘
|
||||
│ Task Pull
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 执行代理层 │
|
||||
│ Node Agent → Playwright 执行 → 采集数据 → 上报结果 │
|
||||
└──────────────────────────┬──────────────────────────────────┘
|
||||
│ Result Report
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 数据回写层 │
|
||||
│ Hub → 更新任务状态 → 通知 Server → WebSocket 推送前端 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
- **调用链路示例**（商品采集）：
|
||||
1. **前端发起**：
|
||||
```typescript
|
||||
// Dashboard: 用户点击采集按钮
|
||||
const handleCollect = async () => {
|
||||
const result = await collectProductDataSource.create({
|
||||
platform: 'TikTok',
|
||||
shopId: 'shop-123',
|
||||
productUrl: 'https://...'
|
||||
});
|
||||
};
|
||||
```
|
||||
2. **后端处理**：
|
||||
```typescript
|
||||
// Server: Controller → Service
|
||||
@router.post('/api/v1/collect/product')
|
||||
async collectProduct(req: Request, res: Response) {
|
||||
const task = await CrawlerService.createCollectTask(req.body);
|
||||
await HubQueueService.pushTask(task);
|
||||
res.json({ taskId: task.id, status: 'PENDING' });
|
||||
}
|
||||
```
|
||||
3. **Hub 调度**：
|
||||
```typescript
|
||||
// Hub: 任务队列管理
|
||||
async pushTask(task: Task) {
|
||||
await TaskQueue.add(task);
|
||||
await this.notifyNodeAgents();
|
||||
}
|
||||
```
|
||||
4. **Node Agent 执行**：
|
||||
```typescript
|
||||
// Node Agent: Playwright 执行
|
||||
async executeTask(task: NodeTask) {
|
||||
const browser = await chromium.launch({ proxy: task.proxy });
|
||||
const page = await browser.newPage();
|
||||
const data = await this.collectProduct(page, task.payload);
|
||||
await this.reportReceipt({ taskId: task.id, data });
|
||||
}
|
||||
```
|
||||
5. **结果回写**：
|
||||
```typescript
|
||||
// Server: 接收结果
|
||||
@router.post('/api/v1/publish/receipt')
|
||||
async handleReceipt(req: Request, res: Response) {
|
||||
await CrawlerService.saveCollectResult(req.body);
|
||||
await WebSocketService.notifyFrontend(req.body.taskId, 'SUCCESS');
|
||||
}
|
||||
```
|
||||
- **状态同步机制**：
|
||||
| 机制 | 说明 |
|
||||
|------|------|
|
||||
| **WebSocket 推送** | 实时推送任务状态到前端 |
|
||||
| **轮询查询** | 前端定时查询任务状态 |
|
||||
| **事件总线** | 内部服务间状态同步 |
|
||||
- **决策点**：
|
||||
- 任务优先级设置
|
||||
- 超时处理策略
|
||||
- 失败重试机制
|
||||
- 并发控制策略
|
||||
- **输入**：用户操作、任务配置、执行参数
|
||||
- **输出**：任务状态、执行结果、通知消息
|
||||
- **状态机**：`USER_ACTION` → `API_REQUEST` → `TASK_CREATED` → `TASK_QUEUED` → `TASK_EXECUTING` → `TASK_COMPLETED` → `RESULT_SAVED` → `FRONTEND_NOTIFIED`
|
||||
|
||||
***
|
||||
|
||||
## 相关KPI
|
||||
|
||||
### Node Agent 任务执行闭环
|
||||
|
||||
| KPI 指标 | 描述 | 适用业务类型 |
|
||||
|---------|------|-------------|
|
||||
| 任务成功率 | 成功执行的任务比例 | TOC + TOB |
|
||||
| 平均执行时间 | 任务执行的平均耗时 | TOC + TOB |
|
||||
| 节点在线率 | Node Agent 在线时间比例 | TOC + TOB |
|
||||
| 采集数据准确率 | 采集数据的准确性 | TOC + TOB |
|
||||
| 反检测成功率 | 未被平台检测的成功率 | TOC + TOB |
|
||||
|
||||
### 前端-后端-Node Agent 调用链路闭环
|
||||
|
||||
| KPI 指标 | 描述 | 适用业务类型 |
|
||||
|---------|------|-------------|
|
||||
| 端到端延迟 | 从用户操作到结果返回的时间 | TOC + TOB |
|
||||
| 链路成功率 | 完整链路执行成功的比例 | TOC + TOB |
|
||||
| 状态同步延迟 | 状态更新到前端显示的时间 | TOC + TOB |
|
||||
| 错误恢复率 | 错误后自动恢复的比例 | TOC + TOB |
|
||||
|
||||
Reference in New Issue
Block a user