系统架构

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

> **搜索标签**: 架构, 系统架构, 技术架构, 设计, 整体架构
---

# 系统架构

## 概述

本文档介绍了企业管理数字化中台的整体架构设计，包括技术架构、部署架构、数据架构和安全架构。

## 技术架构

### 分层架构

系统采用经典的分层架构设计，共分为四层：

```
┌─────────────────────────────────────────────────┐
│           表现层 (Presentation Layer)           │
│  Next.js 16 + React 19 + shadcn/ui + Ant Design │
└─────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────┐
│            应用层 (Application Layer)            │
│      API Routes + Manager Layer + Business      │
└─────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────┐
│             数据层 (Data Layer)                 │
│        Drizzle ORM + Repository Pattern         │
└─────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────┐
│          基础设施层 (Infrastructure)            │
│    PostgreSQL + Redis + Object Storage (Qiniu)  │
└─────────────────────────────────────────────────┘
```

### 表现层 (Presentation Layer)

**技术栈**:
- Next.js 16 (App Router)
- React 19
- TypeScript 5
- shadcn/ui
- Ant Design
- Tailwind CSS 4

**职责**:
- 页面渲染
- 用户交互
- 数据展示
- 表单验证

**特性**:
- 服务端渲染 (SSR)
- 客户端组件 (CSR)
- 静态生成 (SSG)
- 增量静态生成 (ISR)

### 应用层 (Application Layer)

**技术栈**:
- Next.js API Routes
- TypeScript
- Drizzle ORM

**职责**:
- 请求处理
- 业务逻辑
- 数据验证
- 权限控制

**设计模式**:
- Manager 模式：封装业务逻辑
- Repository 模式：数据访问抽象
- Service 模式：复杂业务编排

### 数据层 (Data Layer)

**技术栈**:
- Drizzle ORM
- PostgreSQL 16

**职责**:
- 数据持久化
- 查询优化
- 事务管理
- 数据验证

**特性**:
- 类型安全的查询
- 自动迁移
- 连接池管理

### 基础设施层 (Infrastructure)

**技术栈**:
- PostgreSQL 16（关系型数据库）
- Redis（缓存）
- 七牛云（对象存储）
- FastAPI（内部服务）

**职责**:
- 数据存储
- 缓存管理
- 文件存储
- 内部服务

## 部署架构

### 生产环境

```
                              ┌─────────────┐
                              │   负载均衡   │
                              │  (Nginx)    │
                              └──────┬──────┘
                                     │
                    ┌────────────────┼────────────────┐
                    ↓                ↓                ↓
             ┌──────────┐     ┌──────────┐     ┌──────────┐
             │  实例 1   │     │  实例 2   │     │  实例 N   │
             │ Next.js  │     │ Next.js  │     │ Next.js  │
             │ :5000    │     │ :5000    │     │ :5000    │
             └────┬─────┘     └────┬─────┘     └────┬─────┘
                  │                │                │
                  └────────────────┼────────────────┘
                                   ↓
                    ┌──────────────────────────────┐
                    │        PostgreSQL 主库        │
                    │         :5432                │
                    └───────────┬──────────────────┘
                                │
                    ┌───────────┴──────────────────┐
                    ↓                             ↓
            ┌──────────────┐            ┌──────────────┐
            │ PostgreSQL 从库│            │   Redis 缓存   │
            │   :5432      │            │   :6379       │
            └──────────────┘            └──────────────┘
```

### 开发环境

```
┌─────────────────────────────────────────┐
│          开发机 (localhost)             │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │   Next.js Dev Server :5000     │   │
│  │   (HMR 热更新)                  │   │
│  └────────────┬────────────────────┘   │
│               │                         │
│               ↓                         │
│  ┌─────────────────────────────────┐   │
│  │   PostgreSQL :5432              │   │
│  │   (Docker / 本地)                │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │   Redis :6379                   │   │
│  │   (Docker / 本地)                │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘
```

### 沙箱环境

```
┌─────────────────────────────────────────┐
│            沙箱环境                      │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │   Next.js Server :5000          │   │
│  └────────────┬────────────────────┘   │
│               │                         │
│               ↓                         │
│  ┌─────────────────────────────────┐   │
│  │   FastAPI Server :9000          │   │
│  │   (沙箱系统服务)                 │   │
│  └────────────┬────────────────────┘   │
│               │                         │
│               ↓                         │
│  ┌─────────────────────────────────┐   │
│  │   PostgreSQL (集成服务)         │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘
```

## 数据架构

### 数据模型

系统采用关系型数据模型，通过外键关联实现数据一致性。

**核心实体**:
- 租户 (Tenant)
- 企业 (Company)
- 用户 (User)
- 员工 (Employee)
- 工资条 (Salary Slip)

**配置实体**:
- 薪资配置 (Salary Config)
- 薪资项配置 (Salary Item Config)
- 社保配置 (Social Insurance Config)
- 税率表 (Tax Rate Table)

**业务实体**:
- 订单 (Order)
- 交易 (Transaction)
- 跟进记录 (Follow Record)

