用户端流程优化设计（v2 统一入口版）¶
针对账号版 v1.1 的流程级优化：学生端统一入口、移除注册/认领、解析发布策略分两种场景、 管理端全流程可控。本文档先定义“页面清单 + 功能与交互设计”，再按批次实现（见文末）。
0. 需求假设（歧义声明）¶
- “实时答题时随机生成解析”：实时答题由主持人现场控节奏，不存在预设发布时机。
本设计落地为：主持人可随时 ①仅公布答案 或 ②公布答案并附解析（解析随公布即时到达学生端）；
另有全局开关“自动公布解析”（公布答案时默认附带）。实时题可录入解析（旧
questions表加analysis），无解析的题只公布答案。 若你的“随机生成”指“系统每轮从解析池随机抽一条展示”，请指正，我们再调整。 - “多套试卷随机作答”：发起一场测验可带 1..n 套试卷，每生只答一套：
固定一套（管理员指定）/随机分配（系统按账号稳定分配一套，学生无感）/学生自选（学生端出现选卷界面）。 多套卷之间题目不允许重复。
1. 设计原则¶
- 学生端只有一个答题入口（工作台）：登录后系统自动呈现“当前由管理员安排的活动”，学生不选择玩法、不选择测验/实时； 仅当活动为“多卷学生自选”时才出现选择层。
- 学生“登录即用”：账号全部由管理员导入/创建，无注册、无认领；首次登录进入“个人信息确认”页，核对/更正姓名与邮箱后进入工作台（此后不再打扰）。
- 解析可见性完全由后端策略控制，前端只做展示。
- 管理员对每个活动的生命周期、试卷构成、解析时机、达标线、时长全部可在后台设置与变更。
2. 数据模型变更（相对 v1.1）¶
-- users
ensure_col(profile_confirmed_at REAL); -- 个人信息确认时间（NULL=未确认）
-- 状态收敛：unclaimed 全部迁移为 normal（认领功能下线）
-- sessions（既有列沿用）
ensure_col(reveal_at REAL); -- scheduled 策略的统一发布时间（NULL=等手动）
ensure_col(join_mode TEXT DEFAULT 'fixed'); -- exam: fixed|assign|choose
ensure_col(paper_plans TEXT DEFAULT '[]'); -- 多卷快照 [{paper_id,title,plan:[...]}]
-- quiz_plan 兼容保留：单卷(=paper_plans 为空)时仍存 quiz_plan
-- session_users
ensure_col(paper_id INTEGER DEFAULT 0); -- 该生实际作答的试卷（0=单卷）
-- legacy 实时题
ensure_col(questions.analysis TEXT DEFAULT ''); -- 实时场解析（主持人公布时下发）
-- status 实时场键
-- reveal=1 当前题答案已公布
-- reveal_ana=1 当前题解析已公布（含答案）
解析策略统一枚举（新值写库，兼容旧值读取）：
| 枚举 | 含义 | 兼容旧值 |
|---|---|---|
| inline | 测验中答完一题立即展示该题解析 | instant |
| submit | 交卷后可见全部解析 | after_submit |
| scheduled | 教师设定统一发布时间自动解锁；也可提前手动“公布解析” | after_end |
| never | 学生端永不展示（仅管理端报告） | report_only |
实时场（live）不受该字段约束：解析公开由主持人“公布答案/公布解析”控制（见 §5.1）。
3. 页面清单与完成状态¶
A. 用户端（登录后，路由）—— 清单编号 A1-A5¶
| ID | 页面/路由 | 功能 | 关键交互流程 | 依赖接口 | 状态 |
|---|---|---|---|---|---|
| A1 | 登录 /login |
密码登录；错误/锁定/停用提示；教师重置入口说明 | 输入用户名或邮箱+密码 → 登录成功 → 未确认资料跳 A2，否则跳 A3 | POST /api/auth/login | 改造中 |
| A2 | 个人信息确认 /profile |
首次登录核对资料（替代“认领”） | 展示 姓名(可改)/用户名(只读)/邮箱(可改) → 点“确认无误，进入”→ 跳 A3；提示“信息不符请联系老师修改” | POST /api/auth/confirm | 新增 |
| A3 | 答题工作台 / |
学生唯一主页面 | 页面载入轮询“当前活动”：实时场进行中→内嵌实时视图；测验进行中→卡片（剩余时间/进度）→进入 A4；活动为空→空态“等待老师发起”；顶部：姓名/我的记录/退出 | GET /api/dashboard | 重写 |
| A4 | 测验作答（全屏子视图，同 A3 页内切换或保留独立 /exam/{sid}） |
整卷作答 | 进入先确定试卷（fixed/assign 自动，choose 出现选卷卡）→ 顺序答题，侧边题号导航 → 单题保存（inline 策略答完即显答案与解析）→ 顶部倒计时，到点自动交卷 → 交卷后按策略显示成绩与解析 | GET /api/exam/open·{sid}/paper PUT answer POST submit | 改造中 |
| A5 | 我的记录 /me |
历史场次成绩与逐题明细 | 列表（含解析解锁状态标记）→ 详情：逐题作答+正确率；解析按策略可见（scheduled 未到时间显示“解析将于 xx:xx 公布”） | GET /api/me/sessions(/sid) | 微调 |
学生端不再出现“实时答题 / 整卷测验”两个并列入口；“整卷测验大厅”列表页下线，改为工作台内的活动卡片。
B. 管理端（无独立口令，沿用本机信任模型）—— 清单编号 B1-B6¶
| ID | 页面/路由 | 功能 | 关键交互 | 依赖接口 | 状态 |
|---|---|---|---|---|---|
| B1 | 题库与组卷 /qbank |
题库/试卷管理；发起测验面板 | 组卷详情内“发起测验”：选 1..n 套试卷→参与方式（固定/随机分配/学生自选）→测验标题→时长→达标线→解析发布（答完即出/交卷后/定时统一发布＋时间控件/仅报告）→确认发起 | POST /api/exam/new（扩展） | 改造中 |
| B2 | 实时场控 /admin |
顺序/随机/抢答实时场 + 解析发布 | 答题控制条新增两组按钮：“公布答案”“答案＋解析”；新增题表单加“解析”输入框；结束本场并结算 | /api/admin/* | 改造中 |
| B3 | 账号管理 /admin/users |
用户/导入/重置 | 删除“待认领”“允许自助注册”；新增“资料待确认”筛选与徽标（profile_confirmed_at 为空） | /api/users、/api/auth/* | 改造中 |
| B4 | 统计报告 /admin/stats |
场次列表+单场报告 | 与 v1.1 相同；scheduled 场次提供“公布解析/提前公布”按钮与发布时间回显 | /api/stats/* | 已完成待回归 |
| B5 | 场次详情（B4 内弹层） | 解析发布控制 | scheduled 未到点可“立即公布”；显示发布状态 | POST /api/sessions/{sid}/reveal | 已完成待回归 |
| B6 | 题库编辑（B1 内） | 组卷校验 | 多卷发起时逐卷校验题目重复/无解析题 | /api/exam/new | 改造中 |
4. 用户端核心流程¶
登录 /login ──首次──> /profile 确认资料 ──> 工作台 /（A3）
（之后直接进入）
工作台活动判定（服务端 /api/dashboard）：
├─ 实时场进行中 -> 内嵌实时答题（题目/选项/抢答/排行，答案解析按主持公布展示）
├─ 测验进行中 -> 卡片: 标题/时长/倒计时/我的状态(未开始|已存 x 题|已完成)
│ └─ click -> A4 作答（choose 模式先选卷）
└─ 空闲 -> “暂无进行中的答题活动，请等待老师发起”
旁侧常驻: 我的记录 / 成绩回顾
A4 作答细节：题号侧栏；未答=灰/已存=蓝/inline 答后标对错；倒计时到点前端自动提交并防重复；
断线恢复：重新进入从 paper 接口恢复已存答案（保留现有行为）。
5. 解析发布细节¶
5.1 实时场（主持人发布制，无预设时间）¶
- 主持端按钮组：
公布答案/公布答案＋解析（解析有内容时）；全局自动解析开关（默认开）。 - 学生端同一卡片分区显示：公布前只展示题干与作答区；公布答案后出现“正确答案”区； 解析被公布后才出现“解析”区。公布答案不自动带解析（保证抢答复盘节奏可控）。
- 实时题解析录入：主持端新增/编辑题表单增加“解析”输入；旧题解析为空时按钮不亮。
5.2 测验（教师预设制）¶
| 策略 | 学生端行为 | 数据触发 |
|---|---|---|
| inline 答完即出 | 保存答案响应即带 correct/analysis，题卡标对错 |
answer API 内联返回 |
| submit 交卷后 | 交卷后记录/回顾页可见；作答中不可见 | submit 后 _can_see_analysis 放行 |
| scheduled 统一发布 | 设定时刻 reveal_at 到达自动解锁；教师可随时手动提前 |
revealed=1 或 now>=reveal_at |
| never | 学生端只有成绩不显示解析 | _can_see_analysis=false |
scheduled 的发布状态回显：未发布显示“解析将于 M月D日 HH:mm 统一公布”；已发布显示时间。 管理端统计报告对 scheduled 场次始终可看解析，并提供“立即公布解析”按钮（等效提前）。
5.3 旧数据兼容¶
sessions.reveal_policy 旧值 instant/after_submit/after_end/report_only 在读路径按映射表换算，
避免已产生场次行为突变；新发起场次一律写新枚举。
6. 多卷测验（join_mode）¶
- 发起：
papers: [paper_id,...]≥1 套。单卷沿用现有quiz_plan；多卷写paper_plans快照。 - 校验：每卷都需有可组卷题目且含解析；卷间 qn_id 不重复；时长/达标线全场统一。
- 参与：
fixed：默认取第一套（等价现有单卷流程，兼容历史）；assign：session_users.paper_id = papers[hash(uid)]，学生看到的是统一标题、卷面不同，无感知；choose：作答入口先返回试卷列表（标题/题数/分值/时长一致），学生选卷后锁定（锁后不可更换）。- 汇总与统计：
session_users.max_score/quiz 计划均以该生paper_id对应卷计算；attempt_items键仍按 (session,user,qn) 唯一（卷间无重复题故安全）；逐题统计以卷分组。
7. 管理员全流程控制点（保证“后端管理员拥有完整流程控制权限”）¶
| 阶段 | 管理员可操作 | 位置 |
|---|---|---|
| 账号 | 导入/新增/停用/重置密码/批量启停/导出密码清单/查看每生记录 | B3 |
| 准备 | 建题、组卷、编辑解析、多卷校验 | B1/B6 |
| 发起测验 | 标题/多卷/参与方式/时长/达标线/解析策略/统一发布时间 | B1 |
| 测验中 | 结束场次（未交自动交卷）；查看实时进度（统计页） | B4 |
| 测验后 | 提前公布解析、查看逐题统计、导出成绩 | B4/B5 |
| 实时场 | 选模式/限时/开始/下一题/插题/公布答案/公布解析/暂停/清空本轮/结束结算 | B2 |
| 记录 | 学生端可回顾；管理员可删改账号（答题记录不可删，保留档案） | B3/A5 |
8. 实施批次与验收¶
- P2 后端模型与账号（users/导入/登录直通/confirm API/去注册认领）
- P3 解析策略后端（exam answer/submit/detail/scheduled reveal + live reveal_ana 与 questions.analysis）
- P4 多卷测验后端（exam new/open/paper/answer/submit + 统计按卷）
- P5 用户端页面（A1 登录、A2 确认、A3 工作台、A4 作答、A5 微调）
- P6 管理端页面（B1 发起面板、B2 实时场控、B3 去认领化、B4/B5 复核）
- P7 回归与文档（冒烟 100%、readme/设计文档同步、清单回填）
验收要点：学生从“老师发账号”到“做完题看解析”的路径 ≤3 次点击；任意活动从发起到结束管理端均可干预； 无手机号；无注册/认领字样残留于界面。