# Frontend Design (Crawlful Hub)

> **定位**：Crawlful Hub 前端架构设计文档 - 包含技术栈、目录结构、核心模块及开发规范。
> **更新日期**: 2026-03-18
> **最高优先级参考**: [Business_Blueprint.md](../00_Business/Business_Blueprint.md)

---

## 1. 技术栈 (Tech Stack)

### 1.1 当前技术栈

| 层级 | 技术 | 版本 | 用途 |
|------|------|------|------|
| **Framework** | React | 18.x | UI 框架 |
| **Language** | TypeScript | 5.x | 开发语言 |
| **Build Tool** | Umi | 4.x | 构建工具 |
| **UI Library** | Ant Design | 5.x | 组件库 |
| **State** | Redux | 4.x | 状态管理 |
| **Router** | Umi Router | 4.x | 路由管理 |
| **Testing** | Jest | 29.x | 单元测试 |

### 1.2 技术栈演进 (2026 Q4 目标)

| 层级 | 技术 | 版本 | 用途 |
|------|------|------|------|
| **Framework** | React | 19 (或 Next.js 15) | UI 框架 |
| **Language** | TypeScript | 5.x | 开发语言 |
| **Build Tool** | Vite (开发) + Rspack (生产) | - | 构建工具 |
| **UI Library** | Ant Design 5.x + 自定义组件库 | - | 组件库 |
| **State** | Zustand + TanStack Query | - | 状态管理 |
| **Router** | Umi Router 4.x | - | 路由管理 |
| **Testing** | Jest | 29.x | 单元测试 |
| **微前端** | qiankun | - | 大型模块独立部署 |

---

## 2. 目录结构 (Directory Structure)

```
dashboard/src/
│
├─ .umi/                        # Umi 生成文件
│   ├─ core/
│   ├─ appData.json
│   └─ exports.ts
│
├─ components/                   # 公共组件
│   ├─ ui/                      # UI 组件库
│   │   ├─ Button.tsx
│   │   ├─ Card.tsx
│   │   ├─ ComponentLibrary.tsx
│   │   ├─ Input.tsx
│   │   ├─ ResponsiveLayout.tsx
│   │   └─ index.ts
│   ├─ LazyLoad.tsx             # 懒加载组件
│   ├─ Table.tsx                # 表格组件
│   ├─ VirtualList.tsx          # 虚拟滚动组件
│   ├── README.md
│   └── index.ts
│
├─ models/                       # 状态管理
│   ├─ StateManagement.ts       # 状态管理主文件
│   ├─ global.ts                # 全局状态
│   ├─ order.ts                 # 订单状态
│   ├─ crossBorder.ts           # 跨境电商状态

├─ pages/
│   ├─ CrossBorder/
│   │   ├─ ProductManagement.tsx        # 跨境商品管理
│   │   ├─ CustomsDeclaration.tsx       # 清关申报
│   │   ├─ LogisticsManagement.tsx      # 物流管理
│   │   ├─ PaymentManagement.tsx        # 支付管理
│   │   ├─ PlatformIntegration.tsx      # 平台集成
│   │   └─ index.tsx

├─ services/
│   ├─ crossBorderDataSource.ts         # 跨境电商数据源
│   ├─ platformIntegrationService.ts    # 平台集成服务
│   ├─ product.ts               # 商品状态
│   └── index.ts
│
├─ pages/                        # 页面组件
│   ├─ ABTest/                  # A/B测试
│   ├─ Ad/                      # 广告管理
│   ├─ AfterSales/              # 售后服务
│   ├─ Auth/                    # 认证
│   ├─ B2B/                     # B2B贸易
│   ├─ B2BTrade/                # B2B贸易
│   ├─ Blacklist/               # 黑名单管理
│   ├─ Compliance/              # 合规管理
│   ├─ Finance/                 # 财务管理
│   ├─ Inventory/               # 库存管理
│   ├─ Logistics/               # 物流管理
│   ├─ Marketing/               # 营销管理
│   ├─ Merchant/                # 商户管理
│   ├─ Orders/                  # 订单管理
│   ├─ Product/                 # 商品管理
│   ├─ Reports/                 # 报表中心
│   ├─ Return/                  # 退货管理
│   ├─ Settings/                # 设置
│   ├─ Suppliers/               # 供应商管理
│   ├─ UserAsset/               # 用户资产
│   └─ index.tsx                # 首页/仪表盘
│
├─ services/                     # API 服务
│   ├─ api/                     # API 客户端
│   │   ├─ client.ts
│   │   ├─ index.ts
│   │   ├─ order.ts
│   │   ├─ product.ts
│   │   └─ user.ts
│   ├─ merchantOrderService.ts  # 商户订单服务
│   ├─ merchantService.ts       # 商户服务
│   ├─ merchantSettlementService.ts # 商户结算服务
│   └─ merchantShopService.ts   # 商户店铺服务
│
├─ tests/                        # 测试文件
│   ├─ frontend.functional.test.ts # 前端功能测试
│   └─ frontend.integration.test.ts # 前端集成测试
│
└─ utils/                        # 工具函数
    ├─ PerformanceOptimization.ts # 性能优化
    ├─ performance.ts           # 性能相关
    ├─ responsive.ts            # 响应式相关
    └─ security.ts              # 安全相关
```

