draw/.trae/documents/抽奖系统技术架构文档.md

# 抽奖系统技术架构文档

## 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);
```