# 抽奖系统部署文档

## 1. 项目简介

本项目是一个基于 React + TypeScript + Vite 技术栈开发的学号抽奖系统，为学校活动提供公平、透明的抽奖服务。系统采用前端单页应用架构，使用 SQLite 本地数据库存储数据，支持离线缓存和实时同步功能。

### 主要功能特性

- **多级奖项设置**：支持一、二、三等奖及特别奖的灵活配置
- **学号抽奖**：基于12位学号的公平抽奖机制
- **实时动画**：炫酷的抽奖动画效果和撒花庆祝
- **数据统计**：完整的中奖记录和数据分析
- **离线缓存**：网络异常时仍可正常运行
- **管理后台**：奖项配置、数据查看、系统设置
- **响应式设计**：适配不同屏幕尺寸

## 2. 环境要求

### 系统要求
- **操作系统**：Windows 10+、macOS 10.15+、Linux (Ubuntu 18.04+)
- **浏览器**：Chrome 90+、Firefox 88+、Safari 14+、Edge 90+
- **屏幕分辨率**：推荐 1920×1080 或更高

### 软件依赖
- **Node.js**：版本 18.19.1 或更高 (推荐使用 LTS 版本)
- **npm**：版本 9.0+ (随 Node.js 安装)
- **Git**：用于代码克隆和版本管理

### 硬件要求
- **内存**：最低 4GB RAM，推荐 8GB+
- **存储空间**：至少 1GB 可用空间
- **网络**：开发时需要网络连接下载依赖

## 3. 安装步骤

### 3.1 克隆项目代码

```bash
# 克隆项目到本地
git clone <项目仓库地址>
cd draw

# 或者直接下载项目压缩包并解压
```

### 3.2 安装项目依赖

```bash
# 安装所有依赖包
npm install

# 如果安装速度慢，可以使用国内镜像
npm install --registry=https://registry.npmmirror.com
```

### 3.3 数据库初始化

项目使用 SQLite 数据库，首次运行时会自动创建数据库文件：

```bash
# 数据库文件位置：./lottery.db
# 初始化脚本位置：./src/database/init.sql
```

数据库包含以下表结构：
- `system_config`：系统配置表
- `prize_config`：奖项配置表
- `lottery_record`：抽奖记录表
- `student`：学生信息表

### 3.4 环境配置检查

```bash
# 检查 Node.js 版本
node --version

# 检查 npm 版本
npm --version

# 检查 TypeScript 编译
npm run check
```

## 4. 配置说明

### 4.1 端口配置

默认开发服务器端口为 `5173`，可在 `vite.config.ts` 中修改：

```typescript
export default defineConfig({
  server: {
    port: 5173,
    host: true, // 允许外部访问
    open: true  // 自动打开浏览器
  }
})
```

### 4.2 数据库配置

数据库配置位于 `src/database/database.ts`：

```typescript
// SQLite 数据库文件路径
const DB_PATH = './lottery.db'

// 数据库连接选项
const options = {
  verbose: console.log, // 开发环境日志
  fileMustExist: false  // 自动创建数据库
}
```

### 4.3 系统默认配置

- **管理员密码**：`admin123` (首次登录后可修改)
- **最大抽奖次数**：每个学号限制 1 次
- **学号隐私保护**：默认隐藏第 3-6 位数字
- **奖项等级**：支持 1-4 级奖项设置

## 5. 运行和启动

### 5.1 开发环境启动

```bash
# 启动开发服务器
npm run dev

# 服务器启动后访问地址
# 本地访问：http://localhost:5173
# 局域网访问：http://[本机IP]:5173
```

### 5.2 生产环境构建

```bash
# 构建生产版本
npm run build

# 构建文件输出到 dist 目录
# 可以部署到任何静态文件服务器
```

### 5.3 预览生产构建

```bash
# 预览生产构建结果
npm run preview

# 访问地址：http://localhost:4173
```

### 5.4 代码检查和格式化

```bash
# TypeScript 类型检查
npm run check

# ESLint 代码检查
npm run lint
```

## 6. 生产环境部署

### 6.1 静态文件部署

1. **构建项目**：
   ```bash
   npm run build
   ```

2. **部署 dist 目录**到以下任一服务器：
   - **Nginx**：配置静态文件服务和 SPA 路由
   - **Apache**：启用 mod_rewrite 支持 SPA
   - **Vercel**：直接部署，自动配置
   - **Netlify**：拖拽部署，零配置

### 6.2 Nginx 配置示例

```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /path/to/dist;
    index index.html;
    
    # SPA 路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
    
    # 安全头设置
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
}
```

### 6.3 Docker 部署

创建 `Dockerfile`：

```dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

构建和运行：

```bash
# 构建镜像
docker build -t lottery-system .

