跳转至

ZJUI-Learn 教师/管理员全页面操作手册（逐页说明）

本文面向老师与平台管理员，按当前项目代码中的路由逐页整理“入口、作用、可执行操作、注意事项”。

依据：

  • 路由主清单：apps/prairielearn/src/server.ts
  • 官方教师文档：
    • docs/course/index.md
    • docs/courseInstance/index.md
    • docs/assessment/overview.md
    • docs/assessment/configuration.md
    • docs/sync.md

1. 先看权限模型（避免“有页面没权限”）

教师端权限在官方文档中分两条线：

  • 课程内容权限（预览者/查看者/编辑者/所有者）
  • 学生数据权限（查看/编辑）

典型对应关系：

  • 查看与题目预览/勾选：课程内容预览者及以上
  • 编辑题目、编辑文件、同步Git：课程内容编辑器及以上
  • 查看学生个人成绩： 学生数据查看器及以上
  • 人工评分、改分、调整考试状态：学生数据编辑

若出现“页面能打开但按钮不可用”，通常是角色权限不足。

2. 页面总览（信息架构）

教师/管理员最常用页面分 6 组：

  1. 全局账号与通用页面（设置、课程申请、工作区）
  2. 课程等级管理（/pl/course/:course_id/...）
  3. 课程实例-课程管理（/pl/course_instance/:id/instructor/course_admin/...）
  4. 课程实例-实例管理（/pl/course_instance/:id/instructor/instance_admin/...）
  5. 课程题目实例-测验与管理（评估/问题详情页）
  6. 平台管理员页面（/pl/administrator/...）

3. 全局与通用页面（老师/管理员常用）

3.1 首页与个人

  • / 与 /pl
    • 作用：平台首页、课程入口与导航中心。
    • 操作：进入课程、查看可访问课程、跳转老师/学生视图。
  • /pl/settings
    • 作用：个人设置页（账号相关、令牌等）。
    • 操作：管理个人偏好与访问令牌（若启用）。
  • /pl/request_course
    • 作用：申请开通课程空间。
    • 操作：提交课程申请（由管理员审批）。
  • /pl/enroll
    • 作用：学生/用户加入课程入口（自助加入流程相关）。

3.2 工作区与辅助

  • /pl/workspace/:workspace_id
    • 作用：工作区页面（编程/交互环境）。
    • 操作：启动与使用工作区。
  • /pl/workspace/:workspace_id/logs
    • 作用：查看工作区日志。
    • 操作：排查运行错误、环境启动失败。
  • 开发型号：/pl/loadFromDisk
    • 作用：强制从磁盘重新加载课程内容。
    • 典型场景：本地修改了 infoCourse.json / infoCourseInstance.json / infoAssessment.json / question info.json 后未生效。

4. 课程级别页面（Course 维度）

URL 出口：/pl/course/:course_id

4.1 课程主入口与上下文

  • /pl/course/:course_id
    • 行为：重定向到.../course_admin。
    • 用途：课程管理总入口。
  • /pl/course/:course_id/effectiveUser
    • 作用：有效用户/代理身份切换相关页面。
    • 场景：排查“某角色看到什么”的访问问题。

