chore: 清理归档文件和文档模板

删除不再需要的归档文件和过时的文档模板,包括多个README、安全策略、前端集成蓝图等文件,同时移除了未使用的业务文档和项目结构文件。

优化项目结构,移除冗余文件,保持代码库整洁。主要删除archive/handover目录下的多个文件及doc目录下的部分文档模板。
This commit is contained in:
2026-03-18 01:21:15 +08:00
parent 56b8a2e2f8
commit 72cd7f6f45
147 changed files with 5982 additions and 16716 deletions

View File

@@ -0,0 +1,470 @@
# Frontend Design (Crawlful Hub)
> **定位**Crawlful Hub 前端架构设计文档 - 包含技术栈、目录结构、核心模块及开发规范。
> **更新日期**: 2026-03-18
> **最高优先级参考**: [Business_Blueprint.md](../00_Business/Business_Blueprint.md)
---
## 1. 技术栈 (Tech Stack)
| 层级 | 技术 | 版本 | 用途 |
|------|------|------|------|
| **Framework** | React | 18.x | UI 框架 |
| **Language** | TypeScript | 5.x | 开发语言 |
| **Build Tool** | Vite | 5.x | 构建工具 |
| **UI Library** | Ant Design | 5.x | 组件库 |
| **State** | Zustand | 4.x | 状态管理 |
| **Query** | TanStack Query | 5.x | 数据获取 |
| **Routing** | React Router | 6.x | 路由管理 |
| **Charts** | Ant Design Charts | 2.x | 数据可视化 |
| **Testing** | Vitest | 1.x | 单元测试 |
---
## 2. 目录结构 (Directory Structure)
```
web/src/
├─ components/ # 公共组件
│ ├─ Layout/ # 布局组件
│ │ ├─ MainLayout.tsx
│ │ ├─ Sidebar.tsx
│ │ └─ Header.tsx
│ ├─ Common/ # 通用组件
│ │ ├─ DataTable.tsx
│ │ ├─ FilterPanel.tsx
│ │ ├─ StatusBadge.tsx
│ │ └─ ActionButtons.tsx
│ └─ Charts/ # 图表组件
│ ├─ ProfitChart.tsx
│ ├─ OrderTrendChart.tsx
│ └─ InventoryChart.tsx
├─ pages/ # 页面组件
│ ├─ Dashboard/ # 首页/仪表盘
│ │ └─ index.tsx
│ ├─ Products/ # 商品管理
│ │ ├─ index.tsx # 商品列表
│ │ ├─ Detail.tsx # 商品详情
│ │ ├─ Create.tsx # 创建商品
│ │ └─ Review.tsx # 商品审核
│ ├─ Orders/ # 订单管理
│ │ ├─ index.tsx # 订单列表
│ │ ├─ Detail.tsx # 订单详情
│ │ └─ Audit.tsx # 订单审核
│ ├─ Finance/ # 财务管理
│ │ ├─ index.tsx # 财务概览
│ │ ├─ Transactions.tsx # 交易流水
│ │ └─ Reconciliation.tsx # 利润对账
│ ├─ Inventory/ # 库存管理
│ │ ├─ index.tsx # 库存概览
│ │ ├─ Warehouses.tsx # 仓库管理
│ │ └─ Forecast.tsx # 库存预测
│ ├─ Marketing/ # 营销广告
│ │ ├─ index.tsx # 营销概览
│ │ ├─ Ads.tsx # 广告管理
│ │ └─ Competitors.tsx # 竞品监控
│ ├─ Suppliers/ # 供应商管理
│ │ ├─ index.tsx # 供应商列表
│ │ └─ Detail.tsx # 供应商详情
│ ├─ Reports/ # 报表分析
│ │ ├─ index.tsx # 报表中心
│ │ ├─ Profit.tsx # 利润报表
│ │ └─ Performance.tsx # 绩效报表
│ ├─ Settings/ # 系统设置
│ │ ├─ index.tsx # 设置首页
│ │ ├─ Profile.tsx # 个人设置
│ │ ├─ Tenant.tsx # 租户设置
│ │ └─ Users.tsx # 用户管理
│ └─ Login/ # 登录页
│ └─ index.tsx
├─ hooks/ # 自定义 Hooks
│ ├─ useAuth.ts # 认证相关
│ ├─ useTenant.ts # 租户相关
│ ├─ useProducts.ts # 商品数据
│ ├─ useOrders.ts # 订单数据
│ └─ useFinance.ts # 财务数据
├─ stores/ # 状态管理 (Zustand)
│ ├─ authStore.ts # 认证状态
│ ├─ tenantStore.ts # 租户状态
│ ├─ productStore.ts # 商品状态
│ └─ uiStore.ts # UI 状态
├─ services/ # API 服务
│ ├─ api.ts # Axios 实例
│ ├─ productService.ts # 商品 API
│ ├─ orderService.ts # 订单 API
│ ├─ financeService.ts # 财务 API
│ └─ authService.ts # 认证 API
├─ types/ # 类型定义
│ ├─ product.ts # 商品类型
│ ├─ order.ts # 订单类型
│ ├─ finance.ts # 财务类型
│ └─ common.ts # 通用类型
├─ utils/ # 工具函数
│ ├─ formatters.ts # 格式化
│ ├─ validators.ts # 校验
│ └─ constants.ts # 常量
├─ styles/ # 样式文件
│ └─ global.css
└─ App.tsx # 应用入口
```
---
## 3. 页面路由 (Routes)
### 3.1 路由结构
```typescript
const routes = [
// 公共路由
{ path: '/login', element: <Login /> },
// 受保护路由
{
path: '/',
element: <MainLayout />,
children: [
{ path: '/', element: <Dashboard /> },
{ path: '/products', element: <Products /> },
{ path: '/products/:id', element: <ProductDetail /> },
{ path: '/products/create', element: <ProductCreate /> },
{ path: '/products/review', element: <ProductReview /> },
{ path: '/orders', element: <Orders /> },
{ path: '/orders/:id', element: <OrderDetail /> },
{ path: '/orders/audit', element: <OrderAudit /> },
{ path: '/finance', element: <Finance /> },
{ path: '/finance/transactions', element: <Transactions /> },
{ path: '/finance/reconciliation', element: <Reconciliation /> },
{ path: '/inventory', element: <Inventory /> },
{ path: '/inventory/warehouses', element: <Warehouses /> },
{ path: '/inventory/forecast', element: <InventoryForecast /> },
{ path: '/marketing', element: <Marketing /> },
{ path: '/marketing/ads', element: <Ads /> },
{ path: '/marketing/competitors', element: <Competitors /> },
{ path: '/suppliers', element: <Suppliers /> },
{ path: '/suppliers/:id', element: <SupplierDetail /> },
{ path: '/reports', element: <Reports /> },
{ path: '/reports/profit', element: <ProfitReport /> },
{ path: '/reports/performance', element: <PerformanceReport /> },
{ path: '/settings', element: <Settings /> },
{ path: '/settings/profile', element: <ProfileSettings /> },
{ path: '/settings/tenant', element: <TenantSettings /> },
{ path: '/settings/users', element: <UserManagement /> },
]
}
];
```
### 3.2 权限路由
```typescript
// 基于角色的路由访问控制
const roleRoutes = {
ADMIN: ['*'], // 所有路由
MANAGER: ['*'], // 所有路由
OPERATOR: [
'/products',
'/orders',
'/inventory'
],
FINANCE: [
'/finance',
'/reports'
],
SOURCING: [
'/products',
'/suppliers'
],
LOGISTICS: [
'/orders',
'/inventory'
],
ANALYST: [
'/reports',
'/marketing/competitors'
]
};
```
---
## 4. 核心模块
### 4.1 商品管理模块
**功能列表**
- 商品列表展示 (分页、筛选、排序)
- 商品详情查看
- 商品创建/编辑
- 商品审核流程
- 批量操作
- 动态定价
- 套利分析
**页面组件**
- `Products/index.tsx` - 商品列表页
- `Products/Detail.tsx` - 商品详情页
- `Products/Create.tsx` - 创建商品页
- `Products/Review.tsx` - 商品审核页
### 4.2 订单管理模块
**功能列表**
- 订单列表展示
- 订单详情查看
- 订单状态流转
- 批量审核
- 订单统计
**页面组件**
- `Orders/index.tsx` - 订单列表页
- `Orders/Detail.tsx` - 订单详情页
- `Orders/Audit.tsx` - 订单审核页
### 4.3 财务管理模块
**功能列表**
- 财务概览仪表盘
- 交易流水查询
- 利润对账
- 账单回放
- 财务统计报表
**页面组件**
- `Finance/index.tsx` - 财务概览页
- `Finance/Transactions.tsx` - 交易流水页
- `Finance/Reconciliation.tsx` - 利润对账页
### 4.4 库存管理模块
**功能列表**
- 库存概览
- 仓库管理
- 库存预测
- 库存预警
**页面组件**
- `Inventory/index.tsx` - 库存概览页
- `Inventory/Warehouses.tsx` - 仓库管理页
- `Inventory/Forecast.tsx` - 库存预测页
### 4.5 营销广告模块
**功能列表**
- 营销概览
- 广告管理
- 竞品监控
- 平台费用监控
**页面组件**
- `Marketing/index.tsx` - 营销概览页
- `Marketing/Ads.tsx` - 广告管理页
- `Marketing/Competitors.tsx` - 竞品监控页
---
## 5. 组件规范
### 5.1 组件命名
- **页面组件**: PascalCase以功能命名 (如 `ProductList`, `OrderDetail`)
- **公共组件**: PascalCase以功能命名 (如 `DataTable`, `FilterPanel`)
- **Hooks**: camelCase`use` 开头 (如 `useProducts`, `useAuth`)
### 5.2 组件结构
```typescript
// 页面组件示例
import React from 'react';
import { useQuery } from '@tanstack/react-query';
import { Table, Button } from 'antd';
import { useProducts } from '@/hooks/useProducts';
export const Products: React.FC = () => {
const { data, isLoading } = useProducts();
const columns = [
{ title: '商品名称', dataIndex: 'title' },
{ title: '平台', dataIndex: 'platform' },
{ title: '状态', dataIndex: 'status' },
{ title: '售价', dataIndex: 'sellingPrice' },
];
return (
<div>
<h1></h1>
<Table
dataSource={data}
columns={columns}
loading={isLoading}
/>
</div>
);
};
```
### 5.3 状态管理
```typescript
// Zustand Store 示例
import { create } from 'zustand';
interface ProductState {
products: Product[];
selectedProduct: Product | null;
setProducts: (products: Product[]) => void;
setSelectedProduct: (product: Product | null) => void;
}
export const useProductStore = create<ProductState>((set) => ({
products: [],
selectedProduct: null,
setProducts: (products) => set({ products }),
setSelectedProduct: (product) => set({ selectedProduct: product }),
}));
```
---
## 6. API 集成
### 6.1 Axios 配置
```typescript
// services/api.ts
import axios from 'axios';
const api = axios.create({
baseURL: import.meta.env.VITE_API_URL,
timeout: 30000,
});
// 请求拦截器
api.interceptors.request.use((config) => {
const token = localStorage.getItem('token');
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
const tenantId = localStorage.getItem('tenantId');
if (tenantId) {
config.headers['X-Tenant-Id'] = tenantId;
}
return config;
});
// 响应拦截器
api.interceptors.response.use(
(response) => response.data,
(error) => {
if (error.response?.status === 401) {
// 处理未授权
window.location.href = '/login';
}
return Promise.reject(error);
}
);
export default api;
```
### 6.2 TanStack Query 配置
```typescript
// hooks/useProducts.ts
import { useQuery, useMutation } from '@tanstack/react-query';
import { productService } from '@/services/productService';
export const useProducts = (params?: ProductParams) => {
return useQuery({
queryKey: ['products', params],
queryFn: () => productService.getAll(params),
});
};
export const useCreateProduct = () => {
return useMutation({
mutationFn: productService.create,
});
};
```
---
## 7. 开发规范
### 7.1 代码规范
- 使用 TypeScript 严格模式
- 组件使用函数式组件 + Hooks
- 使用绝对路径导入 (`@/components/...`)
- 避免使用 `any` 类型
### 7.2 样式规范
- 使用 Ant Design 组件默认样式
- 自定义样式使用 CSS Modules 或 Tailwind
- 遵循设计系统规范
### 7.3 错误处理
```typescript
// 错误边界
import { ErrorBoundary } from 'react-error-boundary';
const ErrorFallback = ({ error }: { error: Error }) => (
<div>
<h2></h2>
<p>{error.message}</p>
</div>
);
// 使用
<ErrorBoundary FallbackComponent={ErrorFallback}>
<App />
</ErrorBoundary>
```
---
## 8. 构建与部署
### 8.1 环境变量
```env
VITE_API_URL=http://localhost:3000/api/v1
VITE_APP_NAME=Crawlful Hub
VITE_APP_VERSION=1.0.0
```
### 8.2 构建命令
```bash
npm install # 安装依赖
npm run dev # 开发模式
npm run build # 生产构建
npm run preview # 预览构建
npm run test # 运行测试
```
---
## 9. 相关文档
- [UI Components](./UI_Components.md)
- [Pages Flow](./Pages_Flow.md)
- [API Consumption](./API_Consumption.md)
- [Backend API Specs](../02_Backend/API_Specs/)
---
*本文档基于业务蓝图设计,最后更新: 2026-03-18*

