examination/docs/requirements.md

需求文档

1. 项目背景

在 CS 领域的学习工作流中，缺少一环通过应试化手段强化知识理解的工具。需要覆盖的知识范围包括但不限于：

• 计算机网络、操作系统等基础领域
• JVM、GC 等运行时机制
• 中间件（Redis、Kafka 等）
• AI / Agent 架构与工程实践
• 以及其他任何 CS 相关的大领域

2. 核心目标

构建一套完整的 题目生成 → 数据存储 → 前端训练 工作流：

1. 前端页面：纯 HTML + CSS + JS 的单页应用，部署到自有服务器
2. 数据存储：通过 Git 仓库存储题目 JSON，按主题组织，按题型拆分文件
3. 题目生成：
   • 提供推荐提示词模板，用于在非 Agent 的 LLM 对话中便捷生成
   • 提供 JSON Schema 标准，确保生成数据可校验
   • 沉淀为 Claude Code Skill，可在 Agent 环境中复用
4. 自定义导入：支持前端直接粘贴/上传 JSON，临时导入使用

3. 功能需求

3.1 前端页面

功能	说明
主题浏览	侧边栏展示所有主题，含名称、描述、题目统计
做题交互	支持 7 种题型的渲染与交互
答案判定	检查答案对错，正确/错误视觉反馈
解析展示	显示正确答案和解析说明
全部显示	一键显示所有题目的答案
提交全部	一键判定所有题目的对错
重置	清除所有作答状态
进度统计	显示已答/正确/错误/待答数量和进度条
自定义导入	弹窗粘贴 JSON 或上传文件，临时加入当前会话
复制题目提示词	题目卡片一键复制格式化的提示词，可在外部 AI 获取解析
导入提示词模板	导入弹窗提供 7 种题型的 AI 生成提示词模板，一键复制

3.2 题型支持

题型	代号	交互方式
单选题	sc	4 选 1，点击选项
多选题	mc	多选多，点击选项
判断题	tf	对/错 按钮
填空题	fb	输入框，支持答案匹配规则
简答题	sa	文本域，关键词匹配
代码阅读	cr	代码块 + 嵌套子题
场景分析	sn	场景描述 + 嵌套子题

3.3 数据管理

功能	说明
Git 存储	题目以 JSON 文件形式存储在 Git 仓库
按主题组织	每个主题一个独立目录
按题型拆分	同一主题下，每种题型一个 JSON 文件
多 Agent 并行	不同题型文件独立，支持多 Agent 并行生成无写冲突
Meta 稳定	主题元信息（meta.json）与题目内容分离，一次生成后稳定

3.4 生成与校验

功能	说明
提示词模板	提供标准化的 LLM 提示词，用于非 Agent 环境生成题目（前端导入页内置）
JSON Schema	定义完整的题目 JSON Schema，用于格式校验
Skill 复用	沉淀为 Claude Code Skill，支持 generate / validate / batch-generate

4. 非功能需求

维度	要求
技术栈	纯前端（HTML + CSS + JS），无后端依赖
部署	可部署到任意静态文件服务器
兼容性	现代浏览器，响应式布局（桌面 + 移动端）
数据安全	.ref/ 参考数据不提交 Git
可扩展	支持新增主题、新增题型，无需修改前端核心逻辑

5. 约束

• 不使用任何前端框架（React/Vue 等），保持单文件 SPA
• 不依赖后端服务，数据通过 fetch 从本地 JSON 文件加载
• 题目 ID 格式统一为 {type_short}-{sequence}（如 fb-001、sc-003）