Zhanglj
c86c3c051e
- Add project overview and feature module descriptions - Document tech stack with usage descriptions - Add quick start guide (installation, dev, build, preview) - Document environment variables and proxy configuration - Add project structure tree with explanations - Add commit convention guide
171 lines
4.9 KiB
Markdown
171 lines
4.9 KiB
Markdown
# 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)
|