refactor: 优化代码结构并修复类型问题
- 移除未使用的TabPane组件 - 修复类型定义和导入方式 - 优化mock数据源的环境变量判断逻辑 - 更新文档结构并归档旧文件 - 添加新的UI组件和Memo组件 - 调整API路径和响应处理
This commit is contained in:
@@ -0,0 +1,371 @@
|
||||
# 前后端插件闭环架构方案
|
||||
|
||||
> **创建日期**: 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*
|
||||
Reference in New Issue
Block a user