WEB/docs/技术架构图.md

# WEB项目技术架构图

## 架构概述

### 背景意义
技术架构图用于展示YOONE WEB项目的整体技术结构，包括前端架构层次、数据流向、组件关系和技术栈组成，为开发团队提供清晰的技术视图。

### 架构定义
采用分层架构模式，将系统划分为表现层、业务层、数据层和基础设施层，实现关注点分离和模块化管理。

## 整体架构图

```mermaid
graph TB
    subgraph "用户层"
        U1[管理员用户]
        U2[普通用户]
    end
    
    subgraph "前端应用层 (React + Umi)"
        subgraph "路由层"
            R1[登录路由]
            R2[业务路由]
            R3[权限路由]
        end
        
        subgraph "页面组件层"
            P1[首页 Home]
            P2[用户管理 Organiza]
            P3[商品管理 Product]
            P4[订单管理 Order]
            P5[库存管理 Stock]
            P6[客户管理 Customer]
            P7[物流管理 Logistics]
            P8[数据统计 Statistics]
        end
        
        subgraph "业务组件层"
            C1[表格组件 ProTable]
            C2[表单组件 ProForm]
            C3[图表组件 Charts]
            C4[布局组件 Layout]
        end
        
        subgraph "工具层"
            T1[API服务 servers/api]
            T2[工具函数 utils]
            T3[常量定义 constants]
            T4[类型定义 typings]
        end
    end
    
    subgraph "状态管理层"
        S1[全局状态 @@initialState]
        S2[用户状态 global model]
        S3[权限状态 access]
    end
    
    subgraph "网络层"
        N1[HTTP请求拦截器]
        N2[响应处理器]
        N3[错误处理器]
    end
    
    subgraph "后端API层"
        A1[用户API /user]
        A2[商品API /product]
        A3[订单API /order]
        A4[库存API /stock]
        A5[物流API /logistics]
        A6[统计API /statistics]
    end
    
    U1 --> R1
    U2 --> R1
    R1 --> P1
    R2 --> P2
    R2 --> P3
    R2 --> P4
    R2 --> P5
    R2 --> P6
    R2 --> P7
    R2 --> P8
    R3 --> S3
    
    P1 --> C1
    P2 --> C2
    P3 --> C3
    P4 --> C4
    
    C1 --> T1
    C2 --> T2
    C3 --> T3
    C4 --> T4
    
    T1 --> N1
    N1 --> N2
    N2 --> N3
    
    N3 --> A1
    N3 --> A2
    N3 --> A3
    N3 --> A4
    N3 --> A5
    N3 --> A6
    
    S1 --> P1
    S2 --> P2
    S3 --> R3
```

## 技术栈架构

### 核心技术栈层次图

```mermaid
graph LR
    subgraph "开发工具层"
        D1[TypeScript 5.7]
        D2[ESLint]
        D3[Prettier]
        D4[Husky]
    end
    
    subgraph "构建工具层"
        B1[Umi Max 4.4]
        B2[Webpack]
        B3[Babel]
        B4[PostCSS]
    end
    
    subgraph "框架层"
        F1[React 18]
        F2[Ant Design 5.4]
        F3[Pro Components 2.4]
    end
    
    subgraph "功能库层"
        L1[ECharts 5.6]
        L2[dayjs 1.11]
        L3[file-saver 2.0]
        L4[xlsx 0.18]
    end
    
    subgraph "运行时层"
        R1[浏览器环境]
        R2[Node.js环境]
    end
    
    D1 --> B1
    D2 --> B1
    D3 --> B1
    D4 --> B1
    
    B1 --> F1
    B2 --> F1
    B3 --> F1
    B4 --> F1
    
    F1 --> L1
    F2 --> L1
    F3 --> L1
    
    L1 --> R1
    L2 --> R1
    L3 --> R1
    L4 --> R1
```

## 数据流架构

### 数据流向图

