校队算法刷题网站实施计划书

一、项目定位

建设一个面向本校算法竞赛队伍的刷题、作业、比赛和积分管理平台。

系统重点解决：

教练统一管理队伍和队员
按队伍或全体队伍布置作业
管理每日一题、题单和比赛记录
记录队员刷题与参赛情况
建立公开、透明、可追溯的积分制度
根据个人隐私设置展示做题数据
维护个人获奖经历

系统不包含以下功能：

AI 总结
发现
博客
独立题库
服务
“我的组织”

其中“我的组织”改为“我的队伍”。

参考网站的前端布局、颜色、组件风格和交互方式可以作为主要参考，但复制源码前必须确认仓库许可证允许使用。建议优先复用视觉设计和页面结构，再根据本项目权限模型重新实现业务逻辑。

二、用户角色

1. 站主

最高权限，负责：

管理站点基础配置
管理教练账号
管理所有用户、队伍和数据
查看所有用户的完整资料、提交记录和代码
修改积分规则
处理异常数据和申诉

2. 教练

本项目默认只有一名主教练，负责：

创建和管理队伍
设置每个队伍的唯一队长
添加、移除队员
布置队伍作业
发布全体队伍作业
设置每日一题
管理比赛、积分规则和获奖记录
查看所有用户信息，不受隐私设置限制

3. 队长

负责本队日常管理：

查看本队作业和完成情况
管理本队题单
记录和维护比赛日志
选择本队参加的比赛
审核或整理队员提交的题目、题单
查看本队成员的做题情况

4. 队员

可以：

查看队伍作业和每日一题
提交题目、题单和比赛记录
记录自己的做题情况
查看允许查看的个人、队伍和排行榜数据
维护个人资料、隐私设置和获奖经历

5. 游客

只能访问登录页或站点公开内容，不能查看受权限控制的刷题数据。

三、主要功能模块

1. 登录与账号

技术方案：

Spring Security
JWT Access Token
Refresh Token
Redis 保存登录状态、刷新令牌和注销令牌
密码使用 BCrypt 加密
登录失败次数限制
关键操作记录审计日志

账号信息包括：

用户名
昵称
头像
学号或内部编号
年级、专业
GitHub、Codeforces 等外部账号
个人简介
隐私等级
获奖情况

2. 队伍管理

队伍信息包括：

队伍名称
队伍简介
创建时间
当前队长
队员列表
队伍累计积分
队伍题单
队伍比赛日志

规则：

每个队伍只能有一名队长
队长必须是该队成员
教练可以更换队长
队长不能自行转让队长权限
队伍成员关系必须保留变更记录
建议使用多对多队伍关系，方便以后支持跨队伍训练

3. 作业系统

作业分为三类：

队伍作业

教练指定一个或多个队伍完成。

内容可以是：

单道题目
一组题目
指定题单
比赛训练任务

全体作业

教练发布后，对所有有效队伍生效。

建议在发布时生成队伍任务快照，避免之后新增队伍导致历史任务数据混乱。

每日一题

每日一题默认面向所有队伍，也可以扩展为指定队伍。

每条任务包含：

题目
发布日期
截止日期
任务说明
奖励积分
完成状态

状态包括：

未开始
进行中
已完成
已逾期
逾期完成

逾期状态必须由后端根据服务器时间计算，前端只负责展示。未完成且超过截止日期的任务显示红色。

时间统一使用中国标准时间，数据库建议保存 UTC 或明确时区的时间戳。

4. 题目、题单和做题记录

系统不建设独立的“题库”页面，而是把题目作为作业、题单、比赛和提交记录的基础数据。

题目字段包括：

题目名称
来源平台
题目编号
题目链接
难度
标签
备注
创建人
创建时间

题单功能：

队伍题单
个人题单
题单描述
题目排序
完成进度
创建者和维护者

队长和队员都可以提供题目或题单。建议采用“提交后进入待审核”的流程，由队长或教练确认后正式加入队伍内容，避免重复和无效数据。

做题记录至少包括：

用户
题目
提交平台
提交链接
提交时间
是否通过
代码内容或代码链接
备注

如果没有接入在线评测平台，第一版可以采用手动记录或提交链接的方式。后续再接入 Codeforces、洛谷等平台 API 自动同步。

5. 比赛管理

比赛模块分为比赛信息、参赛选择和比赛日志。

比赛信息：

比赛名称
比赛等级
比赛时间
比赛来源
比赛链接
比赛说明
对应积分

队长功能：

选择本队参加的比赛
记录参赛成员
填写比赛结果
上传或填写比赛总结
维护比赛日志

比赛日志包括：

比赛名称
比赛日期
参赛队员
名次或成绩
通过题数
比赛链接
赛后总结
相关题单

6. 积分系统

积分必须采用“积分事件流水”设计，而不是只保存一个可修改的总分。

每一条积分事件包括：

用户
积分类型
积分数值
关联对象
产生原因
产生时间
操作人
唯一幂等编号

建议积分规则：

首次完成一道题：获得基础积分
完成每日一题：获得额外积分
完成作业：根据作业设置获得积分
参加不同等级比赛：获得对应积分
比赛取得名次：获得额外积分
队伍贡献题目或题单：可以设置少量贡献积分

需要限制：

同一用户同一道题默认只计算一次刷题积分
同一每日任务只能获得一次奖励
重复提交不能重复刷分
删除或撤销记录时，通过反向积分事件修正
积分规则由教练或站主配置
网站正式上线时间之前的历史记录默认不计分，除非后续手动导入

