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

抽奖系统技术架构文档

1. Architecture design

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

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

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)

-- 创建系统配置表
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);