```mermaid
sequenceDiagram
    participant U as 用户界面
    participant C as 组件层
    participant S as 状态管理
    participant A as API层
    participant B as 后端服务
    
    U->>C: 用户操作
    C->>S: 更新状态
    S->>A: 发起请求
    A->>B: HTTP请求
    B-->>A: 响应数据
    A-->>S: 处理响应
    S-->>C: 状态更新
    C-->>U: 界面更新
```

### 权限控制流程

```mermaid
graph TD
    A[用户登录] --> B{Token验证}
    B -->|有效| C[获取用户信息]
    B -->|无效| D[跳转登录页]
    C --> E[解析用户权限]
    E --> F{路由权限检查}
    F -->|有权限| G[渲染页面]
    F -->|无权限| H[显示403页面]
    G --> I[页面级权限控制]
    I --> J[功能按钮权限]
```

## 组件架构设计

### 组件层次结构

| 层级 | 组件类型 | 职责描述 | 示例组件 |
|------|---------|---------|---------|
| 1 | 页面组件 | 业务页面容器，路由对应 | Home、Order/List |
| 2 | 业务组件 | 特定业务逻辑封装 | OrderTable、ProductForm |
| 3 | 通用组件 | 可复用UI组件 | InternationalPhoneInput |
| 4 | 基础组件 | Ant Design组件 | Table、Form、Button |

### 组件通信模式

```mermaid
graph TB
    subgraph "父子组件通信"
        P1[父组件] -->|Props| C1[子组件]
        C1 -->|Events| P1
    end
    
    subgraph "跨组件通信"
        G1[全局状态] --> C2[组件A]
        G1 --> C3[组件B]
        C2 --> G1
        C3 --> G1
    end
    
    subgraph "兄弟组件通信"
        S1[共同父组件] --> B1[兄弟组件1]
        S1 --> B2[兄弟组件2]
        B1 -.->|通过父组件| B2
    end
```

## API架构设计

### API接口分层

```mermaid
graph TB
    subgraph "API接口层"
        A1[用户接口 user.ts]
        A2[订单接口 order.ts]
        A3[商品接口 product.ts]
        A4[库存接口 stock.ts]
        A5[物流接口 logistics.ts]
        A6[统计接口 statistics.ts]
    end
    
    subgraph "请求处理层"
        R1[请求拦截器]
        R2[响应拦截器]
        R3[错误处理器]
    end
    
    subgraph "数据传输层"
        D1[HTTP Client]
        D2[请求配置]
        D3[类型定义]
    end
    
    A1 --> R1
    A2 --> R1
    A3 --> R1
    A4 --> R1
    A5 --> R1
    A6 --> R1
    
    R1 --> R2
    R2 --> R3
    
    R3 --> D1
    D1 --> D2
    D2 --> D3
```

### API调用流程

```mermaid
sequenceDiagram
    participant C as 组件
    participant API as API函数
    participant I as 拦截器
    participant H as HTTP客户端
    participant S as 后端服务
    
    C->>API: 调用API函数
    API->>I: 请求拦截
    I->>I: 添加Token
    I->>H: 发送请求
    H->>S: HTTP请求
    S-->>H: 响应数据
    H-->>I: 响应拦截
    I-->>I: 错误处理
    I-->>API: 返回结果
    API-->>C: 返回数据
```

## 构建部署架构

### 构建流程图

```mermaid
graph LR
    subgraph "开发环境"
        D1[源代码]
        D2[TypeScript编译]
        D3[热重载]
    end
    
    subgraph "构建流程"
        B1[代码检查]
        B2[类型检查]
        B3[打包构建]
        B4[资源优化]
    end
    
    subgraph "部署环境"
        P1[静态资源]
        P2[CDN分发]
        P3[Web服务器]
    end
    
    D1 --> D2
    D2 --> D3
    D3 --> B1
    B1 --> B2
    B2 --> B3
    B3 --> B4
    B4 --> P1
    P1 --> P2
    P2 --> P3
```

### 环境配置对比

