# 前后端插件闭环架构方案

> **创建日期**: 2026-03-20  
> **状态**: 设计中  
> **优先级**: 最高

---

## 1. 系统架构总览

### 1.1 三端闭环架构

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           Crawlful Hub Platform                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐       │
│  │   Dashboard     │     │     Server      │     │   Node Agent    │       │
│  │   (前端控制台)   │◄───►│    (后端服务)    │◄───►│   (插件代理)     │       │
│  │                 │     │                 │     │                 │       │
│  │  - 操作入口      │     │  - 业务逻辑      │     │  - 平台采集      │       │
│  │  - 状态展示      │     │  - 数据存储      │     │  - 自动化操作    │       │
│  │  - 多店铺管理    │     │  - AI策略        │     │  - 反检测        │       │
│  │  - 数据可视化    │     │  - 报表系统      │     │  - 多实例并发    │       │
│  └────────┬────────┘     └────────┬────────┘     └────────┬────────┘       │
│           │                       │                       │                 │
│           └───────────────────────┼───────────────────────┘                 │
│                                   │                                          │
│                                   ▼                                          │
│                    ┌──────────────────────────────┐                          │
│                    │      Shared Type Center      │                          │
│                    │    (统一类型定义中心)         │                          │
│                    │                              │                          │
│                    │  - messaging.ts (消息类型)   │                          │
│                    │  - domain.ts (领域类型)      │                          │
│                    │  - api.ts (API类型)          │                          │
│                    │  - plugin.ts (插件类型)      │                          │
│                    └──────────────────────────────┘                          │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 1.2 数据流向

```
用户操作 → Dashboard → Server API → Service层 → 数据库
                              ↓
                        Node Agent → 平台采集 → 数据回传
                              ↓
                        Server处理 → Dashboard展示
```

---

## 2. 前端闭环 (Dashboard)

### 2.1 页面模块

| 模块 | 页面 | 功能 | 对应后端服务 |
|------|------|------|-------------|
| **商品管理** | ProductList, ProductDetail, ProductPublishForm | 商品CRUD、刊登、定价 | ProductService |
| **订单管理** | OrderList, OrderDetail, ExceptionOrder | 订单处理、异常处理 | OrderService |
| **营销管理** | AdPlanPage, AdDelivery, ROIAnalysis | 广告计划、投放、ROI分析 | MarketingService |
| **财务管理** | Transactions, Reconciliation | 交易记录、对账 | FinanceService |
| **库存管理** | InventoryForecast, Warehouses | 库存预测、仓库管理 | InventoryService |
| **物流管理** | LogisticsTrack, FreightCalc | 物流跟踪、运费计算 | LogisticsService |
| **B2B贸易** | EnterpriseQuote, BatchOrder, ContractManage | 企业报价、批量订单、合同管理 | B2BTradeService |
| **合规管理** | CertificateManage, ComplianceCheck | 证书管理、合规检查 | ComplianceService |
| **多商户** | MerchantManage, MerchantSettlementManage | 商户管理、结算 | MerchantService |
| **系统设置** | UserManagement, TenantSettings, SystemSettings | 用户、租户、系统设置 | SettingsService |

### 2.2 DataSource层设计

```typescript
// 前端数据源抽象层
export interface DataSource<T> {
  list(params?: QueryParams): Promise<T[]>;
  get(id: string): Promise<T | null>;
  create(data: Partial<T>): Promise<T>;
  update(id: string, data: Partial<T>): Promise<T>;
  delete(id: string): Promise<void>;
}

// 实现示例
export class ProductDataSource implements DataSource<Product> {
  async list(params?: ProductQueryParams): Promise<Product[]> {
    const response = await http.get('/api/products', { params });
    return response.data;
  }
  // ...
}
```

### 2.3 状态管理

```typescript
// Umi Model 设计
export interface ModelState<T> {
  data: T[];
  loading: boolean;
  error: string | null;
  pagination: {
    current: number;
    pageSize: number;
    total: number;
  };
}
```

---

## 3. 后端闭环 (Server)

### 3.1 服务分层架构

