first commit

2025-09-18 23:34:55 +08:00
commit 1f669143cc
84 changed files with 96383 additions and 0 deletions
--- a/部署文档.md
+++ b/部署文档.md
@@ -0,0 +1,408 @@
+# 抽奖系统部署文档
+
+## 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