4.2 课程管理（课程管理）页面

  • /pl/course/:course_id/course_admin
    • 作用：课程管理主框架页。
  • .../course_admin/getting_started
    • 作用：课程初始化任务与待办检查。
    • 操作：按任务清单完成首轮配置。
  • .../course_admin/settings
    • 作用：课程等级配置（对应infoCourse.json 维度）。
    • 操作：名称、时区、课程元数据检查。
  • .../course_admin/sharing
    • 作用：共享配置与共享集合（共享集）管理。
    • 操作：维护题目共享策略。
  • .../course_admin/staff
    • 作用：课程成员与权限配置。
    • 操作：分配内容权限与学生数据权限。
  • .../course_admin/sets
    • 作用：评估集配置。
    • 操作：维护HW/Exam/Quiz等集合展示逻辑。
  • .../course_admin/modules
    • 作用：评估模块配置。
    • 操作：按章节/模块组织测验。
  • .../course_admin/topics
    • 作用：题目主题管理。
    • 操作：规范题库主题标签。
  • .../course_admin/tags
    • 作用：题目标签管理。
    • 操作：维护检索标签体系。
  • .../course_admin/instances
    • 作用：课程实例列表与管理入口。
    • 操作：创建新学期实例、进入实例管理。
  • .../course_admin/questions
    • 作用：题库总览。
    • 操作：筛选、搜索、批量查看题目状态。
  • .../course_admin/questions/create
    • 作用：新建题目。
    • 操作：空白创建、模板创建、QID规范化。
  • .../course_admin/ai_generate_question
    • 作用：AI 题目生成入口（当前项目为上传起点）。
    • 操作：上传题目素材文件，进入后续 AI 流程。
  • /pl/course/:course_id/ai_generate_question_drafts
    • 作用：保留ZJUI-Learn企业版原有的AI题目草流程稿。
  • .../course_admin/issues
    • 作用：题目问题反馈汇总（学生问题）。
    • 操作：定位题目缺陷、跟进关闭。
  • .../course_admin/syncs
    • 作用：Git同步页面。
    • 操作：从远程仓库拉取、查看同步历史；与docs/sync.md建议流程配合。
  • .../course_admin/file_view
    • 作用：课程文件浏览器。
    • 操作：浏览仓库目录与文件内容。
  • .../course_admin/file_edit
    • 作用：网页内文件编辑器。
    • 操作：在线编辑并提交（需编辑/所有者）。
  • .../course_admin/file_download
    • 作用：文件下载入口。
    • 操作：导出课程相关文件。

4.3 题目详情页（课程维度）

  • /pl/course/:course_id/question/:question_id/settings
    • 作用：题目设置页。
    • 操作：题目元信息、测试、共享设置。
  • .../question/:question_id/preview
    • 作用：题目预览页。
    • 操作：查看渲染效果、试答、切换变体。
  • .../question/:question_id/statistics
    • 作用：题目统计。
    • 操作：查看正确率、使用分布，辅助题目改进。
  • .../question/:question_id/file_view
  • .../question/:question_id/file_edit
  • .../question/:question_id/file_download
    • 作用：题目文件浏览/编辑/下载。
    • 典型操作：修改info.json、question.html、server.py。
  • .../question/:question_id/clientFilesQuestion
  • .../question/:question_id/generatedFilesQuestion
  • .../question/:question_id/submission/:submission_id/file
    • 作用：题目资源、生成文件、提交文件查看。

4.4 课程级辅助页

  • /pl/course/:course_id/file_transfer
    • 作用：文件迁移/传输辅助。
  • /pl/course/:course_id/grading_job
    • 作用：查看评分任务详情。
  • /pl/course/:course_id/jobSequence
    • 作用：查看后台作业链路（调试/运维向）。
  • /pl/course/:course_id/edit_error
    • 作用：编辑错误展示页。
  • /pl/course/:course_id/copy_public_question
    • 作用：从公开题库拷贝题目到本课程。
  • /pl/course/:course_id/copy_public_course_instance
    • 作用：从公开课程实例复制内容。

5.实例课程教师页面（课程实例/讲师）

URL 出口：/pl/course_instance/:course_instance_id/instructor

默认跳转：

  • .../instructor -> .../instance_admin/assessments

6. Instance Admin（实例管理）逐页说明

6.1 核心实例管理

  • .../instance_admin/settings
    • 作用：实例基础配置（对应infoCourseInstance.json 维度）。
    • 操作：实例名称、学生入口、自助加入策略等。
  • .../instance_admin/publishing
    • 作用：发布时间窗与发布扩展。
    • 操作：设置startDate/endDate，为特定学生延长延长时间。
  • .../instance_admin/assessments
    • 作用：实例内测验列表总览。
    • 操作：进入单个评估管理页面。
  • .../instance_admin/students
    • 作用：学生名单页。
    • 操作：邀请学生、批量操作、同步学生信息。
  • .../instance_admin/students/labels
    • 作用：学生标签管理。
    • 操作：创建/编辑标签、按UID分配标签。
  • .../instance_admin/enrollment
    • 作用：学生详情与单人管理入口。
    • 操作：查看该生记录、执行封禁/解封等操作。
  • .../instance_admin/gradebook
    • 作用：成绩册。
    • 操作：查看分数、导出成绩、定位异常分布。
  • .../instance_admin/lti
    • 作用：LTI配置页（LTI1.1/链接管理相关）。
    • 操作：配置LMS活动参数、链接评估。