# 运行容器
docker run -d -p 80:80 --name lottery lottery-system
```

### 6.4 宝塔面板部署

1. **上传项目文件**到网站根目录
2. **安装 Node.js**：在宝塔面板安装 Node.js 环境
3. **构建项目**：
   ```bash
   cd /www/wwwroot/your-site
   npm install
   npm run build
   ```
4. **配置网站**：将网站根目录指向 `dist` 文件夹
5. **设置伪静态**：添加 SPA 路由规则

## 7. 常见问题和解决方案

### 7.1 安装依赖问题

**问题**：`npm install` 失败或速度慢

**解决方案**：
```bash
# 清理缓存
npm cache clean --force

# 使用国内镜像
npm config set registry https://registry.npmmirror.com

# 或使用 cnpm
npm install -g cnpm
cnpm install
```

### 7.2 端口占用问题

**问题**：端口 5173 被占用

**解决方案**：
```bash
# 查看端口占用
netstat -ano | findstr :5173

# 杀死占用进程
taskkill /PID <进程ID> /F

# 或修改端口
npm run dev -- --port 3000
```

### 7.3 数据库权限问题

**问题**：SQLite 数据库创建失败

**解决方案**：
```bash
# 检查目录权限
ls -la lottery.db

# 修改权限 (Linux/macOS)
chmod 666 lottery.db
chmod 755 .
```

### 7.4 构建失败问题

**问题**：TypeScript 编译错误

**解决方案**：
```bash
# 检查类型错误
npm run check

# 更新依赖
npm update

# 重新安装
rm -rf node_modules package-lock.json
npm install
```

### 7.5 浏览器兼容性问题

**问题**：在旧版浏览器中功能异常

**解决方案**：
- 升级浏览器到支持的版本
- 检查控制台错误信息
- 确保启用 JavaScript

### 7.6 网络连接问题

**问题**：局域网无法访问

**解决方案**：
```bash
# 启动时绑定所有网络接口
npm run dev -- --host 0.0.0.0

# 检查防火墙设置
# Windows: 允许 Node.js 通过防火墙
# Linux: sudo ufw allow 5173
```

## 8. 项目结构说明

```
draw/
├── public/                 # 静态资源目录
│   └── favicon.svg        # 网站图标
├── src/                   # 源代码目录
│   ├── components/        # React 组件
│   │   ├── ConfettiEffect.tsx    # 撒花效果组件
│   │   ├── LotteryAnimation.tsx  # 抽奖动画组件
│   │   ├── PrizeDisplay.tsx      # 奖项展示组件
│   │   └── ...                   # 其他组件
│   ├── pages/             # 页面组件
│   │   ├── Home.tsx       # 首页/登录页
│   │   ├── Lottery.tsx    # 抽奖主界面
│   │   ├── Admin.tsx      # 管理后台
│   │   └── ...            # 其他页面
│   ├── database/          # 数据库相关
│   │   ├── database.ts    # 数据库连接
│   │   └── init.sql       # 初始化脚本
│   ├── services/          # 业务服务
│   │   ├── lotteryService.ts     # 抽奖逻辑
│   │   ├── cacheService.ts       # 缓存服务
│   │   └── ...                   # 其他服务
│   ├── store/             # 状态管理
│   │   └── index.ts       # Zustand 状态
│   ├── hooks/             # 自定义 Hooks
│   ├── contexts/          # React Context
│   ├── types.ts           # TypeScript 类型定义
│   └── main.tsx           # 应用入口
├── .trae/                 # 项目文档
│   └── documents/         # 需求和架构文档
├── lottery.db             # SQLite 数据库文件
├── package.json           # 项目配置和依赖
├── vite.config.ts         # Vite 构建配置
├── tsconfig.json          # TypeScript 配置
├── tailwind.config.js     # Tailwind CSS 配置
└── README.md              # 项目说明
```

### 核心文件说明

- **App.tsx**：应用主组件，包含路由配置
- **main.tsx**：应用入口，挂载 React 应用
- **database.ts**：SQLite 数据库操作封装
- **lotteryService.ts**：抽奖核心业务逻辑
- **types.ts**：全局 TypeScript 类型定义
- **index.css**：全局样式和 Tailwind CSS 导入

### 重要配置文件

- **vite.config.ts**：开发服务器和构建配置
- **tsconfig.json**：TypeScript 编译选项
- **tailwind.config.js**：CSS 框架配置
- **package.json**：项目元信息和脚本命令

---

## 技术支持

如遇到部署问题，请检查：

1. **环境版本**：确保 Node.js 版本符合要求
2. **依赖安装**：确保所有依赖正确安装
3. **端口占用**：确保端口未被其他程序占用
4. **权限设置**：确保有足够的文件读写权限
5. **网络连接**：确保网络连接正常

更多技术细节请参考项目文档目录下的需求文档和架构文档。

**项目版本**：v1.0.0  
**最后更新**：2024年12月  
**技术栈**：React 18 + TypeScript + Vite + SQLite