# Custom Focus Duration

## Context
- 当前考试页面 `src/pages/QuizPage.tsx` 仅实现倒计时与提交逻辑，未对“离开页面/切换标签页”进行任何约束或记录。
- 管理端已有系统配置能力（`system_configs` 表 + `SystemConfigModel` + 管理端配置页），适合用于落地“可配置的离开页面容忍时长”。

## Goals / Non-Goals
- Goals:
  - 支持管理员配置“考试进行中允许离开页面的累计时长（秒）”，并在考试页面实时生效。
  - 当累计离开页面时长超过阈值时，系统按统一规则处理（默认：自动交卷并提示原因）。
  - 配置缺省时不改变现有考试流程（默认关闭该约束）。
- Non-Goals:
  - 不实现更复杂的反作弊能力（如摄像头、屏幕录制、进程检测、强制全屏、OS 级别限制）。
  - 不新增外部依赖服务或第三方 SaaS。

## Decisions
- 决策：将“焦点容忍时长”作为系统配置项持久化，默认关闭。
  - 方案：在 `system_configs` 中新增配置类型（例如 `quiz_focus_config`），形如 `{ enabled: boolean, maxUnfocusedSeconds: number }`。
  - 理由：与现有配置存储模式一致；默认关闭可避免对现有行为产生破坏性变更。
- 决策：焦点离开判定使用浏览器 Page Visibility 能力（`document.hidden`/`visibilitychange`）并累计离开时长。
  - 理由：实现成本低、跨浏览器兼容性较好、无需引入新技术栈。
- 决策：超阈值处理默认“自动交卷”。
  - 理由：规则清晰、可验证；与现有“时间到自动交卷”路径类似，便于复用提交逻辑。

## Risks / Trade-offs
- 误判风险：移动端切后台、系统弹窗等可能导致短暂 `hidden`。
  - 缓解：默认关闭；管理员可设置更宽松阈值（例如 10–30 秒）。
- 可绕过：用户可在同一标签内切换窗口但仍保持可见，或使用分屏。
  - 缓解：该能力只覆盖“标签页不可见”的场景；不将其描述为强反作弊。
- 体验影响：过严阈值会导致误触发交卷。
  - 缓解：在 UI 明确提示该规则与当前阈值；触发前可选“超阈值预警”作为后续增强。

## Migration Plan
- 以“默认关闭”的配置发布（`enabled: false`），确保升级后不影响现有考试行为。
- 管理端提供配置入口后，由管理员在需要的考试场景手动开启并设置阈值。
- 回滚策略：关闭 `enabled` 即可恢复为原行为。

## Open Questions
- 是否需要将“违规触发记录”写入答题记录（`quiz_records`）以便统计与审计？
- 超阈值动作是否需要支持可配置（仅警告 / 记录违规 / 自动交卷）？