```
Controller层 (请求处理)
    │
    ├── 参数验证 (Zod Schema)
    ├── 权限校验 (RBAC Middleware)
    └── 调用Service层
            │
Service层 (业务逻辑) ← 核心层
    │
    ├── 业务编排
    ├── 状态流转 (State Machine)
    ├── 事务管理
    └── 调用Repository层
            │
Repository层 (数据访问)
    │
    ├── 数据库CRUD (Knex.js)
    ├── 缓存操作 (Redis)
    └── 外部API调用
```

### 3.2 核心服务清单

| 领域 | 服务 | 职责 |
|------|------|------|
| **商品** | ProductService | 商品管理、SKU管理、定价 |
| **订单** | OrderService | 订单处理、履约、售后 |
| **营销** | MarketingService | 广告计划、投放优化 |
| **财务** | FinanceService | 对账、结算、利润核算 |
| **库存** | InventoryService | 库存管理、预测、补货 |
| **物流** | LogisticsService | 物流渠道、运费计算 |
| **B2B** | B2BTradeService | 企业贸易、批量订单 |
| **合规** | ComplianceService | 证书管理、合规检查 |
| **商户** | MerchantService | 多商户管理、结算 |
| **AI** | AIService | AI决策、自动化 |
| **Agent** | OperationAgentService | Agent任务调度 |

### 3.3 状态机设计

```typescript
// 订单状态机
export const OrderStateMachine = {
  states: {
    PENDING: { transitions: ['CONFIRMED', 'CANCELLED'] },
    CONFIRMED: { transitions: ['PROCESSING', 'CANCELLED'] },
    PROCESSING: { transitions: ['SHIPPED', 'EXCEPTION'] },
    SHIPPED: { transitions: ['DELIVERED', 'RETURNED'] },
    DELIVERED: { transitions: ['COMPLETED', 'RETURNED'] },
    COMPLETED: { transitions: [] },
    CANCELLED: { transitions: [] },
    RETURNED: { transitions: ['REFUNDED'] },
    REFUNDED: { transitions: [] },
    EXCEPTION: { transitions: ['PROCESSING', 'CANCELLED'] }
  }
};
```

---

## 4. 插件闭环 (Node Agent)

### 4.1 Agent架构

```
Node Agent (Playwright)
    │
    ├── 任务调度器
    │   ├── 任务轮询
    │   ├── 任务执行
    │   └── 结果上报
    │
    ├── 平台适配器
    │   ├── TikTokAdapter
    │   ├── TemuAdapter
    │   ├── AliExpressAdapter
    │   ├── AmazonAdapter
    │   └── ShopeeAdapter
    │
    └── 反检测系统
        ├── 指纹隔离
        ├── 代理IP
        └── 行为模拟
```

### 4.2 任务类型

```typescript
export enum TaskType {
  COLLECT_PRODUCT = 'COLLECT_PRODUCT',     // 商品采集
  COLLECT_ORDER = 'COLLECT_ORDER',         // 订单采集
  PUBLISH_PRODUCT = 'PUBLISH_PRODUCT',     // 商品刊登
  PROCESS_ORDER = 'PROCESS_ORDER',         // 订单处理
  SYNC_INVENTORY = 'SYNC_INVENTORY',       // 库存同步
  MANAGE_AD = 'MANAGE_AD',                 // 广告管理
  PRICE_ADJUST = 'PRICE_ADJUST',           // 价格调整
  RETURN_PROCESS = 'RETURN_PROCESS',       // 退货处理
}
```

### 4.3 通信协议

```typescript
// 任务请求
interface TaskRequest {
  taskId: string;
  traceId: string;
  tenantId: string;
  shopId: string;
  type: TaskType;
  platform: string;
  params: Record<string, any>;
  priority: 'HIGH' | 'MEDIUM' | 'LOW';
  timeout: number;
}

// 任务结果
interface TaskResult {
  taskId: string;
  traceId: string;
  status: 'SUCCESS' | 'FAILED' | 'TIMEOUT';
  data?: any;
  error?: string;
  duration: number;
}
```

---

## 5. 类型对齐方案

### 5.1 统一类型中心

```
server/src/shared/types/
├── index.ts              # 统一导出
├── domain.ts             # 领域类型
├── api.ts                # API类型
├── messaging.ts          # 消息类型
├── plugin.ts             # 插件类型
├── enums.ts              # 枚举定义
└── dto/                  # DTO类型
    ├── product.dto.ts
    ├── order.dto.ts
    └── ...
```