View File

@@ -0,0 +1,367 @@
# Pages Flow (Crawlful Hub)
> **定位**Crawlful Hub 前端页面流转文档 - 描述各模块页面间的跳转关系和数据流。
> **更新日期**: 2026-03-18
> **最高优先级参考**: [Business_ClosedLoops.md](../00_Business/Business_ClosedLoops.md)
---
## 1. 页面流转总览
```
登录页
仪表盘 (Dashboard)
├──► 商品管理
│ ├── 商品列表 ──► 商品详情
│ │ ├── 编辑商品
│ │ └── 审核商品
│ ├── 创建商品
│ └── 商品审核
├──► 订单管理
│ ├── 订单列表 ──► 订单详情
│ │ └── 状态流转
│ └── 订单审核
├──► 财务管理
│ ├── 财务概览
│ ├── 交易流水
│ └── 利润对账
├──► 库存管理
│ ├── 库存概览
│ ├── 仓库管理
│ └── 库存预测
├──► 营销广告
│ ├── 营销概览
│ ├── 广告管理
│ └── 竞品监控
├──► 供应商管理
│ ├── 供应商列表 ──► 供应商详情
│ └── 供应商审核
├──► 报表分析
│ ├── 利润报表
│ └── 绩效报表
└──► 系统设置
├── 个人设置
├── 租户设置
└── 用户管理
```
---
## 2. 商品管理模块
### 2.1 页面流转图
```
商品列表页 (/products)
├──► 创建商品 (/products/create) ──► 返回列表
├──► 商品详情 (/products/:id)
│ ├── 编辑 ──► 编辑页 (/products/:id/edit)
│ └── 审核 ──► 审核弹窗
└──► 商品审核 (/products/review)
```
### 2.2 页面说明
| 页面 | 路径 | 功能 | 权限 |
|------|------|------|------|
| 商品列表 | `/products` | 展示所有商品,支持筛选、排序、分页 | product:read |
| 商品详情 | `/products/:id` | 展示商品详细信息,支持编辑、删除 | product:read |
| 创建商品 | `/products/create` | 表单创建新商品 | product:create |
| 编辑商品 | `/products/:id/edit` | 编辑商品信息 | product:update |
| 商品审核 | `/products/review` | 审核待上架商品 | product:review |
### 2.3 数据流
```
商品列表页
├── 加载数据: GET /api/v1/products
├── 筛选操作
│ ├── 平台筛选
│ ├── 状态筛选
│ └── 关键词搜索
├── 分页操作
│ └── GET /api/v1/products?page={n}
└── 批量操作
├── 批量审核
└── 批量删除
```
---
## 3. 订单管理模块
### 3.1 页面流转图
```
订单列表页 (/orders)
├──► 订单详情 (/orders/:id)
│ ├── 状态流转
│ ├── 编辑信息
│ └── 查看账单
└──► 订单审核 (/orders/audit)
```
### 3.2 页面说明
| 页面 | 路径 | 功能 | 权限 |
|------|------|------|------|
| 订单列表 | `/orders` | 展示所有订单,支持筛选 | order:read |
| 订单详情 | `/orders/:id` | 展示订单详细信息 | order:read |
| 订单审核 | `/orders/audit` | 批量审核订单 | order:audit |
### 3.3 状态流转
```
订单详情页
├── 当前状态: PULLED
│ └── 操作: 审核 ──► PENDING_REVIEW
├── 当前状态: PENDING_REVIEW
│ └── 操作: 确认 ──► CONFIRMED
├── 当前状态: CONFIRMED
│ └── 操作: 分配 ──► ALLOCATED
├── 当前状态: ALLOCATED
│ └── 操作: 准备发货 ──► READY_TO_SHIP
├── 当前状态: READY_TO_SHIP
│ └── 操作: 发货 ──► SHIPPED
├── 当前状态: SHIPPED
│ └── 操作: 送达 ──► DELIVERED
└── 当前状态: DELIVERED
└── 操作: 关闭 ──► CLOSED
```
---
## 4. 财务管理模块
### 4.1 页面流转图
```
财务概览 (/finance)
├──► 交易流水 (/finance/transactions)
│ └── 查看详情
└──► 利润对账 (/finance/reconciliation)
└── 查看对账结果
```
### 4.2 页面说明
| 页面 | 路径 | 功能 | 权限 |
|------|------|------|------|
| 财务概览 | `/finance` | 展示财务关键指标 | finance:read |
| 交易流水 | `/finance/transactions` | 查看所有交易记录 | finance:read |
| 利润对账 | `/finance/reconciliation` | 执行利润对账 | finance:reconcile |
### 4.3 数据流
```
财务概览页
├── 加载统计数据: GET /api/v1/finance/stats
├── 图表数据
│ ├── 营收趋势图
│ ├── 利润分布图
│ └── 平台占比图
└── 快捷操作
├── 查看交易流水
└── 执行利润对账
```
---
## 5. 库存管理模块
### 5.1 页面流转图
```
库存概览 (/inventory)
├──► 仓库管理 (/inventory/warehouses)
│ ├── 创建仓库
│ └── 编辑仓库
└──► 库存预测 (/inventory/forecast)
└── 查看预测结果
```
### 5.2 页面说明
| 页面 | 路径 | 功能 | 权限 |
|------|------|------|------|
| 库存概览 | `/inventory` | 展示库存总览 | inventory:read |
| 仓库管理 | `/inventory/warehouses` | 管理仓库信息 | inventory:manage |
| 库存预测 | `/inventory/forecast` | 查看库存预测 | inventory:read |
---
## 6. 营销广告模块
### 6.1 页面流转图
```
营销概览 (/marketing)
├──► 广告管理 (/marketing/ads)
│ ├── 创建广告
│ └── 广告报表
└──► 竞品监控 (/marketing/competitors)
└── 竞品详情
```
### 6.2 页面说明
| 页面 | 路径 | 功能 | 权限 |
|------|------|------|------|
| 营销概览 | `/marketing` | 展示营销关键指标 | marketing:read |
| 广告管理 | `/marketing/ads` | 管理广告投放 | marketing:manage |
| 竞品监控 | `/marketing/competitors` | 监控竞品动态 | marketing:read |
---
## 7. 供应商管理模块
### 7.1 页面流转图
```
供应商列表 (/suppliers)
├──► 创建供应商
└──► 供应商详情 (/suppliers/:id)
├── 编辑信息
└── 查看交易记录
```
### 7.2 页面说明
| 页面 | 路径 | 功能 | 权限 |
|------|------|------|------|
| 供应商列表 | `/suppliers` | 展示所有供应商 | supplier:read |
| 供应商详情 | `/suppliers/:id` | 展示供应商详细信息 | supplier:read |
---
## 8. 报表分析模块
### 8.1 页面流转图
```
报表中心 (/reports)
├──► 利润报表 (/reports/profit)
└──► 绩效报表 (/reports/performance)
```
### 8.2 页面说明
| 页面 | 路径 | 功能 | 权限 |
|------|------|------|------|
| 报表中心 | `/reports` | 展示所有报表入口 | report:read |
| 利润报表 | `/reports/profit` | 查看利润分析报表 | report:read |
| 绩效报表 | `/reports/performance` | 查看绩效分析报表 | report:read |
---
## 9. 系统设置模块
### 9.1 页面流转图
```
设置首页 (/settings)
├──► 个人设置 (/settings/profile)
├──► 租户设置 (/settings/tenant)
└──► 用户管理 (/settings/users)
├── 创建用户
└── 编辑用户
```
### 9.2 页面说明
| 页面 | 路径 | 功能 | 权限 |
|------|------|------|------|
| 设置首页 | `/settings` | 设置导航 | - |
| 个人设置 | `/settings/profile` | 修改个人信息 | - |
| 租户设置 | `/settings/tenant` | 管理租户配置 | tenant:manage |
| 用户管理 | `/settings/users` | 管理系统用户 | user:manage |
---
## 10. 全局交互
### 10.1 导航菜单
```
侧边栏菜单
├── 仪表盘
├── 商品管理
├── 订单管理
├── 财务管理
├── 库存管理
├── 营销广告
├── 供应商
├── 报表分析
└── 系统设置
```
### 10.2 面包屑导航
```
首页 / 商品管理 / 商品详情
首页 / 订单管理 / 订单审核
首页 / 财务管理 / 利润对账
```
### 10.3 快捷操作
| 操作 | 触发方式 | 说明 |
|------|----------|------|
| 全局搜索 | Ctrl + K | 快速搜索商品、订单 |
| 通知中心 | 顶部图标 | 查看系统通知 |
| 个人菜单 | 头像下拉 | 个人设置、退出登录 |
---
## 11. 相关文档
- [Frontend Design](./Frontend_Design.md)
- [UI Components](./UI_Components.md)
- [Business ClosedLoops](../00_Business/Business_ClosedLoops.md)
---
*本文档基于业务闭环设计,最后更新: 2026-03-18*

