makemd/docs/01_Architecture/17_Frontend_Backend_Plugin_ClosedLoop.md

前后端插件闭环架构方案

创建日期: 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层设计

// 前端数据源抽象层
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 状态管理

// 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 状态机设计

// 订单状态机
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 任务类型

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 通信协议

// 任务请求
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驱动开发

// 使用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 前后端类型同步

// 前端从后端导入类型
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. 相关文档

• 业务闭环总览
• 服务编排总图
• Node Agent设计
• 统一类型管理
• 状态机定义

---

最后更新: 2026-03-20