feat: 添加前端页面和业务说明书

refactor(server): 重构服务层代码结构 feat(server): 添加基础设施、跨境电商、AI决策等核心服务 docs: 完善前端业务说明书和开发进度文档 style: 格式化代码和文档
2026-03-18 19:12:38 +08:00
parent c932a67be2
commit 6d0d2b6157
140 changed files with 23859 additions and 5833 deletions
--- a/docs/03_Frontend/Frontend_Design.md
+++ b/docs/03_Frontend/Frontend_Design.md
@@ -12,110 +12,89 @@
 |------|------|------|------|
 | **Framework** | React | 18.x | UI 框架 |
 | **Language** | TypeScript | 5.x | 开发语言 |
-| **Build Tool** | Vite | 5.x | 构建工具 |
+| **Build Tool** | Umi | 4.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 | 单元测试 |
+| **State** | Redux | 4.x | 状态管理 |
+| **Router** | Umi Router | 4.x | 路由管理 |
+| **Testing** | Jest | 29.x | 单元测试 |

 ---

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

 ```
-web/src/
+dashboard/src/
+│
+├─ .umi/                        # Umi 生成文件
+│   ├─ core/
+│   ├─ appData.json
+│   └─ exports.ts
 │
 ├─ components/                   # 公共组件
-│   ├─ Layout/                  # 布局组件
-│   │   ├─ MainLayout.tsx
-│   │   ├─ Sidebar.tsx
-│   │   └─ Header.tsx
-│   ├─ Common/                  # 通用组件
-│   │   ├─ DataTable.tsx
-│   │   ├─ FilterPanel.tsx
-│   │   ├─ StatusBadge.tsx
-│   │   └─ ActionButtons.tsx
-│   └─ Charts/                  # 图表组件
-│       ├─ ProfitChart.tsx
-│       ├─ OrderTrendChart.tsx
-│       └─ InventoryChart.tsx
+│   ├─ 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/                        # 页面组件
-│   ├─ Dashboard/               # 首页/仪表盘
-│   │   └─ index.tsx
-│   ├─ Products/                # 商品管理
-│   │   ├─ index.tsx            # 商品列表
-│   │   ├─ Detail.tsx           # 商品详情
-│   │   ├─ Create.tsx           # 创建商品
-│   │   └─ Review.tsx           # 商品审核
-│   ├─ Orders/                  # 订单管理
-│   │   ├─ index.tsx            # 订单列表
-│   │   ├─ Detail.tsx           # 订单详情
-│   │   └─ Audit.tsx            # 订单审核
+│   ├─ ABTest/                  # A/B测试
+│   ├─ Ad/                      # 广告管理
+│   ├─ AfterSales/              # 售后服务
+│   ├─ Auth/                    # 认证
+│   ├─ B2B/                     # B2B贸易
+│   ├─ B2BTrade/                # B2B贸易
+│   ├─ Blacklist/               # 黑名单管理
+│   ├─ Compliance/              # 合规管理
 │   ├─ Finance/                 # 财务管理
-│   │   ├─ index.tsx            # 财务概览
-│   │   ├─ Transactions.tsx     # 交易流水
-│   │   └─ Reconciliation.tsx   # 利润对账
 │   ├─ Inventory/               # 库存管理
-│   │   ├─ index.tsx            # 库存概览
-│   │   ├─ Warehouses.tsx       # 仓库管理
-│   │   └─ Forecast.tsx         # 库存预测
-│   ├─ Marketing/               # 营销广告
-│   │   ├─ index.tsx            # 营销概览
-│   │   ├─ Ads.tsx              # 广告管理
-│   │   └─ Competitors.tsx      # 竞品监控
+│   ├─ Logistics/               # 物流管理
+│   ├─ Marketing/               # 营销管理
+│   ├─ Merchant/                # 商户管理
+│   ├─ Orders/                  # 订单管理
+│   ├─ Product/                 # 商品管理
+│   ├─ Reports/                 # 报表中心
+│   ├─ Return/                  # 退货管理
+│   ├─ Settings/                # 设置
 │   ├─ 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 状态
+│   ├─ UserAsset/               # 用户资产
+│   └─ index.tsx                # 首页/仪表盘
 │
 ├─ services/                     # API 服务
-│   ├─ api.ts                   # Axios 实例
-│   ├─ productService.ts        # 商品 API
-│   ├─ orderService.ts          # 订单 API
-│   ├─ financeService.ts        # 财务 API
-│   └─ authService.ts           # 认证 API
+│   ├─ api/                     # API 客户端
+│   │   ├─ client.ts
+│   │   ├─ index.ts
+│   │   ├─ order.ts
+│   │   ├─ product.ts
+│   │   └─ user.ts
+│   ├─ merchantOrderService.ts  # 商户订单服务
+│   ├─ merchantService.ts       # 商户服务
+│   ├─ merchantSettlementService.ts # 商户结算服务
+│   └─ merchantShopService.ts   # 商户店铺服务
 │
-├─ types/                        # 类型定义
-│   ├─ product.ts               # 商品类型
-│   ├─ order.ts                 # 订单类型
-│   ├─ finance.ts               # 财务类型
-│   └─ common.ts                # 通用类型
+├─ tests/                        # 测试文件
+│   ├─ frontend.functional.test.ts # 前端功能测试
+│   └─ frontend.integration.test.ts # 前端集成测试
 │
-├─ utils/                        # 工具函数
-│   ├─ formatters.ts            # 格式化
-│   ├─ validators.ts            # 校验
-│   └─ constants.ts             # 常量
-│
-├─ styles/                       # 样式文件
-│   └─ global.css
-│
-└─ App.tsx                       # 应用入口
+└─ utils/                        # 工具函数
+    ├─ PerformanceOptimization.ts # 性能优化
+    ├─ performance.ts           # 性能相关
+    ├─ responsive.ts            # 响应式相关
+    └─ security.ts              # 安全相关
 ```

 ---
