refactor: 重构项目结构并优化类型定义

- 移除extension模块,将功能迁移至node-agent
- 修复类型导出问题,使用export type明确类型导出
- 统一数据库连接方式,从直接导入改为使用config/database
- 更新文档中的项目结构描述
- 添加多个服务的实用方法,如getForecast、getBalances等
- 修复类型错误和TS1205警告
- 优化RedisService调用方式
- 添加新的实体类型定义
- 更新审计日志格式,统一字段命名
This commit is contained in:
2026-03-21 15:04:06 +08:00
parent 888d3844f3
commit 15ee1758f5
286 changed files with 9110 additions and 21453 deletions

View File

@@ -218,7 +218,7 @@ project
├─ .trae/rules/ # 编码与项目特定规则
├─ docs/ # 分类文档 (业务、数据、架构、规范、质量)
├─ server/src/ # 后端服务 (api, service, repository, domains, workers)
├─ extension/src/ # 浏览器插件 (background, content)
├─ node-agent/src/ # Playwright自动化代理 (无API平台执行)
├─ console/src/ # 前端控制台 (pages, components, services, stores)
```

View File

@@ -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 |

View File

@@ -0,0 +1,305 @@
# 业务闭环任务列表
> **创建日期**: 2026-03-20
> **状态**: 进行中
> **优先级**: 最高
---
## 🔒 当前任务占用状态
| Agent | 占用模块 | 涉及任务 | 主要文件 | 开始时间 | 状态 |
|-------|----------|----------|----------|----------|------|
| AI-Backend-1 | 编译错误修复 | BE-COMP001~BE-COMP010 | 多个服务文件 | 2026-03-20 10:00 | 🔒 进行中 |
---
## 1. P0 核心闭环任务 (立即执行)
### 1.1 商品采集刊登闭环
| 任务ID | 任务描述 | 前端 | 后端 | 插件 | 状态 |
|--------|----------|------|------|------|------|
| BE-P001 | 商品采集服务完善 | - | ProductService | Node Agent | ✅ 已完成 |
| BE-P002 | 自动刊登服务完善 | - | AutoListingService | Node Agent | ⚠️ 需修复 |
| BE-P003 | 定价服务完善 | - | PricingService | - | ✅ 已完成 |
| BE-P004 | 商品状态机实现 | - | ProductStateMachine | - | ✅ 已完成 |
| FE-P001 | 商品列表页面 | ProductList | - | - | ✅ 已完成 |
| FE-P002 | 商品详情页面 | ProductDetail | - | - | ✅ 已完成 |
| FE-P003 | 商品刊登表单 | ProductPublishForm | - | - | ✅ 已完成 |
| PL-P001 | TikTok采集适配器 | - | - | TikTokAdapter | 📝 待开发 |
| PL-P002 | Temu采集适配器 | - | - | TemuAdapter | 📝 待开发 |
| PL-P003 | Amazon采集适配器 | - | - | AmazonAdapter | ✅ 已完成 |
### 1.2 订单履约闭环
| 任务ID | 任务描述 | 前端 | 后端 | 插件 | 状态 |
|--------|----------|------|------|------|------|
| BE-O001 | 订单服务完善 | - | OrderService | - | ✅ 已完成 |
| BE-O002 | 订单聚合服务 | - | OrderAggregationService | - | ✅ 已完成 |
| BE-O003 | 统一履约服务 | - | UnifiedFulfillmentService | - | ✅ 已完成 |
| BE-O004 | 订单状态机实现 | - | OrderStateMachine | - | ✅ 已完成 |
| FE-O001 | 订单列表页面 | OrderList | - | - | ✅ 已完成 |
| FE-O002 | 订单详情页面 | OrderDetail | - | - | ✅ 已完成 |
| FE-O003 | 异常订单页面 | ExceptionOrder | - | - | ✅ 已完成 |
| PL-O001 | 订单处理适配器 | - | - | OrderAdapter | 📝 待开发 |
### 1.3 财务对账闭环
| 任务ID | 任务描述 | 前端 | 后端 | 插件 | 状态 |
|--------|----------|------|------|------|------|
| BE-F001 | 财务服务完善 | - | FinanceService | - | ✅ 已完成 |
| BE-F002 | 对账服务完善 | - | ReconciliationService | - | ✅ 已完成 |
| BE-F003 | 利润核算服务 | - | OrderProfitService | - | ✅ 已完成 |
| BE-F004 | 结算服务完善 | - | SettlementService | - | ✅ 已完成 |
| FE-F001 | 交易记录页面 | Transactions | - | - | ✅ 已完成 |
| FE-F002 | 对账页面 | Reconciliation | - | - | ✅ 已完成 |
---
## 2. P1 重要闭环任务 (近期执行)
### 2.1 广告营销闭环
| 任务ID | 任务描述 | 前端 | 后端 | 插件 | 状态 |
|--------|----------|------|------|------|------|
| BE-AD001 | 营销服务完善 | - | MarketingService | - | ✅ 已完成 |
| BE-AD002 | 广告优化服务 | - | AdOpsService | - | ✅ 已完成 |
| BE-AD003 | ROI分析服务 | - | ROIAnalysisService | - | ✅ 已完成 |
| FE-AD001 | 广告计划页面 | AdPlanPage | - | - | ✅ 已完成 |
| FE-AD002 | 广告投放页面 | AdDelivery | - | - | ✅ 已完成 |
| FE-AD003 | ROI分析页面 | ROIAnalysis | - | - | ✅ 已完成 |
| PL-AD001 | 广告管理适配器 | - | - | AdAdapter | 📝 待开发 |
### 2.2 库存管理闭环
| 任务ID | 任务描述 | 前端 | 后端 | 插件 | 状态 |
|--------|----------|------|------|------|------|
| BE-INV001 | 库存服务完善 | - | InventoryService | - | ⚠️ 需修复 |
| BE-INV002 | 库存预测服务 | - | InventoryForecastService | - | ✅ 已完成 |
| BE-INV003 | 仓库管理服务 | - | WMSWaveService | - | ✅ 已完成 |
| FE-INV001 | 库存预测页面 | InventoryForecast | - | - | ✅ 已完成 |
| FE-INV002 | 仓库管理页面 | Warehouses | - | - | ✅ 已完成 |
| PL-INV001 | 库存同步适配器 | - | - | InventoryAdapter | 📝 待开发 |
### 2.3 物流管理闭环
| 任务ID | 任务描述 | 前端 | 后端 | 插件 | 状态 |
|--------|----------|------|------|------|------|
| BE-LOG001 | 物流服务完善 | - | LogisticsService | - | ✅ 已完成 |
| BE-LOG002 | 运费计算服务 | - | DynamicShippingService | - | ✅ 已完成 |
| BE-LOG003 | 物流跟踪服务 | - | LogisticsTrackerService | - | ✅ 已完成 |
| FE-LOG001 | 物流跟踪页面 | LogisticsTrack | - | - | ✅ 已完成 |
| FE-LOG002 | 运费计算页面 | FreightCalc | - | - | ✅ 已完成 |
### 2.4 B2B贸易闭环
| 任务ID | 任务描述 | 前端 | 后端 | 插件 | 状态 |
|--------|----------|------|------|------|------|
| BE-B2B001 | B2B贸易服务 | - | B2BTradeService | - | ✅ 已完成 |
| BE-B2B002 | 企业报价服务 | - | EnterpriseQuoteService | - | ✅ 已完成 |
| BE-B2B003 | 批量订单服务 | - | BatchOrderService | - | ✅ 已完成 |
| FE-B2B001 | 企业报价页面 | EnterpriseQuote | - | - | ✅ 已完成 |
| FE-B2B002 | 批量订单页面 | BatchOrder | - | - | ✅ 已完成 |
| FE-B2B003 | 合同管理页面 | ContractManage | - | - | ✅ 已完成 |
### 2.5 合规管理闭环
| 任务ID | 任务描述 | 前端 | 后端 | 插件 | 状态 |
|--------|----------|------|------|------|------|
| BE-COMP001 | 合规服务完善 | - | ComplianceService | - | ⚠️ 需修复 |
| BE-COMP002 | 证书数据库服务 | - | CertificateDatabaseService | - | ⚠️ 需修复 |
| BE-COMP003 | 合规检查服务 | - | ComplianceGateService | - | ⚠️ 需修复 |
| FE-COMP001 | 证书管理页面 | CertificateManage | - | - | ✅ 已完成 |
| FE-COMP002 | 合规检查页面 | ComplianceCheck | - | - | ✅ 已完成 |
---
## 3. P2 增强闭环任务 (后续执行)
### 3.1 多商户闭环
| 任务ID | 任务描述 | 前端 | 后端 | 插件 | 状态 |
|--------|----------|------|------|------|------|
| BE-M001 | 商户服务完善 | - | MerchantService | - | ✅ 已完成 |
| BE-M002 | 商户结算服务 | - | MerchantSettlementService | - | ✅ 已完成 |
| BE-M003 | 商户店铺服务 | - | MerchantShopService | - | ✅ 已完成 |
| FE-M001 | 商户管理页面 | MerchantManage | - | - | ✅ 已完成 |
| FE-M002 | 商户结算页面 | MerchantSettlementManage | - | - | ✅ 已完成 |
### 3.2 AI自动化闭环
| 任务ID | 任务描述 | 前端 | 后端 | 插件 | 状态 |
|--------|----------|------|------|------|------|
| BE-AI001 | AI服务完善 | - | AIService | - | ⚠️ 需修复 |
| BE-AI002 | 自动选品服务 | - | ProductSelectionService | - | ✅ 已完成 |
| BE-AI003 | 自动定价服务 | - | DynamicPricingAGIService | - | ✅ 已完成 |
| BE-AI004 | 智能客服服务 | - | ChatBotService | - | ✅ 已完成 |
| FE-AI001 | 自动选品页面 | AutoProductSelection | - | - | ✅ 已完成 |
| FE-AI002 | 动态定价页面 | DynamicPricing | - | - | ✅ 已完成 |
### 3.3 治理闭环
| 任务ID | 任务描述 | 前端 | 后端 | 插件 | 状态 |
|--------|----------|------|------|------|------|
| BE-G001 | RBAC引擎完善 | - | RBACEngine | - | ✅ 已完成 |
| BE-G002 | 审批服务完善 | - | ApprovalService | - | ✅ 已完成 |
| BE-G003 | 审计服务完善 | - | AuditService | - | ✅ 已完成 |
| BE-G004 | 配额治理服务 | - | QuotaGovernanceService | - | ✅ 已完成 |
---
## 4. 编译错误修复任务
### 4.1 Server编译错误
| 任务ID | 错误类型 | 数量 | 状态 |
|--------|----------|------|------|
| BE-COMP001 | TS2339 (属性不存在) | 101 | 🔒 进行中 |
| BE-COMP002 | TS2576 (参数数量不匹配) | 72 | 📝 待处理 |
| BE-COMP003 | TS2345 (参数类型不匹配) | 54 | 📝 待处理 |
| BE-COMP004 | TS2322 (类型不匹配) | 54 | 📝 待处理 |
| BE-COMP005 | TS7006 (隐式any) | 40 | 📝 待处理 |
| BE-COMP006 | TS2307 (模块未找到) | 32 | 📝 待处理 |
| BE-COMP007 | TS2564 (属性未初始化) | 30 | 📝 待处理 |
| BE-COMP008 | TS2554 (参数数量不匹配) | 29 | 📝 待处理 |
### 4.2 Dashboard编译错误
| 任务ID | 错误类型 | 数量 | 状态 |
|--------|----------|------|------|
| FE-COMP001 | TS2322 (类型不匹配) | TBD | 📝 待处理 |
| FE-COMP002 | 其他类型错误 | TBD | 📝 待处理 |
---
## 5. Node Agent任务
### 5.1 核心框架
| 任务ID | 任务描述 | 状态 |
|--------|----------|------|
| NA-001 | Node Agent基础框架 | ✅ 已完成 |
| NA-002 | 任务调度器实现 | ✅ 已完成 |
| NA-003 | 任务执行引擎 | ✅ 已完成 |
| NA-004 | 结果上报机制 | ✅ 已完成 |
| NA-005 | 反检测系统 | 📝 待开发 |
### 5.2 平台适配器
| 任务ID | 平台 | 状态 |
|--------|------|------|
| NA-TIKTOK | TikTok Shop适配器 | 📝 待开发 |
| NA-TEMU | Temu适配器 | 📝 待开发 |
| NA-AMAZON | Amazon适配器 | ✅ 已完成 |
| NA-SHOPEE | Shopee适配器 | ✅ 已完成 |
| NA-ALIEXPRESS | AliExpress适配器 | ✅ 已完成 |
| NA-1688 | 1688适配器 | 📝 待开发 |
---
## 6. 后台管理任务
### 6.1 用户权限管理
| 任务ID | 任务描述 | 前端 | 后端 | 状态 |
|--------|----------|------|------|------|
| ADM-001 | 用户管理页面 | UserManagement | UserService | ✅ 已完成 |
| ADM-002 | 角色管理页面 | RoleManagement | RBACEngine | ✅ 已完成 |
| ADM-003 | 权限管理 | - | PermissionService | ✅ 已完成 |
### 6.2 租户管理
| 任务ID | 任务描述 | 前端 | 后端 | 状态 |
|--------|----------|------|------|------|
| ADM-010 | 租户管理页面 | TenantSettings | TenantService | ✅ 已完成 |
| ADM-011 | 配额管理 | - | QuotaGovernanceService | ✅ 已完成 |
| ADM-012 | 数据隔离 | - | DataIsolationService | ✅ 已完成 |
### 6.3 监控审计
| 任务ID | 任务描述 | 前端 | 后端 | 状态 |
|--------|----------|------|------|------|
| ADM-020 | 监控中心 | Monitoring | MonitoringService | ✅ 已完成 |
| ADM-021 | 审计中心 | - | AuditService | ✅ 已完成 |
| ADM-022 | 告警管理 | - | AlertService | ✅ 已完成 |
---
## 7. 任务统计
### 7.1 总体进度
| 类别 | 总数 | 已完成 | 进行中 | 待处理 |
|------|------|--------|--------|--------|
| 后端服务 | 45 | 38 | 5 | 2 |
| 前端页面 | 35 | 35 | 0 | 0 |
| 插件适配器 | 10 | 4 | 0 | 6 |
| 编译修复 | 8 | 0 | 1 | 7 |
| 后台管理 | 15 | 15 | 0 | 0 |
| **总计** | **113** | **92** | **6** | **15** |
### 7.2 完成率
```
总体完成率: 81.4%
├── 后端服务: 84.4%
├── 前端页面: 100%
├── 插件适配器: 40%
├── 编译修复: 0%
└── 后台管理: 100%
```
---
## 8. 下一步行动
### 8.1 立即执行 (本周)
1. **修复编译错误** (BE-COMP001~BE-COMP008)
- 修复TS2339错误 (属性不存在)
- 修复TS2576错误 (参数数量不匹配)
- 修复TS2322错误 (类型不匹配)
2. **完善关键服务**
- InventoryService.updateStock方法
- ComplianceService.searchKeyword属性
- PublishService.publishToPlatform方法
### 8.2 近期执行 (下周)
3. **开发Node Agent适配器**
- TikTok Shop适配器
- Temu适配器
- 1688适配器
4. **完善反检测系统**
- 指纹隔离
- 代理轮换
- 行为模拟
### 8.3 后续执行 (本月)
5. **集成测试**
- 前后端集成测试
- 插件集成测试
- 端到端测试
6. **性能优化**
- 数据库查询优化
- 缓存策略优化
- API响应优化
---
## 9. 相关文档
- [前后端插件闭环架构](../01_Architecture/17_Frontend_Backend_Plugin_ClosedLoop.md)
- [全局功能方案](../01_Architecture/18_Global_Features_Plan.md)
- [Agent功能方案](../01_Architecture/19_Agent_Features_Plan.md)
- [后台管理方案](../01_Architecture/20_Admin_System_Plan.md)
- [Task Overview](../00_Business/Task_Overview.md)
---
*最后更新: 2026-03-20*