View File

@@ -0,0 +1,493 @@
# UI Components (Crawlful Hub)
> **定位**Crawlful Hub 前端 UI 组件规范 - 基于 Ant Design 5.x 的组件库使用指南。
> **更新日期**: 2026-03-18
---
## 1. 设计系统
### 1.1 色彩规范
```typescript
// 主色调
const colors = {
primary: '#1890ff', // 主色
success: '#52c41a', // 成功
warning: '#faad14', // 警告
error: '#f5222d', // 错误
info: '#1890ff', // 信息
};
// 中性色
const neutral = {
textPrimary: 'rgba(0, 0, 0, 0.85)',
textSecondary: 'rgba(0, 0, 0, 0.65)',
textDisabled: 'rgba(0, 0, 0, 0.25)',
border: '#d9d9d9',
background: '#f5f5f5',
};
```
### 1.2 字体规范
```typescript
const typography = {
fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial',
fontSize: {
small: '12px',
base: '14px',
medium: '16px',
large: '20px',
xlarge: '24px',
},
};
```
---
## 2. 基础组件
### 2.1 按钮 (Button)
**使用场景**
- 主操作:蓝色主按钮
- 次操作:默认按钮
- 危险操作:红色按钮
- 文字链接:链接按钮
**示例**
```tsx
import { Button, Space } from 'antd';
// 主操作
<Button type="primary"></Button>
// 次操作
<Button></Button>
// 危险操作
<Button type="primary" danger></Button>
// 图标按钮
<Button icon={<PlusOutlined />}></Button>
// 加载状态
<Button loading></Button>
```
### 2.2 表单 (Form)
**使用场景**
- 商品创建/编辑
- 订单审核
- 用户设置
**示例**
```tsx
import { Form, Input, Select, Button } from 'antd';
const ProductForm: React.FC = () => {
const [form] = Form.useForm();
const onFinish = (values: any) => {
console.log(values);
};
return (
<Form form={form} onFinish={onFinish} layout="vertical">
<Form.Item
name="title"
label="商品名称"
rules={[{ required: true }]}
>
<Input placeholder="请输入商品名称" />
</Form.Item>
<Form.Item name="platform" label="平台">
<Select>
<Select.Option value="AMAZON">Amazon</Select.Option>
<Select.Option value="EBAY">eBay</Select.Option>
<Select.Option value="SHOPIFY">Shopify</Select.Option>
</Select>
</Form.Item>
<Form.Item>
<Button type="primary" htmlType="submit"></Button>
</Form.Item>
</Form>
);
};
```
### 2.3 表格 (Table)
**使用场景**
- 商品列表
- 订单列表
- 交易流水
**示例**
```tsx
import { Table, Tag } from 'antd';
const ProductTable: React.FC = () => {
const columns = [
{
title: '商品名称',
dataIndex: 'title',
key: 'title',
},
{
title: '平台',
dataIndex: 'platform',
key: 'platform',
},
{
title: '状态',
dataIndex: 'status',
key: 'status',
render: (status: string) => {
const colorMap: Record<string, string> = {
DRAFTED: 'default',
PENDING_REVIEW: 'processing',
APPROVED: 'success',
REJECTED: 'error',
};
return <Tag color={colorMap[status]}>{status}</Tag>;
},
},
{
title: '售价',
dataIndex: 'sellingPrice',
key: 'sellingPrice',
render: (price: number) => `$${price.toFixed(2)}`,
},
{
title: '操作',
key: 'action',
render: (_, record) => (
<Space>
<Button type="link"></Button>
<Button type="link"></Button>
</Space>
),
},
];
return (
<Table
columns={columns}
dataSource={products}
rowKey="id"
pagination={{ pageSize: 20 }}
/>
);
};
```
### 2.4 卡片 (Card)
**使用场景**
- 仪表盘统计卡片
- 商品信息展示
- 订单概要
**示例**
```tsx
import { Card, Statistic } from 'antd';
import { ArrowUpOutlined } from '@ant-design/icons';
// 统计卡片
<Card>
<Statistic
title="本月营收"
value={112893}
precision={2}
valueStyle={{ color: '#3f8600' }}
prefix="$"
suffix={<ArrowUpOutlined />}
/>
</Card>
// 带标题的卡片
<Card title="商品信息" extra={<a href="#"></a>}>
<p>商品名称: Product Name</p>
<p>平台: Amazon</p>
<p>状态: 已上架</p>
</Card>
```
---
## 3. 业务组件
### 3.1 状态徽章 (StatusBadge)
**组件定义**
```tsx
import { Badge } from 'antd';
interface StatusBadgeProps {
status: string;
type: 'product' | 'order' | 'payment';
}
const statusMap: Record<string, Record<string, { color: string; text: string }>> = {
product: {
DRAFTED: { color: 'default', text: '草稿' },
PENDING_REVIEW: { color: 'processing', text: '待审核' },
APPROVED: { color: 'success', text: '已通过' },
REJECTED: { color: 'error', text: '已拒绝' },
LISTED: { color: 'success', text: '已上架' },
DELISTED: { color: 'default', text: '已下架' },
},
order: {
PULLED: { color: 'default', text: '已拉取' },
PENDING_REVIEW: { color: 'processing', text: '待审核' },
CONFIRMED: { color: 'success', text: '已确认' },
SHIPPED: { color: 'blue', text: '已发货' },
DELIVERED: { color: 'success', text: '已送达' },
},
payment: {
PENDING: { color: 'warning', text: '待支付' },
COMPLETED: { color: 'success', text: '已完成' },
FAILED: { color: 'error', text: '失败' },
REFUNDED: { color: 'default', text: '已退款' },
},
};
export const StatusBadge: React.FC<StatusBadgeProps> = ({ status, type }) => {
const config = statusMap[type]?.[status] || { color: 'default', text: status };
return <Badge status={config.color as any} text={config.text} />;
};
```
### 3.2 筛选面板 (FilterPanel)
**组件定义**
```tsx
import { Form, Input, Select, DatePicker, Button, Space } from 'antd';
interface FilterPanelProps {
onFilter: (values: any) => void;
onReset: () => void;
}
export const FilterPanel: React.FC<FilterPanelProps> = ({ onFilter, onReset }) => {
const [form] = Form.useForm();
return (
<Form form={form} layout="inline" onFinish={onFilter}>
<Form.Item name="keyword" label="关键词">
<Input placeholder="搜索..." allowClear />
</Form.Item>
<Form.Item name="platform" label="平台">
<Select allowClear style={{ width: 120 }}>
<Select.Option value="AMAZON">Amazon</Select.Option>
<Select.Option value="EBAY">eBay</Select.Option>
<Select.Option value="SHOPIFY">Shopify</Select.Option>
</Select>
</Form.Item>
<Form.Item name="dateRange" label="日期">
<DatePicker.RangePicker />
</Form.Item>
<Form.Item>
<Space>
<Button type="primary" htmlType="submit"></Button>
<Button onClick={() => { form.resetFields(); onReset(); }}></Button>
</Space>
</Form.Item>
</Form>
);
};
```
### 3.3 数据表格 (DataTable)
**组件定义**
```tsx
import { Table, TableProps } from 'antd';
interface DataTableProps<T> extends TableProps<T> {
loading?: boolean;
pagination?: {
current: number;
pageSize: number;
total: number;
};
onPageChange?: (page: number, pageSize: number) => void;
}
export function DataTable<T extends object>({
loading,
pagination,
onPageChange,
...tableProps
}: DataTableProps<T>) {
return (
<Table<T>
{...tableProps}
loading={loading}
pagination={pagination ? {
...pagination,
showSizeChanger: true,
showTotal: (total) => `${total}`,
onChange: onPageChange,
} : false}
scroll={{ x: 'max-content' }}
/>
);
}
```
---
## 4. 图表组件
### 4.1 利润趋势图
**使用 Ant Design Charts**
```tsx
import { Line } from '@ant-design/charts';
const ProfitChart: React.FC = () => {
const data = [
{ date: '2026-03-01', profit: 1000 },
{ date: '2026-03-02', profit: 1200 },
{ date: '2026-03-03', profit: 900 },
// ...
];
const config = {
data,
xField: 'date',
yField: 'profit',
smooth: true,
point: {
size: 5,
shape: 'diamond',
},
label: {
style: {
fill: '#aaa',
},
},
};
return <Line {...config} />;
};
```
### 4.2 订单分布图
```tsx
import { Pie } from '@ant-design/charts';
const OrderDistributionChart: React.FC = () => {
const data = [
{ type: 'Amazon', value: 400 },
{ type: 'eBay', value: 300 },
{ type: 'Shopify', value: 300 },
];
const config = {
data,
angleField: 'value',
colorField: 'type',
radius: 0.8,
label: {
type: 'outer',
},
};
return <Pie {...config} />;
};
```
---
## 5. 布局组件
### 5.1 主布局 (MainLayout)
```tsx
import { Layout, Menu } from 'antd';
import { Outlet, useNavigate } from 'react-router-dom';
const { Header, Sider, Content } = Layout;
const MainLayout: React.FC = () => {
const navigate = useNavigate();
const menuItems = [
{ key: '/', label: '仪表盘', icon: <DashboardOutlined /> },
{ key: '/products', label: '商品管理', icon: <ShoppingOutlined /> },
{ key: '/orders', label: '订单管理', icon: <FileTextOutlined /> },
{ key: '/finance', label: '财务管理', icon: <DollarOutlined /> },
{ key: '/inventory', label: '库存管理', icon: <InboxOutlined /> },
{ key: '/marketing', label: '营销广告', icon: <BarChartOutlined /> },
{ key: '/suppliers', label: '供应商', icon: <TeamOutlined /> },
{ key: '/reports', label: '报表分析', icon: <PieChartOutlined /> },
{ key: '/settings', label: '系统设置', icon: <SettingOutlined /> },
];
return (
<Layout style={{ minHeight: '100vh' }}>
<Sider theme="light">
<div style={{ height: 64, padding: 16 }}>Crawlful Hub</div>
<Menu
mode="inline"
items={menuItems}
onClick={({ key }) => navigate(key)}
/>
</Sider>
<Layout>
<Header style={{ background: '#fff', padding: '0 24px' }}>
{/* Header content */}
</Header>
<Content style={{ margin: 24, padding: 24, background: '#fff' }}>
<Outlet />
</Content>
</Layout>
</Layout>
);
};
```
---
## 6. 表单校验规则
```typescript
// utils/validators.ts
export const validators = {
required: (message: string) => ({ required: true, message }),
email: { type: 'email', message: '请输入有效的邮箱地址' },
price: (min: number = 0) => ({
validator: (_: any, value: number) => {
if (value >= min) return Promise.resolve();
return Promise.reject(new Error(`价格不能低于 ${min}`));
},
}),
url: { type: 'url', message: '请输入有效的URL' },
};
```
---
## 7. 相关文档
- [Frontend Design](./Frontend_Design.md)
- [Pages Flow](./Pages_Flow.md)
- [Ant Design 官方文档](https://ant.design/)
---
*本文档基于 Ant Design 5.x最后更新: 2026-03-18*