6.2 实例文件页

  • .../instance_admin/file_view
  • .../instance_admin/file_edit
  • .../instance_admin/file_download
    • 作用：实例层文件浏览/在线编辑/下载。
    • 典型文件：courseInstances/<term>/infoCourseInstance.json 与足球文件。

6.3 企业版可选

  • .../instance_admin/ai_grading（企业）
  • .../instance_admin/billing（企业）
  • .../instance_admin/lti13_instance（企业）

7. Course Admin（实例内课程管理）逐页说明

URL 出口：/pl/course_instance/:id/instructor/course_admin

该组页面功能与课程级别 course_admin 基本对齐，区别是上下文绑定在某个课程实例的讲师入口下。

  • .../settings
  • .../sharing
  • .../staff
  • .../sets
  • .../modules
  • .../instances
  • .../getting_started
  • .../issues
  • .../questions
  • .../questions/create
  • .../ai_generate_question
  • .../syncs
  • .../topics
  • .../tags
  • .../file_view
  • .../file_edit
  • .../file_download

企业版原有的.../instructor/ai_generate_question_drafts路由保持不变，与上传生成入口并存。

8.考核管理页面（教师最核心）

URL 出口：/pl/course_instance/:id/instructor/assessment/:assessment_id

  • .../settings
    • 作用：测验基础设置与学生直达链接等。
    • 操作：设置标题、类型（作业/考试）、实例策略。
  • .../questions
    • 作用：题目编排页。
    • 操作题目：管理区域、顺序、分值规则与抽取题逻辑。
  • .../groups
    • 作用：分组作业管理。
    • 操作：建组、导入CSV分组、随机分组、角色配置。
  • .../access
    • 作用：访问控制（开放时间、密码、信用比例等）。
    • 操作：配置访问规则。
  • .../assessment_statistics
    • 作用：测验整体统计。
    • 操作：分析整体表现、分布、难度。
  • .../question_statistics
    • 作用：题目维度统计。
    • 操作：定位异常题、低区分度题。
  • .../downloads
    • 作用：导出页面。
    • 操作：下载成绩、分组、日志相关数据。
  • .../uploads
    • 作用：上传页面（如分组导入、成绩/名单辅助上传等视配置而定）。
  • .../regrading
    • 作用：重评分页面。
    • 操作：触发重评分任务，修复规则更新后的历史评分。
  • .../instances
    • 作用：评估实例列表。
    • 操作：查看学生/小组实例状态，定位异常实例。
  • .../manual_grading
    • 作用：人工评分入口。
    • 子页面：
      • .../manual_grading/assessment_question/:assessment_question_id
      • .../manual_grading/instance_question/:instance_question_id
    • 操作：逐题批改、给反馈、修正分数。
  • .../assessment_instance/:assessment_instance_id
    • 作用：单个评测实例详情。
    • 操作：查看事件时间线、提交记录、评分细节。
  • .../file_view / .../file_edit / .../file_download
    • 作用：评估目录文件管理。
    • 典型文件：infoAssessment.json、附加资源文件。

9.问题管理页（教师题目工作台）

URL 出口：/pl/course_instance/:id/instructor/question/:question_id

  • .../settings
    • 作用：题目设置页（题目元数据、测试、共享配置）。
  • .../preview
    • 作用：题目预览页（含试答与渲染验证）。
  • .../statistics
    • 作用：题目统计页。
  • .../file_view / .../file_edit / .../file_download
    • 作用：题目文件操作页。
    • 常改文件：info.json、question.html、server.py。
  • .../clientFilesQuestion / .../generatedFilesQuestion
    • 作用：题目客户端资源与生成资源查看。
  • .../submission/:submission_id/file
    • 作用：提交文件查看（用于调试评分与学生提交排查）。
  • .../externalImageCapture/variant/:variant_id
    • 作用：外部图像采集相关入口（图像型题目/捕获流程）。

