# ai小说工坊

**Repository Path**: baymax2018/ai-novel-workshop

## Basic Information

- **Project Name**: ai小说工坊
- **Description**: 一站式多故事管理平台，集成 AI 辅助创作、多人协作、版本管理与社区发布等功能，为小说创作者提供从构思到分享的完整创作闭环。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-21
- **Last Updated**: 2026-08-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 小说创作工坊

一站式多故事管理平台，集成 AI 辅助创作、多人协作、版本管理与社区发布等功能，为小说创作者提供从构思到分享的完整创作闭环。

---

## 技术栈

### 前端
| 技术 | 用途 |
| :--- | :--- |
| **Vue 3** (Composition API + `<script setup>`) | 前端框架 |
| **Vite** | 构建工具 |
| **TypeScript** | 类型安全 |
| **Pinia** | 状态管理 |
| **Vue Router** | 路由管理 |
| **Axios** | HTTP 请求 |
| **TailwindCSS** | 样式方案 |
| **marked + DOMPurify** | Markdown 渲染 + XSS 防护 |
| **ECharts** | 监控图表 |
| **lucide-vue-next** | 图标库 |
| **sortablejs** | 拖拽排序 |
| **@sentry/vue** | 前端错误监控 |

### 后端
| 技术 | 用途 |
| :--- | :--- |
| **Node.js** (≥ 18 LTS) | 运行环境 |
| **Express** | Web 框架 |
| **MySQL 8.0+** | 关系型数据库 |
| **mysql2** | 数据库驱动 |
| **JWT (jsonwebtoken)** | 无状态用户认证 |
| **bcrypt** | 密码加密 |
| **Winston** | 日志记录 |
| **openai** (阿里云百炼 DashScope) | AI 服务适配 |
| **Swagger** | API 文档自动生成 |

---

## 功能概览

### 核心创作
- **多故事管理** — 创建、复制、重命名、删除故事，卡片式列表管理
- **侧边工作台** — 大纲编辑、角色管理（标签分类+拖拽排序）、章节列表（状态筛选+拖拽排序）、世界观结构化字段
- **AI 辅助创作** — 多模型选择（qwen-plus/max/turbo）、流式输出+打字机效果、高级参数调节（温度/Top-P/频率惩罚）、上下文策略（最近N章/定期摘要/无上下文）、批量章节生成、角色智能提示
- **章节编辑器** — Markdown 编辑/预览、30 秒自动保存、版本历史管理、版本对比（行级 Diff 高亮）、一键回滚

### 协作与社区
- **多人协作** — 邀请成员、权限管理（Owner/Collaborator/Viewer）、合并请求（MR）工作流、类 Git 冲突检测与解决
- **社区发布** — 提交发布申请、管理员审核、社区广场浏览（分类/热度/最新排序）、点赞/评论/举报
- **通知系统** — 站内信通知（评论/点赞/审核/MR）、未读红点、一键标记已读

### 导出与扩展
- **导出功能** — TXT/MD 格式，支持完整故事或仅正文
- **搜索筛选** — 故事标题搜索、章节关键词搜索+状态筛选

### 运维管理
- **管理后台** — 发布审核、举报处理、敏感词管理、分类管理、用户管理
- **监控面板** — AI 调用统计、活跃用户数、系统健康状态
- **日志系统** — Winston 分级日志、数据库慢查询日志、Sentry 前端错误监控

### 用户体验
- **暗色模式** — 浅色/深色一键切换，持久化用户偏好
- **响应式设计** — 桌面/平板/移动端三档适配，汉堡菜单导航，触摸友好按钮

---

## 快速开始

### 方式一：Docker 一键部署（推荐）

```bash
# 1. 配置环境变量
cp .env.example .env
# 编辑 .env，填入 DASHSCOPE_API_KEY 和 JWT_SECRET

# 2. 一键启动（MySQL + 后端 + 前端）
docker compose --env-file .env up -d

# 3. 访问
#    前端界面：http://localhost:8080
#    API 文档：http://localhost:8080/api-docs
#    健康检查：http://localhost:8080/health

# 4. 停止
docker compose down
```

> Docker 镜像已发布到 Docker Hub：`byneko/ai-novel-workshop-backend`、`byneko/ai-novel-workshop-frontend`

### 方式二：手动部署

#### 环境要求

| 工具 | 版本要求 |
| :--- | :--- |
| Node.js | ≥ 18 LTS |
| npm / pnpm | npm ≥ 9 / pnpm ≥ 8 |
| MySQL | 8.0+ |

#### 1. 后端

```bash
cd backend

# 安装依赖
npm install

# 配置环境变量（复制模板后修改）
cp .env.example .env
# 编辑 .env 填入数据库连接信息和 AI API Key

# 初始化数据库
mysql -u root -p < src/utils/init.sql

# 启动开发服务器（端口 3000）
npm run dev
```

#### 2. 前端

```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务器（端口 5173）
npm run dev
```

#### 3. 访问

