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,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);
+```