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
|
||||
- Vue 3
|
||||
- JavaScript
|
||||
- Vue Router
|
||||
- Pinia
|
||||
- TanStack Vue Query
|
||||
- Element Plus
|
||||
- SCSS
|
||||
- Vue I18n
|
||||
- Vue Flow
|
||||
Novel-AI Frontend 是 SuperTale 创意故事平台的用户界面，提供从剧本创作、角色管理、资源编排到视频生成的完整工作流。本项目为现有前端应用的 Vue 3 + JavaScript 重构版本。
|
||||
|
||||
## 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
|
||||
pnpm --filter supertale-vue-rewrite dev
|
||||
pnpm --filter supertale-vue-rewrite build
|
||||
git clone <仓库地址>
|
||||
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
|
||||
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