# 需求文档

## 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`）