first commit

2025-09-18 23:34:55 +08:00
commit 1f669143cc
84 changed files with 96383 additions and 0 deletions
--- a/.trae/documents/抽奖系统产品需求文档.md
+++ b/.trae/documents/抽奖系统产品需求文档.md
@@ -0,0 +1,97 @@
+# 抽奖系统产品需求文档
+
+## 1. Product Overview
+
+本产品是一个基于H5技术的学号抽奖系统，为学校活动提供公平、透明的抽奖服务。系统支持多级奖项设置、实时数据统计和离线缓存功能，确保在网络异常情况下也能正常运行。
+
+- 解决传统抽奖方式不够透明、数据难以统计的问题，为学校师生提供现代化的抽奖解决方案。
+- 目标是成为校园活动的标准抽奖工具，提升活动参与度和公信力。
+
+## 2. Core Features
+
+### 2.1 User Roles
+
+| Role | Registration Method | Core Permissions |
+|------|---------------------|------------------|
+| 管理员 | 密码登录 | 系统配置、奖项设置、数据查看、背景管理 |
+| 学生用户 | 学号输入 | 参与抽奖、查看中奖结果 |
+
+### 2.2 Feature Module
+
+我们的抽奖系统包含以下主要页面：
+
+1. **登录页面**：密码验证、系统准入控制
+2. **抽奖主界面**：三列布局展示、学号输入、屏幕键盘、抽奖操作
+3. **后台管理页面**：奖项配置、抽奖次数设置、数据统计
+4. **数据查询页面**：中奖记录查看、学号隐私保护
+5. **系统设置页面**：背景图片管理、界面配置
+
+### 2.3 Page Details
+
+| Page Name | Module Name | Feature description |
+|-----------|-------------|---------------------|
+| 登录页面 | 密码验证模块 | 输入系统密码，验证通过后进入抽奖系统 |
+| 抽奖主界面 | 奖项展示区 | 显示各级奖品名称、中奖概率、已中出数量（左侧2/9宽度） |
+| 抽奖主界面 | 学号输入区 | 12位数字学号输入框、屏幕数字键盘（140px*140px，间距10px）、退格清空按钮（中间5/9宽度） |
+| 抽奖主界面 | 开奖结果区 | 实时显示中奖情况、历史记录（右侧2/9宽度） |
+| 抽奖主界面 | 抽奖动画模块 | 弹出浮窗、3秒滚动摇奖效果、中奖信息展示 |
+| 后台管理页面 | 奖项配置模块 | 设置总奖数、一二三等奖名称数量、抽奖次数限制 |
+| 后台管理页面 | 数据统计模块 | 查看所有中奖数据、学号记录、抽奖时间 |
+| 数据查询页面 | 查询接口模块 | 实时查看出奖情况、学号隐私保护（*号替换） |
+| 系统设置页面 | 背景管理模块 | 本地图片选择、背景大小位置调整 |
+| 系统设置页面 | 缓存同步模块 | 本地缓存管理、网络恢复后数据同步 |
+
+## 3. Core Process
+
+**管理员流程：**
+系统启动 → 密码登录 → 奖项配置 → 背景设置 → 启动抽奖 → 实时监控 → 数据导出
+
+**学生用户流程：**
+进入抽奖页面 → 输入12位学号 → 点击抽奖按钮 → 观看摇奖动画 → 查看中奖结果 → 结束或继续抽奖
+
+**系统内部流程：**
+学号验证 → 抽奖次数检查 → 本地缓存记录 → 概率计算 → 结果生成 → 数据同步
+
+```mermaid
+graph TD
+    A[系统启动] --> B[密码登录]
+    B --> C[抽奖主界面]
+    C --> D[学号输入]
+    D --> E[抽奖次数验证]
+    E --> F[抽奖动画]
+    F --> G[结果展示]
+    G --> H[数据记录]
+    H --> I[本地缓存]
+    I --> J[网络同步]
+    
+    C --> K[后台管理]
+    K --> L[奖项配置]
+    K --> M[数据查询]
+    K --> N[系统设置]
+```
+
+## 4. User Interface Design
+
+### 4.1 Design Style
+
+- **主色调**：#1890FF（蓝色主题），#52C41A（成功绿色）
+- **辅助色**：#FAAD14（警告黄色），#F5222D（错误红色）
+- **按钮样式**：圆角矩形，3D立体效果，悬停渐变动画
+- **字体**：微软雅黑 16px-24px，数字使用等宽字体
+- **布局风格**：卡片式设计，顶部导航，响应式网格布局
+- **图标风格**：线性图标配合实心填充，统一视觉风格
+
+### 4.2 Page Design Overview
+
+| Page Name | Module Name | UI Elements |
+|-----------|-------------|-------------|
+| 登录页面 | 密码输入框 | 居中卡片布局，深色背景，白色输入框，蓝色登录按钮 |
+| 抽奖主界面 | 三列布局 | 1920*1080全屏，左中右2:5:2比例，无滚动条设计 |
+| 抽奖主界面 | 屏幕键盘 | 3*4数字矩阵，140px*140px按钮，10px间距，触摸反馈 |
+| 抽奖主界面 | 抽奖动画 | 模态弹窗，旋转滚动效果，3秒倒计时，结果高亮显示 |
+| 后台管理页面 | 配置表单 | 表格布局，输入框验证，实时预览，保存确认 |
+| 数据查询页面 | 数据表格 | 分页显示，搜索过滤，学号脱敏，导出功能 |
+
+### 4.3 Responsiveness
+
+系统主要针对1920*1080分辨率设计，桌面优先适配。支持触摸交互优化，屏幕键盘具备触觉反馈效果。在较小屏幕上自动调整布局比例，确保核心功能可用性。
--- a/.trae/documents/抽奖系统技术架构文档.md
+++ b/.trae/documents/抽奖系统技术架构文档.md
@@ -0,0 +1,247 @@
+# 抽奖系统技术架构文档
+
+## 1. Architecture design
+
+```mermaid
+graph TD
+    A[用户浏览器] --> B[React前端应用]
+    B --> C[SQLite数据库接口]
+    C --> D[SQLite本地数据库]
+    B --> E[本地缓存 LocalStorage]
+    B --> F[文件系统存储]
+    
+    subgraph "前端层"
+        B
+        E
+    end
+    
+    subgraph "数据层"
+        C
+        D
+        F
+    end
+```
+
+## 2. Technology Description
+
+- Frontend: React@18 + TypeScript + Tailwind CSS@3 + Vite + Framer Motion
+- Database: SQLite + better-sqlite3
+- 状态管理: Zustand
+- 本地存储: LocalStorage + SQLite
+- 动画库: Framer Motion + CSS3 Animations
+- 文件处理: Node.js File System API
+
+## 3. Route definitions
+
+| Route | Purpose |
+|-------|---------|
+| / | 登录页面，密码验证和系统准入 |
+| /lottery | 抽奖主界面，三列布局的核心抽奖功能 |
+| /admin | 后台管理页面，奖项配置和系统设置 |
+| /admin/prizes | 奖项管理子页面，设置各级奖品信息 |
+| /admin/records | 数据查询子页面，查看中奖记录 |
+| /admin/settings | 系统设置子页面，背景和参数配置 |
+
+## 4. API definitions
+
+### 4.1 Core API
+
+**身份认证相关**
+```
+POST /api/auth/login
+```
+
+Request:
+| Param Name | Param Type | isRequired | Description |
+|------------|------------|------------|-------------|
+| password | string | true | 系统管理密码 |
+
+Response:
+| Param Name | Param Type | Description |
+|------------|------------|-------------|
+| success | boolean | 登录是否成功 |
+| session | string | 会话标识 |
+
+**抽奖相关**
+```
+POST /api/lottery/draw
+```
+
+Request:
+| Param Name | Param Type | isRequired | Description |
+|------------|------------|------------|-------------|
+| studentId | string | true | 12位学号 |
+| timestamp | number | true | 抽奖时间戳 |
+
+Response:
+| Param Name | Param Type | Description |
+|------------|------------|-------------|
+| success | boolean | 抽奖是否成功 |
+| prize | object | 中奖信息 |
+| remaining | number | 剩余抽奖次数 |
+
+**奖项配置**
+```
+GET/POST /api/prizes
+```
+
+**中奖记录查询**
+```
+GET /api/records
+```
+
+Request:
+| Param Name | Param Type | isRequired | Description |
+|------------|------------|------------|-------------|
+| page | number | false | 页码 |
+| limit | number | false | 每页数量 |
+| hidePositions | array | false | 学号隐藏位置 |
+
+## 5. Server architecture diagram
+
+```mermaid
+graph TD
+    A[客户端/前端] --> B[路由层]
+    B --> C[组件层]
+    C --> D[状态管理层]
+    D --> E[数据服务层]
+    E --> F[缓存层]
+    E --> G[(SQLite数据库)]
+    
+    subgraph 前端架构
+        B
+        C
+        D
+        E
+        F
+    end
+    
+    subgraph 数据层
+        G
+        H[本地存储]
+        I[文件系统]
+    end
+    
+    F --> H
+    F --> I
+```
+
+## 6. Data model
+
+### 6.1 Data model definition
+
+```mermaid
+erDiagram
+    SYSTEM_CONFIG ||--o{ PRIZE_CONFIG : contains
+    PRIZE_CONFIG ||--o{ LOTTERY_RECORD : generates
+    STUDENT ||--o{ LOTTERY_RECORD : participates
+    
+    SYSTEM_CONFIG {
+        uuid id PK
+        string admin_password
+        int max_draw_times
+        json background_config
+        json hide_positions
+        timestamp created_at
+        timestamp updated_at
+    }
+    
+    PRIZE_CONFIG {
+        uuid id PK
+        string prize_name
+        int prize_level
+        int total_quantity
+        int remaining_quantity
+        decimal probability
+        boolean is_active
+        timestamp created_at
+    }
+    
+    STUDENT {
+        string student_id PK
+        int draw_count
+        timestamp first_draw_at
+        timestamp last_draw_at
+    }
+    
+    LOTTERY_RECORD {
+        uuid id PK
+        string student_id FK
+        uuid prize_id FK
+        string prize_name
+        int prize_level
+        timestamp draw_time
+        boolean is_synced
+        json cache_data
+    }
+```
+
+### 6.2 Data Definition Language
+
+**系统配置表 (system_config)**
+```sql
+-- 创建系统配置表
+CREATE TABLE system_config (
+    id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+    admin_password TEXT NOT NULL DEFAULT 'admin123',
+    max_draw_times INTEGER DEFAULT 1,
+    background_config TEXT DEFAULT '{}',
+    hide_positions TEXT DEFAULT '3,4,5,6',
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- 创建奖项配置表
+CREATE TABLE prize_config (
+    id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+    prize_name TEXT NOT NULL,
+    prize_level INTEGER NOT NULL CHECK (prize_level IN (1,2,3,4)),
+    total_quantity INTEGER NOT NULL DEFAULT 0,
+    remaining_quantity INTEGER NOT NULL DEFAULT 0,
+    probability REAL DEFAULT 0.0000,
+    is_active INTEGER DEFAULT 1,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- 创建学生表
+CREATE TABLE students (
+    student_id TEXT PRIMARY KEY,
+    draw_count INTEGER DEFAULT 0,
+    first_draw_at DATETIME,
+    last_draw_at DATETIME
+);
+
+-- 创建抽奖记录表
+CREATE TABLE lottery_records (
+    id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+    student_id TEXT NOT NULL,
+    prize_id TEXT REFERENCES prize_config(id),
+    prize_name TEXT NOT NULL,
+    prize_level INTEGER NOT NULL,
+    draw_time DATETIME DEFAULT CURRENT_TIMESTAMP,
+    is_synced INTEGER DEFAULT 0,
+    cache_data TEXT DEFAULT '{}'
+);
+
+-- 创建索引
+CREATE INDEX idx_lottery_records_student_id ON lottery_records(student_id);
+CREATE INDEX idx_lottery_records_draw_time ON lottery_records(draw_time DESC);
+CREATE INDEX idx_lottery_records_prize_level ON lottery_records(prize_level);
+CREATE INDEX idx_students_draw_count ON students(draw_count);
+
+-- 创建触发器用于更新时间戳
+CREATE TRIGGER update_system_config_timestamp 
+    AFTER UPDATE ON system_config
+    BEGIN
+        UPDATE system_config SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id;
+    END;
+
+-- 初始化数据
+INSERT INTO system_config (admin_password, max_draw_times) VALUES ('admin123', 1);
+
+INSERT INTO prize_config (prize_name, prize_level, total_quantity, remaining_quantity, probability) VALUES
+('一等奖-iPad', 1, 1, 1, 0.0010),
+('二等奖-蓝牙耳机', 2, 5, 5, 0.0050),
+('三等奖-保温杯', 3, 20, 20, 0.0200),
+('谢谢参与', 4, 9974, 9974, 0.9740);
+```