# 技术栈概览

> **文档版本**：v1.1  
> **最后更新**：2025-01-18

---

## 目录

1. [核心技术栈](#1-核心技术栈)
2. [开发工具](#2-开发工具)
3. [特殊功能依赖](#3-特殊功能依赖)
4. [技术选型理由](#4-技术选型理由)
5. [依赖版本清单](#5-依赖版本清单)

---

## 1. 核心技术栈

### 1.1 基础框架

| 类别         | 技术选型   | 版本    | 说明          |
| ------------ | ---------- | ------- | ------------- |
| **框架**     | React      | ^19.2.0 | UI 框架       |
| **语言**     | TypeScript | ~5.9.3  | 类型安全      |
| **构建工具** | Vite       | ^7.2.4  | 快速构建、HMR |

### 1.2 状态管理

| 类别           | 技术选型       | 版本    | 说明           |
| -------------- | -------------- | ------- | -------------- |
| **客户端状态** | Zustand        | ^5.0.5  | 轻量级状态管理 |
| **服务端状态** | TanStack Query | ^5.80.7 | 服务端状态管理 |

### 1.3 样式方案

| 类别          | 技术选型             | 版本     | 说明            |
| ------------- | -------------------- | -------- | --------------- |
| **CSS 框架**  | Tailwind CSS         | ^4.1.18  | 原子化 CSS (v4) |
| **UI 组件库** | shadcn/ui + Radix UI | latest   | 可定制组件      |
| **图标库**    | lucide-react         | ^0.562.0 | 图标集          |

### 1.4 网络与数据

| 类别            | 技术选型        | 版本     | 说明        |
| --------------- | --------------- | -------- | ----------- |
| **HTTP 客户端** | Axios           | ^1.10.0  | API 请求    |
| **表单处理**    | React Hook Form | ^7.57.0  | 表单验证    |
| **表单验证**    | Zod             | ^3.25.64 | Schema 验证 |
| **日期处理**    | date-fns        | ^4.1.0   | 日期工具    |

### 1.5 路由与国际化

| 类别       | 技术选型      | 版本    | 说明       |
| ---------- | ------------- | ------- | ---------- |
| **路由**   | React Router  | ^7.6.1  | 客户端路由 |
| **国际化** | react-i18next | ^15.5.2 | 多语言支持 |

### 1.6 交互功能

| 类别     | 技术选型 | 版本             | 说明     |
| -------- | -------- | ---------------- | -------- |
| **拖拽** | @dnd-kit | ^6.3.1 / ^10.0.0 | 拖拽排序 |

---

## 2. 开发工具

| 工具            | 用途                       |
| --------------- | -------------------------- |
| **ESLint**      | 代码质量检查 (Flat Config) |
| **Prettier**    | 代码格式化                 |
| **Husky**       | Git Hooks                  |
| **lint-staged** | 暂存文件检查               |

---

## 3. 特殊功能依赖

### 3.1 文档解析

| 依赖               | 版本     | 用途             |
| ------------------ | -------- | ---------------- |
| **fountain-js**    | ^1.2.4   | 剧本格式解析     |
| **mammoth**        | ^1.11.0  | Word 文档解析    |
| **pdfjs-dist**     | ^5.4.530 | PDF 文件解析     |
| **turndown**       | ^7.2.2   | HTML 转 Markdown |
| **react-markdown** | ^10.1.0  | Markdown 渲染    |

---

## 4. 技术选型理由

### 4.1 React 19

**选择理由**：

- 并发渲染支持，提升大型列表和复杂交互的性能
- Suspense 支持异步数据加载
- 自动批处理减少渲染次数
- 成熟的生态系统

**适用场景**：

- 复杂的分镜列表渲染
- 时间轴的实时交互
- 大量组件的状态同步

### 4.2 Vite 7

**选择理由**：

- 基于 ESM 的极速开发服务器
- 快速的 HMR（热模块替换）
- 优化的生产构建
- 开箱即用的 TypeScript 支持
- 原生支持 Tailwind v4

**性能优势**：

- 开发服务器启动时间 < 1s
- HMR 更新时间 < 100ms
- 生产构建优化（Tree-shaking、代码分割）

### 4.3 Zustand 5

**选择理由**：

- 极简 API，学习成本低
- 无 Provider 包装，使用灵活
- TypeScript 原生支持
- 支持中间件扩展（devtools、persist）

**对比其他方案**：

- vs Redux：更轻量，无样板代码
- vs Context API：性能更好，避免不必要的重渲染
- vs Jotai/Recoil：更简单直观

### 4.4 Tailwind CSS v4 + shadcn/ui

**选择理由**：

- **Tailwind v4 新特性**：使用 `@theme` 指令配置，无需 JS 配置文件
- 原子化 CSS 减少样式冲突
- shadcn/ui 组件基于 Radix UI，可完全自定义
- 统一的设计系统（Pro Studio 主题）
- 优秀的开发体验

**优势**：

- 样式与组件解耦
- 响应式设计简单
- 深色模式支持完善
- 构建产物体积小

### 4.5 @dnd-kit

**选择理由**：

- 现代化的拖拽库
- 支持键盘无障碍访问
- 高性能，支持虚拟列表
- 用于分镜排序、时间轴编辑

**适用场景**：

- 分镜列表拖拽排序
- 时间轴轨道项拖拽
- 资源库拖拽上传

---

## 5. 依赖版本清单

### 5.1 生产依赖

```json
{
  "dependencies": {
    "react": "^19.2.0",
    "react-dom": "^19.2.0",
    "react-router-dom": "^7.6.1",
    "@tanstack/react-query": "^5.80.7",
    "@tanstack/react-query-devtools": "^5.80.7",
    "zustand": "^5.0.5",
    "axios": "^1.10.0",
    "zod": "^3.25.64",
    "react-hook-form": "^7.57.0",
    "@hookform/resolvers": "^5.1.0",
    "date-fns": "^4.1.0",
    "lucide-react": "^0.562.0",
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.4.0",
    "class-variance-authority": "^0.7.1",
    "@radix-ui/react-*": "^1.0.0+",
    "@dnd-kit/core": "^6.3.1",
    "@dnd-kit/sortable": "^10.0.0",
    "@dnd-kit/utilities": "^3.2.2",
    "i18next": "^25.2.1",
    "react-i18next": "^15.5.2",
    "i18next-browser-languagedetector": "^8.0.5",
    "i18next-http-backend": "^3.0.2",
    "fountain-js": "^1.2.4",
    "mammoth": "^1.11.0",
    "pdfjs-dist": "^5.4.530",
    "turndown": "^7.2.2",
    "react-markdown": "^10.1.0",
    "remark-breaks": "^4.0.0"
  }
}
```

### 5.2 开发依赖

```json
{
  "devDependencies": {
    "typescript": "~5.9.3",
    "vite": "^7.2.4",
    "@vitejs/plugin-react": "^5.1.1",
    "@tailwindcss/vite": "^4.1.18",
    "tailwindcss": "^4.1.18",
    "tailwindcss-animate": "^1.0.7",
    "@tailwindcss/typography": "^0.5.19",
    "postcss": "^8.5.6",
    "autoprefixer": "^10.4.23",
    "eslint": "^9.39.2",
    "@eslint/js": "^9.39.2",
    "typescript-eslint": "^8.52.0",
    "eslint-plugin-react-hooks": "^7.0.1",
    "eslint-plugin-react-refresh": "^0.4.26",
    "eslint-config-prettier": "^10.1.8",
    "eslint-plugin-prettier": "^5.5.4",
    "prettier": "^3.7.4",
    "globals": "^16.5.0",
    "husky": "^9.1.7",
    "lint-staged": "^16.2.7",
    "@types/node": "^24.10.1",
    "@types/react": "^19.2.5",
    "@types/react-dom": "^19.2.3",
    "@types/turndown": "^5.0.6"
  }
}
```

---

## 相关文档

- [项目结构](./02-project-structure.md)
- [构建与开发环境](./03-build-environment.md)
- [状态管理](./04-state-management.md)

---

**最后更新**：2025-01-18 | **版本**：v1.1