10. 讲师辅助与调试页面

  • .../instructor/grading_job
    • 评分任务详情查看。
  • .../instructor/jobSequence
    • 后台作业链路调试（开发/运维常用）。
  • .../instructor/edit_error
    • 在线编辑错误展示页。
  • .../instructor/effectiveUser
    • 有效用户切换与权限排查页面。

11. 管理员页面（平台级）

URL 出口：/pl/administrator

  • /pl/administrator/admins
    • 作用：管理员账号管理。
    • 操作：查看/增删管理员资格（按系统策略）。
  • /pl/administrator/settings
    • 作用：全站级设置。
    • 操作：平台配置查看与调整（依页面能力）。
  • /pl/administrator/institutions
    • 作用：机构管理。
    • 操作：新增机构、维护机构信息。
  • /pl/administrator/courses
    • 作用：课程总览（全站）。
    • 操作：筛选、查看课程状态与归属。
  • /pl/administrator/courseRequests
    • 作用：课程申请审批。
    • 操作：处理教师创建课程请求。
  • /pl/administrator/workspaces
    • 作用：工作区全局管理。
    • 操作：监控工作区状态，排查异常。
  • /pl/administrator/features
    • 作用：特性开关管理。
    • 操作：启停功能、灰度验证。
  • /pl/administrator/queries
    • 作用：查询模板列表页。
    • 操作：选择平台运维查询。
  • /pl/administrator/query
    • 作用：单查询执行页。
    • 操作：执行查询、查看结果（注意权限与风险）。
  • /pl/administrator/jobSequence
    • 作用：全站任务链路观测页。
  • /pl/administrator/batchedMigrations
    • 作用：批量迁移任务管理页。
    • 操作：观察迁移状态、排查迁移异常。

企业版可选：

  • /pl/administrator/institution/:institution_id（企业）
  • /pl/institution/:institution_id/admin（企业）

12. 老师高频操作路径（实操导航）

12.1 新学期开课（最常用）

  1. 进入 course_admin/instances 创建新课程实例
  2. 进入 instance_admin/settings 检查实例参数
  3. 进入 instance_admin/publishing 设置开放区间
  4. 进入 instance_admin/assessments 核对测试
  5. 进入 instance_admin/students 邀请/同步学生

12.2 建题与发布

  1. course_admin/questions 浏览题库
  2. 题目 course_admin/questions/create 新建
  3. question/:id/file_edit 编辑三文件
  4. question/:id/preview 验证显示与评分
  5. assessment/:id/questions 挂题并设定分值
  6. assessment/:id/access 配开放规则

12.3 期中/期末运维

  1. assessment/:id/instances 看考试详细资料
  2. assessment/:id/manual_grading 手动批改
  3. assessment/:id/regrading 统一重评分
  4. instance_admin/gradebook 取得成绩

13. 页面与配置文件对应关系（便于定位）

  • 课程设置相关页面（settings/sets/modules/topics/tags/staff） -> 主要应答 infoCourse.json
  • 实例设置与发布页面（instance_admin/settings/publishing） -> 主要应答 infoCourseInstance.json
  • 测验设置页（评估/设置/问题/访问/组） -> 主要应答 infoAssessment.json
  • 问题设置与编辑页面（question/settings/preview/file_edit） -> 主要应答 questions/<QID>/{info.json,question.html,server.py}

本地开发时，修改JSON元信息后通常需要使用 Load from disk 使变更立即生效。

14. 备注：关于“每一个页面”的边界

本手册涵盖了 server.ts 中教师与管理员相关的主要页面路由（含重定向入口、文件页、详情页、管理页）。

不作为“业务页面”单独展开的内容包括：

  • trpc / API 接口路由
  • 静态资源路由（elements、cacheableElements 等）
  • 纯中间件与错误处理路径

如你需要，我可以下一步继续生成一版“带截图位的培训版”（按老师日常流程组织，每页加“你会看到什么按钮、应该点哪里”），适合直接发给教师团队培训使用。

培训落地版本已补充在：docs/TEACHER_TRAINING_PLAYBOOK_ZH.md。