Files

wurenzhi 2b86715c09 refactor: 优化代码结构并修复类型问题

- 移除未使用的TabPane组件
- 修复类型定义和导入方式
- 优化mock数据源的环境变量判断逻辑
- 更新文档结构并归档旧文件
- 添加新的UI组件和Memo组件
- 调整API路径和响应处理

2026-03-23 12:41:35 +08:00

19 KiB

Raw Permalink Blame History

Frontend Design (Crawlful Hub)

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

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 - 用户资产

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 组件结构

// 页面组件示例
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. 前端发展规划

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. 相关文档

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

19 KiB Raw Permalink Blame History Unescape Escape

Frontend Design (Crawlful Hub)

1. 技术栈 (Tech Stack)

1.1 当前技术栈

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

2. 目录结构 (Directory Structure)

3. 页面路由 (Routes)

3.1 路由结构

3.2 权限路由

4. 核心模块

4.1 商品管理模块

4.2 订单管理模块

4.3 商户管理模块

4.4 售后服务模块

4.5 物流管理模块

4.6 合规管理模块

4.7 黑名单管理模块

4.8 B2B贸易模块

4.9 广告管理模块

4.10 财务管理模块

4.11 库存管理模块

4.12 营销管理模块

4.13 供应商管理模块

4.14 报表中心模块

4.15 设置模块

4.16 A/B测试模块

4.11 退货管理模块

4.12 用户资产管理模块

4.13 多语言管理模块

5. 组件规范

5.1 组件命名

5.2 组件结构

5.3 状态管理

6. API 集成

6.1 API 客户端配置

6.2 API 服务

7. 开发规范

7.1 代码规范

7.2 样式规范

7.3 错误处理

8. 构建与部署

8.1 环境变量

8.2 构建命令

9. 前端发展规划

9.1 前端架构规划

9.2 页面功能扩展计划

9.3 组件库规划

9.4 性能优化规划

9.5 开发体验优化

10. 相关文档

19 KiB

Raw Permalink Blame History