### 数据流

```
┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│   用户   │ ──→ │  API     │ ──→ │ Manager  │ ──→ │ Repository│
│  请求    │     │  Routes  │     │  Layer   │     │   Layer   │
└──────────┘     └──────────┘     └──────────┘     └─────┬────┘
                                                            │
                                                            ↓
                                                    ┌──────────────┐
                                                    │  PostgreSQL  │
                                                    └──────────────┘
```

### 缓存策略

**缓存类型**:
- 查询结果缓存：使用内存缓存
- 会话缓存：使用 Redis
- 文件缓存：使用对象存储

**缓存失效**:
- 时间失效：TTL（默认 5 分钟）
- 主动失效：更新/删除操作时清除
- 定期清理：每分钟清理过期缓存

## 安全架构

### 认证授权

**认证机制**:
- JWT Token 认证
- 支持多种登录方式（密码、短信、微信）
- Token 有效期：24 小时

**授权机制**:
- RBAC（基于角色的访问控制）
- 数据隔离：租户级别
- 权限验证：API 层 + Manager 层双重验证

### 数据安全

**加密存储**:
- 密码：bcrypt 加密
- 敏感配置：AES 加密
- 传输加密：HTTPS/TLS

**数据隔离**:
- 租户数据完全隔离
- 行级数据权限控制
- 敏感数据脱敏显示

### 网络安全

**防护措施**:
- CORS 策略
- XSS 防护
- CSRF 防护
- SQL 注入防护

## 微服务架构

**服务拆分**:
- 前端服务：Next.js 应用
- 认证服务：登录、登出、权限
- 业务服务：工资条、订单、支付
- 通知服务：邮件、短信、微信
- 存储服务：文件上传、下载

**服务通信**:
- 同步调用：HTTP REST API
- 异步通信：消息队列（计划中）

## 性能架构

### 前端性能

**优化策略**:
- 代码分割
- 懒加载
- 图片优化
- 浏览器缓存

**监控指标**:
- 首次内容绘制 (FCP)
- 首次有意义绘制 (FMP)
- 交互时间 (TTI)
- 累积布局偏移 (CLS)

### 后端性能

**优化策略**:
- 数据库索引优化
- 查询优化
- 缓存策略
- 连接池管理

**监控指标**:
- API 响应时间
- 数据库查询时间
- 错误率
- 吞吐量

## 可扩展性

### 水平扩展

**扩展策略**:
- 无状态服务：支持水平扩展
- 数据库读写分离：支持多从库
- 缓存集群：支持 Redis 集群
- 负载均衡：支持多实例部署

### 垂直扩展

**扩展策略**:
- 数据库升级
- 服务器升级
- 网络带宽升级

## 高可用性

### 故障恢复

**恢复策略**:
- 数据备份：每日全量备份
- 自动故障转移：主从切换
- 服务降级：核心服务优先

### 容灾备份

**备份策略**:
- 异地备份
- 多副本存储
- 定期恢复演练

## 监控和日志

### 应用监控

**监控内容**:
- 应用性能
- 错误追踪
- 资源使用

**监控工具**:
- 应用日志
- 系统日志
- 性能指标

### 日志管理

**日志分类**:
- 应用日志：/app/work/logs/bypass/app.log
- 开发日志：/app/work/logs/bypass/dev.log
- 控制台日志：/app/work/logs/bypass/console.log

**日志级别**:
- DEBUG：调试信息
- INFO：一般信息
- WARN：警告信息
- ERROR：错误信息

## 技术选型理由

### Next.js 16

**选择理由**:
- React 生态最成熟的服务端框架
- 支持多种渲染模式（SSR、CSR、SSG）
- 内置 API Routes，无需额外后端框架
- 优秀的开发体验（HMR、TypeScript 支持）
- 强大的生态系统（UI 组件、工具库）

### PostgreSQL

**选择理由**:
- 成熟稳定的关系型数据库
- 优秀的性能和扩展性
- 支持 JSON 类型，灵活存储
- 强大的事务支持
- 活跃的社区和丰富的工具

### Drizzle ORM

**选择理由**:
- TypeScript-first，类型安全
- 轻量级，性能优秀
- SQL-like API，学习成本低
- 自动迁移支持
- 与 PostgreSQL 完美集成

### 七牛云存储

**选择理由**:
- 国内访问速度快
- 成本低
- 支持多种存储类型
- 提供 CDN 加速
- 丰富的 SDK 支持

## 未来规划

### 短期计划

1. 引入消息队列（RabbitMQ/Kafka）
2. 实现微服务架构
3. 添加实时通信（WebSocket）
4. 优化数据库查询性能

### 长期计划

1. 支持 Kubernetes 部署
2. 实现多地域部署
3. 引入 AI 能力
4. 构建开发者生态

## 参考文档

- [技术栈说明](./架构结构.md)
- [API 接口文档](../04-API文档/API接口文档.md)
- [数据库字典](../05-数据库/数据库字典.md)
- [开发规范](../03-开发指南/开发指南.md)
- [部署指南](../08-版本管理/README.md)