# 项目技术栈架构文档

> 更新时间：2026-01-21  
> 部署方式：Docker Compose

---

## 📋 目录

- [前端技术栈](#前端技术栈)
- [后端技术栈](#后端技术栈)
- [基础设施](#基础设施)
- [开发工具](#开发工具)

---

## 🎨 前端技术栈

### 核心框架
- **React 19.2.0** - UI 框架
- **TypeScript 5.9.3** - 类型系统
- **Vite 7.2.4** - 构建工具

### 路由与状态管理
- **React Router DOM 7.6.1** - 客户端路由
- **Zustand 5.0.5** - 轻量级状态管理
- **TanStack Query 5.80.7** - 服务端状态管理与数据缓存

### UI 组件库
- **Radix UI** - 无样式可访问组件库
  - Dialog, Dropdown, Popover, Tooltip 等 20+ 组件
- **Lucide React 0.562.0** - 图标库
- **Tailwind CSS 4.1.18** - 原子化 CSS 框架
- **Tailwind Animate** - 动画工具

### 表单与验证
- **React Hook Form 7.57.0** - 表单管理
- **Zod 3.25.64** - Schema 验证
- **@hookform/resolvers 5.1.0** - 表单验证集成

### 拖拽与交互
- **@dnd-kit** - 拖拽排序
  - core 6.3.1
  - sortable 10.0.0
  - utilities 3.2.2

### 文档处理
- **Fountain.js 1.2.4** - 剧本格式解析
- **Mammoth 1.11.0** - Word 文档解析
- **PDF.js 5.4.530** - PDF 渲染
- **Turndown 7.2.2** - HTML 转 Markdown
- **React Markdown 10.1.0** - Markdown 渲染

### 国际化
- **i18next 25.2.1** - 国际化框架
- **react-i18next 15.5.2** - React 集成
- **i18next-browser-languagedetector** - 语言检测
- **i18next-http-backend** - 远程翻译加载

### 工具库
- **Axios 1.10.0** - HTTP 客户端
- **date-fns 4.1.0** - 日期处理
- **clsx + tailwind-merge** - 类名合并
- **class-variance-authority** - 组件变体管理

### 虚拟化
- **react-window 2.2.5** - 列表虚拟化
- **react-virtualized-auto-sizer** - 自动尺寸计算

---

## ⚙️ 后端技术栈

### 核心框架
- **FastAPI 0.109.0** - 现代异步 Web 框架
- **Uvicorn 0.27.0** - ASGI 服务器（支持 HTTP/2）
- **Python 3.11+** - 编程语言

### ORM 与数据库
- **SQLModel 0.0.14** - SQL ORM（基于 Pydantic + SQLAlchemy）
- **Alembic 1.13.1** - 数据库迁移工具
- **asyncpg 0.29.0** - PostgreSQL 异步驱动

### 缓存
- **Redis 5.0.1** - 内存数据库
- **hiredis 2.3.2** - Redis 高性能 C 解析器

### 认证与安全
- **python-jose[cryptography] 3.3.0** - JWT 令牌
- **passlib[bcrypt] 1.7.4** - 密码哈希

### 配置管理
- **pydantic-settings 2.1.0** - 配置管理
- **python-dotenv 1.0.0** - 环境变量加载

### 工具库
- **loguru 0.7.2** - 日志系统
- **python-dateutil 2.8.2** - 日期处理
- **pytz 2023.3** - 时区处理
- **uuid-utils 0.9.0** - UUID 工具
- **pypinyin 0.51.0** - 中文转拼音

### 开发工具
- **pytest 7.4.4** - 测试框架
- **pytest-asyncio 0.23.3** - 异步测试支持
- **httpx 0.26.0** - 异步 HTTP 客户端
- **black 24.1.1** - 代码格式化
- **ruff 0.1.14** - 快速 Linter

---

## 🐳 基础设施

### 容器化
- **Docker** - 容器运行时
- **Docker Compose** - 多容器编排

### 数据库
- **PostgreSQL 17 Alpine** - 主数据库
  - 端口：6181
  - 支持 UUID v7

### 缓存
- **Redis 7 Alpine** - 缓存与会话存储
  - 端口：6183

### 对象存储
- **S3 兼容存储** - 使用 boto3 SDK
  - 生产环境：阿里云 OSS
  - 开发环境：可选 AWS S3、MinIO 等
  - 支持所有 S3 兼容存储服务

### 网络
- **jointo-network** - Docker Bridge 网络
- **CORS 配置** - 支持跨域请求

---

## 🛠️ 开发工具

### 前端开发
- **ESLint 9.39.2** - 代码检查
- **Prettier 3.7.4** - 代码格式化
- **Husky 9.1.7** - Git Hooks
- **lint-staged 16.2.7** - 暂存文件检查

### 后端开发
- **Black** - Python 代码格式化
- **Ruff** - Python Linter
- **pytest** - 单元测试

### 构建与部署
- **Vite** - 前端构建（开发端口：6160）
- **Uvicorn** - 后端服务（端口：6170）
- **Docker Multi-stage Build** - 生产环境构建

---

## 📊 端口分配

| 服务         | 端口  | 说明                |
|--------------|-------|---------------------|
| 前端开发服务 | 6160  | Vite Dev Server     |
| 后端 API     | 6170  | FastAPI Application |
| PostgreSQL   | 6181  | 数据库              |
| Redis        | 6183  | 缓存                |
| Adminer      | 6184  | 数据库管理工具      |

---

## 🔄 数据流架构

```
┌─────────────┐
│   Browser   │
│  (React)    │
└──────┬──────┘
       │ HTTP/REST
       ↓
┌─────────────┐      ┌──────────┐
│  FastAPI    │─────→│  Redis   │
│  (Uvicorn)  │      │  (Cache) │
└──────┬──────┘      └──────────┘
       │
       ↓
┌─────────────┐      ┌──────────────┐
│ PostgreSQL  │      │ S3 Storage   │
│  (Primary)  │      │ (OSS/S3/etc) │
└─────────────┘      └──────────────┘
```

---

## 📝 备注

- 所有服务通过 Docker Compose 统一管理
- 前端使用 Vite 进行开发和构建
- 后端采用异步架构（asyncpg + FastAPI）
- 数据库使用 PostgreSQL 17 最新特性
- 对象存储使用 boto3 SDK，支持所有 S3 兼容存储（阿里云 OSS、AWS S3 等）