# 项目设置指南

## 环境要求

- Node.js >= 16
- pnpm >= 8

## 安装步骤

### 1. 安装所有依赖

```bash
pnpm install:all
```

或者分别安装：

```bash
# 根目录
pnpm install

# 后端
cd backend
pnpm install

# 前端
cd ../frontend
pnpm install
```

### 2. 初始化数据库

```bash
cd backend
pnpm run migrate
```

这将创建所有必要的数据库表并插入默认设置。

### 3. 启动开发服务器

在项目根目录运行：

```bash
pnpm dev
```

这将同时启动：
- 后端服务：http://localhost:3000
- 前端服务：http://localhost:5173

或者分别启动：

```bash
# 后端
pnpm dev:backend

# 前端（新终端）
pnpm dev:frontend
```

## 项目结构

```
just-demo/
├── backend/              # 后端服务
│   ├── src/
│   │   ├── controllers/  # 控制器
│   │   ├── models/       # 数据模型
│   │   ├── routes/       # 路由
│   │   ├── middleware/   # 中间件
│   │   ├── utils/        # 工具函数
│   │   ├── config/       # 配置文件
│   │   └── migrations/   # 数据库迁移
│   ├── uploads/          # 上传文件存储
│   └── package.json
├── frontend/             # 前端应用
│   ├── src/
│   │   ├── views/        # 页面组件
│   │   ├── components/   # 通用组件
│   │   ├── router/       # 路由配置
│   │   ├── store/        # 状态管理
│   │   ├── api/          # API接口
│   │   └── utils/        # 工具函数
│   └── package.json
├── database/             # 数据库文件
└── package.json          # 根配置
```

## 功能特性

### 已实现功能

1. **用户认证系统**
   - 用户注册（第一个注册的为超级管理员）
   - 用户登录（JWT token认证）
   - 用户信息获取

2. **项目管理**
   - 上传单个HTML文件或ZIP压缩包
   - 项目列表展示（网格布局）
   - 项目筛选（分类、标签）
   - 项目搜索
   - 项目详情查看
   - 项目删除（仅创建者或管理员）

3. **文件管理**
   - 附件上传和下载
   - Markdown文档上传和查看
   - 静态资源服务

4. **预览功能**
   - iframe沙盒预览
   - 项目信息抽屉
   - 文档查看器

5. **系统设置**
   - 允许/禁止注册
   - 允许/禁止上传
   - 仅超级管理员可修改

6. **安全措施**
   - 文件类型验证
   - 文件大小限制
   - 路径遍历防护
   - XSS防护（CSP头）
   - JWT认证
   - 密码加密（bcrypt）
   - 权限验证

## API端点

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

### 项目
- `GET /api/projects` - 获取项目列表
- `GET /api/projects/:id` - 获取项目详情
- `POST /api/projects` - 上传项目（需要登录）
- `DELETE /api/projects/:id` - 删除项目（需要登录）
- `GET /api/projects/:id/preview` - 预览项目

### 文件
- `GET /api/files/:projectId/*` - 获取项目文件
- `GET /api/files/attachment/:id` - 下载附件
- `GET /api/files/document/:id` - 获取文档

### 设置
- `GET /api/settings` - 获取所有设置（需要管理员权限）
- `PUT /api/settings/:key` - 更新设置（需要超级管理员权限）

## 数据库表结构

- `users` - 用户表
- `projects` - 项目表
- `attachments` - 附件表
- `documents` - 文档表
- `settings` - 设置表

## 注意事项

1. 首次注册的用户自动成为超级管理员
2. 上传的文件存储在 `backend/uploads/` 目录
3. 数据库文件存储在 `database/` 目录
4. 生产环境请修改 `backend/src/config/config.ts` 中的 `jwtSecret`
5. 文件大小限制：单个HTML文件10MB，ZIP文件50MB

## 开发说明

- 后端使用 TypeScript + Koa3
- 前端使用 TypeScript + Vue3 + Vite
- 数据库使用 SQLite + Knex.js
- 包管理使用 pnpm