# 项目结构

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

---

## 目录

1. [目录结构](#1-目录结构)
2. [模块职责说明](#2-模块职责说明)
3. [导入别名配置](#3-导入别名配置)

---

## 1. 目录结构

```
src/
├── app/                          # 应用入口层
│   ├── App.tsx                   # 根组件
│   ├── Router.tsx                # 路由配置
│   └── providers/                # Provider 组件
│       ├── index.tsx
│       ├── QueryProvider.tsx
│       └── ThemeProvider.tsx
│
├── components/                   # 组件层
│   ├── ui/                       # 基础 UI 组件 (shadcn/ui)
│   │   ├── button.tsx
│   │   ├── input.tsx
│   │   ├── dialog.tsx
│   │   └── ...
│   │
│   ├── layout/                   # 布局组件
│   │   ├── AppLayout.tsx         # 应用主布局
│   │   ├── TopBar.tsx            # 顶部导航栏
│   │   ├── LeftSidebar.tsx       # 左侧边栏（项目/素材库）
│   │   ├── CenterArea.tsx        # 中间区域（分镜列表+预览+AI输入）
│   │   └── RightSidebar.tsx      # 右侧边栏（图片提示词/角度变换/镜头调整）
│   │
│   ├── features/                 # 功能组件
│   │   ├── storyboard/           # 分镜相关
│   │   │   ├── StoryboardPanel.tsx
│   │   │   ├── StoryboardItem.tsx
│   │   │   ├── StoryboardEditor.tsx
│   │   │   └── index.ts
│   │   │
│   │   ├── timeline/             # 分镜看板相关
│   │   │   ├── Storyboard BoardPanel.tsx
│   │   │   ├── Storyboard BoardTrack.tsx
│   │   │   ├── Storyboard BoardItem.tsx
│   │   │   ├── Storyboard BoardControls.tsx
│   │   │   └── index.ts
│   │   │
│   │   ├── preview/              # 预览相关
│   │   │   ├── PreviewPanel.tsx
│   │   │   ├── VideoPlayer.tsx
│   │   │   ├── PlaybackControls.tsx
│   │   │   └── index.ts
│   │   │
│   │   ├── ai/                   # AI 功能
│   │   │   ├── AIPromptPanel.tsx
│   │   │   ├── AIGenerateForm.tsx
│   │   │   ├── AIPreviewModal.tsx
│   │   │   └── index.ts
│   │   │
│   │   ├── resources/            # 资源管理
│   │   │   ├── ResourcePanel.tsx
│   │   │   ├── ResourceGrid.tsx
│   │   │   ├── ResourceUploader.tsx
│   │   │   └── index.ts
│   │   │
│   │   ├── project/              # 项目管理
│   │   │   ├── ProjectList.tsx
│   │   │   ├── ProjectCard.tsx
│   │   │   ├── CreateProjectModal.tsx
│   │   │   └── index.ts
│   │   │
│   │   └── settings/             # 设置
│   │       ├── SettingsPanel.tsx
│   │       ├── ExportSettings.tsx
│   │       └── index.ts
│   │
│   └── common/                   # 通用组件
│       ├── LoadingSpinner.tsx
│       ├── ErrorBoundary.tsx
│       ├── EmptyState.tsx
│       ├── Tooltip.tsx
│       └── index.ts
│
├── hooks/                        # 自定义 Hooks
│   ├── api/                      # API 相关 Hooks
│   │   ├── useProjects.ts
│   │   ├── useStoryboards.ts
│   │   ├── useResources.ts
│   │   └── useAIGenerate.ts
│   │
│   ├── useDebounce.ts
│   ├── useLocalStorage.ts
│   ├── useMediaQuery.ts
│   ├── useKeyboardShortcuts.ts
│   └── index.ts
│
├── stores/                       # Zustand 状态管理
│   ├── appStore.ts               # 全局应用状态
│   ├── projectStore.ts           # 项目状态
│   ├── editorStore.ts            # 编辑器状态
│   ├── uiStore.ts                # UI 状态
│   └── index.ts
│
├── services/                     # 服务层
│   ├── api/                      # API 服务
│   │   ├── client.ts             # Axios 客户端配置
│   │   ├── projects.ts           # 项目 API
│   │   ├── storyboards.ts        # 分镜 API
│   │   ├── resources.ts          # 资源 API
│   │   ├── ai.ts                 # AI 生成 API
│   │   └── index.ts
│   │
│   └── mock/                     # Mock 数据服务
│       ├── mockClient.ts
│       ├── mockData.ts
│       └── handlers.ts
│
├── types/                        # TypeScript 类型定义
│   ├── project.ts
│   ├── storyboard.ts
│   ├── resource.ts
│   ├── timeline.ts
│   ├── ai.ts
│   ├── api.ts
│   └── index.ts
│
├── utils/                        # 工具函数
│   ├── format.ts                 # 格式化工具
│   ├── validation.ts             # 验证工具
│   ├── storage.ts                # 存储工具
│   ├── time.ts                   # 时间处理
│   └── index.ts
│
├── constants/                    # 常量定义
│   ├── config.ts                 # 配置常量
│   ├── routes.ts                 # 路由常量
│   ├── keys.ts                   # 键名常量
│   └── index.ts
│
├── styles/                       # 全局样式
│   ├── globals.css               # 全局 CSS
│   └── animations.css            # 动画定义
│
├── assets/                       # 静态资源
│   ├── images/
│   └── fonts/
│
├── lib/                          # 第三方库配置
│   └── utils.ts                  # shadcn/ui 工具
│
├── main.tsx                      # 应用入口
└── vite-env.d.ts                 # Vite 类型声明
```

---

## 2. 模块职责说明

| 目录                   | 职责                     | 原则               |
| ---------------------- | ------------------------ | ------------------ |
| `app/`                 | 应用配置、Provider、路由 | 只放应用级配置     |
| `components/ui/`       | 基础 UI 组件             | 无业务逻辑，纯展示 |
| `components/layout/`   | 布局组件                 | 定义页面结构       |
| `components/features/` | 功能组件                 | 按功能模块组织     |
| `components/common/`   | 通用组件                 | 跨模块复用         |
| `hooks/`               | 自定义 Hooks             | 逻辑复用           |
| `stores/`              | 全局状态                 | Zustand stores     |
| `services/`            | 外部服务交互             | API 调用、Mock     |
| `types/`               | 类型定义                 | 所有 TS 类型       |
| `utils/`               | 工具函数                 | 纯函数，无副作用   |
| `constants/`           | 常量                     | 配置、枚举、键名   |

### 2.1 组件层级说明

#### UI 组件 (`components/ui/`)

- **职责**：提供基础的、可复用的 UI 组件
- **特点**：无业务逻辑，完全受控
- **示例**：Button、Input、Dialog、Select
- **来源**：主要来自 shadcn/ui

#### 布局组件 (`components/layout/`)

- **职责**：定义页面的整体结构和布局
- **特点**：组合 UI 组件，定义页面骨架
- **示例**：AppLayout、TopBar、Sidebar

#### 功能组件 (`components/features/`)

- **职责**：实现具体的业务功能
- **特点**：包含业务逻辑，调用 API 和状态管理
- **组织**：按功能模块分组（storyboard、timeline、preview 等）

#### 通用组件 (`components/common/`)

- **职责**：跨功能模块复用的组件
- **特点**：通用性强，可配置性高
- **示例**：LoadingSpinner、ErrorBoundary、EmptyState

---

## 3. 导入别名配置

### 3.1 Vite 配置

```typescript
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import path from "path";

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
      "@components": path.resolve(__dirname, "./src/components"),
      "@hooks": path.resolve(__dirname, "./src/hooks"),
      "@stores": path.resolve(__dirname, "./src/stores"),
      "@services": path.resolve(__dirname, "./src/services"),
      "@types": path.resolve(__dirname, "./src/types"),
      "@utils": path.resolve(__dirname, "./src/utils"),
      "@constants": path.resolve(__dirname, "./src/constants"),
      "@assets": path.resolve(__dirname, "./src/assets"),
    },
  },
});
```

### 3.2 TypeScript 配置

```json
// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@hooks/*": ["src/hooks/*"],
      "@stores/*": ["src/stores/*"],
      "@services/*": ["src/services/*"],
      "@types/*": ["src/types/*"],
      "@utils/*": ["src/utils/*"],
      "@constants/*": ["src/constants/*"],
      "@assets/*": ["src/assets/*"]
    }
  }
}
```

### 3.3 使用示例

```typescript
// ✅ 推荐：使用别名
import { Button } from "@components/ui/button";
import { useStoryboards } from "@hooks/api/useStoryboards";
import { useEditorStore } from "@stores/editorStore";
import { cn } from "@/lib/utils";
import type { Storyboard } from "@types";

// ❌ 避免：使用相对路径（深层嵌套时）
import { Button } from "../../../components/ui/button";
import { useStoryboards } from "../../../hooks/api/useStoryboards";
```

---

## 相关文档

- [技术栈概览](./01-tech-stack.md)
- [开发规范](./13-dev-standards.md)
- [状态管理](./04-state-management.md)

---

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