# Jointo - 前端需求文档总览

> **技术栈**：React + TypeScript + Vite  
> **项目名称**：jointo  
> **项目域名**：https://www.jointo.ai  
> **文档版本**：v1.1  
> **最后更新**：2025-01-18

---

## 📚 文档导航

本目录包含Jointo项目的完整前端技术需求文档，按功能模块和技术层次组织。

### 核心架构文档

| 文档                                                 | 说明                              | 状态      |
| ---------------------------------------------------- | --------------------------------- | --------- |
| [01-tech-stack.md](./01-tech-stack.md)               | 技术栈选型、框架版本、依赖清单    | ✅        |
| [02-project-structure.md](./02-project-structure.md) | 项目结构、目录规范、模块职责      | ✅        |
| [03-build-environment.md](./03-build-environment.md) | 构建配置、环境变量、开发脚本      | ✅        |
| [04-state-management.md](./04-state-management.md)   | 状态管理、Zustand、TanStack Query | ✅        |
| [05-routing.md](./05-routing.md)                     | 路由设计、路由守卫、导航结构      | ✅        |
| [06-api-layer.md](./06-api-layer.md)                 | API 层设计、请求封装、Mock 服务   | ✅        |
| [07-styling.md](./07-styling.md)                     | 样式方案、Tailwind v4、主题配置   | ✅        |
| [08-i18n.md](./08-i18n.md)                           | 国际化、多语言支持、语言切换      | ✅        |
| [09-theme-system.md](./09-theme-system.md)           | 主题系统、深色/亮色模式、CSS 变量 | ✅        |
| [10-performance.md](./10-performance.md)             | 性能优化、代码分割、虚拟列表      | ✅        |
| [11-testing.md](./11-testing.md)                     | 测试策略、单元测试、E2E 测试      | ⚠️ 规划中 |
| [12-deployment.md](./12-deployment.md)               | 部署方案、构建配置、CI/CD         | ✅        |
| [13-dev-standards.md](./13-dev-standards.md)         | 开发规范、命名规范、代码风格      | ✅        |
| [14-toolchain.md](./14-toolchain.md)                 | 工具链配置、ESLint、Prettier      | ✅        |

---

## 🚀 快速开始

### 1. 了解技术栈

从 [技术栈选型](./01-tech-stack.md) 开始，了解项目使用的核心技术和依赖。

### 2. 熟悉项目结构

查看 [项目结构](./02-project-structure.md)，理解目录组织和模块职责。

### 3. 配置开发环境

参考 [构建与开发环境](./03-build-environment.md) 配置本地开发环境。

### 4. 理解状态管理

阅读 [状态管理](./04-state-management.md)，掌握 Zustand 和 TanStack Query 的使用。

### 5. 开发新功能

- 路由：参考 [路由设计](./05-routing.md)
- API 调用：参考 [API 层设计](./06-api-layer.md)
- 样式开发：参考 [样式方案](./07-styling.md)
- 遵循 [开发规范](./13-dev-standards.md)

---

## 📋 技术栈概览

| 类别          | 技术选型             | 版本             |
| ------------- | -------------------- | ---------------- |
| **框架**      | React                | ^19.2.0          |
| **语言**      | TypeScript           | ~5.9.3           |
| **构建工具**  | Vite                 | ^7.2.4           |
| **状态管理**  | Zustand              | ^5.0.5           |
| **数据请求**  | TanStack Query       | ^5.80.7          |
| **样式方案**  | Tailwind CSS         | ^4.1.18          |
| **UI 组件库** | shadcn/ui + Radix UI | latest           |
| **路由**      | React Router         | ^7.6.1           |
| **表单处理**  | React Hook Form      | ^7.57.0          |
| **表单验证**  | Zod                  | ^3.25.64         |
| **国际化**    | react-i18next        | ^15.5.2          |
| **拖拽**      | @dnd-kit             | ^6.3.1 / ^10.0.0 |

---

## 🏗️ 系统架构图

```
┌─────────────────────────────────────────────────────────────┐
│                     用户界面层 (UI Layer)                     │
│              React Components + shadcn/ui                    │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│                   状态管理层 (State Layer)                    │
│         Zustand (客户端状态) + TanStack Query (服务端状态)    │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│                   服务层 (Service Layer)                      │
│              API Client (Axios) + Mock Service               │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│                   后端 API (Backend API)                      │
│                    FastAPI + PostgreSQL                      │
└─────────────────────────────────────────────────────────────┘
```

---

## 📝 文档维护

- 每个文档应保持独立性，避免过度依赖其他文档
- 文档间通过相对链接关联
- 代码示例应保持最新，与实际实现同步
- 重大变更需更新相关文档的版本号和更新日期

### 变更记录

**v1.1 (2025-01-18)**

- 文档结构重构：将单一文档拆分为 14 个模块化文档
- 更新至实际实现版本
- 更新所有依赖版本至实际使用版本
- 更新 Tailwind CSS v4 配置方式
- 更新 ESLint Flat Config 配置
- 修正路由结构（移除独立编辑器页面）
- 补充特殊功能依赖说明
- 标注测试工具为未来规划

**v1.0 (2025-01-08)**

- 初始版本，从 PRD 文档中拆分

---

## 🔗 相关文档

- [后端技术文档](../backend/README.md)
- [数据库设计](../backend/04-database-design.md)
- [API 设计规范](../backend/05-api-design.md)
- [Figma 设计稿分析](../../figma-analysis-report.md)
- [文档迁移指南](./MIGRATION.md) - 从旧文档迁移说明

---

## 📦 项目启动

```bash
# 安装依赖
cd client
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览生产构建
npm run preview

# 代码检查
npm run lint

# 代码格式化
npm run format
```

---

**维护者**：前端开发团队  
**联系方式**：dev@jointo.ai