# Novel-AI Frontend

> AI 驱动的创意故事与视频制作平台前端 — SuperTale 项目 Vue 3 重构版

## 项目概述

Novel-AI Frontend 是 SuperTale 创意故事平台的用户界面，提供从剧本创作、角色管理、资源编排到视频生成的完整工作流。本项目为现有前端应用的 Vue 3 + JavaScript 重构版本。

## 功能模块

| 模块 | 说明 |
| --- | --- |
| **项目管理** | 项目的创建、概览与看板式管理 |
| **内容接入** | 小说/剧本等原始内容的导入与解析 |
| **角色管理** | 角色设定、形象管理与一致性维护 |
| **资源管理** | 图片、音频、视频等素材的统一管理 |
| **风格管理** | 视觉风格、渲染风格的预设与切换 |
| **分集编辑** | 多阶段分集创作流程（剧本 → 分镜 → 渲染） |
| **自由创作区** | 基于 Vue Flow 的节点式可视化画布编辑 |
| **AI 助手** | 与 AI 助手的交互面板 |
| **任务管理** | 后台渲染任务的状态追踪与管理 |
| **视频播放** | 作品的在线预览与播放 |

## 技术栈

| 技术 | 用途 |
| --- | --- |
| [Vue 3](https://vuejs.org/) | 前端框架（Composition API） |
| [Vite 6](https://vitejs.dev/) | 构建工具与开发服务器 |
| [Vue Router 4](https://router.vuejs.org/) | 路由管理（含导航守卫鉴权） |
| [Pinia](https://pinia.vuejs.org/) | 状态管理 |
| [TanStack Vue Query](https://tanstack.com/query/latest) | 服务端状态管理与数据请求 |
| [Element Plus](https://element-plus.org/) | UI 组件库 |
| [Vue Flow](https://vueflow.dev/) | 节点式可视化画布引擎 |
| [Ky](https://github.com/sindresorhus/ky) | 轻量 HTTP 客户端 |
| [Vue I18n](https://vue-i18n.intlify.dev/) | 国际化（中/英文） |
| [SCSS](https://sass-lang.com/) | 样式预处理 |
| [Lucide](https://lucide.dev/) | 图标库 |

## 快速开始

### 环境要求

- Node.js >= 18
- pnpm（推荐）或 npm / yarn

### 安装

```bash
git clone <仓库地址>
cd frontend/vue-rewrite
pnpm install
```

### 开发

```bash
pnpm dev
```

开发服务器默认运行在 `http://localhost:5174`。

### 构建

```bash
pnpm build
```

### 预览构建产物

```bash
pnpm preview
```

## 环境变量

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `VITE_USE_MOCK` | `true` | 是否启用 Mock API（设为 `false` 连接真实后端） |
| `VITE_API_URL` | `http://127.0.0.1:8780` | 后端 API 地址 |

## Mock 模式

项目默认启用 Mock 模式（`VITE_USE_MOCK=true`），可在无需后端服务的情况下独立开发与导航：

- 认证自动恢复为 `mock_user` 身份
- 项目和任务 API 使用本地内存数据
- 可通览所有页面而无需后端依赖

关闭 Mock 模式：

```bash
VITE_USE_MOCK=false pnpm dev
```

## 代理配置

开发服务器自动代理以下路径到后端：

| 路径 | 目标 |
| --- | --- |
| `/api/v1/*` | `VITE_API_URL`（默认 `http://127.0.0.1:8780`） |
| `/static/*` | `VITE_API_URL` |

## 项目结构

```text
src/
├── api/              # API 请求模块（基于 ky）
│   ├── http.js       #   HTTP 客户端实例
│   ├── auth.js       #   认证相关接口
│   ├── projects.js   #   项目相关接口
│   └── ...

├── queries/          # TanStack Vue Query 封装
│   ├── auth.js       #   认证查询/变更 hooks
│   ├── projects.js   #   项目查询/变更 hooks
│   └── ...

├── stores/           # Pinia 状态仓库
│   ├── auth.js       #   认证状态（含 session 恢复）
│   └── app.js        #   应用级状态

├── router/           # 路由配置
│   └── index.js      #   路由表 + 导航守卫

├── views/            # 页面组件
│   ├── LoginView.vue
│   ├── WatchView.vue
│   ├── projects/     #   项目管理页面
│   ├── episodes/     #   分集编辑页面
│   ├── freezone/     #   自由创作区（Vue Flow 画布）
│   └── ...

├── layouts/          # 布局组件
│   ├── AppLayout.vue       #   主布局（侧边栏 + 顶栏）
│   └── ProjectLayout.vue   #   项目级布局

├── i18n/             # 国际化
│   ├── zh-CN.js      #   中文语言包
│   └── en-US.js      #   英文语言包

├── config/           # 运行时配置
│   └── runtime.js    #   Mock 开关等运行时标识

├── styles/           # 全局样式
│   └── index.scss

├── App.vue           # 根组件
└── main.js           # 入口文件
```

## 提交规范

本项目使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

```text
feat:      新功能
fix:       Bug 修复
refactor:  代码重构
perf:      性能优化
style:     样式/格式变更
chore:     构建/工具链变更
docs:      文档更新
test:      测试变更
```

## 许可

[MIT](LICENSE)