---

## 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 商品管理模块

**功能列表**
- 商品列表展示 (分页、筛选、排序)
- 商品详情查看
- 商品创建/编辑
- 商品审核流程
- 批量操作
- 动态定价
- 套利分析

**页面组件**
- `Product/index.tsx` - 商品管理入口
- `Product/ProductDetail.tsx` - 商品详情页
- `Product/ProductPublishForm.tsx` - 商品发布表单
- `Product/MaterialUpload.tsx` - 物料上传

### 4.2 订单管理模块

**功能列表**
- 订单列表展示
- 订单详情查看
- 订单状态流转
- 批量审核
- 订单统计
- 异常订单处理
- 订单聚合分析

**页面组件**
- `Orders/index.tsx` - 订单管理入口
- `Orders/OrderList.tsx` - 订单列表页
- `Orders/OrderDetail.tsx` - 订单详情页
- `Orders/ExceptionOrder.tsx` - 异常订单处理
- `Orders/OrderAggregation.tsx` - 订单聚合分析

### 4.3 商户管理模块

**功能列表**
- 商户列表管理
- 商户订单管理
- 商户结算管理
- 商户店铺管理

**页面组件**
- `Merchant/index.tsx` - 商户管理入口
- `Merchant/MerchantManage.tsx` - 商户管理
- `Merchant/MerchantOrderManage.tsx` - 商户订单管理
- `Merchant/MerchantSettlementManage.tsx` - 商户结算管理
- `Merchant/MerchantShopManage.tsx` - 商户店铺管理

### 4.4 售后服务模块

**功能列表**
- 退货申请处理
- 退款流程管理
- 客户服务

**页面组件**
- `AfterSales/index.tsx` - 售后服务入口
- `AfterSales/ReturnApply.tsx` - 退货申请
- `AfterSales/RefundProcess.tsx` - 退款流程
- `AfterSales/CustomerService.tsx` - 客户服务

### 4.5 物流管理模块

**功能列表**
- 物流选择
- 运费计算
- 物流追踪

**页面组件**
- `Logistics/index.tsx` - 物流管理入口
- `Logistics/LogisticsSelect.tsx` - 物流选择
- `Logistics/FreightCalc.tsx` - 运费计算
- `Logistics/LogisticsTrack.tsx` - 物流追踪

### 4.6 合规管理模块

**功能列表**
- 合规检查
- 证书管理
- 证书过期提醒

**页面组件**
- `Compliance/index.tsx` - 合规管理入口
- `Compliance/ComplianceCheck.tsx` - 合规检查
- `Compliance/CertificateManage.tsx` - 证书管理
- `Compliance/CertificateExpiryReminder.tsx` - 证书过期提醒

### 4.7 黑名单管理模块

**功能列表**
- 黑名单管理
- 风险监控

**页面组件**
- `Blacklist/index.tsx` - 黑名单管理入口
- `Blacklist/BlacklistManage.tsx` - 黑名单管理
- `Blacklist/RiskMonitor.tsx` - 风险监控

### 4.8 B2B贸易模块

**功能列表**
- 企业报价
- 批量订单
- 合同管理

