hanboyx/malware-analysis-education-platform

# 恶意软件分析教育平台 恶意软件分析教育平台是一个基于 Web 的教育平台，旨在以安全、结构化和可衡量的方式准备并向学生提供恶意软件分析培训。 该代码仓库包含了在 Sprint 1 阶段基于 Next.js 的技术项目骨架。Admin 和 Student 相关的产品功能尚未开发。 ## 产品愿景 该平台的目的是让单个管理员能够通过层次化和基于 block 的内容编辑器创建技术培训；同时让学生能够在安全的环境中跟进已发布的培训并解决问题。 该产品仅包含两个角色： - **Admin**：创建、编辑、预览和发布内容。 - **Student**：消费已发布的内容，下载文件，解决问题，查看提示和解决方案，并跟踪他们的进度。 Instructor、Reviewer、Content Manager、Training Manager 或任何类似的额外角色均不包含在产品范围内。 ## 基本原则 - 内容按照“培训 → 模块 → 课程 → 章节 → block”的层次结构进行组织。 - Admin 不直接编辑原始 JSON；内容编辑操作通过可视化界面完成。 - 内容 block 可以通过拖放进行排序，并通过经过验证的表单字段进行编辑。 - 草稿、预览和发布是彼此独立的生命周期步骤。 - 学生只能访问已发布的内容。 - 初期 MVP 不包含真实或可执行的恶意软件样本。 - 授权不仅在界面层实施，还在服务器和数据库层实施。 - 模糊且具有高返工成本的技术决策被记录为 **ADR 候选**。 ## 计划的技术栈 | 领域 | 技术 | 目的 | |---|---| | 应用框架 | Next.js | 在单个 Web 应用中提供 Admin 和 Student 体验 | | 语言 | TypeScript | 提供端到端的类型安全 | | 样式 | Tailwind CSS | 开发符合设计系统且一致的用户界面 | | 组件 | shadcn/ui | 使用易于访问且可定制的界面组件 | | 富文本 | Tiptap | 准备可视化的富文本 block | | 拖放 | dnd-kit | 安全地对 block 和内容元素进行排序 | | 后端服务 | Supabase | 提供身份验证、PostgreSQL、Storage 及必要的服务器功能 | | 数据库 | PostgreSQL | 存储关系型内容和进度数据 | | 单元/组件测试 | Vitest | 验证业务规则和组件行为 | | 端到端测试 | Playwright | 通过浏览器验证关键的 Admin 和 Student 流程 | ## 文档导航 - [产品需求](docs/PRODUCT_REQUIREMENTS.md)：愿景、用户、范围、功能性与非功能性需求。 - [架构](docs/ARCHITECTURE.md)：系统边界、分层、数据流和技术原则。 - [开发计划](docs/DEVELOPMENT_PLAN.md)：阶段、交付物、质量门和风险。 - [设计系统](docs/DESIGN_SYSTEM.md)：视觉语言、组件原则、可访问性和界面行为。 - [内容模型](docs/CONTENT_MODEL.md)：培训层次结构、block、发布生命周期和验证。 - [安全规则](docs/SECURITY_RULES.md)：授权、文件安全、RLS、日志记录和威胁应对方法。 - [数据库 Schema](docs/DATABASE_SCHEMA.md)：表、字段、关系、约束和策略。 - [验收标准](docs/ACCEPTANCE_CRITERIA.md)：MVP 完成标准和场景。 - [贡献和 Agent 规则](AGENTS.md)：针对在代码仓库上工作的开发者和代码 Agent 的约束规则。 ## MVP 范围概述 MVP 包括 Admin 身份验证、培训层次结构管理、基于 block 的内容创作、可视化且安全的培训附件上传、问题-提示-解决方案流程、草稿/预览/发布、学生注册和登录流程、已发布课程的消费以及基本的进度跟踪。 不属于 MVP 的主要事项包括： - 托管真实的、可执行的或受密码保护的恶意软件样本 - Sandbox、虚拟机或动态恶意软件执行基础设施 - 多管理员、团队或机构结构 - Admin 和 Student 之外的角色 - 证书、计费、市场、直播课程和社交功能 - 移动应用程序和离线使用 ## 本地开发 要求： - Node.js 24 - npm 11 或更新的兼容版本 开始： ``` npm ci npm run dev ``` ## 本地 Supabase 集成 进行本地 migration 和实际的 auth/RLS 验证需要 Docker Desktop 或 Docker API 兼容的 container runtime。Supabase CLI 不会进行全局安装；将使用项目的 devDependency 和 npm 脚本。 ``` # .env.example dosyasını .env.local olarak kopyalayıp yalnız local test # credential alanlarını doldurun. npm run db:start npm run db:status npm run db:reset npm run auth:bootstrap npm run test:integration npm run db:stop ``` `LOCAL_ADMIN_EMAIL`、`LOCAL_ADMIN_PASSWORD`、`LOCAL_STUDENT_EMAIL` 和 `LOCAL_STUDENT_PASSWORD` 仅用于本地测试。Service-role key 仅从 CLI 状态引入到 bootstrap/test process 中；不会传递给浏览器或 public env。Bootstrap 不会在生产环境中使用。有关详细流程，请参阅 [本地 Supabase 操作指南](docs/LOCAL_SUPABASE.md)。 ## 身份验证 身份验证基于 Supabase Auth、Next.js App Router 和 `@supabase/ssr` cookie 会话。在本地环境中，只需要以下公共变量： - `NEXT_PUBLIC_SUPABASE_URL` - `NEXT_PUBLIC_SUPABASE_ANON_KEY` 登录页面位于 `/login` 路径。`/admin` 和 `/student` 路由需要会话； 未经身份验证的请求将被重定向到 `/login` 页面。严格的角色 检查通过服务器端的 profile 查询完成。如果 Student 访问 `/admin`，将被重定向到 `/student`；如果 Admin 访问 `/student`，将被重定向到 `/admin`。 如果未定义环境变量，主页和登录界面会正常打开；但实际的 登录操作将返回安全的配置错误。代码仓库的标准测试不使用真实的 Supabase 帐户、密码或 secret。 需要 Docker 的集成测试集是独立的，并且包含在可选的 `npm run test:integration` 命令中。 ## 质量检查 本地质量检查： ``` npm run format:check npm run lint npm run typecheck npm run test:coverage npm run build npm run test:e2e npm audit --audit-level=high ``` GitHub Actions 会在目标为 `main` 的 pull request、向 `main` 的推送以及手动触发时，运行相同的格式化、lint、typecheck、coverage、build 以及高严重级别的 dependency audit 质量门。Playwright Chromium 冒烟测试作为单独的 job 运行，失败时的输出将作为限时 artifact 保存。 Vitest 的覆盖率下限执行标准为：语句 `%70`、分支 `%60`、函数 `%65` 和行 `%70`。这些阈值在本地 `npm run test:coverage` 命令和 CI 中保持一致。 变更必须通过从短期分支向 `main` 发起的 pull request 提交。在 PR 模板中的范围、验证、安全、文档和可访问性检查未完全通过之前，不得进行合并。 ## 文档状态 这些文档在开发开始前定义了目标架构和产品边界。在实施过程中，如果决策发生变化，应在相关文档中进行更新；对于模糊或重要的选项，必须通过 ADR 予以最终确定。 ## ADR 候选 在初始实施阶段需要进一步明确决定的主题包括： 1. Next.js 版本及使用 App Router 的具体细节。 2. Supabase 访问层中的 Server Actions、Route Handlers 和/或独立服务层的边界。 3. block 内容如何在规范化表与 JSONB 之间进行划分。 4. 针对已发布内容的版本控制和不可变快照策略。 5. 文件上传时的防病毒/扫描提供商及隔离工作流。 6. 学生进度是通过客户端事件、服务器端操作还是基于事件的模型进行记录。

标签：DAST, Syscall, Web开发, 内容管理系统, 在线教育, 恶意软件分析, 测试用例, 特征检测, 自动化攻击, 请求拦截