refactor: 优化代码结构并修复类型问题
- 移除未使用的TabPane组件 - 修复类型定义和导入方式 - 优化mock数据源的环境变量判断逻辑 - 更新文档结构并归档旧文件 - 添加新的UI组件和Memo组件 - 调整API路径和响应处理
This commit is contained in:
33
docs/ARCH/_index.md
Normal file
33
docs/ARCH/_index.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# 架构设计索引
|
||||
|
||||
> **入口**: [../README.md](../README.md)
|
||||
|
||||
---
|
||||
|
||||
## 架构文件
|
||||
|
||||
| 文件 | 内容 | 大小 |
|
||||
|------|------|------|
|
||||
| [system.md](system.md) | 系统架构、组件关系、通信机制 | ~400行 |
|
||||
| [domain.md](domain.md) | 领域模型、实体关系、状态机 | ~400行 |
|
||||
| [frontend.md](frontend.md) | 前端架构、组件设计、状态管理 | ~300行 |
|
||||
| [backend.md](backend.md) | 后端架构、服务设计、数据流 | ~300行 |
|
||||
| [plugin.md](plugin.md) | 插件架构、通信机制、自动化 | ~200行 |
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ 系统层级
|
||||
|
||||
```
|
||||
前端控制台 → 后端服务 → 运营代理 → 平台适配器 → 第三方平台
|
||||
↓ ↑
|
||||
←-------------- 数据回传 -------------
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
- [规则中心](../RULES/_index.md)
|
||||
- [任务中心](../TASKS/_index.md)
|
||||
- [服务地图](../SERVICES/_index.md)
|
||||
286
docs/ARCH/backend.md
Normal file
286
docs/ARCH/backend.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# 后端架构
|
||||
|
||||
> **入口**: [_index.md](_index.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. 技术栈
|
||||
|
||||
| 技术 | 版本 | 用途 |
|
||||
|------|------|------|
|
||||
| Node.js | 18.x | 运行时 |
|
||||
| Express | 4.x | Web框架 |
|
||||
| TypeScript | 5.x | 类型系统 |
|
||||
| Knex.js | 3.x | 数据库ORM |
|
||||
| Redis | 6.x | 缓存/队列 |
|
||||
| BullMQ | 4.x | 任务队列 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 目录结构
|
||||
|
||||
```
|
||||
server/src/
|
||||
├── api/ # API层
|
||||
│ ├── routes/ # 路由定义
|
||||
│ ├── controllers/ # 控制器
|
||||
│ └── middlewares/ # 中间件
|
||||
├── services/ # 服务层
|
||||
│ ├── ProductService.ts
|
||||
│ ├── OrderService.ts
|
||||
│ └── ...
|
||||
├── models/ # 数据模型
|
||||
├── repositories/ # 数据访问层
|
||||
├── core/ # 核心模块
|
||||
│ ├── connectors/ # 平台连接器
|
||||
│ └── orchestrator/ # 编排器
|
||||
├── utils/ # 工具函数
|
||||
├── types/ # 类型定义
|
||||
└── config/ # 配置文件
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 分层架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ API层 (Controller) │
|
||||
│ - 请求处理 │
|
||||
│ - 参数校验 │
|
||||
│ - 权限检查 │
|
||||
└─────────────────────────┬───────────────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 服务层 (Service) │
|
||||
│ - 业务逻辑 │
|
||||
│ - 事务管理 │
|
||||
│ - 状态流转 │
|
||||
└─────────────────────────┬───────────────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 数据访问层 (Repository) │
|
||||
│ - 数据库操作 │
|
||||
│ - 缓存操作 │
|
||||
│ - 外部API调用 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 服务层设计
|
||||
|
||||
### 4.1 服务模板
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* [BE-P001] 商品服务
|
||||
* @description 商品主数据管理
|
||||
*/
|
||||
export class ProductService {
|
||||
private static TABLE_NAME = 'cf_product';
|
||||
|
||||
static async list(params: ListParams): Promise<Product[]> {
|
||||
const query = db(this.TABLE_NAME)
|
||||
.where('tenant_id', params.tenantId);
|
||||
|
||||
if (params.status) {
|
||||
query.where('status', params.status);
|
||||
}
|
||||
|
||||
return query;
|
||||
}
|
||||
|
||||
static async get(id: string): Promise<Product | null> {
|
||||
return db(this.TABLE_NAME).where({ id }).first();
|
||||
}
|
||||
|
||||
static async create(data: CreateProductRequest): Promise<Product> {
|
||||
const [product] = await db(this.TABLE_NAME)
|
||||
.insert({
|
||||
...data,
|
||||
id: generateId(),
|
||||
created_at: new Date(),
|
||||
updated_at: new Date(),
|
||||
})
|
||||
.returning('*');
|
||||
|
||||
return product;
|
||||
}
|
||||
|
||||
static async update(id: string, data: UpdateProductRequest): Promise<Product> {
|
||||
const [product] = await db(this.TABLE_NAME)
|
||||
.where({ id })
|
||||
.update({
|
||||
...data,
|
||||
updated_at: new Date(),
|
||||
})
|
||||
.returning('*');
|
||||
|
||||
return product;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 服务命名规范
|
||||
|
||||
| 后缀 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| Service | 业务服务 | ProductService |
|
||||
| Repository | 数据访问 | ProductRepository |
|
||||
| Connector | 平台连接 | ShopifyConnector |
|
||||
| Orchestrator | 编排器 | PublishOrchestrator |
|
||||
|
||||
---
|
||||
|
||||
## 5. 中间件
|
||||
|
||||
### 5.1 权限中间件
|
||||
|
||||
```typescript
|
||||
export const authorize = (permission: string) => {
|
||||
return async (ctx: Context, next: Next) => {
|
||||
const { user } = ctx.state;
|
||||
|
||||
if (!user) {
|
||||
throw new UnauthorizedError('未登录');
|
||||
}
|
||||
|
||||
const hasPermission = await checkPermission(user, permission);
|
||||
if (!hasPermission) {
|
||||
throw new ForbiddenError('无权限');
|
||||
}
|
||||
|
||||
await next();
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### 5.2 使用方式
|
||||
|
||||
```typescript
|
||||
router.get(
|
||||
'/api/v1/products',
|
||||
authorize('product:read'),
|
||||
ProductController.list
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 任务队列
|
||||
|
||||
### 6.1 队列定义
|
||||
|
||||
```typescript
|
||||
import { Queue, Worker } from 'bullmq';
|
||||
|
||||
export const collectionQueue = new Queue('collection', {
|
||||
connection: redis,
|
||||
});
|
||||
|
||||
export const collectionWorker = new Worker(
|
||||
'collection',
|
||||
async (job) => {
|
||||
const { platform, shopId, type } = job.data;
|
||||
|
||||
// 执行采集任务
|
||||
const result = await CollectionAdapterService.executeCollectionTask(
|
||||
platform,
|
||||
shopId,
|
||||
type
|
||||
);
|
||||
|
||||
return result;
|
||||
},
|
||||
{ connection: redis, concurrency: 10 }
|
||||
);
|
||||
```
|
||||
|
||||
### 6.2 任务添加
|
||||
|
||||
```typescript
|
||||
await collectionQueue.add('collect-products', {
|
||||
platform: 'SHOPIFY',
|
||||
shopId: 'shop-001',
|
||||
type: 'product',
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 错误处理
|
||||
|
||||
### 7.1 错误类型
|
||||
|
||||
```typescript
|
||||
export class AppError extends Error {
|
||||
constructor(
|
||||
public code: string,
|
||||
public message: string,
|
||||
public statusCode: number = 500
|
||||
) {
|
||||
super(message);
|
||||
}
|
||||
}
|
||||
|
||||
export class ValidationError extends AppError {
|
||||
constructor(message: string) {
|
||||
super('VAL_INVALID_PARAM', message, 400);
|
||||
}
|
||||
}
|
||||
|
||||
export class UnauthorizedError extends AppError {
|
||||
constructor(message: string) {
|
||||
super('AUTH_UNAUTHORIZED', message, 401);
|
||||
}
|
||||
}
|
||||
|
||||
export class ForbiddenError extends AppError {
|
||||
constructor(message: string) {
|
||||
super('AUTH_FORBIDDEN', message, 403);
|
||||
}
|
||||
}
|
||||
|
||||
export class NotFoundError extends AppError {
|
||||
constructor(message: string) {
|
||||
super('BIZ_NOT_FOUND', message, 404);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 7.2 错误处理中间件
|
||||
|
||||
```typescript
|
||||
export const errorHandler = async (ctx: Context, next: Next) => {
|
||||
try {
|
||||
await next();
|
||||
} catch (error) {
|
||||
if (error instanceof AppError) {
|
||||
ctx.status = error.statusCode;
|
||||
ctx.body = {
|
||||
success: false,
|
||||
error: {
|
||||
code: error.code,
|
||||
message: error.message,
|
||||
},
|
||||
};
|
||||
} else {
|
||||
ctx.status = 500;
|
||||
ctx.body = {
|
||||
success: false,
|
||||
error: {
|
||||
code: 'SYS_INTERNAL_ERROR',
|
||||
message: '内部服务器错误',
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*最后更新: 2026-03-22*
|
||||
193
docs/ARCH/domain.md
Normal file
193
docs/ARCH/domain.md
Normal file
@@ -0,0 +1,193 @@
|
||||
# 领域模型
|
||||
|
||||
> **入口**: [_index.md](_index.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. 核心领域
|
||||
|
||||
| 领域 | 英文 | 说明 |
|
||||
|------|------|------|
|
||||
| 商品 | Product | 商品主数据、SKU、Listing |
|
||||
| 订单 | Order | 订单、履约、售后 |
|
||||
| 库存 | Inventory | 库存、仓储、补货 |
|
||||
| 财务 | Finance | 对账、结算、利润 |
|
||||
| 营销 | Marketing | 广告、投放、推广 |
|
||||
| 客户 | Customer | 客户、用户、资产 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 商品领域模型
|
||||
|
||||
### 2.1 实体关系
|
||||
|
||||
```
|
||||
┌─────────────┐ 1:N ┌─────────────┐ 1:N ┌─────────────┐
|
||||
│ SPU │─────────────→│ SKU │─────────────→│ Listing │
|
||||
│ (商品主数据) │ │ (变体) │ │ (平台刊登) │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
│ │ │
|
||||
│ 1:N │ 1:N │ 1:1
|
||||
↓ ↓ ↓
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ 图片库 │ │ 库存 │ │ 价格 │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
```
|
||||
|
||||
### 2.2 商品状态机
|
||||
|
||||
```
|
||||
DRAFT → PENDING_REVIEW → ACTIVE → INACTIVE
|
||||
↓
|
||||
ARCHIVED
|
||||
```
|
||||
|
||||
| 状态 | 说明 |
|
||||
|------|------|
|
||||
| DRAFT | 草稿 |
|
||||
| PENDING_REVIEW | 待审核 |
|
||||
| ACTIVE | 活跃 |
|
||||
| INACTIVE | 停用 |
|
||||
| ARCHIVED | 归档 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 订单领域模型
|
||||
|
||||
### 3.1 实体关系
|
||||
|
||||
```
|
||||
┌─────────────┐ 1:N ┌─────────────┐ 1:N ┌─────────────┐
|
||||
│ Order │─────────────→│ OrderItem │─────────────→│ SKU │
|
||||
│ (订单) │ │ (订单项) │ │ (商品) │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
│
|
||||
│ 1:1
|
||||
↓
|
||||
┌─────────────┐ 1:N ┌─────────────┐
|
||||
│ 履约记录 │─────────────→│ 物流信息 │
|
||||
└─────────────┘ └─────────────┘
|
||||
```
|
||||
|
||||
### 3.2 订单状态机
|
||||
|
||||
```
|
||||
PENDING → CONFIRMED → PROCESSING → SHIPPED → DELIVERED → COMPLETED
|
||||
↓ ↓ ↓ ↓
|
||||
CANCELLED CANCELLED CANCELLED RETURNED
|
||||
```
|
||||
|
||||
| 状态 | 说明 |
|
||||
|------|------|
|
||||
| PENDING | 待处理 |
|
||||
| CONFIRMED | 已确认 |
|
||||
| PROCESSING | 处理中 |
|
||||
| SHIPPED | 已发货 |
|
||||
| DELIVERED | 已送达 |
|
||||
| COMPLETED | 已完成 |
|
||||
| CANCELLED | 已取消 |
|
||||
| RETURNED | 已退货 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 库存领域模型
|
||||
|
||||
### 4.1 实体关系
|
||||
|
||||
```
|
||||
┌─────────────┐ 1:N ┌─────────────┐
|
||||
│ Warehouse │─────────────→│ Inventory │
|
||||
│ (仓库) │ │ (库存) │
|
||||
└─────────────┘ └─────────────┘
|
||||
│
|
||||
│ 1:N
|
||||
↓
|
||||
┌─────────────┐
|
||||
│ 库存变动记录 │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
### 4.2 库存状态
|
||||
|
||||
| 状态 | 说明 |
|
||||
|------|------|
|
||||
| IN_STOCK | 有库存 |
|
||||
| LOW_STOCK | 低库存 |
|
||||
| OUT_OF_STOCK | 缺货 |
|
||||
| RESERVED | 预留 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 财务领域模型
|
||||
|
||||
### 5.1 实体关系
|
||||
|
||||
```
|
||||
┌─────────────┐ 1:N ┌─────────────┐ 1:N ┌─────────────┐
|
||||
│ Settlement │─────────────→│ Settlement │─────────────→│ Order │
|
||||
│ (结算单) │ │ Item │ │ (订单) │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
│
|
||||
│ 1:1
|
||||
↓
|
||||
┌─────────────┐
|
||||
│ 对账记录 │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
### 5.2 结算状态
|
||||
|
||||
| 状态 | 说明 |
|
||||
|------|------|
|
||||
| PENDING | 待结算 |
|
||||
| PROCESSING | 处理中 |
|
||||
| COMPLETED | 已完成 |
|
||||
| FAILED | 失败 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 营销领域模型
|
||||
|
||||
### 6.1 实体关系
|
||||
|
||||
```
|
||||
┌─────────────┐ 1:N ┌─────────────┐ 1:N ┌─────────────┐
|
||||
│ Campaign │─────────────→│ Ad │─────────────→│ AdCreative │
|
||||
│ (广告计划) │ │ (广告) │ │ (广告素材) │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
```
|
||||
|
||||
### 6.2 广告状态
|
||||
|
||||
| 状态 | 说明 |
|
||||
|------|------|
|
||||
| DRAFT | 草稿 |
|
||||
| PENDING_REVIEW | 待审核 |
|
||||
| ACTIVE | 投放中 |
|
||||
| PAUSED | 已暂停 |
|
||||
| COMPLETED | 已完成 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 客户领域模型
|
||||
|
||||
### 7.1 实体关系
|
||||
|
||||
```
|
||||
┌─────────────┐ 1:N ┌─────────────┐ 1:N ┌─────────────┐
|
||||
│ Customer │─────────────→│ Order │─────────────→│ Address │
|
||||
│ (客户) │ │ (订单) │ │ (地址) │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
```
|
||||
|
||||
### 7.2 客户状态
|
||||
|
||||
| 状态 | 说明 |
|
||||
|------|------|
|
||||
| ACTIVE | 活跃 |
|
||||
| INACTIVE | 非活跃 |
|
||||
| BLACKLISTED | 黑名单 |
|
||||
|
||||
---
|
||||
|
||||
*最后更新: 2026-03-22*
|
||||
209
docs/ARCH/frontend.md
Normal file
209
docs/ARCH/frontend.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# 前端架构
|
||||
|
||||
> **入口**: [_index.md](_index.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. 技术栈
|
||||
|
||||
| 技术 | 版本 | 用途 |
|
||||
|------|------|------|
|
||||
| UmiJS | 4.x | 前端框架 |
|
||||
| React | 18.x | UI库 |
|
||||
| Ant Design | 5.x | 组件库 |
|
||||
| TypeScript | 5.x | 类型系统 |
|
||||
| axios | 1.x | HTTP请求 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 目录结构
|
||||
|
||||
```
|
||||
dashboard/src/
|
||||
├── pages/ # 页面组件
|
||||
│ ├── product/ # 商品管理
|
||||
│ ├── order/ # 订单管理
|
||||
│ ├── inventory/ # 库存管理
|
||||
│ ├── finance/ # 财务管理
|
||||
│ └── ...
|
||||
├── components/ # 公共组件
|
||||
│ ├── Layout/ # 布局组件
|
||||
│ ├── Table/ # 表格组件
|
||||
│ └── Form/ # 表单组件
|
||||
├── models/ # 状态管理
|
||||
│ ├── product.ts # 商品状态
|
||||
│ ├── order.ts # 订单状态
|
||||
│ └── user.ts # 用户状态
|
||||
├── services/ # 数据源
|
||||
│ ├── productDataSource.ts
|
||||
│ └── orderDataSource.ts
|
||||
├── utils/ # 工具函数
|
||||
├── types/ # 类型定义
|
||||
└── mock/ # Mock数据
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 页面结构
|
||||
|
||||
### 3.1 标准页面模板
|
||||
|
||||
```tsx
|
||||
import { PageContainer } from '@ant-design/pro-components';
|
||||
import { Table, Button, Space } from 'antd';
|
||||
|
||||
const ProductList: React.FC = () => {
|
||||
const columns = [
|
||||
{ title: '商品名称', dataIndex: 'name' },
|
||||
{ title: '价格', dataIndex: 'price' },
|
||||
{ title: '状态', dataIndex: 'status' },
|
||||
];
|
||||
|
||||
return (
|
||||
<PageContainer>
|
||||
<Space style={{ marginBottom: 16 }}>
|
||||
<Button type="primary">新建</Button>
|
||||
</Space>
|
||||
<Table columns={columns} dataSource={[]} />
|
||||
</PageContainer>
|
||||
);
|
||||
};
|
||||
|
||||
export default ProductList;
|
||||
```
|
||||
|
||||
### 3.2 页面分类
|
||||
|
||||
| 页面类型 | 说明 | 示例 |
|
||||
|---------|------|------|
|
||||
| 列表页 | 数据展示、筛选、操作 | 商品列表、订单列表 |
|
||||
| 详情页 | 单条数据详情 | 商品详情、订单详情 |
|
||||
| 表单页 | 数据创建/编辑 | 新建商品、编辑订单 |
|
||||
| 分析页 | 数据可视化 | 销售报表、利润分析 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 状态管理
|
||||
|
||||
### 4.1 Umi Model
|
||||
|
||||
```typescript
|
||||
// models/product.ts
|
||||
import { useState, useCallback } from 'react';
|
||||
import { productDataSource } from '@/services/productDataSource';
|
||||
|
||||
export default function useProductModel() {
|
||||
const [products, setProducts] = useState<Product[]>([]);
|
||||
const [loading, setLoading] = useState(false);
|
||||
|
||||
const fetchProducts = useCallback(async (params) => {
|
||||
setLoading(true);
|
||||
try {
|
||||
const data = await productDataSource.list(params);
|
||||
setProducts(data);
|
||||
} finally {
|
||||
setLoading(false);
|
||||
}
|
||||
}, []);
|
||||
|
||||
return {
|
||||
products,
|
||||
loading,
|
||||
fetchProducts,
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 使用方式
|
||||
|
||||
```tsx
|
||||
import { useModel } from 'umi';
|
||||
|
||||
const ProductList = () => {
|
||||
const { products, loading, fetchProducts } = useModel('product');
|
||||
|
||||
useEffect(() => {
|
||||
fetchProducts({});
|
||||
}, []);
|
||||
|
||||
return <Table loading={loading} dataSource={products} />;
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 数据源层
|
||||
|
||||
### 5.1 DataSource设计
|
||||
|
||||
```typescript
|
||||
// services/productDataSource.ts
|
||||
import { request } from 'umi';
|
||||
|
||||
export const productDataSource = {
|
||||
list: async (params: ListParams) => {
|
||||
const response = await request('/api/v1/products', { params });
|
||||
return response.data;
|
||||
},
|
||||
|
||||
get: async (id: string) => {
|
||||
const response = await request(`/api/v1/products/${id}`);
|
||||
return response.data;
|
||||
},
|
||||
|
||||
create: async (data: CreateProductRequest) => {
|
||||
const response = await request('/api/v1/products', {
|
||||
method: 'POST',
|
||||
data,
|
||||
});
|
||||
return response.data;
|
||||
},
|
||||
|
||||
update: async (id: string, data: UpdateProductRequest) => {
|
||||
const response = await request(`/api/v1/products/${id}`, {
|
||||
method: 'PUT',
|
||||
data,
|
||||
});
|
||||
return response.data;
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 5.2 Mock支持
|
||||
|
||||
```typescript
|
||||
// mock/product.ts
|
||||
export default {
|
||||
'GET /api/v1/products': {
|
||||
success: true,
|
||||
data: [
|
||||
{ id: '1', name: '商品1', price: 100 },
|
||||
{ id: '2', name: '商品2', price: 200 },
|
||||
],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 组件规范
|
||||
|
||||
### 6.1 组件大小限制
|
||||
|
||||
| 类型 | 限制 |
|
||||
|------|------|
|
||||
| UI组件 | ≤ 300 行 |
|
||||
| 页面组件 | ≤ 500 行 |
|
||||
| 复杂组件 | 拆分子组件 |
|
||||
|
||||
### 6.2 组件命名
|
||||
|
||||
| 类型 | 格式 | 示例 |
|
||||
|------|------|------|
|
||||
| 页面 | PascalCase | `ProductList.tsx` |
|
||||
| 组件 | PascalCase | `ProductCard.tsx` |
|
||||
| 工具 | camelCase | `formatPrice.ts` |
|
||||
|
||||
---
|
||||
|
||||
*最后更新: 2026-03-22*
|
||||
203
docs/ARCH/plugin.md
Normal file
203
docs/ARCH/plugin.md
Normal file
@@ -0,0 +1,203 @@
|
||||
# 插件架构
|
||||
|
||||
> **入口**: [_index.md](_index.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. 插件结构
|
||||
|
||||
```
|
||||
node-agent/src/
|
||||
├── background/ # 后台脚本
|
||||
│ └── index.ts # 主入口
|
||||
├── content/ # 内容脚本
|
||||
│ └── index.ts # 页面注入
|
||||
├── popup/ # 弹窗页面
|
||||
│ └── index.tsx # 弹窗UI
|
||||
├── connectors/ # 平台连接器
|
||||
│ ├── ShopifyConnector.ts
|
||||
│ └── AmazonConnector.ts
|
||||
└── utils/ # 工具函数
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 通信机制
|
||||
|
||||
### 2.1 消息类型
|
||||
|
||||
```typescript
|
||||
// 消息类型定义
|
||||
interface Message {
|
||||
type: string;
|
||||
payload: any;
|
||||
traceId: string;
|
||||
}
|
||||
|
||||
// 消息类型枚举
|
||||
enum MessageType {
|
||||
// 商品采集
|
||||
COLLECT_PRODUCT = 'COLLECT_PRODUCT',
|
||||
COLLECT_ORDER = 'COLLECT_ORDER',
|
||||
|
||||
// 自动化操作
|
||||
AUTO_PUBLISH = 'AUTO_PUBLISH',
|
||||
AUTO_UPDATE_PRICE = 'AUTO_UPDATE_PRICE',
|
||||
|
||||
// 数据同步
|
||||
SYNC_INVENTORY = 'SYNC_INVENTORY',
|
||||
SYNC_ORDER = 'SYNC_ORDER',
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 消息流程
|
||||
|
||||
```
|
||||
前端控制台 → 后端服务 → 插件Background → Content Script → 平台页面
|
||||
↑ │
|
||||
└──────────── 数据回传 ──────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 连接器设计
|
||||
|
||||
### 3.1 连接器接口
|
||||
|
||||
```typescript
|
||||
interface IPlatformConnector {
|
||||
platformCode: string;
|
||||
capabilities: {
|
||||
hasApi: boolean;
|
||||
supportsPriceSync: boolean;
|
||||
supportsInventorySync: boolean;
|
||||
supportsOrderPull: boolean;
|
||||
};
|
||||
|
||||
pullProducts(shopId: string): Promise<PlatformProduct[]>;
|
||||
pullOrders(shopId: string): Promise<PlatformOrder[]>;
|
||||
pushListing(product: Product): Promise<ListingResult>;
|
||||
updatePrice(listingId: string, price: number): Promise<void>;
|
||||
syncInventory(listingId: string, stock: number): Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 连接器实现
|
||||
|
||||
```typescript
|
||||
export class ShopifyConnector implements IPlatformConnector {
|
||||
platformCode = 'SHOPIFY';
|
||||
capabilities = {
|
||||
hasApi: true,
|
||||
supportsPriceSync: true,
|
||||
supportsInventorySync: true,
|
||||
supportsOrderPull: true,
|
||||
};
|
||||
|
||||
async pullProducts(shopId: string): Promise<PlatformProduct[]> {
|
||||
// Shopify API 调用
|
||||
}
|
||||
|
||||
async pullOrders(shopId: string): Promise<PlatformOrder[]> {
|
||||
// Shopify API 调用
|
||||
}
|
||||
|
||||
// ... 其他方法
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 自动化流程
|
||||
|
||||
### 4.1 任务执行
|
||||
|
||||
```
|
||||
1. 后端下发任务 → Redis Queue
|
||||
2. Agent Worker 接收任务
|
||||
3. 选择对应 Connector
|
||||
4. 执行操作（API/页面操作）
|
||||
5. 回传结果 → 后端服务
|
||||
6. 更新任务状态
|
||||
```
|
||||
|
||||
### 4.2 错误重试
|
||||
|
||||
```typescript
|
||||
const retryOptions = {
|
||||
attempts: 3,
|
||||
backoff: {
|
||||
type: 'exponential',
|
||||
delay: 1000,
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 代理管理
|
||||
|
||||
### 5.1 代理配置
|
||||
|
||||
```typescript
|
||||
interface ProxyConfig {
|
||||
host: string;
|
||||
port: number;
|
||||
username?: string;
|
||||
password?: string;
|
||||
protocol: 'http' | 'https' | 'socks5';
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 代理轮换
|
||||
|
||||
```typescript
|
||||
class ProxyManager {
|
||||
private proxies: ProxyConfig[];
|
||||
private currentIndex = 0;
|
||||
|
||||
getNext(): ProxyConfig {
|
||||
const proxy = this.proxies[this.currentIndex];
|
||||
this.currentIndex = (this.currentIndex + 1) % this.proxies.length;
|
||||
return proxy;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 指纹管理
|
||||
|
||||
### 6.1 指纹配置
|
||||
|
||||
```typescript
|
||||
interface FingerprintConfig {
|
||||
userAgent: string;
|
||||
viewport: { width: number; height: number };
|
||||
locale: string;
|
||||
timezone: string;
|
||||
webgl: { vendor: string; renderer: string };
|
||||
fonts: string[];
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 指纹生成
|
||||
|
||||
```typescript
|
||||
class FingerprintGenerator {
|
||||
generate(): FingerprintConfig {
|
||||
return {
|
||||
userAgent: this.randomUserAgent(),
|
||||
viewport: this.randomViewport(),
|
||||
locale: 'en-US',
|
||||
timezone: 'America/New_York',
|
||||
webgl: this.randomWebGL(),
|
||||
fonts: this.randomFonts(),
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*最后更新: 2026-03-22*
|
||||
189
docs/ARCH/system.md
Normal file
189
docs/ARCH/system.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# 系统架构
|
||||
|
||||
> **入口**: [_index.md](_index.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. 系统层级
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 前端控制台 │
|
||||
│ (UmiJS + Ant Design + TypeScript) │
|
||||
└─────────────────────────┬───────────────────────────────────┘
|
||||
│ HTTP/WebSocket
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 后端服务 │
|
||||
│ (Node.js + Express + TypeScript) │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ Controller │→ │ Service │→ │ Repository │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────────┬───────────────────────────────────┘
|
||||
│ Message Queue
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 运营代理 │
|
||||
│ (Node.js + Puppeteer) │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ Task Runner │→ │ Connector │→ │ Browser │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────────┬───────────────────────────────────┘
|
||||
│ Platform API / Scraping
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 第三方平台 │
|
||||
│ Shopify │ Amazon │ TikTok │ Shopee │ Temu │ ... │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心组件
|
||||
|
||||
### 2.1 前端控制台
|
||||
|
||||
| 组件 | 技术 | 职责 |
|
||||
|------|------|------|
|
||||
| 路由 | UmiJS | 页面路由、权限控制 |
|
||||
| 状态 | Umi Model | 全局状态管理 |
|
||||
| UI | Ant Design | 组件库、布局 |
|
||||
| 请求 | axios | API调用、拦截器 |
|
||||
|
||||
### 2.2 后端服务
|
||||
|
||||
| 组件 | 技术 | 职责 |
|
||||
|------|------|------|
|
||||
| 路由 | Express Router | 路由定义、中间件 |
|
||||
| 控制器 | Controller | 请求处理、参数校验 |
|
||||
| 服务 | Service | 业务逻辑、事务管理 |
|
||||
| 数据访问 | Knex.js | 数据库操作 |
|
||||
| 缓存 | Redis | 缓存、会话、队列 |
|
||||
| 队列 | BullMQ | 异步任务处理 |
|
||||
|
||||
### 2.3 运营代理
|
||||
|
||||
| 组件 | 技术 | 职责 |
|
||||
|------|------|------|
|
||||
| 任务调度 | BullMQ Worker | 任务执行、重试 |
|
||||
| 浏览器 | Puppeteer | 页面操作、数据采集 |
|
||||
| 代理管理 | Proxy Manager | 代理池、IP轮换 |
|
||||
| 指纹管理 | Fingerprint | 浏览器指纹、防检测 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 通信机制
|
||||
|
||||
### 3.1 前端 ↔ 后端
|
||||
|
||||
```
|
||||
HTTP REST API
|
||||
├── 认证: JWT Token
|
||||
├── 请求: JSON
|
||||
└── 响应: JSON
|
||||
|
||||
WebSocket
|
||||
├── 实时通知
|
||||
├── 任务进度
|
||||
└── 系统事件
|
||||
```
|
||||
|
||||
### 3.2 后端 ↔ 运营代理
|
||||
|
||||
```
|
||||
Redis Message Queue
|
||||
├── 任务下发
|
||||
├── 结果回传
|
||||
└── 状态同步
|
||||
```
|
||||
|
||||
### 3.3 运营代理 ↔ 平台
|
||||
|
||||
```
|
||||
Platform API
|
||||
├── 官方API (Shopify, Amazon)
|
||||
├── 非官方API (TikTok, Shopee)
|
||||
└── 页面采集 (Temu, 1688)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据流
|
||||
|
||||
### 4.1 商品采集流程
|
||||
|
||||
```
|
||||
用户请求 → Controller → CollectionService
|
||||
↓
|
||||
创建采集任务 → Redis Queue → Agent Worker
|
||||
↓
|
||||
Connector → 平台API/页面 → 解析数据
|
||||
↓
|
||||
回传数据 → ProductService → 存储数据库
|
||||
↓
|
||||
WebSocket通知 → 前端更新
|
||||
```
|
||||
|
||||
### 4.2 订单履约流程
|
||||
|
||||
```
|
||||
订单创建 → OrderService → 库存检查
|
||||
↓
|
||||
InventoryService → 库存扣减
|
||||
↓
|
||||
FulfillmentService → 物流创建
|
||||
↓
|
||||
通知用户 → WebSocket/SMS/Email
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 部署架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 负载均衡 │
|
||||
└─────────────────────────┬───────────────────────────────────┘
|
||||
│
|
||||
┌───────────────┼───────────────┐
|
||||
↓ ↓ ↓
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│ 前端实例 │ │ 前端实例 │ │ 前端实例 │
|
||||
└──────────┘ └──────────┘ └──────────┘
|
||||
│ │ │
|
||||
└───────────────┼───────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ API网关 │
|
||||
└─────────────────────────┬───────────────────────────────────┘
|
||||
│
|
||||
┌───────────────┼───────────────┐
|
||||
↓ ↓ ↓
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│ 后端实例 │ │ 后端实例 │ │ 后端实例 │
|
||||
└──────────┘ └──────────┘ └──────────┘
|
||||
│ │ │
|
||||
└───────────────┼───────────────┘
|
||||
↓
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│ MySQL │ │ Redis │ │ Agent │
|
||||
└──────────┘ └──────────┘ └──────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 技术栈
|
||||
|
||||
| 层级 | 技术 | 版本 |
|
||||
|------|------|------|
|
||||
| 前端框架 | UmiJS | 4.x |
|
||||
| UI组件库 | Ant Design | 5.x |
|
||||
| 后端框架 | Express | 4.x |
|
||||
| 数据库 | MySQL | 8.0 |
|
||||
| 缓存 | Redis | 6.x |
|
||||
| 队列 | BullMQ | 4.x |
|
||||
| 浏览器 | Puppeteer | 21.x |
|
||||
|
||||
---
|
||||
|
||||
*最后更新: 2026-03-22*
|
||||
Reference in New Issue
Block a user