docs/v1.0/requirements/frontend/02-project-structure.md

项目结构

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

---

目录

1. 目录结构
2. 模块职责说明
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 配置

// 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 配置

// 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 使用示例

// ✅ 推荐：使用别名
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";

---

相关文档

• 技术栈概览
• 开发规范
• 状态管理

---

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