wurenzhi
72cd7f6f45
删除不再需要的归档文件和过时的文档模板，包括多个README、安全策略、前端集成蓝图等文件，同时移除了未使用的业务文档和项目结构文件。 优化项目结构，移除冗余文件，保持代码库整洁。主要删除archive/handover目录下的多个文件及doc目录下的部分文档模板。
471 lines
12 KiB
Markdown
471 lines
12 KiB
Markdown
# 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*
|