docs: rewrite README with comprehensive project overview
- 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
This commit is contained in:
@@ -1,41 +1,170 @@
|
|||||||
# SuperTale Vue Rewrite
|
# Novel-AI Frontend
|
||||||
|
|
||||||
Vue 3 + JavaScript rewrite workspace for the existing SuperTale creator frontend.
|
> AI 驱动的创意故事与视频制作平台前端 — SuperTale 项目 Vue 3 重构版
|
||||||
|
|
||||||
## Stack
|
## 项目概述
|
||||||
|
|
||||||
- Vite
|
Novel-AI Frontend 是 SuperTale 创意故事平台的用户界面，提供从剧本创作、角色管理、资源编排到视频生成的完整工作流。本项目为现有前端应用的 Vue 3 + JavaScript 重构版本。
|
||||||
- Vue 3
|
|
||||||
- JavaScript
|
|
||||||
- Vue Router
|
|
||||||
- Pinia
|
|
||||||
- TanStack Vue Query
|
|
||||||
- Element Plus
|
|
||||||
- SCSS
|
|
||||||
- Vue I18n
|
|
||||||
- Vue Flow
|
|
||||||
|
|
||||||
## Explicitly Not Migrated
|
## 功能模块
|
||||||
|
|
||||||
- `piko-mini-game`
|
| 模块 | 说明 |
|
||||||
- `rewards`
|
| --- | --- |
|
||||||
- `companion`
|
| **项目管理** | 项目的创建、概览与看板式管理 |
|
||||||
|
| **内容接入** | 小说/剧本等原始内容的导入与解析 |
|
||||||
|
| **角色管理** | 角色设定、形象管理与一致性维护 |
|
||||||
|
| **资源管理** | 图片、音频、视频等素材的统一管理 |
|
||||||
|
| **风格管理** | 视觉风格、渲染风格的预设与切换 |
|
||||||
|
| **分集编辑** | 多阶段分集创作流程（剧本 → 分镜 → 渲染） |
|
||||||
|
| **自由创作区** | 基于 Vue Flow 的节点式可视化画布编辑 |
|
||||||
|
| **AI 助手** | 与 AI 助手的交互面板 |
|
||||||
|
| **任务管理** | 后台渲染任务的状态追踪与管理 |
|
||||||
|
| **视频播放** | 作品的在线预览与播放 |
|
||||||
|
|
||||||
## Commands
|
## 技术栈
|
||||||
|
|
||||||
|
| 技术 | 用途 |
|
||||||
|
| --- | --- |
|
||||||
|
| [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
|
```bash
|
||||||
pnpm --filter supertale-vue-rewrite dev
|
git clone <仓库地址>
|
||||||
pnpm --filter supertale-vue-rewrite build
|
cd frontend/vue-rewrite
|
||||||
|
pnpm install
|
||||||
```
|
```
|
||||||
|
|
||||||
The dev server defaults to `http://localhost:5174` and proxies `/api/v1` and `/static` to `VITE_API_URL` or `http://127.0.0.1:8780`.
|
### 开发
|
||||||
|
|
||||||
## Mock Mode
|
|
||||||
|
|
||||||
Mock API is enabled by default unless `VITE_USE_MOCK=false` is set.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
VITE_USE_MOCK=true
|
pnpm dev
|
||||||
```
|
```
|
||||||
|
|
||||||
In mock mode, auth is auto-restored as `mock_user`, project and task APIs use local in-memory data, and the app can be navigated without a backend.
|
开发服务器默认运行在 `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)
|
||||||
|
|||||||
Reference in New Issue
Block a user