makemd/docs/03_Frontend/Frontend_Design.md

Frontend Design (Crawlful Hub)

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

---

1. 技术栈 (Tech Stack)

层级	技术	版本	用途
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	单元测试

---

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                 # 订单状态
│   ├─ 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 路由结构

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 权限路由

// 基于角色的路由访问控制
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 - 用户资产

---

5. 组件规范

5.1 组件命名

• 页面组件: PascalCase，以功能命名 (如 ProductList, OrderDetail)
• 公共组件: PascalCase，以功能命名 (如 DataTable, FilterPanel)
• Hooks: camelCase，以 use 开头 (如 useProducts, useAuth)

5.2 组件结构

// 页面组件示例
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 状态管理

// 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 客户端配置

// 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 服务

// 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 错误处理

// 错误边界
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 环境变量

VITE_API_URL=http://localhost:3000/api/v1
VITE_APP_NAME=Crawlful Hub
VITE_APP_VERSION=1.0.0

8.2 构建命令

npm install       # 安装依赖
npm run dev       # 开发模式
npm run build     # 生产构建
npm run preview   # 预览构建
npm run test      # 运行测试

---

9. 相关文档

• UI Components
• Pages Flow
• API Consumption
• Backend API Specs

---

本文档基于业务蓝图设计，最后更新: 2026-03-18