# FischerX 系统架构

> **文档版本**: v1.0.0  
> **创建日期**: 2026-05-25  
> **最后更新**: 2026-05-25  
> **文档作者**: FischerX 团队  
> **文档状态**: 已发布  
> **适用范围**: 全体开发人员、架构师

## 目录

- [一、架构概述](#一架构概述)
- [二、架构层次](#二架构层次)
- [三、模块划分](#三模块划分)
- [四、技术架构](#四技术架构)
- [五、数据架构](#五数据架构)
- [六、部署架构](#六部署架构)

---

## 一、架构概述

### 1.1 设计理念

FischerX 采用现代化全栈架构设计，遵循以下核心原则：

- **模块化设计**: 将系统拆分为独立可复用的模块，降低耦合度
- **可扩展性**: 支持水平扩展和垂直扩展，预留技术升级空间
- **快速开发**: 开箱即用的基础设施配置，提升开发效率
- **业务复用**: 提取通用业务模式，固化行业最佳实践
- **标准化**: 统一的代码规范、接口标准、数据标准
- **国内适配**: 充分考虑国内环境特殊性，提供完整的国内生态集成

### 1.2 架构目标

- **高可用性**: 99.9% 以上的系统可用性
- **高性能**: 接口响应时间 < 200ms（P95）
- **可维护性**: 清晰的代码结构，完善的文档
- **可扩展性**: 支持从单体应用平滑过渡到微服务
- **安全性**: 满足国内合规要求，数据安全有保障

---

## 二、架构层次

### 2.1 整体架构图

```mermaid
graph TB
    subgraph "应用层"
        WebApp[Web应用]
        AdminApp[管理后台]
        MobileApp[移动应用]
        MiniApp[小程序]
    end
    
    subgraph "业务层"
        UserMod[用户管理]
        AuthMod[权限控制]
        PayMod[支付系统]
        ContMod[内容管理]
        OrderMod[订单系统]
        NotifyMod[消息通知]
        FileMod[文件存储]
        AnalyMod[数据分析]
    end
    
    subgraph "服务层"
        AuthSvc[认证服务]
        PaySvc[支付网关]
        SMSSvc[短信服务]
        VerifySvc[实名认证]
        MapSvc[地图服务]
        AISvc[AI服务]
        MonitorSvc[监控服务]
        LogSvc[日志服务]
    end
    
    subgraph "数据层"
        PostgreSQL[(PostgreSQL)]
        Redis[(Redis)]
        RabbitMQ[(RabbitMQ)]
        Elastic[(Elasticsearch)]
        OSS[(对象存储)]
    end
    
    subgraph "基础设施层"
        K8s[Kubernetes]
        SLB[负载均衡]
        CDN[CDN加速]
        CI_CD[CI/CD]
        Monitor[监控告警]
        Logging[日志收集]
    end
    
    WebApp --> UserMod
    WebApp --> AuthMod
    WebApp --> PayMod
    WebApp --> ContMod
    WebApp --> OrderMod
    WebApp --> NotifyMod
    
    AdminApp --> UserMod
    AdminApp --> AuthMod
    AdminApp --> ContMod
    AdminApp --> OrderMod
    AdminApp --> AnalyMod
    
    MobileApp --> UserMod
    MobileApp --> PayMod
    MobileApp --> OrderMod
    MobileApp --> NotifyMod
    
    MiniApp --> UserMod
    MiniApp --> PayMod
    MiniApp --> OrderMod
    
    UserMod --> AuthSvc
    UserMod --> PostgreSQL
    UserMod --> Redis
    
    AuthMod --> AuthSvc
    AuthMod --> PostgreSQL
    AuthMod --> Redis
    
    PayMod --> PaySvc
    PayMod --> PostgreSQL
    PayMod --> RabbitMQ
    PayMod --> Redis
    
    ContMod --> PostgreSQL
    ContMod --> OSS
    ContMod --> Elastic
    
    OrderMod --> PostgreSQL
    OrderMod --> RabbitMQ
    OrderMod --> Redis
    
    NotifyMod --> SMSSvc
    NotifyMod --> RabbitMQ
    
    FileMod --> OSS
    FileMod --> CDN
    
    AnalyMod --> PostgreSQL
    AnalyMod --> Elastic
    
    AuthSvc --> PostgreSQL
    AuthSvc --> Redis
    
    PaySvc --> PostgreSQL
    PaySvc --> Redis
    
    MonitorSvc --> Monitor
    LogSvc --> Logging
    
    PostgreSQL --> K8s
    Redis --> K8s
    RabbitMQ --> K8s
    Elastic --> K8s
    OSS --> CDN
```

### 2.2 层次说明

#### 应用层
- **Web应用**: 面向用户的主站应用
- **管理后台**: 面向运营人员的管理系统
- **移动应用**: React Native 开发的移动应用
- **小程序**: 微信/支付宝小程序

#### 业务层
- **用户管理模块**: 用户注册、登录、信息管理
- **权限控制模块**: RBAC 权限模型、角色管理、权限分配
- **支付系统模块**: 微信支付、支付宝支付、银联支付
- **内容管理模块**: 内容发布、审核、评论管理
- **订单系统模块**: 订单创建、状态管理、查询统计
- **消息通知模块**: 短信、邮件、推送、站内消息
- **文件存储模块**: 对象存储、文件上传下载、CDN加速
- **数据分析模块**: 用户行为分析、业务统计、数据可视化

#### 服务层
- **认证服务**: JWT Token管理、OAuth2.0集成
- **支付网关**: 统一支付接口、多支付渠道切换
- **短信服务**: 阿里云短信集成
- **实名认证**: 身份证验证、人脸识别
- **地图服务**: 高德地图集成
- **AI服务**: 百度AI、阿里AI集成
- **监控服务**: 性能监控、错误追踪
- **日志服务**: 日志收集、分析、查询

#### 数据层
- **PostgreSQL**: 主关系数据库
- **Redis**: 分布式缓存、会话存储
- **RabbitMQ**: 可靠消息传递
- **Elasticsearch**: 全文搜索、日志分析
- **对象存储**: 阿里云OSS/腾讯云COS

#### 基础设施层
- **Kubernetes**: 容器编排
- **负载均衡**: SLB/CLB
- **CDN加速**: 阿里云CDN
- **CI/CD**: 阿里云云效/Jenkins
- **监控告警**: 阿里云ARMS/Prometheus+Grafana
- **日志收集**: 阿里云SLS/ELK Stack

---

## 三、模块划分

### 3.1 核心模块清单

```yaml
基础模块:
  1. 用户管理模块
     - 用户注册/登录
     - 手机号验证码登录
     - 微信/支付宝登录
     - 实名认证
     - 用户信息管理
  
  2. 权限控制模块
     - RBAC权限模型
     - 角色管理
     - 权限分配
     - 资源访问控制
  
  3. 认证授权模块
     - JWT Token管理
     - Session管理
     - OAuth2.0集成
     - 多因素认证
  
  4. 文件存储模块
     - 对象存储集成
     - 文件上传/下载
     - 图片处理（压缩、裁剪、水印）
     - CDN加速
  
  5. 消息通知模块
     - 短信通知（阿里云短信）
     - 邮件通知
     - 推送通知（小程序、App）
     - 站内消息

业务模块:
  1. 支付系统模块
     - 微信支付集成
     - 支付宝支付集成
     - 银联支付集成
     - 订单管理
     - 退款处理
  
  2. 内容管理模块
     - 内容发布
     - 内容审核（敏感词过滤）
     - 评论管理
     - 标签分类
  
  3. 订单系统模块
     - 订单创建
     - 订单状态管理
     - 订单查询
     - 订单统计
  
  4. 数据分析模块
     - 用户行为分析
     - 业务数据统计
     - 数据可视化
     - 报表生成

服务模块:
  1. 第三方服务集成
     - 地图服务（高德地图）
     - AI服务（百度AI、阿里AI）
     - 实名认证服务
     - OCR识别服务
  
  2. 监控服务模块
     - 性能监控
     - 错误追踪
     - 用户行为追踪
     - 业务指标监控
  
  3. 日志服务模块
     - 日志收集
     - 日志分析
     - 日志查询
     - 日志告警
```

### 3.2 模块依赖关系

```mermaid
graph LR
    UserMod[用户管理] --> AuthMod[认证授权]
    UserMod --> FileMod[文件存储]
    
    AuthMod[认证授权] --> AuthSvc[认证服务]
    
    PayMod[支付系统] --> OrderMod[订单系统]
    PayMod[支付系统] --> NotifyMod[消息通知]
    
    ContMod[内容管理] --> FileMod[文件存储]
    ContMod[内容管理] --> UserMod[用户管理]
    
    OrderMod[订单系统] --> UserMod[用户管理]
    OrderMod[订单系统] --> NotifyMod[消息通知]
    
    NotifyMod[消息通知] --> UserMod[用户管理]
    
    AnalyMod[数据分析] --> UserMod[用户管理]
    AnalyMod[数据分析] --> OrderMod[订单系统]
    AnalyMod[数据分析] --> ContMod[内容管理]
```

---

## 四、技术架构

### 4.1 技术栈总览

| 层级 | 技术选型 | 说明 |
|------|---------|------|
| **前端框架** | Next.js 14+ | React 框架，支持 SSR/SSG |
| **前端语言** | TypeScript 5+ | 类型安全 |
| **前端UI** | Shadcn UI + Tailwind CSS | 组件库 + 原子化 CSS |
| **前端状态** | Zustand + React Query | 轻量级状态管理 |
| **后端框架** | NestJS | 企业级 Node.js 框架 |
| **后端语言** | TypeScript | 前后端技术栈统一 |
| **ORM** | Prisma | 类型安全的 ORM |
| **数据库** | PostgreSQL 15+ | 主关系数据库 |
| **缓存** | Redis 7+ | 分布式缓存 |
| **消息队列** | RabbitMQ | 可靠消息传递 |
| **搜索引擎** | Elasticsearch 8+ | 全文搜索 |
| **对象存储** | 阿里云 OSS | 国内首选云存储 |
| **容器化** | Docker + Kubernetes | 容器编排 |
| **CI/CD** | 阿里云云效 | 国内 CI/CD 平台 |
| **监控** | 阿里云 ARMS + Sentry | 应用监控 + 错误追踪 |
| **日志** | 阿里云 SLS | 日志服务 |

### 4.2 前端技术架构

```yaml
核心框架:
  - Next.js 14+ (React框架，支持SSR/SSG)
  - TypeScript 5+ (类型安全)
  - React 18+ (并发渲染、Suspense)

UI组件库:
  - Shadcn UI (基于Radix UI的组件库)
  - Tailwind CSS 3+ (原子化CSS)
  - Ant Design 5+ (企业级组件库，国内生态)

状态管理:
  - Zustand (轻量级状态管理)
  - React Query (服务端状态管理)
  - React Hook Form (表单管理)

工具链:
  - Vite (构建工具)
  - ESLint + Prettier (代码规范)
  - Vitest + Playwright (测试框架)
```

### 4.3 后端技术架构

```yaml
核心框架:
  - Node.js 20+ LTS
  - NestJS (企业级Node.js框架)

ORM框架:
  - Prisma (Node.js ORM，类型安全)

API设计:
  - RESTful API (标准接口)
  - GraphQL (灵活查询)
  - tRPC (端到端类型安全)

认证授权:
  - Passport.js (Node.js认证中间件)
  - JWT + RBAC权限控制
```

---

## 五、数据架构

### 5.1 数据库选型

| 数据库类型 | 技术选型 | 使用场景 |
|-----------|---------|---------|
| **关系型数据库** | PostgreSQL 15+ | 主数据库，存储业务数据 |
| **缓存数据库** | Redis 7+ | 分布式缓存、会话存储 |
| **消息队列** | RabbitMQ | 异步任务、事件驱动 |
| **搜索引擎** | Elasticsearch 8+ | 全文搜索、日志分析 |
| **对象存储** | 阿里云 OSS | 文件、图片、视频存储 |

### 5.2 数据流向

```mermaid
graph LR
    App[前端应用] --> API[API服务]
    API --> PostgreSQL[(PostgreSQL)]
    API --> Redis[(Redis)]
    API --> RabbitMQ[(RabbitMQ)]
    API --> OSS[(对象存储)]
    
    Worker[后台任务] --> RabbitMQ
    Worker --> PostgreSQL
    Worker --> Redis
    
    Search[搜索服务] --> Elastic[(Elasticsearch)]
    Search --> PostgreSQL
    
    Analy[分析服务] --> PostgreSQL
    Analy --> Elastic
```

---

## 六、部署架构

### 6.1 环境划分

| 环境 | 用途 | 数据隔离 |
|------|------|---------|
| **开发环境** | 日常开发、调试 | 独立数据库 |
| **测试环境** | 功能测试、集成测试 | 独立数据库（测试数据） |
| **预发布环境** | 发布前验证 | 独立数据库（生产数据快照） |
| **生产环境** | 正式对外服务 | 生产数据库 |

### 6.2 部署架构图

```mermaid
graph TB
    subgraph "CDN层"
        CDN[阿里云CDN]
    end
    
    subgraph "负载均衡层"
        SLB[阿里云SLB]
    end
    
    subgraph "应用层"
        WebPod1[Web Pod 1]
        WebPod2[Web Pod 2]
        WebPodN[Web Pod N]
        APIPod1[API Pod 1]
        APIPod2[API Pod 2]
        APIPodN[API Pod N]
    end
    
    subgraph "服务层"
        Redis[(Redis 主从)]
        RabbitMQ[(RabbitMQ 集群)]
        Elastic[(Elasticsearch 集群)]
    end
    
    subgraph "数据层"
        PostgreSQL[(PostgreSQL 主从)]
        OSS[(阿里云OSS)]
    end
    
    CDN --> SLB
    SLB --> WebPod1
    SLB --> WebPod2
    SLB --> WebPodN
    SLB --> APIPod1
    SLB --> APIPod2
    SLB --> APIPodN
    
    WebPod1 --> Redis
    WebPod1 --> APIPod1
    WebPod2 --> Redis
    WebPod2 --> APIPod2
    WebPodN --> Redis
    WebPodN --> APIPodN
    
    APIPod1 --> PostgreSQL
    APIPod1 --> Redis
    APIPod1 --> RabbitMQ
    APIPod1 --> OSS
    APIPod2 --> PostgreSQL
    APIPod2 --> Redis
    APIPod2 --> RabbitMQ
    APIPod2 --> OSS
    APIPodN --> PostgreSQL
    APIPodN --> Redis
    APIPodN --> RabbitMQ
    APIPodN --> OSS
    
    RabbitMQ --> Elastic
    PostgreSQL --> Elastic
```

### 6.3 容器编排

使用 Kubernetes 进行容器编排，主要包括：

- **Deployment**: 管理无状态应用
- **StatefulSet**: 管理有状态应用（数据库、Redis等）
- **Service**: 服务发现和负载均衡
- **ConfigMap/Secret**: 配置管理
- **Ingress**: 外部访问入口
- **HPA**: 水平自动扩缩容

---

## 七、演进路线

### 7.1 第一阶段：单体应用

- 所有模块部署在同一个应用中
- 共享数据库和缓存
- 适合初期快速迭代

### 7.2 第二阶段：服务拆分

- 将核心模块拆分为独立服务
- 用户服务、支付服务、订单服务等
- 服务间通过 API 或消息队列通信

### 7.3 第三阶段：微服务架构

- 完全微服务化
- 每个服务独立部署、扩展
- 服务网格治理
- 链路追踪、熔断降级

---

> **文档维护**: 本文档由架构师维护，架构重大变更时更新  
> **反馈渠道**: 如有问题，请提交 Issue 或联系架构师  
> **最后更新**: 2026-05-25  
> **文档状态**: 已发布