# 系统架构总览

> **版本**: v2.1
> **最后更新**: 2026-04-06

---

## 概述

FF AI Workspace 是一个基于 **Next.js + NestJS + PostgreSQL + Temporal.io** 的全栈企业智能工作空间，采用文档驱动开发和领域驱动设计理念。

---

## 整体架构

```
┌──────────────────────────────────────────────────────────┐
│                     用户层 (Clients)                      │
│                      Web Browser                         │
└────────────────────────┬─────────────────────────────────┘
                         ↓
┌──────────────────────────────────────────────────────────┐
│                    前端应用层 (Frontend)                   │
│                   Next.js 16 App Router                   │
│  ┌──────────┬──────────┬──────────┬──────────┬────────┐ │
│  │ 审批中心  │ 表单管理  │ 绩效管理  │ 组织管理  │ ...   │ │
│  └──────────┴──────────┴──────────┴──────────┴────────┘ │
│  React 19 | TypeScript 5 | Tailwind CSS 4 | Zustand 5    │
└────────────────────────┬─────────────────────────────────┘
                         ↓ REST API
┌──────────────────────────────────────────────────────────┐
│                   后端服务层 (Backend)                     │
│                    NestJS 11 + Prisma 6                   │
│  ┌──────────┬──────────┬──────────┬──────────┬────────┐ │
│  │ 审批引擎  │ 表单引擎  │ 通知服务  │ 文件服务  │ ...   │ │
│  └──────────┴──────────┴──────────┴──────────┴────────┘ │
│  Guards: 认证 | 授权 | 限流 | 日志 | 监控                │
│  Node.js 20 | TypeScript 5 | Prisma ORM                  │
└──────────┬───────────────────────────────┬───────────────┘
           ↓                               ↓
┌─────────────────────┐   ┌────────────────────────────────┐
│   Temporal.io       │   │   数据持久层 (Database)          │
│   工作流编排引擎     │   │   PostgreSQL 16                 │
│   审批流 | 同步任务  │   │   18 个 Schema（按业务域隔离）    │
│   定时任务 | 重试    │   │   Multi-Schema | JSONB           │
└─────────────────────┘   └────────────────────────────────┘
```

> 认证/授权/限流等横切关注点通过 NestJS Guards 和 Interceptors 实现，不是独立的网关服务。

---

## 技术栈

> 具体版本见各 `package.json`，以下只列工具选型。

### 前端

Next.js（App Router）、React、TypeScript、Tailwind CSS、Zustand（状态管理）、React Query（数据获取）、Zod（运行时验证）

### 后端

Node.js、NestJS、Prisma（ORM）、PostgreSQL、Temporal.io（工作流引擎）、Redis（缓存）

### 基础设施

Docker Compose（本地开发 + 基础服务）、MinIO（对象存储）、Nginx（反向代理，生产 Docker 内）、PM2（进程管理，生产 Docker 外）

---

## 数据库架构

采用 Prisma 多 Schema 架构，按业务域隔离（18 个 Schema）。详见 [数据库架构](./04-database-architecture.md)。

---

## 架构设计原则

### 分层架构

```
展示层 (Controller / Page Component)
    ↓
业务逻辑层 (Service / Custom Hooks)
    ↓
数据访问层 (Repository / API Client)
    ↓
数据层 (Database / External API)
```

### 核心原则

- **模块化设计** — 前端按路由分组，后端按领域划分，数据库按业务域隔离
- **松耦合、高内聚** — 模块通过明确接口通信，职责单一，避免循环依赖
- **领域驱动** — 统一语言贯穿代码和文档，领域模型驱动数据库设计

---

## 安全架构

### 认证

JWT 双 Token 机制：Access Token + Refresh Token。支持 Azure Entra ID SSO。

### 权限

RBAC + PBAC 双重控制：

```
用户 → 角色（多对多） → 权限 → 资源
```

---

## 部署架构

### 生产环境

单机部署。前后端由 PM2 管理（Docker 外），基础服务在 Docker 内：

```
Internet → Nginx (Docker)
              ↓
    Frontend (PM2) + Backend (PM2)
              ↓
    PostgreSQL (Docker) + Redis (Docker) + Temporal (Docker) + MinIO (Docker)
```

---

## 相关文档

- [前端架构](./03-frontend-architecture.md)
- [后端架构](./02-backend-architecture.md)
- [数据库架构](./04-database-architecture.md)