makemd/docs/03_Frontend/Frontend_Design.md

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