# Scenario

**Repository Path**: kyrin_soft/Scenario

## Basic Information

- **Project Name**: Scenario
- **Description**: 基于AI的小说生成器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-25
- **Last Updated**: 2026-01-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小说构建应用 (Scenario Builder)

一个基于 React + Vite + Ant Design 和 Node.js + Express + SQLite 的小说构建应用，支持小说、世界、人物、事件、时间线等模块的管理，并通过元数据管理系统实现动态字段配置。

## 📋 目录

- [技术栈](#技术栈)
- [功能特性](#功能特性)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [项目结构](#项目结构)
- [使用说明](#使用说明)
- [API 接口](#api-接口)
- [数据库](#数据库)
- [开发指南](#开发指南)
- [脚本说明](#脚本说明)
- [许可证](#许可证)

## 🛠 技术栈

### 前端
- **React 19** - UI 框架
- **Vite** - 构建工具
- **TypeScript** - 类型安全
- **Ant Design 6** - UI 组件库
- **React Router 7** - 路由管理
- **Axios** - HTTP 客户端
- **@dnd-kit** - 拖拽排序功能
- **Monaco Editor** - 代码编辑器
- **D3.js** - 数据可视化
- **React Markdown** - Markdown 渲染

### 后端
- **Node.js** - 运行时环境
- **Express 5** - Web 框架
- **TypeScript** - 类型安全
- **SQLite (better-sqlite3)** - 数据库
- **JWT** - 身份认证
- **Multer** - 文件上传
- **CORS** - 跨域支持

## ✨ 功能特性

1. **元数据管理**：动态配置各模块的字段，支持多种字段类型（文本、数字、日期、选择等）
2. **小说管理**：小说的创建、编辑、删除和列表展示，支持故事集合管理
3. **设定管理（世界观）**：世界观的完整 CRUD 功能
4. **人物管理**：人物的完整 CRUD 功能，支持角色关系图
5. **事件管理**：事件的完整 CRUD 功能
6. **时间线管理**：时间线的管理，支持表格和时间轴两种视图
7. **动态表单**：根据元数据配置自动生成表单字段
8. **用户认证**：基于 JWT 的用户注册、登录和权限管理
9. **多租户支持**：支持多用户数据隔离
10. **AI 辅助功能**：集成 AI 功能辅助创作
11. **图形可视化**：支持关系图、时间轴等可视化展示

## 📦 环境要求

- **Node.js**: >= 18.0.0
- **npm**: >= 9.0.0
- **操作系统**: Windows / macOS / Linux

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd scenario
```

### 2. 安装依赖

#### 安装认证模块依赖（如果存在）
```bash
cd auth-module
npm install
cd ..
```

#### 安装后端依赖
```bash
cd backend
npm install
cd ..
```

#### 安装前端依赖
```bash
cd frontend
npm install
cd ..
```

### 3. 启动服务

#### 方式一：使用启动脚本（推荐）

**Windows:**
```bash
restart.bat
```

**Linux/macOS:**
```bash
chmod +x restart.sh
./restart.sh
```

#### 方式二：手动启动

**启动后端服务：**
```bash
cd backend
npm run dev
```
后端服务将在 `http://localhost:3001` 启动

**启动前端服务（新终端）：**
```bash
cd frontend
npm run dev
```
前端应用将在 `http://localhost:5173` 启动

### 4. 访问应用

打开浏览器访问 `http://localhost:5173`

## 📁 项目结构

```
scenario/
├── auth-module/           # 认证模块（独立模块）
│   ├── backend/           # 认证后端代码
│   ├── frontend/          # 认证前端组件
│   └── examples/          # 使用示例
├── frontend/              # React 前端应用
│   ├── src/
│   │   ├── components/    # 通用组件
│   │   ├── pages/         # 页面组件
│   │   ├── services/      # API 服务
│   │   ├── utils/         # 工具函数
│   │   ├── contexts/      # React Context
│   │   ├── hooks/         # 自定义 Hooks
│   │   └── config/        # 配置文件
│   ├── public/            # 静态资源
│   └── package.json
├── backend/               # Node.js 后端
│   ├── src/
│   │   ├── routes/        # 路由定义
│   │   ├── controllers/   # 控制器
│   │   ├── services/      # 业务逻辑
│   │   ├── database/      # 数据库初始化
│   │   ├── middleware/    # 中间件
│   │   ├── auth/          # 认证相关
│   │   └── index.ts       # 入口文件
│   ├── database/          # 数据库文件
│   ├── scripts/           # 工具脚本
│   └── package.json
├── .gitignore             # Git 忽略文件
├── restart.sh             # 启动脚本（Linux/macOS）
├── restart.bat            # 启动脚本（Windows）
├── stop.sh                # 停止脚本（Linux/macOS）
├── stop.bat               # 停止脚本（Windows）
└── README.md              # 项目文档
```

## 📖 使用说明

1. **首次使用**：
   - 启动应用后，首先需要注册用户账号
   - 登录后进入系统

2. **配置元数据**：
   - 在"元数据管理"页面为各个模块配置字段
   - 支持字段类型：文本、数字、日期、选择、多行文本等

3. **管理数据**：
   - 在各个管理模块中创建、编辑和删除数据
   - 支持拖拽排序、批量操作等功能

4. **动态字段**：
   - 在元数据管理中配置的字段会自动出现在对应的管理模块中
   - 无需修改代码即可扩展字段

## 🔌 API 接口

### 认证相关
- `POST /api/auth/register` - 用户注册
- `POST /api/auth/login` - 用户登录
- `GET /api/auth/me` - 获取当前用户信息

### 元数据管理
- `GET /api/metadata/modules` - 获取所有模块
- `GET /api/metadata/fields/:moduleId` - 获取模块字段
- `POST /api/metadata/fields` - 创建字段
- `PUT /api/metadata/fields/:id` - 更新字段
- `DELETE /api/metadata/fields/:id` - 删除字段

### 小说管理
- `GET /api/novels` - 获取所有小说
- `GET /api/novels/:id` - 获取单个小说
- `POST /api/novels` - 创建小说
- `PUT /api/novels/:id` - 更新小说
- `DELETE /api/novels/:id` - 删除小说

### 其他模块
- **世界观管理** (`/api/worldviews`)
- **人物管理** (`/api/characters`)
- **事件管理** (`/api/events`)
- **时间线管理** (`/api/timelines`)
- **地点管理** (`/api/locations`)
- **组织管理** (`/api/organizations`)
- **故事集合管理** (`/api/story-collections`)
- **图形关系** (`/api/graph`)

所有 API 接口遵循 RESTful 规范，支持标准的 CRUD 操作。

## 💾 数据库

- **数据库类型**: SQLite
- **数据库文件**: `backend/database/scenario.db`
- **初始化**: 首次运行时会自动创建数据库和表结构
- **迁移**: 支持数据库迁移脚本（`backend/src/database/migrate.ts`）

### 数据库管理

```bash
# 清空数据库（开发环境）
cd backend
npm run clear-db
```

## 💻 开发指南

### 后端开发

```bash
cd backend
npm run dev      # 开发模式，使用 nodemon 自动重启
npm run build    # 构建 TypeScript 代码
npm start        # 生产模式运行
```

### 前端开发

```bash
cd frontend
npm run dev      # 开发模式，支持热更新
npm run build    # 构建生产版本
npm run preview  # 预览构建结果
npm run lint     # 代码检查
```

### 代码规范

- 使用 TypeScript 进行类型检查
- 遵循 ESLint 代码规范
- 使用 Prettier 格式化代码（如已配置）

## 📜 脚本说明

### 启动脚本

- **restart.sh / restart.bat**: 停止现有服务并重新启动前后端服务
  - 自动检查端口占用
  - 后台运行服务
  - 生成日志文件（backend.log, frontend.log）

### 停止脚本

- **stop.sh / stop.bat**: 停止所有运行中的服务

### 日志文件

- `backend.log`: 后端服务日志
- `frontend.log`: 前端服务日志（如果使用脚本启动）

## 🔒 安全说明

- 使用 JWT 进行身份认证
- 密码使用 bcrypt 加密存储
- 支持多租户数据隔离
- API 接口需要认证（除登录、注册外）

## 📝 注意事项

1. **数据库文件**: 数据库文件位于 `backend/database/scenario.db`，建议定期备份
2. **环境变量**: 生产环境请配置 `.env` 文件，设置 JWT 密钥等敏感信息
3. **端口占用**: 确保 3001（后端）和 5173（前端）端口未被占用
4. **依赖安装**: 确保先安装 `auth-module` 的依赖，因为前后端都依赖此模块

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📚 文档

项目详细文档位于 `docs/` 目录：

- [部署说明](./README-DEPLOY.md) - 一键部署脚本使用说明
- [原生部署说明](./docs/原生部署说明.md) - 详细部署文档
- [功能说明](./docs/README.md#功能说明文档) - 各功能模块使用说明
- [技术文档](./docs/README.md#技术文档) - 技术实现细节和分析

## 📄 许可证

MIT