| 环境 | 构建模式 | API地址 | 特性 |
|------|---------|---------|------|
| 开发环境 | development | http://localhost:7001 | 热重载、Source Map |
| 生产环境 | production | https://api.yoone.ca | 代码压缩、资源优化 |

## 性能优化架构

### 性能优化策略

```mermaid
graph TB
    subgraph "加载优化"
        L1[代码分割]
        L2[懒加载]
        L3[预加载]
    end
    
    subgraph "渲染优化"
        R1[虚拟滚动]
        R2[组件缓存]
        R3[防抖节流]
    end
    
    subgraph "资源优化"
        A1[图片压缩]
        A2[资源合并]
        A3[CDN加速]
    end
    
    subgraph "缓存策略"
        C1[浏览器缓存]
        C2[HTTP缓存]
        C3[应用缓存]
    end
    
    L1 --> R1
    L2 --> R2
    L3 --> R3
    
    R1 --> A1
    R2 --> A2
    R3 --> A3
    
    A1 --> C1
    A2 --> C2
    A3 --> C3
```

## 安全架构设计

### 安全防护层次

```mermaid
graph TB
    subgraph "认证授权层"
        S1[JWT Token认证]
        S2[权限验证]
        S3[设备指纹识别]
    end
    
    subgraph "数据安全层"
        D1[HTTPS传输]
        D2[数据加密]
        D3[敏感信息脱敏]
    end
    
    subgraph "应用安全层"
        A1[XSS防护]
        A2[CSRF防护]
        A3[输入验证]
    end
    
    S1 --> D1
    S2 --> D2
    S3 --> D3
    
    D1 --> A1
    D2 --> A2
    D3 --> A3
```

## 监控架构设计

### 监控体系结构

```mermaid
graph LR
    subgraph "前端监控"
        F1[性能监控]
        F2[错误监控]
        F3[用户行为]
    end
    
    subgraph "数据收集"
        C1[埋点数据]
        C2[日志收集]
        C3[性能指标]
    end
    
    subgraph "数据分析"
        A1[实时分析]
        A2[报表生成]
        A3[告警通知]
    end
    
    F1 --> C1
    F2 --> C2
    F3 --> C3
    
    C1 --> A1
    C2 --> A2
    C3 --> A3
```

## 架构演进规划

### 短期优化(1-3个月)

1. **组件库建设**
   - 提取公共业务组件
   - 建立组件文档系统
   - 实现组件单元测试

2. **性能优化**
   - 实现路由级代码分割
   - 添加组件懒加载
   - 优化打包体积

### 中期升级(3-6个月)

1. **状态管理升级**
   - 引入Redux Toolkit
   - 实现状态持久化
   - 优化数据流管理

2. **工程化完善**
   - 建立自动化测试
   - 完善CI/CD流程
   - 添加代码质量检查

### 长期规划(6个月以上)

1. **微前端架构**
   - 模块联邦改造
   - 独立部署能力
   - 团队协作优化

2. **技术栈升级**
   - React 19升级
   - 新特性应用
   - 性能进一步优化

## 架构最佳实践

### 设计原则

| 原则 | 描述 | 实现方式 |
|------|------|---------|
| 单一职责 | 每个组件只负责一个功能 | 组件功能拆分 |
| 开闭原则 | 对扩展开放，对修改关闭 | 插件化设计 |
| 依赖倒置 | 依赖抽象而非具体实现 | 接口定义 |
| 关注点分离 | 不同关注点分层处理 | 分层架构 |

### 代码组织规范

```typescript
// 推荐的文件组织结构
src/
├── components/          // 公共组件
│   ├── Business/       // 业务组件
│   └── Common/         // 通用组件
├── pages/              // 页面组件
│   └── [Module]/       // 按模块组织
├── services/           // API服务
├── utils/              // 工具函数
├── hooks/              // 自定义Hook
├── constants/          // 常量定义
└── types/              // 类型定义
```

---

*文档版本: v1.0*  
*更新时间: 2024年12月*  
*维护团队: 前端开发组*