打开浏览器访问 `http://localhost:5173`，注册账号后即可开始创作。

---

## 项目结构

```
ai-novel-workshop/
├── README.md
├── .env.example
├── .github/workflows/ci.yml       # GitHub Actions CI/CD
│
├── backend/
│   ├── Dockerfile                 # 后端 Docker 镜像
│   ├── .dockerignore
│   ├── docker-entrypoint.sh       # Docker 启动脚本（等待 MySQL + 自动初始化）
│   └── src/                       # 后端（Node.js + Express）
│   ├── src/
│   │   ├── app.js                 # Express 应用入口
│   │   ├── server.js              # 服务器启动
│   │   ├── config/                # 配置（数据库、JWT、AI、Swagger）
│   │   ├── middleware/            # 中间件（auth、adminAuth、errorHandler、rateLimiter）
│   │   ├── routes/                # 路由（16 个模块）
│   │   ├── controllers/           # 控制器（18 个）
│   │   ├── services/              # 服务层（14 个）
│   │   ├── models/                # 数据模型（20 个）
│   │   └── utils/                 # 工具函数
│   ├── ecosystem.config.js        # PM2 配置
│   └── package.json
│
├── frontend/
│   ├── Dockerfile                 # 前端 Docker 镜像（多阶段构建）
│   ├── .dockerignore
│   ├── nginx.conf                 # Nginx 配置（API 代理 + SPA fallback）
│   └── src/                       # 前端（Vue 3 + Vite）
│   ├── src/
│   │   ├── api/                   # API 请求层（13 个模块）
│   │   ├── assets/                # 样式、图标
│   │   ├── components/            # 组件（通用 + 业务，30+ 个）
│   │   ├── composables/           # 组合式函数（6 个）
│   │   ├── router/                # 路由配置
│   │   ├── stores/                # Pinia 状态管理（6 个）
│   │   ├── views/                 # 页面视图（16 个）
│   │   └── utils/                 # 工具函数
│   ├── vite.config.ts
│   └── package.json
│
├── docker-compose.yml             # Docker Compose 编排（MySQL + 后端 + 前端）
├── .env.example                   # 环境变量配置模板
├── tests/                         # 测试
│   ├── backend/                   # 后端测试（Jest + Supertest）
│   ├── e2e/                       # E2E 测试（Cypress）
│   └── mobile-compatibility-checklist.md
│
├── 需求文档.md                     # 需求规格说明书
├── 概要设计文档.md                 # 概要设计说明书
├── 详细设计文档.md                 # 详细设计说明书
└── (更多文档见项目根目录)
```

---

## 数据库

18 张业务表，涵盖用户、故事、章节、角色、版本、协作、社区、通知等模块。核心表关系：

```
users (1) ──→ (N) stories
stories (1) ──→ (N) chapters ──→ (N) chapter_versions
stories (1) ──→ (N) roles
stories (1) ──→ (N) collaborations
stories (1) ──→ (N) merge_requests
stories (1) ──→ (1) published_stories
```

---

## 测试

| 类型 | 框架 | 覆盖内容 |
| :--- | :--- | :--- |
| 后端单元测试 | Jest | 服务层、中间件、工具函数 |
| 后端集成测试 | Supertest | API 端点（auth、health、stories） |
| 前端单元测试 | Vitest | Composables、Stores |
| E2E 测试 | Cypress | 用户注册-登录-故事创作-编辑-保存流程 |
| 移动端兼容性 | 清单 | 20 项测试用例 |

---

## API 文档

启动后端后访问 Swagger 文档：

```
http://localhost:3000/api-docs
```

核心接口分类：

| 分类 | 前缀 | 认证 |
| :--- | :--- | :--- |
| 用户认证 | `/auth/*` | 部分需要 |
| 故事管理 | `/api/stories/*` | 需要 |
| 章节管理 | `/api/stories/:id/chapters/*` | 需要 |
| 角色管理 | `/api/stories/:id/roles/*` | 需要 |
| AI 生成 | `/api/stream/*` | 需要 |
| 版本管理 | `/api/chapter-versions/*` | 需要 |
| 协作 | `/api/collaborations/*` | 需要 |
| 社区 | `/api/community/*` | 部分需要 |
| 管理后台 | `/admin/*` | 需要（admin 角色） |

---

## 文档索引

| 文档 | 说明 |
| :--- | :--- |
| `需求文档.md` | 需求规格说明书（SRS） |
| `概要设计文档.md` | 系统架构与模块划分 |
| `详细设计文档.md` | 前后端/数据库/API 详细设计 |
| `开发流程文档.md` | 环境配置、编码规范、测试部署流程 |
| `用户手册.md` | 面向最终用户的操作指南 |
| `系统管理员手册.md` | 面向运维人员的安装维护指南 |
| `部署文档.md` | 环境依赖、部署拓扑、回滚方案 |
| `项目完成情况报告.md` | 各模块完成度与测试数据 |

---

## License

[MIT](LICENSE)