icedcoke23/scratch-community

# Scratch Community - Scratch 编程学习与创作社区 一个面向青少年的 Scratch 编程学习与创作社区平台，集成在线编辑器、智能代码分析、题库系统、竞赛、社交互动和教学管理等功能。 [](https://github.com/icedcoke23/scratch-community/actions/workflows/ci.yml) ## 技术栈 | 层级 | 技术 | |------|------| | 前端 | Vue 3.5 + TypeScript + Vite + Element Plus + Pinia | | 后端 | Spring Boot 3.2 + MyBatis-Plus 3.5 + Java 17 | | 数据库 | MySQL 8.0 + Redis 7 + Caffeine 本地缓存 | | 对象存储 | MinIO | | 认证 | JWT + Refresh Token 双 Token 方案 | | 实时通信 | WebSocket (STOMP) + SSE | | 安全 | DFA 敏感词过滤 + 分布式锁 + 滑动窗口限流 + 幂等性保护 | | 可观测性 | TraceId 链路追踪 + Resilience4j 熔断器 + Prometheus + Grafana | | 部署 | Docker Compose + Nginx + GitHub Actions CI/CD | ## 项目结构 ├── frontend-vue/ # 前端 Vue 3 项目 │ ├── src/ │ │ ├── api/ # API 接口层 (52 个模块, 300+ 方法) │ │ ├── views/ # 页面组件 (60+ 路由) │ │ ├── components/ # 通用组件 (80+ 组件) │ │ ├── stores/ # Pinia 状态管理 │ │ ├── router/ # 路由配置 │ │ ├── i18n/ # 国际化（中/英/日/韩） │ │ ├── composables/ # 组合式函数 │ │ ├── styles/ # 全局样式 │ │ └── utils/ # 工具函数 │ └── public/scratch3/ # Scratch 编辑器静态资源 │ ├── backend/ # 后端 Spring Boot 多模块项目 │ ├── scratch-app/ # 启动模块 + 健康检查 │ ├── scratch-user/ # 用户模块 (注册/登录/OAuth/家长/积分/成就/贡献) │ ├── scratch-social/ # 社交模块 (Feed/评论/关注/收藏/博客/讨论/工作室/团队/AI点评/协作) │ ├── scratch-judge/ # 判题模块 (题目/竞赛/Rating/学习路径/AI出题/防作弊) │ ├── scratch-classroom/ # 班级模块 (作业/学情分析/成绩簿/教学计划/教程/资源/查重) │ ├── scratch-editor/ # 编辑器模块 (项目CRUD/SB3解析/版本/编辑锁/云变量/背包/资产库/代码分析) │ ├── scratch-system/ # 系统模块 (通知/审核/配置/敏感词/轮播图/举报/徽章/活动/邮件/帮助/私信) │ ├── scratch-common-core/ # 通用核心 (异常处理/工具类/Swagger) │ ├── scratch-common-security/ # 安全认证 (JWT/权限/限流/幂等) │ ├── scratch-common-redis/ # Redis 缓存 │ ├── scratch-common-audit/ # 审计日志 │ ├── scratch-sb3/ # SB3 文件解析 + 智能分析引擎 │ └── scratch-judge-core/ # 判题核心 │ ├── sandbox/ # Node.js 判题沙箱 (进程隔离 + seccomp) ├── docker/ # Docker 部署配置 ├── deploy/ # 部署脚本 ├── docs/ # 项目文档 └── scripts/ # 运维脚本 ## 核心功能 ### 作品与创作 - Scratch 在线编辑器（TurboWarp iframe 嵌入） - 作品上传、展示、点赞、收藏、Remix 再创作 - AI 辅助代码审查（SSE 流式输出） - 编辑锁机制（Redis 分布式锁，5 分钟超时自动释放） - 封面智能提取（保存时自动从 VM 提取舞台截图） - 版本管理（版本列表 / 对比 / 回滚） - 协作编辑（WebSocket 实时光标 + 聊天） ### 智能代码分析引擎 - **编程概念检测**: 15 种编程概念识别（循环/条件/变量/过程/并行/消息/克隆等） - **代码质量评分**: 4 维度评分（命名 20% + 结构 30% + 抽象 30% + 交互 20%） - **代码风格检测**: 5 类问题（命名规范/代码组织/复杂度热点/资源管理/最佳实践），0-100 分 - **代码相似度检测**: 5 维度加权（积木余弦 25% + 脚本拓扑 15% + 自定义积木 Jaccard 20% + 变量 Jaccard 15% + 3-gram 25%） - **扩展分析**: 使用统计 + 兼容性检查 + 教育类识别 + 多样性评分 + 建议生成 - **解析性能监控**: 耗时/内存/缓存命中率/慢解析警告 - **批量分析**: 最多 20 个项目同时分析 - **项目对比**: 2-5 个项目概念矩阵 + 质量对比 + 复杂度对比 ### 题库系统 - 选择题 / 多选题 / 判断题 / Scratch 编程题 - 编程题分屏答题界面（左侧题目 + 右侧编辑器） - 全屏切换（分栏 / 全屏题目 / 全屏编辑器） - 每日一题推荐 - 题解与讨论 - AI 出题（智能生成题目） - 题单管理（创建 / 排序 / 发布） - 学习路径（个性化推荐 + 能力画像） ### 竞赛系统 - 竞赛创建与管理（自动状态转换 + 定时结算） - 实时评测反馈（SSE） - 排行榜与成绩统计 - Rating 系统（ELO 评分 + 排名 + 历史 + 趋势 + 统计） - 防作弊（切屏检测 + 代码相似度检测 + 作弊风险报告） - 成绩导出（CSV） ### 社交互动 - Feed 信息流（最新/最热/关注排序 + 多样性注入 + 推荐原因） - 讨论区（问答 / 分享 / 通用 + 置顶 + 精华） - 博客系统（Markdown 编辑 + 发布 + 评论） - 工作室（项目集合 + 成员管理 + 评论） - 团队（协作组 + 成员角色） - 排行榜（点赞 / 评分 / 贡献 / Rating） - 消息与通知（WebSocket + SSE 双通道实时推送） - 私信系统（会话 + 屏蔽） - 搜索（全文搜索 + 高级搜索 + 搜索建议 + 热门关键词） - 推荐系统（猜你喜欢 / 相似项目 / 趋势 / 标签推荐） - 标签系统（标签云 / 项目标签 / 标签浏览） - 收藏夹（多收藏夹管理） ### 教学管理 - 班级创建与邀请码加入 - 作业布置与批改（批量批改 + 评分模板 + 同伴互评） - 作业查重（SimilarityDetector + Caffeine 缓存 + 风险摘要） - 代码风格检测（5 类问题 + 严重程度分级） - 成绩簿（班级统计 + 学生趋势 + CSV 导出） - 学情分析（Caffeine 缓存 + 能力画像 + 雷达图 + 薄弱环节） - 教学计划（课时管理 + 进度追踪） - 互动教程（步骤引导 + 进度追踪） - 课堂资源（上传 / 下载 / 管理） - 课堂讨论与公告 ### 系统管理 - 用户与角色管理（批量操作 + 角色权限配置） - 内容审核（AI 文本/图片审核 + 举报管理） - 敏感词过滤（DFA 自动机 + 动态加载） - 公告与轮播图管理 - 操作日志审计 - 系统配置（分类管理 + 批量更新） - 死信队列管理 - 邮件模板管理 - 帮助文章管理 - 徽章与成就系统 - 活动管理 - 性能监控仪表盘 ### 积分与成就 - 5 种积分规则 + 等级体系 - 每日签到 + 连续签到奖励 - 成就系统（多分类 + 进度追踪） - 徽章系统（展示 + 授予 + 撤销） - 贡献值排行 ### 其他 - 家长看板（关联学生 + 学习数据监控） - OAuth 第三方登录 - PWA 支持（Service Worker + 离线模式） - 国际化（中/英/日/韩 4 种语言） - 深色模式 - 移动端适配 - 无障碍（WCAG 2.1 AA） ## API 概览 | 模块 | 控制器数 | 端点数 | 核心功能 | |------|---------|--------|---------| | scratch-editor | 10 | ~60 | 项目CRUD/SB3/版本/编辑锁/云变量/背包/资产库/代码分析 | | scratch-social | 14 | ~90 | Feed/评论/关注/收藏/博客/讨论/工作室/团队/AI点评/协作/搜索/推荐/标签 | | scratch-classroom | 9 | ~55 | 作业/学情/成绩簿/教学计划/教程/资源/查重/风格检测 | | scratch-system | 20 | ~85 | 通知/审核/配置/敏感词/轮播图/举报/徽章/活动/邮件/帮助/私信 | | scratch-judge | 10 | ~55 | 题目/竞赛/Rating/学习路径/AI出题/防作弊/导出 | | scratch-user | 6 | ~55 | 注册登录/OAuth/家长/积分/成就/贡献/管理 | | scratch-app | 1 | 7 | 健康检查/就绪探针/存活探针 | | **合计** | **71** | **~408** | | ## 前端页面 | 模块 | 页面数 | 核心页面 | |------|--------|---------| | 社区 | 22 | 信息流/项目详情/用户主页/讨论/博客/排行榜/搜索/工作室/团队/标签/活动/公告 | | 编辑器 | 2 | 新建项目/编辑项目 | | 协作 | 1 | 协作编辑 | | 判题/竞赛 | 10 | 题库/题目详情/题解/题单/竞赛/评测记录/学习路径/AI出题 | | 教室 | 11 | 班级管理/作业/学情分析/成绩簿/课堂资源/讨论/公告/教学计划/学生画像 | | 个人 | 8 | 积分/通知/消息/背包/设置/成就/家长看板/离线模式 | | 管理后台 | 26 | 仪表盘/用户/作品/评论/审核/配置/竞赛/班级/角色/日志/健康/活动/帮助/邮件/敏感词/死信/举报/徽章/AI审核/讨论/题解/工作室/公告/教学计划 | | **合计** | **~80** | | ## 快速开始 ### 环境要求 - JDK 17+ - Node.js 18+ - MySQL 8.0+ - Redis 7+ - MinIO ### 后端启动 cd backend mvn package -Dmaven.test.skip=true # 配置数据库连接 export DB_USER=scratch export DB_PASSWORD=scratch123 export REDIS_PASSWORD= java -jar scratch-app/target/scratch-app-0.1.0-SNAPSHOT.jar \ --spring.profiles.active=dev ### 前端启动 cd frontend-vue npm install npm run dev 访问 http://localhost:5173 ### Docker 部署 cd docker docker-compose up -d 详见 [部署文档](docs/DEPLOYMENT.md)。 ## API 文档 后端集成 SpringDoc OpenAPI（Swagger UI），启动后端后访问： http://localhost:8080/swagger-ui.html API 概览见下文「API 概览」章节，各模块端点定义位于 `backend/scratch-*/src/main/java/.../controller/`。 ## CI/CD 项目使用 GitHub Actions 实现自动化： - **CI 流水线** (`ci.yml`): Lint + Type Check + Test + Security Scan - **部署流水线** (`deploy.yml`): 构建 Docker 镜像 → 推送 GHCR → SSH 部署 → 健康检查 → 自动回滚 - 支持多环境：develop (自动) / staging (手动) / production (手动 + 回滚保护) ## 配置 复制 `.env.example` 为 `.env` 并填写配置： cp .env.example .env 关键配置项： - 数据库连接信息 - Redis 连接信息 - MinIO 访问密钥 - JWT 密钥 - Sandbox API Key ## 国际化 支持四种语言： - 简体中文（zh-CN） - English（en-US） - 日本語（ja-JP） - 한국어（ko-KR） ## 文档 | 文档 | 说明 | |------|------| | [部署指南](docs/DEPLOYMENT.md) | Docker Compose 一键部署 + 环境变量配置 | | [开发进度](docs/PROGRESS.md) | 版本历史 + 里程碑 + 功能完成度 | | [开发计划](docs/plans/ToDo.md) | 待开发项 + 架构审计发现 + 优化路线图 | | [优化建议](docs/OPTIMIZATION_SUGGESTIONS.md) | 与官方 Scratch 对比 + 优化路线图 | | [项目深度分析](docs/PROJECT_DEEP_ANALYSIS.md) | 架构/数据库/业务模块/前端机制详解 | | [项目创作分析](docs/PROJECT_CREATION_ANALYSIS.md) | SB3 处理/编辑器集成/Remix/协作编辑 | | [ER 图](docs/ER_DIAGRAM.md) | 23+ 张表实体关系图 | | [架构决策](docs/ADR.md) | 6 个关键架构决策记录 | | [编码规范](docs/CODING_STANDARDS.md) | Java/TS/数据库/API/Git/安全规范 | | [无障碍](docs/accessibility.md) | WCAG 2.1 AA 标准 | ## 最近更新 (v4.9.7) - **并发安全**: `CollabService.handleEdit` 版本号比较改为 `ConcurrentHashMap.compute()` 原子化；`SystemController` SSE emitter 替换改为 `compute()` 原子关闭旧连接并写入新连接 - **幂等保护**: 作业提交/回复、比赛提交/虚拟参赛、博客/讨论/工作室写操作、用户关注/班级/管理员批量创建等关键 POST 接口统一添加 `@Idempotent` - **依赖注入规范**: `AiReviewService`、`AiProblemGeneratorService`、`CompetitionController`、`AiReviewController` 的 `@Autowired(required=false)` 字段注入统一改为 `ObjectProvider` 构造器注入 - **错误处理**: `AiReviewService.toVO()` JSON 解析失败由静默吞异常改为记录 `WARN` 日志并保留空集合降级 - **性能优化**: `SocialService.getComments` 与 `PrivateMessageService.getConversations/getMessages` 由 N+1 查询改为批量 IN 查询 + Map 索引组装 - **API 契约**: `TutorialController`、`TeachingPlanController`、`HomeworkController`、`UserController.classProjects`、`AdminController` 多处 `R` 收敛为具体泛型 - **安全**: `CloudVariableWebSocket.set` 增加 token 校验与项目所有者权限校验；`applicationContext` 标记 `volatile` - **架构审计**: 完成第十轮深度审计，新增 SSE 资源管理、幂等 Key 命名空间、云变量鉴权粒度、R/Map 弱类型等 8 项【待审核】项；`C2-1`、`C2-2` 标记为已完成 - **文档/仓库治理**: `ToDo.md` 已完成项迁移至 `changeList.md`；README 更新至 v4.9.7；仓库保持 private，CI 额度不足时临时 public 执行后立即恢复 ## 历史更新 (v4.9.6) - **测试修复**: `UserServiceTest` 密码值从 `Test123`（7 位）更新为 `Test1234`（8 位，含大写/小写/数字 3 种类型），适配新增的 `PasswordValidator` 密码强度策略 - **CI 修复**: 修复 private 仓库 GitHub Actions runner 额度耗尽导致的 CI 全部失败；临时切换 public 执行 CI（run 27791202807 全部 8 个 job 通过）后立即恢复 private - **文档整理**: `ToDo.md` 中已完成项归档至 `changeList.md`，`ToDo.md` 仅保留待开发与【待审核】项；`changeList.md` 新增 2026-06-19 CI 修复与测试修复记录 ## 历史更新 (v4.9.5) - **安全/架构修复**: `HelpArticleController` / `HelpArticleCompatibilityController` 迁移为 `HelpArticleVO` / `HelpArticleDTO`，消除 mass-assignment 风险 - **并发安全**: `EditLockService` 使用 Lua 脚本原子化续期/释放，修复 TOCTOU 竞态；`PointService.dailyCheckin` 使用 Redis SETNX 原子标记避免重复发积分；`UserService.register` / `HomeworkService.submit` 捕获 `DuplicateKeyException` 防御并发重复 - **依赖注入统一**: `PointService`、`HealthController` 改为 `ObjectProvider` 构造器注入；`NotifyService` 统一使用 `@RequiredArgsConstructor` - **可观测性**: `HealthController` MinIO 健康检查由 `listBuckets()` 改为轻量 `bucketExists("{prefix}sb3")` - **异常处理**: `HomeworkService.toVO` 静默吞异常改为记录 WARN 日志 - **审计治理**: 更新 `docs/plans/ToDo.md` 与 `docs/changeList.md`，新增第七轮审计待审核项 - **文档/仓库治理**: 整理 `docs/plans/ToDo.md` 与 `docs/changeList.md`，将本轮已完成的修复项归档；仓库已恢复私人状态；创建 v4.9.5 标签 ## 历史更新 (v4.9.4) - **CI/文档治理**: 在 `docs/DEPLOYMENT.md` 新增私人仓库 GitHub Actions 额度耗尽时的应急公开/恢复流程；`frontend-vue/package.json` 新增 `lint:all` 脚本统一执行 ESLint + Prettier 检查 - **性能修复**: `ProjectService`、`HomeworkGradingService` 改为注入 Spring `ObjectMapper` Bean，消除方法内重复 `new ObjectMapper()` 实例化 - **数据库审计**: 核对关键高频字段索引（`project_tag.tag_id`、`project_comment.parent_id`、`notification(user_id,is_read)`），确认已存在无需重复添加 - **上一轮修复延续**: 仓库整理与变更日志归档（`docs/changeList.md`），保持 ToDo.md 与已完成项同步 ## 历史更新 (v4.9.3) - **安全加固**: TagController 项目标签 IDOR 修复；NotificationController/DiscussionController/BlogController/StudioController/CollabController 写操作补齐 `@RequireRole`；OAuth 登录接口添加 `@RateLimit`；PublicPathConfig 移除过宽公开路径；EmailTemplate 改用 DTO 防止 mass-assignment - **前端质量修复**: AsyncErrorBoundary 定时器泄漏修复；LoginDialog 卸载时清理 interval；sanitize.ts 改用 DOMPurify；ProjectDetailView 路由参数响应式；request.ts 重试拦截器前置；AppHeader 硬编码中文迁移至 i18n - **仓库整理**: README/CHANGELOG/ToDo.md 同步；仓库恢复为私人状态；新增 v4.9.3 tag ## 许可证 本项目仅供学习和研究使用。

标签：Scratch, Spring Boot, Vue 3, 在线教育, 域名枚举, 少儿编程, 版权保护, 社区平台, 自定义请求头