前端可以使用 Recharts 展示：

个人积分趋势
队伍积分排行
月度刷题数量
不同难度题目分布
比赛积分变化
每日一题完成率

7. 个人隐私设置

个人隐私等级设计为：

完全私密

外部用户不能查看做题情况
同队伍成员可以查看必要的做题进度
教练和站主可以无限制查看

部分私密

可以查看基本资料、总积分、完成题数等汇总信息
不能查看详细提交记录
不能查看具体代码
教练和站主不受限制

公开

可以查看公开资料
可以查看做题记录
可以查看提交详情和代码，但用户可以单独关闭代码展示

所有后端接口必须进行权限判断，不能只依靠前端隐藏页面。

建议设计统一的数据脱敏层：

PRIVATE
TEAM_ONLY
PUBLIC
ADMIN_VISIBLE

排行榜、队伍统计和用户详情接口都必须按照隐私等级返回不同字段，避免通过接口间接泄露隐私。

8. 个人获奖情况

个人中心增加获奖记录：

奖项名称
比赛名称
获奖等级
获奖时间
证书图片或链接
备注
是否公开展示

队员可以提交，队长或教练审核，站主可以修改或删除。

四、技术架构

后端

采用分层架构：

Controller：接口层
Service：业务层
Mapper：MyBatis-Plus 数据访问层
Domain/Entity：实体模型
DTO/VO：请求和返回对象
Security：JWT 和权限校验
Scheduler：逾期任务、积分统计、数据同步
Common：统一异常、返回体、分页、日志

主要模块：

用户与认证
队伍管理
作业管理
每日一题
题目与题单
比赛与日志
提交记录
积分系统
隐私控制
获奖记录
管理后台

Redis 使用场景

JWT 刷新令牌
登录状态
验证码或登录限流
热门排行榜缓存
队伍统计缓存
接口幂等控制
定时任务锁

前端

沿用参考网站的技术和视觉方向：

React 19
Vite
TypeScript
shadcn/ui
TanStack Query
Recharts
React Router
表单校验可以使用 Zod

页面结构建议：

登录页
首页仪表盘
我的队伍
作业中心
每日一题
题单
比赛
积分排行
个人中心
管理后台

删除原参考网站中的：

发现
博客
题库
服务

导航中的“我的组织”改为“我的队伍”。

五、核心数据库表

建议初步设计以下表：

user
role
team
team_member
problem
problem_list
problem_list_item
assignment
assignment_target
assignment_progress
submission_record
contest
team_contest
contest_log
score_event
score_rule
user_score_summary
award
audit_log

关键约束：

队伍只能有一个队长
用户名和外部平台账号按需求设置唯一约束
同一用户同一题目的积分事件只能生成一次
同一每日任务只能产生一次完成奖励
所有重要修改保留操作人和时间

六、开发阶段

第一阶段：需求确认与原型设计

产出：

最终功能清单
用户角色和权限矩阵
页面导航结构
数据库初稿
积分规则初稿
隐私展示规则
参考网站源码许可证确认

第二阶段：项目基础搭建

完成：

Spring Boot 3 项目
React + Vite 项目
MySQL、Redis、JWT 基础配置
统一返回结构
全局异常处理
登录、退出、刷新令牌
基础布局和主题样式

第三阶段：用户与队伍管理

完成：

用户资料
教练账号
队伍创建
队员管理
唯一队长
队伍首页
我的队伍页面
权限控制

第四阶段：作业与每日一题

完成：

队伍作业
全体作业
每日一题
截止日期
逾期标红
完成状态
作业进度统计
教练管理页面

第五阶段：题单、刷题和比赛

完成：

题目记录
队伍题单
个人题单
队员贡献题目
比赛选择
比赛日志
参赛成员
比赛成绩记录

第六阶段：积分、排行和个人中心

完成：

积分事件
积分规则
个人积分
队伍积分
排行榜
积分趋势图
隐私设置
获奖记录

第七阶段：测试与上线

完成：

权限测试
隐私测试
积分幂等测试
队长唯一性测试
作业逾期测试
前后端接口测试
移动端适配
数据库备份
HTTPS
Docker 部署
日志和异常监控

七、测试重点

必须重点测试：

普通用户无法访问教练接口
队员无法修改队长
一个队伍不能同时存在两个队长
私密用户数据不会通过排行榜泄露
教练和站主可以查看完整信息
同一道题不能重复获得积分
同一每日一题不能重复获得奖励
截止日期跨时区时状态正确
全体作业不会漏掉有效队伍
删除记录后积分能够正确修正
多人同时提交时不会重复生成积分

八、部署方案

建议使用 Docker Compose 部署：

Nginx
Spring Boot
MySQL 8
Redis
前端静态文件

上线前配置：

HTTPS
JWT 密钥和数据库密码使用环境变量
MySQL 定时备份
Redis 持久化
访问日志
错误日志
管理操作审计
文件上传大小和类型限制

九、推荐的第一版范围

第一版优先实现：

登录和角色权限
队伍与队长管理
队伍作业和全体作业
每日一题与逾期状态
题目、题单和做题记录
比赛日志
基础积分和排行榜
隐私设置
个人获奖信息
管理后台

在线判题平台自动同步、复杂比赛排名、移动端独立应用、消息推送等功能放到第二阶段，避免第一版范围过大。

按照这个范围，项目可以先形成一个完整可用的校内算法队伍管理平台，再逐步扩展自动同步和更复杂的数据分析功能。

刷题计划书