引入openspec管理
This commit is contained in:
41
openspec/changes/add-custom-focus-duration/proposal.md
Normal file
41
openspec/changes/add-custom-focus-duration/proposal.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# 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`）以便统计与审计？
|
||||
- 超阈值动作是否需要支持可配置（仅警告 / 记录违规 / 自动交卷）？
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Custom Focus Duration
|
||||
系统 MUST 支持配置“考试进行中允许离开页面的累计时长（秒）”，并在考试页面生效。
|
||||
|
||||
#### Scenario: Default disabled
|
||||
- **GIVEN** 焦点约束配置为关闭或不存在
|
||||
- **WHEN** 用户在考试进行中切换到其他标签页导致页面不可见
|
||||
- **THEN** 系统 MUST 不因焦点离开而自动交卷
|
||||
|
||||
#### Scenario: Enforce configured maximum
|
||||
- **GIVEN** 焦点约束配置启用且 `maxUnfocusedSeconds` 为 10
|
||||
- **WHEN** 用户在考试进行中累计离开页面 12 秒
|
||||
- **THEN** 系统 MUST 自动提交该次考试
|
||||
- **AND** 系统 MUST 告知用户自动提交的原因是“离开页面超时”
|
||||
|
||||
### Requirement: Unfocused Duration Accumulation
|
||||
系统 MUST 在一次考试会话内累计多次离开页面的总时长，并以累计值与阈值比较。
|
||||
|
||||
#### Scenario: Multiple unfocused intervals
|
||||
- **GIVEN** 焦点约束配置启用且 `maxUnfocusedSeconds` 为 10
|
||||
- **WHEN** 用户先离开页面 6 秒后返回，再离开页面 5 秒后返回
|
||||
- **THEN** 系统 MUST 将累计离开页面时长视为 11 秒
|
||||
- **AND** 系统 MUST 自动提交该次考试
|
||||
|
||||
15
openspec/changes/add-custom-focus-duration/tasks.md
Normal file
15
openspec/changes/add-custom-focus-duration/tasks.md
Normal file
@@ -0,0 +1,15 @@
|
||||
## 1. 配置与接口
|
||||
- [ ] 1.1 扩展系统配置模型以支持读取/更新焦点配置
|
||||
- [ ] 1.2 增加管理端 API：获取/更新焦点配置
|
||||
- [ ] 1.3 增加前端管理页配置项：启用开关与最大离开秒数
|
||||
|
||||
## 2. 考试页面行为
|
||||
- [ ] 2.1 在考试开始后监听 `visibilitychange` 并累计离开页面时长
|
||||
- [ ] 2.2 超过阈值时自动交卷并展示原因提示
|
||||
- [ ] 2.3 确保刷新/路由切换时事件监听被正确清理
|
||||
|
||||
## 3. 测试与校验
|
||||
- [ ] 3.1 为新增管理端接口补充可执行的接口测试
|
||||
- [ ] 3.2 为焦点累计逻辑补充前端单测或最小可验证测试
|
||||
- [ ] 3.3 运行 `npm run check` 与 `npm run build`
|
||||
|
||||
@@ -1,13 +0,0 @@
|
||||
# Change: Fix QuizPage useEffect Bug
|
||||
|
||||
## Why
|
||||
在QuizPage.tsx中，useEffect钩子末尾错误地调用了clearQuiz()函数，导致从SubjectSelectionPage传递过来的题目数据被立即清除，引发"Cannot read properties of undefined (reading 'type')"错误。
|
||||
|
||||
## What Changes
|
||||
- 移除QuizPage.tsx useEffect钩子末尾的clearQuiz()调用
|
||||
- 修改清除逻辑，只清除answers对象而保留题目数据
|
||||
- 添加对currentQuestion的空值检查，确保组件正确渲染
|
||||
|
||||
## Impact
|
||||
- Affected specs: quiz
|
||||
- Affected code: src/pages/QuizPage.tsx
|
||||
@@ -1,17 +0,0 @@
|
||||
## MODIFIED Requirements
|
||||
### Requirement: Quiz Page State Management
|
||||
The system SHALL preserve question data when navigating to QuizPage from other pages, and only clear答题状态(answers) to ensure proper component rendering.
|
||||
|
||||
#### Scenario: Navigation from SubjectSelectionPage
|
||||
- **WHEN** user selects a subject and navigates to QuizPage
|
||||
- **THEN** the system SHALL preserve the questions data
|
||||
- **THEN** the system SHALL clear only the answers state
|
||||
- **THEN** the system SHALL render the first question correctly
|
||||
|
||||
### Requirement: Quiz Page Error Handling
|
||||
The system SHALL properly handle null or undefined question data to prevent runtime errors during rendering.
|
||||
|
||||
#### Scenario: Null Question Data
|
||||
- **WHEN** currentQuestion is null or undefined
|
||||
- **THEN** the system SHALL display a loading state instead of crashing
|
||||
- **THEN** the system SHALL NOT attempt to access properties of undefined objects
|
||||
@@ -1,8 +0,0 @@
|
||||
## 1. Implementation
|
||||
- [x] 1.1 移除QuizPage.tsx useEffect钩子末尾的clearQuiz()调用
|
||||
- [x] 1.2 修改清除逻辑，只清除answers对象而保留题目数据
|
||||
- [x] 1.3 添加对currentQuestion的空值检查，确保组件正确渲染
|
||||
|
||||
## 2. Validation
|
||||
- [x] 2.1 运行项目确保bug已修复
|
||||
- [x] 2.2 验证从SubjectSelectionPage可以正常跳转到QuizPage并显示题目
|
||||
@@ -1,38 +0,0 @@
|
||||
# Change: User Group Management System
|
||||
|
||||
## Status
|
||||
**Pending Testing** (Note: Add User Group functionality is not yet tested)
|
||||
|
||||
## Why
|
||||
To manage users more efficiently by grouping them and assigning exam tasks to groups.
|
||||
|
||||
## What Changes
|
||||
1. **User Group Management**:
|
||||
* Add "User Group" management module in User Management interface.
|
||||
* Support CRUD for user groups.
|
||||
* System built-in "All Users" group.
|
||||
2. **User-Group Association**:
|
||||
* Show user groups in user details.
|
||||
* Support multi-select for user groups.
|
||||
* Audit log for group changes.
|
||||
3. **Exam Task Assignment**:
|
||||
* Support assigning tasks by individual users and user groups.
|
||||
* Handle duplicate selections (user in selected group).
|
||||
* Show unique user count.
|
||||
4. **Permissions**:
|
||||
* Admin only for managing groups.
|
||||
5. **Data Consistency**:
|
||||
* Cascade delete for groups and users.
|
||||
* Protect "All Users" group.
|
||||
|
||||
## Impact
|
||||
- Affected specs: user-group
|
||||
- Affected code:
|
||||
- api/database/index.ts
|
||||
- api/models/userGroup.ts
|
||||
- api/controllers/userGroupController.ts
|
||||
- api/controllers/userController.ts
|
||||
- api/controllers/examTaskController.ts
|
||||
- src/pages/admin/UserManagePage.tsx
|
||||
- src/pages/admin/UserGroupManage.tsx
|
||||
- src/pages/admin/ExamTaskPage.tsx
|
||||
@@ -1,44 +0,0 @@
|
||||
# Spec: User Group Management
|
||||
|
||||
## 1. User Group Management Functionality
|
||||
- **Module**: New "User Group" management module in User Management interface.
|
||||
- **CRUD**: Support Create, Read, Update, Delete for user groups.
|
||||
- **Group Info**: Group Name, Description, Created Time.
|
||||
- **"All Users" Special Group**:
|
||||
- All users automatically belong to this group.
|
||||
- Users cannot voluntarily exit this group.
|
||||
- New users automatically join this group.
|
||||
- This group cannot be deleted.
|
||||
|
||||
## 2. User-Group Association Management
|
||||
- **Display**: User details page shows the list of user groups.
|
||||
- **Assignment**: Support multi-select to set user groups.
|
||||
- **Multi-group**: Single user can belong to multiple groups.
|
||||
- **Audit**: Log user group changes (Audit log).
|
||||
|
||||
## 3. Exam Task Assignment Functionality
|
||||
- **Assignment Methods**:
|
||||
- Select by Individual User.
|
||||
- Select by User Group.
|
||||
- **Hybrid Selection**: Support selecting both specific users and user groups simultaneously.
|
||||
- **Deduplication**:
|
||||
- System automatically removes duplicates when a user is selected directly and also belongs to a selected group.
|
||||
- Keep only one instance in the task assignment result.
|
||||
- Record original selection in assignment log.
|
||||
|
||||
## 4. Permissions & Verification
|
||||
- **Admin**: Adding/Modifying user groups requires administrator permissions.
|
||||
- **Scope**: Users can only view groups they have permission to manage.
|
||||
- **Verification**: Both Frontend and Backend must verify user group operation permissions.
|
||||
|
||||
## 5. Data Consistency Assurance
|
||||
- **Delete Group**: Automatically remove all user associations when a group is deleted.
|
||||
- **Delete User**: Automatically remove from all user groups when a user is deleted.
|
||||
- **Protection**: Built-in "All Users" group cannot be modified or deleted.
|
||||
|
||||
## 6. Interface Design Requirements
|
||||
- **Component**: Use multi-select component for user group selection.
|
||||
- **Identification**: Clearly identify the "All Users" special group.
|
||||
- **Count Display**: Clearly display the final actual assigned user count (after deduplication) in the Exam Task Assignment interface.
|
||||
|
||||
**Note**: The "Add User Group" functionality has been implemented but is currently **untested**.
|
||||
Reference in New Issue
Block a user