Beta 阶段展示文档
项目亮点总结
成员与分工简介
OSome 课程开发团队根据个人技术栈进行团队分工，并且在团队成员出现特殊状况的情况下及时调整分工，保证任务顺利完成。
典型用户场景
-
场景 1：
-
姓名：夜捉人
-
身份：OS 课程助教
-
时间：课上考试期间
-
需求：发布考试中实时通知
-
本平台满足需求的场景：
在上机考试过程中，夜捉人助教发现有一道题目需要进一步解释。他登录管理端，编辑了一则通知，对题目的内容进行详细说明，并在检查无误后发布。很快，所有正在参加考试的同学都在页面的右上角看到了这一则通知。
-
-
场景 2：
-
姓名：小红
-
身份：OS 课程学生
-
时间：完成课下实验时
-
需求：讨论区发帖
-
本平台满足需求的场景：
小红完成了本次课下任务，对任务中涉及到的知识点有非常深的感触和理解。她打开讨论区，采用 Markdown 发布了一篇关于这次实验的心得体会和可能的注意事项。很快，她的帖子收到了其他几位同学的点赞和回复，还收到了助教的认证。
-
-
场景 3：
-
姓名：小蓝
-
身份：OS 课程学生
-
时间：完成课下实验时
-
需求：查看讨论区
-
本平台满足需求的场景：
小蓝在完成课下任务时遇到了困难。他打开讨论区，搜索实验中遇到问题的关键词，很快就找到了一篇获得助教认证的帖子。他按照帖子中的内容进行了修改，很快就通过了课下测试。他给主题帖点了赞，并订阅该帖子，以便随时获得帖子和更新。
-
-
场景 4：
-
姓名：吴老师
-
身份：OS 课程教师
-
时间：新助教上任时
-
需求：配置助教权限
-
本平台满足需求的场景：
吴老师为新招的助教创建了账号。每一位助教的只能和权限不尽相同：有的助教负责更新教程部分，有的助教负责管理题目，有的管理考试等。老师直接采用已经按照职能分配好权限的模板为新助教的账号授权，很快就完成了助教权限分配的工作。
-
-
场景 5：
-
姓名：吴老师
-
身份：OS 课程教师
-
时间：课上测试后
-
需求：查看学生成绩
-
本平台满足需求的场景：
课上考试结束了。吴老师很关心班上的学生的考试情况，他打开管理端，调出本次考试的成绩。统计图很直观地展示了学生的成绩分布。他为了进一步了解具体的细节统计信息，输入了自定义的要求进行查询。系统解析了查询语法树后精准反馈了查询结果。
-
-
场景 6：
-
姓名：辰囸添
-
身份：OS 课程助教
-
时间：课上测试后
-
需求：考试其他需求
-
本平台满足需求的场景：
新北地下机房在考试中发生了断网的情况，助教为了保证考试的公平，为这个机房内所有的学生延长了相应的考试时间。一部分同学提前交卷离场了，但是原先的测试脚本存在 bug，辰囸添对这部分同学的提交采用新的脚本进行了批量重测。
-
杀手级功能
- 我们的系统提供了非常美观的统计学生学习情况的界面。可以分别查询不同老师的同学们的成绩分布情况（柱状图），每个同学各个 Lab 的完成情况（表格），每个 Lab 的完成时间等信息（折线图），方便教师对于本班同学学习情况的了解。
- 同时我们还支持了评测信息的结构化输出，评测结果会以 JSON 的方式进行反馈，前端按照这一格式进行渲染，可以有效帮助同学和老师了解反馈信息。
- 支持评测记录导出功能，方便课程归档
项目发布情况
以 yzr 为核心的 OSome 课程平台开发团队，始终保持与操作系统课程老师紧密沟通。
6 月 5 日，我们邀请操作系统课程的沃天宇老师，进行长达三小时的视频会议。我们向沃老师提出了在 Osome 平台上进行定于 6 月 9 日的最后一次考试。由于时间紧急，测试不充分，且考试对稳定性要求较高，我们最终未能完成这一次发布计划。
在 yzr 的领导下，组员们集思广益，决定通过 Osome 平台向全体同学发布历次上机的成绩，便于学生统一阅览。
软件工程质量
- 优秀的代码质量
- 完善的开发、部署指导
- 覆盖全开发过程的 CI/CD 配置
- 完整的单元测试机制、日志机制
- 自动化的前端代码风格检查
- 使用 tag 来管理 issue
项目管理情况
成员简介、个人博客地址
| 姓名/昵称 | 头像 | 自我介绍 | 博客地址 |
|---|---|---|---|
| gyp |  |
我和 yzr 平均一下等于二分之一个 yzr 呢 | 毕业隐私保护 |
| cjy |  |
Good Game Well Play! | 毕业隐私保护 |
| yzr |  |
好好生活，注意休息 | 毕业隐私保护 |
| fxj |  |
劳逸结合，过好 UTC+08:00 的生活 | 毕业隐私保护 |
| ch |  |
神犇奆佬带带我 orzzzzz | 毕业隐私保护 |
| ptw |  |
再也不想熬夜干活了 | 毕业隐私保护 |
| wwq |  |
楼上带带 qwq | 毕业隐私保护 |
项目管理概述
- 范围管理：由大家共同协商决定需求是否纳入实现范围。
- 时间管理：
- 以模块化的整体规划为顶层，根据功能模块的技术难度与依赖关系设计。
- 将任务划分为子任务作为中层，见 Beta 阶段任务划分文档。
- 在各子项目中创建 Issue 作为底层，实现项目进度的动态化管理，并使用 Tag 来管理 Issue。
- 使用自动化工具绘制燃尽图，聚合底层数据，作为项目进度管理抓手。
- 成本管理：
- 在部署阶段对若干服务进行资源限额与专属资源配置，避免整体资源使用超出现有额度。
- 质量管理：
- 实现以 Merge Request 功能为核心的 Code Review 机制，通过 Review 后方贡献方可生效。
分工协作情况
- 在 Alpha 阶段的基础上，根据技术栈等因素综合考量，将开发人员分组分工，实现效益最大化，技术积累成本最小化：
- gyp 负责后端 API 实现与甲方对接。
- cjy 负责管理前端页面设计、管理前端页面实现与前端测试。
- yzr 负责评测机制实现、后端测试、文档记录、需求整合分析、项目管理。
- fxj 负责后端 API 实现与后端测试。
- ch 负责前端基础机制实现、学生前端页面设计、学生前端页面实现与安全测试。
- ptw 负责教程功能实现、服务部署、系统架构设计与维护、技术支持。
- wwq 负责前端统计机制实现、管理前端页面设计、管理前端页面实现与前端测试。
沟通对接模式
- 基于功能对接的沟通：
- 前后端同学直接对接
- 应用开发同学与应用部署同学直接对接
- 基于需求对接的沟通：
- 安排 gyp、yzr 负责与需求方对接
- fxj 负责汇总与分析需求
- 基于设计迭代的沟通：
- 微信群直接沟通
- Scrum Meeting 直接沟通
时间/质量/资源的平衡
在时间极为有限的情况下，我们以需求为导向进行取舍，由于学生报告目前是通过课程中心或 spoc 平台提交，整合进我们的系统对学生还是教师都不能使这项工作变得更加轻松，我们在和操作系统老师的讨论之后共同决定取消此功能，将更多的精力用于保证 Beta 阶段原定目标：支持老师、助教和同学们在 OSome 平台完成一次考试，并优先测试了鉴权与登录、用户管理、课程管理、评测管理、通知发布、讨论区等功能，以保证其质量。
此外，OSome 团队成员彼此熟悉、配合默契且对项目抱有认同感，认为这是一件有意义和价值的事，甘愿将团队任务置于更高的优先级，为此不惜牺牲其它课程的课下或课上时间，在此也需要感谢 OSome 团队成员在其它课程中的队友的支持理解与感同身受。
实际进展（燃尽图）
燃尽图通过动态获取剩余开启 Issue 的数量并绘制图像，直观地展示了项目进度，成为我们管理项目进度的一个有力抓手。
角色、具体贡献、贡献分
贡献分配表：
| 姓名 | 总计 | 占比 | 初步得分 | 下取整 | 未分配贡献 | 最终得分 |
|---|---|---|---|---|---|---|
| gyp | 187 | 0.141666667 | 49.58333333 | 49 | 2.2 | 49 |
| cjy | 184 | 0.139393939 | 48.78787879 | 48 | 2.971428571 | 49 |
| yzr | 203 | 0.153787879 | 53.82575758 | 53 | 3.114285714 | 54 |
| fxj | 172 | 0.13030303 | 45.60606061 | 45 | 2.285714286 | 45 |
| ch | 195 | 0.147727273 | 51.70454545 | 51 | 2.657142857 | 52 |
| ptw | 184 | 0.139393939 | 48.78787879 | 48 | 2.971428571 | 49 |
| 王雯清 | 195 | 0.147727273 | 51.70454545 | 51 | 2.657142857 | 52 |
用户场景
项目预期
项目预期
-
项目开发前的目标：
在 Beta 阶段开发前，我们拟定进一步完善最初的项目目标，即在 Alpha 版本的基础之上，为学生提供全新的贴吧式讨论区，为助教提供完整的考试控制接口，为教师提供权限管理、成绩可视化查看、记录存档等功能。
-
预期的典型用户场景
-
场景 1：发布考试中实时通知
在上机考试过程中，夜捉人助教发现有一道题目需要进一步解释。他登录管理端，编辑了一则通知，对题目的内容进行详细说明，并在检查无误后发布。很快，所有正在参加考试的同学都在页面的右上角看到了这一则通知。
-
场景 2：讨论区发帖
小红完成了本次课下任务，对任务中涉及到的知识点有非常深的感触和理解。她打开讨论区，采用 Markdown 发布了一篇关于这次实验的心得体会和可能的注意事项。很快，她的帖子收到了其他几位同学的点赞和回复，还收到了助教的认证。
-
场景 3：查看讨论区
小蓝在完成课下任务时遇到了困难。他打开讨论区，搜索实验中遇到问题的关键词，很快就找到了一篇获得助教认证的帖子。他按照帖子中的内容进行了修改，很快就通过了课下测试。他给主题帖点了赞，并订阅该帖子，以便随时获得帖子和更新。
-
场景 4：配置助教权限
吴老师为新招的助教创建了账号。每一位助教的只能和权限不尽相同：有的助教负责更新教程部分，有的助教负责管理题目，有的管理考试等。老师直接采用已经按照职能分配好权限的模板为新助教的账号授权，很快就完成了助教权限分配的工作。
-
场景 5：查看学生成绩
课上考试结束了。吴老师很关心班上的学生的考试情况，他打开管理端，调出本次考试的成绩。统计图很直观地展示了学生的成绩分布。他为了进一步了解具体的细节统计信息，输入了自定义的要求进行查询。系统解析了查询语法树后精准反馈了查询结果。
-
场景 6：考试其他需求
新北地下机房在考试中发生了断网的情况，助教为了保证考试的公平，为这个机房内所有的学生延长了相应的考试时间。一部分同学提前交卷离场了，但是原先的测试脚本存在 bug，辰囸添对这部分同学的提交采用新的脚本进行了批量重测。
-
-
预期的功能描述
| 用户端 | 功能 | 验收标准 |
| 学生端 | 教程 |
- 学生可在前端网页查看对应 Lab 的教程 - 教程的形式包括文本、图片 - 教程在上机测试过程中可关闭 |
| 考试 |
- 支持 Alpha 阶段学生端所有的评测功能 - 考试之前，可登陆学生端查看考试座位 - 完成答题后，可在考试界面中签退 |
|
| 讨论区 |
- 每个学生都可发帖，支持 Markdown 和图片插入 - 每个主题帖都可添加标签 - 学生可对主题帖进行回复，也可对他人回帖进行回复 - 学生可对优秀的主题帖和回帖进行点赞 - 自己的帖子收到点赞和回复时，会有消息通知 |
|
| 教师端 | 教学信息 |
- 可以查看每个教学班的学习情况，包括班级平均分、学习困难学生 - 可查看具体每个同学的课下实验通过情况 |
| 考试信息 |
- 配置考试相关信息，如题目仓库、分支地址等 - 在考试现场对每位到场学生签到 - 以图表形式查看每次上机测试后学生成绩分布等统计信息 |
|
| 通知管理 |
- 可针对任务发布 Markdown 格式的消息提醒 - 可让学生前端直接弹窗提醒 | |
| 评测结点管理 |
- 申请评测机令牌 - 查看评测机心跳 |
项目功能（BETA）
项目发布的功能：
整个课程平台分为学生端和管理端两个平台，在这里介绍 Beta 版本的新增的功能。
在学生端：
在提交评测界面将学生情况界面和任务列表界面合并到一块，前者使用方块的形式展示个人完成情况，后者则详细展示了任务列表的信息。
讨论区功能，学生可以在讨论区发布帖子、点赞和取消点赞、订阅帖子，教师和助教可以置顶需要的帖子。
教程模块，用于展示 Markdown 格式的教程，在教程中可以插入选择题、填空题。
个人信息界面中增加了上传图片修改个人头像的方法。
通知提醒模块，可以提醒用户还未读取的通知。
在教师端：
导航栏增加了全局管理，将用户管理、课程管理、题目管理、评测节点和令牌管理这五个与当前课程无关的配置合并到了一块。
查看评测节点功能，教师和助教可以实时查看评测机的心跳情况，及时发现出现问题的评测机。
令牌管理界面，教师和助教可以在前端申请评测机令牌，并用于评测机上。
通知管理功能，对于发送的通知和通知内容进行管理。
统计分析功能，教师和助教可以非常直观和美观的查看考试的通过情况，各个老师班级的通过情况，学生的通过情况和提交统计信息。
考试配置模块，可以对参加考试的同学进行配置，可以对个人和筛选列表进行考试延时，查看考试的异常 IP 地址。
评测管理部分增加重评，可以重评测试记录或一个测试记录列表，增加了评测记录导出功能方便课程去归档。
平台发布：
-
正式版
-
内测版
-
支持的浏览器版本
- Chrome 98+
- Edge 99+
- Firefox 98+
- Opera 82+
- Safari 15.2+
所有账号由课程管理员（老师或助教）创建，不允许自行注册。
联系课程组可获取正式账号或开发账号，用于登录正式版本或内测版本；联系开发团队只能获取开发账号，用于登录内测版本。
申请账号后即可登录并按照上面展示的方法使用系统。
未满足的场景
经过再三权衡，没有完成学生每个 Lab 的报告提交。学生报告目前是通过课程中心或 spoc 平台提交。考虑到整合进我们的系统对学生还是教师都不能使这项工作变得更加轻松，我们在和操作系统老师的讨论之后共同决定，不需要完成这项工作。
用户日活
推广努力
早在 Beta 阶段开始之初，yzr 就亲自部署、亲自安排，与操作系统老师沟通，计划在 Beta 版本发布时，在平台上组织进行一次考试。
由于以 yzr 为核心的 OSome 开发团队多半为操作系统课程助教，与操作系统课程组有着紧密联系。在与沃天宇老师经过长达三个小时的沟通过后，我们认识到面向学生的考试对稳定性要求较高。且由于考试时间紧迫（最后一次考试是 6 月 9 日），我们的测试十分不充分。最终放弃了原定的考试计划。
最终，在 yzr 的带领下，我们决定通过平台向学生发布实验课程成绩。由于和操作系统课程组的深入联系，我们从老师那里拿到了过往的历次学生上机成绩，并将其导入系统。学生可以通过我们的平台统览全部的成绩。
日活分析
- 截至 6 月 18 日，平台中已经有 1257 次有效提交，且没有发生问题
- 应 OS 老师的要求，在没有官方推广的情况下，我们在 Beta 发布阶段达到了日活过百，最高的一个小时达到了 96 人的活跃度。
用户功能反馈
- 学生
- Alpha 版本希望添加头像功能，该功能在 Beta 版本已实现
- 学生在 Beta 部分能体验到的功能有限（应操作系统的老师要求，结合疫情期间的影响，本系统在 Beta 阶段没有额外开放考试和实验）
- 教师
- 在实际投入使用前还需要大量压力测试
- 新系统与旧系统依然存在部分兼容问题（如评测格式不同等）
用户 bug 反馈
- 暂未收到任何 bug 反馈。
特色功能
杀手功能
- 我们的系统提供了非常美观的统计学生学习情况的界面。可以分别查询不同老师的同学们的成绩分布情况（柱状图），每个同学各个 Lab 的完成情况（表格），每个 Lab 的完成时间等信息（折线图），方便教师对于本班同学学习情况的了解。
- 同时我们还支持了评测信息的结构化输出，评测结果会以 JSON 的方式进行反馈，前端按照这一格式进行渲染，可以有效帮助同学和老师了解反馈信息。
- 支持评测记录导出功能，方便课程归档
竞品分析
在原有的操作系统平台上，教师端查询同学的完成情况需要进入另一个网站进行查询，采用表格的形式渲染数据，数据内容和表现形式比较单一。我们吸取了原有平台的问题，将此功能合并到我们的新平台中，提供了柱状图、表格图和折线图等多种表现方式，数据的内容也更加丰富，方便老师去查看学生完成情况。
对于原有操作系统实验课的评测结果，结果内容保存在对应 log 分支下的时间戳文件，输出的格式也包含各种各样的内容，不方面助教和老师进行查错。在我们的新平台中，评测结果将按照特定的格式反馈给后端，由后端来根据身份信息选择向前端反馈 JSON 格式的反馈信息，前端根据这一格式进行渲染，这样更加美观的查看评测结果。
在原有操作系统实验课中需要助教手动进行课程归档，我们在新平台中支持了这一功能。只需点击前端按钮就可以反馈给助教和老师归档的命令，按照这一命令在 Shell 中执行即可完成归档。
自我评价
我们的课程项目是应用新技术、融合软件工程思想的典范，将 OS 课程的传统需求与开源社区的优质框架接轨，找准了新需求的出发点，明确了新场景的切入点，抓好了新形势下的落脚点。立足当前，着眼长远，抓住机遇，应对挑战。过程中有重点、分步骤，融入全过程，贯穿各方面，切实抓稳，扎实推进，明确职责，强化规范。必将激发激发同学们的巨大学习热情，凝聚课程组的无穷工作力量，催生 OS 教学的丰硕成果，展现北航计算机学院的全新魅力。另外，我们的课程项目扎根 S.T.A.R. 教辅团队，促进计算机学院教、学、研相结合，建设一流助教团队、打造一流核心课程、产出一流工程项目，展现北航学生敢为人先、志向远大的可贵品格。
用户评价
通过问卷的形式收集学生评价，截至 6 月 18 日，已收到 30 份问卷，其中 1 人评价为一般，2 人评价为满意，27 人评价为很满意。
- 学生
- “平台比较精美”
- “界面清爽”
- “太厉害了啊”
- “这个 OSOME 确实棒”
- “前端非常美观”
- 助教
- 希望开发评测时，有“上传标程”、“上传数据”等功能，将标程与数据解耦
- 教师
- 待功能完善后可以考虑推广给其它高校
- 统计功能高级
软件工程质量
文档与代码规范
- 每个仓库具有 readme，作为完整的开发指南，包含以下几方面的信息：
- 本地开发、构建说明
- 部署说明
- 配置说明
- 依赖说明
- 使用以下自动化工具检查代码质量，不通过时 CI/CD 失败：
- ESLint
- Prettier
- API 文档由 swagger 自动生成，省去人工维护的成本。
可传承性
- 代码质量
- 项目代码结构性好
- 层次清晰
- 标识符表意清楚，无需注释
- 重要概念有 OSome 平台概念介绍，避免混淆
- 指导质量
- 项目均有 readme.md，指导本地开发、测试流程。
- 服务均有 docker-compose.yml 留档，可以使用同样的命令启动所有服务：
docker compose up -d。 - 重要机制已形成固化记录（子站反代、Docker Registry 等），帮助使用。
单元测试
在期末压力下，后端仅对新增的 API 中较重要的一部分进行了单元测试，最终后端代码覆盖率达到 54.5%。涉及单元测试如下述所示：
var stages = [][]func(*testing.T){
{rootLogin, staff1Login, staff2Login, studentLogin, illegalLogin},
{tokenExpirationAfterLogout, tokenExpirationAfterResetPassword},
{rootCreateAccount, staffCreateAccount, illegalCreateAccount},
{rootUpdateAccount, staffUpdateAccount, illegalUpdateAccount},
{rootResetAccountPassword, staffResetAccountPassword, illegalResetAccountPassword, illegalSetPermission},
{rootQueryAllAccounts, staffQueryAllAccounts, illegalQueryAllAccounts},
{getAllTeachers},
{rootGetAccountPermissions, staffGetAccountPermissions, illegalGetAccountPermissions},
{rootGetAccountCourses, staffGetAccountCourses, illegalGetAccountCourses},
{getAllAnnouncements},
{rootCreateAnnouncement, staffCreateAnnouncement, illegalCreateAnnouncement},
{rootUpdateAnnouncement, staffUpdateAnnouncement, illegalUpdateAnnouncement},
{rootDeleteAnnouncement, staffDeleteAnnouncement, illegalDeleteAnnouncement},
{rootGetAllCourses, staffGetAllCourses, illegalGetAllCourses},
{rootCreateCourse, staffCreateCourse, illegalCreateCourse},
{rootUpdateCourse, staffUpdateCourse, illegalUpdateCourse},
{rootQueryAllJudgeResults, staffQueryAllJudgeResults, illegalQueryAllJudgeResults},
{selfJudgeResult},
{rootGetJudgeResultDetail, staffGetJudgeResultDetail, illegalGetJudgeResultDetail},
{rootGetAllLabs, staffGetAllLabs, illegalGetAllLabs},
{rootCreateLab, staffCreateLab, illegalCreateLab},
{rootUpdateLab, staffUpdateLab, illegalUpdateLab},
{rootDeleteLab, staffDeleteLab, illegalDeleteLab},
{rootChangeLabsOrder, staffChangeLabsOrder, illegalChangeLabsOrder},
{discussionTest},
{notificationTest},
{rootCreateProblem, staffCreateProblem, illegalCreateProblem},
{rootUpdateProblem, staffUpdateProblem, illegalUpdateProblem},
}
共有 76 个测试用例，测试用例的代码行达到 2267 行。
DevOps
CI/CD 是敏捷开发的关键。我们为学生前端、教师前端、后端、评测端、评测环境都配置了 Gitlab CI/CD，从而自动进行回归测试、构建、部署到服务器，极大提高了团队开发效率——除了运维同学外，自动构建、部署的过程对于开发者来说是近乎透明的，开发者只需要知道有一个机制使得开发者每一次 push/merge 都能在服务器上看到效果，而不关心这个机制的具体实现。
Docker 容器技术也是敏捷开发与系统运维的关键。容器技术在我们的开发过程中起到了关键作用：
- 我们可以在一个机器上同时运行多个服务且互不冲突
- 我们利用 Docker 镜像来包装、发布分布式评测机，只需在 V-TEST 上运行 docker-compose 即可自动拉取评测机镜像，扩充评测结点。
经验教训
- 开发时要及时与老师沟通，找准需求
- 要注意保持整体设计风格的统一性