**页面组件**
- `B2B/index.tsx` - B2B贸易入口
- `B2B/EnterpriseQuote.tsx` - 企业报价
- `B2B/BatchOrder.tsx` - 批量订单
- `B2B/ContractManage.tsx` - 合同管理

### 4.9 广告管理模块

**功能列表**
- 广告投放管理
- ROI分析
- 广告计划

**页面组件**
- `Ad/index.tsx` - 广告管理入口
- `Ad/AdDelivery.tsx` - 广告投放
- `Ad/ROIAnalysis.tsx` - ROI分析
- `Ad/AdPlanPage.tsx` - 广告计划

### 4.10 财务管理模块

**功能列表**
- 财务概览
- 交易记录
- 对账记录

**页面组件**
- `Finance/index.tsx` - 财务管理入口
- `Finance/Transactions.tsx` - 交易记录
- `Finance/Reconciliation.tsx` - 对账记录

### 4.11 库存管理模块

**功能列表**
- 库存概览
- 仓库管理
- 库存预测

**页面组件**
- `Inventory/index.tsx` - 库存管理入口
- `Inventory/Warehouses.tsx` - 仓库管理
- `Inventory/InventoryForecast.tsx` - 库存预测

### 4.12 营销管理模块

**功能列表**
- 营销概览
- 广告管理
- 竞争对手分析

**页面组件**
- `Marketing/index.tsx` - 营销管理入口
- `Marketing/Ads.tsx` - 广告管理
- `Marketing/Competitors.tsx` - 竞争对手分析

### 4.13 供应商管理模块

**功能列表**
- 供应商列表
- 供应商详情
- 供应商产品管理

**页面组件**
- `Suppliers/index.tsx` - 供应商管理入口
- `Suppliers/SupplierDetail.tsx` - 供应商详情

### 4.14 报表中心模块

**功能列表**
- 报表概览
- 利润报表
- 绩效报表

**页面组件**
- `Reports/index.tsx` - 报表中心入口
- `Reports/ProfitReport.tsx` - 利润报表
- `Reports/PerformanceReport.tsx` - 绩效报表

### 4.15 设置模块

**功能列表**
- 设置概览
- 个人设置
- 租户设置
- 用户管理

**页面组件**
- `Settings/index.tsx` - 设置入口
- `Settings/ProfileSettings.tsx` - 个人设置
- `Settings/TenantSettings.tsx` - 租户设置
- `Settings/UserManagement.tsx` - 用户管理

### 4.16 A/B测试模块

**功能列表**
- A/B测试配置
- 测试结果分析

**页面组件**
- `ABTest/index.tsx` - A/B测试入口
- `ABTest/ABTestConfig.tsx` - A/B测试配置
- `ABTest/ABTestResults.tsx` - 测试结果分析

### 4.11 退货管理模块

**功能列表**
- 退货监控
- SKU管理

**页面组件**
- `Return/index.tsx` - 退货管理入口
- `Return/ReturnMonitor.tsx` - 退货监控
- `Return/SKUManage.tsx` - SKU管理

### 4.12 用户资产管理模块

**功能列表**
- 会员等级管理
- 积分管理
- 用户资产

**页面组件**
- `UserAsset/index.tsx` - 用户资产管理入口
- `UserAsset/MemberLevel.tsx` - 会员等级管理
- `UserAsset/PointsManage.tsx` - 积分管理
- `UserAsset/UserAssets.tsx` - 用户资产

### 4.13 多语言管理模块

**功能列表**
- 语言切换
- 翻译管理
- 多语言内容发布
- 语言资源管理

**页面组件**
- `I18n/index.tsx` - 多语言管理入口
- `I18n/LanguageSwitcher.tsx` - 语言切换组件
- `I18n/TranslationManage.tsx` - 翻译管理
- `I18n/ContentPublish.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
// Redux Store 示例
import { createStore, combineReducers, applyMiddleware } from 'redux';
import thunk from 'redux-thunk';
import { createLogger } from 'redux-logger';

// 定义状态类型
interface AppState {
  user: UserState;
  products: ProductState;
  orders: OrderState;
  loading: boolean;
  error: string | null;
}

// 组合reducers
const rootReducer = combineReducers({
  user: userReducer,
  products: productsReducer,
  orders: ordersReducer,
  app: appReducer,
});

// 中间件
const middleware = [thunk];
if (process.env.NODE_ENV === 'development') {
  middleware.push(createLogger());
}

// 创建store
const store = createStore(rootReducer, applyMiddleware(...middleware));

export default store;
```