### 5.2 Schema驱动开发

```typescript
// 使用Zod定义Schema，自动推导类型
import { z } from 'zod';

export const ProductSchema = z.object({
  id: z.string(),
  title: z.string(),
  price: z.number(),
  status: z.enum(['DRAFT', 'PENDING', 'APPROVED', 'REJECTED']),
  // ...
});

export type Product = z.infer<typeof ProductSchema>;
```

### 5.3 前后端类型同步

```typescript
// 前端从后端导入类型
import type { Product, Order, Customer } from '@shared/types';

// 或者通过API文档生成
// openapi-typescript生成前端类型
```

---

## 6. 业务闭环清单

### 6.1 核心业务闭环

| 闭环 | 前端 | 后端 | 插件 | 状态 |
|------|------|------|------|------|
| 商品采集刊登 | ProductList, ProductPublishForm | ProductService, AutoListingService | Node Agent采集 | ✅ |
| 订单履约 | OrderList, OrderDetail | OrderService, UnifiedFulfillmentService | Node Agent订单处理 | ✅ |
| 广告营销 | AdPlanPage, ROIAnalysis | MarketingService, AdOpsService | Node Agent广告管理 | ✅ |
| 库存管理 | InventoryForecast, Warehouses | InventoryService, InventoryForecastService | Node Agent库存同步 | ✅ |
| 财务对账 | Transactions, Reconciliation | FinanceService, ReconciliationService | - | ✅ |
| B2B贸易 | EnterpriseQuote, BatchOrder | B2BTradeService | - | ✅ |
| 合规管理 | CertificateManage | ComplianceService, CertificateDatabaseService | - | ✅ |
| 多商户 | MerchantManage | MerchantService, MerchantSettlementService | - | ✅ |

### 6.2 AI自动化闭环

| 闭环 | 功能 | 服务 | 状态 |
|------|------|------|------|
| 自动选品 | AI评分、自动筛选 | ProductSelectionService, AIService | ✅ |
| 自动定价 | 动态定价、利润计算 | PricingService, DynamicPricingAGIService | ✅ |
| 自动上架 | 批量刊登、模板化 | AutoListingService | ✅ |
| 智能客服 | 自动回复、意图识别 | ChatBotService, CustomerService | ✅ |
| 异常检测 | 风险识别、自动告警 | ExceptionMonitor, IntelligentExceptionHandler | ✅ |

### 6.3 治理闭环

| 闭环 | 功能 | 服务 | 状态 |
|------|------|------|------|
| 权限管理 | RBAC、层级隔离 | RBACEngine, PermissionService | ✅ |
| 审批流程 | 工作流、审批链 | ApprovalService, WorkflowEngineService | ✅ |
| 审计日志 | 操作记录、追溯 | AuditService, AgentTraceAuditService | ✅ |
| 配额管理 | 资源限制、熔断 | QuotaGovernanceService, QuotaCircuitBreakerService | ✅ |

---

## 7. 实现优先级

### P0 - 核心闭环 (立即完成)

1. **商品采集刊登闭环**
   - 前端: ProductList, ProductPublishForm
   - 后端: ProductService, AutoListingService
   - 插件: Node Agent采集任务

2. **订单履约闭环**
   - 前端: OrderList, OrderDetail
   - 后端: OrderService, UnifiedFulfillmentService
   - 插件: Node Agent订单处理

3. **财务对账闭环**
   - 前端: Transactions, Reconciliation
   - 后端: FinanceService, ReconciliationService

### P1 - 重要闭环 (近期完成)

4. **广告营销闭环**
5. **库存管理闭环**
6. **B2B贸易闭环**
7. **合规管理闭环**

### P2 - 增强闭环 (后续完成)

8. **多商户闭环**
9. **AI自动化闭环**
10. **治理闭环**

---

## 8. 相关文档

- [业务闭环总览](../00_Business/Business_ClosedLoops.md)
- [服务编排总图](../01_Architecture/04_Service_Map.md)
- [Node Agent设计](../04_Plugin/01_NodeAgent_Design.md)
- [统一类型管理](../01_Architecture/16_Unified_Type_Management.md)
- [状态机定义](../01_Architecture/06_State_Machine.md)

---

*最后更新: 2026-03-20*