@@ -212,10 +191,10 @@ const roleRoutes = {
 - 套利分析

 **页面组件**
- `Products/index.tsx` - 商品列表页
- `Products/Detail.tsx` - 商品详情页
- `Products/Create.tsx` - 创建商品页
- `Products/Review.tsx` - 商品审核页
+- `Product/index.tsx` - 商品管理入口
+- `Product/ProductDetail.tsx` - 商品详情页
+- `Product/ProductPublishForm.tsx` - 商品发布表单
+- `Product/MaterialUpload.tsx` - 物料上传

 ### 4.2 订单管理模块

@@ -225,51 +204,214 @@ const roleRoutes = {
 - 订单状态流转
 - 批量审核
 - 订单统计
+- 异常订单处理
+- 订单聚合分析

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

-### 4.3 财务管理模块
+### 4.3 商户管理模块

 **功能列表**
- 财务概览仪表盘
- 交易流水查询
- 利润对账
- 账单回放
- 财务统计报表
+- 商户列表管理
+- 商户订单管理
+- 商户结算管理
+- 商户店铺管理

 **页面组件**
- `Finance/index.tsx` - 财务概览页
- `Finance/Transactions.tsx` - 交易流水页
- `Finance/Reconciliation.tsx` - 利润对账页
+- `Merchant/index.tsx` - 商户管理入口
+- `Merchant/MerchantManage.tsx` - 商户管理
+- `Merchant/MerchantOrderManage.tsx` - 商户订单管理
+- `Merchant/MerchantSettlementManage.tsx` - 商户结算管理
+- `Merchant/MerchantShopManage.tsx` - 商户店铺管理

-### 4.4 库存管理模块
+### 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/Forecast.tsx` - 库存预测页
+- `Inventory/index.tsx` - 库存管理入口
+- `Inventory/Warehouses.tsx` - 仓库管理
+- `Inventory/InventoryForecast.tsx` - 库存预测

-### 4.5 营销广告模块
+### 4.12 营销管理模块

 **功能列表**
 - 营销概览
 - 广告管理
- 竞品监控
- 平台费用监控
+- 竞争对手分析

 **页面组件**
- `Marketing/index.tsx` - 营销概览页
- `Marketing/Ads.tsx` - 广告管理页
- `Marketing/Competitors.tsx` - 竞品监控页
+- `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` - 用户资产

 ---

@@ -316,36 +458,52 @@ export const Products: React.FC = () => {
 ### 5.3 状态管理

 ```typescript
-// Zustand Store 示例
-import { create } from 'zustand';
+// Redux Store 示例
+import { createStore, combineReducers, applyMiddleware } from 'redux';
+import thunk from 'redux-thunk';
+import { createLogger } from 'redux-logger';

-interface ProductState {
-  products: Product[];
-  selectedProduct: Product | null;
-  setProducts: (products: Product[]) => void;
-  setSelectedProduct: (product: Product | null) => void;
+// 定义状态类型
+interface AppState {
+  user: UserState;
+  products: ProductState;
+  orders: OrderState;
+  loading: boolean;
+  error: string | null;
 }

-export const useProductStore = create<ProductState>((set) => ({
-  products: [],
-  selectedProduct: null,
-  setProducts: (products) => set({ products }),
-  setSelectedProduct: (product) => set({ selectedProduct: product }),
-}));
+// 组合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 Axios 配置
+### 6.1 API 客户端配置

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

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

@@ -355,10 +513,6 @@ api.interceptors.request.use((config) => {
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
-  const tenantId = localStorage.getItem('tenantId');
-  if (tenantId) {
-    config.headers['X-Tenant-Id'] = tenantId;
-  }
  return config;
 });

@@ -368,7 +522,7 @@ api.interceptors.response.use(
  (error) => {
    if (error.response?.status === 401) {
      // 处理未授权
-      window.location.href = '/login';
+      window.location.href = '/Auth/LoginPage';
    }
    return Promise.reject(error);
  }
@@ -377,24 +531,43 @@ api.interceptors.response.use(
 export default api;
 ```

-### 6.2 TanStack Query 配置
+### 6.2 API 服务

 ```typescript
-// hooks/useProducts.ts
-import { useQuery, useMutation } from '@tanstack/react-query';
-import { productService } from '@/services/productService';
+// services/api/product.ts
+import api from './client';

-export const useProducts = (params?: ProductParams) => {
-  return useQuery({
-    queryKey: ['products', params],
-    queryFn: () => productService.getAll(params),
-  });
+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}`);
+  },
 };

-export const useCreateProduct = () => {
-  return useMutation({
-    mutationFn: productService.create,
-  });
+// 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 });
+  },
 };
 ```