---

## 6. API 集成

### 6.1 API 客户端配置

```typescript
// services/api/client.ts
import axios from 'axios';

const api = axios.create({
  baseURL: process.env.API_URL || 'http://localhost:3000/api',
  timeout: 30000,
});

// 请求拦截器
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// 响应拦截器
api.interceptors.response.use(
  (response) => response.data,
  (error) => {
    if (error.response?.status === 401) {
      // 处理未授权
      window.location.href = '/Auth/LoginPage';
    }
    return Promise.reject(error);
  }
);

export default api;
```

### 6.2 API 服务

```typescript
// services/api/product.ts
import api from './client';

export const productService = {
  getAll: (params?: any) => {
    return api.get('/products', { params });
  },
  getById: (id: string) => {
    return api.get(`/products/${id}`);
  },
  create: (data: any) => {
    return api.post('/products', data);
  },
  update: (id: string, data: any) => {
    return api.put(`/products/${id}`, data);
  },
  delete: (id: string) => {
    return api.delete(`/products/${id}`);
  },
};

// services/api/order.ts
import api from './client';

export const orderService = {
  getAll: (params?: any) => {
    return api.get('/orders', { params });
  },
  getById: (id: string) => {
    return api.get(`/orders/${id}`);
  },
  updateStatus: (id: string, status: string) => {
    return api.put(`/orders/${id}/status`, { status });
  },
};
```

---

## 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. 前端发展规划

### 9.1 前端架构规划

- **微前端架构**: 采用 qiankun 实现大型模块独立部署，解决大型应用构建慢、维护难的问题
- **BFF 层**: 引入 Backend for Frontend 模式，统一接口管理，减少前端复杂度
- **多端适配**: 支持桌面端、平板端和移动端的响应式布局
- **离线能力**: 实现 PWA，支持离线访问核心功能

### 9.2 页面功能扩展计划

| 模块 | 现有功能 | 计划扩展 |
|------|---------|---------|
| 商品管理 | 基础商品管理、套利分析 | 智能选品推荐、商品生命周期管理、多平台批量操作 |
| 订单管理 | 订单列表、状态流转 | 智能审单、异常订单自动处理、多渠道订单聚合 |
| 财务管理 | 基础财务概览 | 智能对账、多币种自动换算、税务报表自动生成 |
| 营销管理 | 广告投放管理 | 智能广告优化、竞品分析、多平台营销协同 |
| 库存管理 | 基础库存管理 | 智能补货建议、库存预测、多仓协同 |
| 物流管理 | 基础物流选择 | 智能物流路径规划、运费优化、实时轨迹监控 |
| 平台集成 | 基础平台连接 | 更多平台集成、API 自动同步、无 API 平台支持 |

### 9.3 组件库规划

- **基础组件**: 基于 Ant Design 5.x 扩展，统一设计规范
- **业务组件**: 封装商品、订单、财务等核心业务组件
- **智能组件**: 集成 AI 能力的智能推荐、智能分析组件
- **可视化组件**: 基于 ECharts 的数据可视化组件库
- **表单组件**: 智能表单验证、动态表单生成

### 9.4 性能优化规划

- **构建优化**: 使用 Vite + Rspack，提升构建速度
- **渲染优化**: 虚拟滚动、懒加载、代码分割
- **缓存策略**: 合理使用浏览器缓存、Service Worker 缓存
- **网络优化**: HTTP/2、HTTP/3 支持，减少请求体积
- **监控体系**: 集成前端性能监控，实时预警性能问题

### 9.5 开发体验优化

- **代码生成**: 基于模板自动生成页面、组件代码
- **Mock 系统**: 完善的 Mock 数据体系，支持离线开发
- **开发工具**: 定制化 VS Code 插件，提升开发效率
- **文档体系**: 自动生成 API 文档、组件文档

---

## 10. 相关文档

- [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*