🎯 学科能力测评系统使用指南

🌐 系统启动

方式一：使用 Docker（推荐）

docker-compose up -d

方式二：本地开发

poetry install
poetry run uvicorn main:app --host 0.0.0.0 --port 8000 --reload

确保系统运行在您的服务器域名或本地环境

📋 完整使用流程

1️⃣ 访问测评列表页

• URL: http://your-server-domain/
• 功能: 查看所有已完成的测评报告
• 操作:
  • 浏览历史报告
  • 分页查看
  • 点击"开始新的测评"

2️⃣ 配置测评

• URL: http://your-server-domain/survey.html
• 功能: 填写学员信息并配置抽题规则
• 必填信息:
  • 学员姓名
  • 学校名称
  • 年级
• 可选配置:
  • 题目标签筛选（年级/册次）
  • 自定义抽题规则（JSON格式）

3️⃣ 开始答题

• URL: 自动生成，格式为 http://your-server-domain/quiz/{sessionId}
• 功能: 完成测评题目
• 操作:
  • 查看学员信息
  • 答题进度条
  • 提交答案

4️⃣ 等待报告生成

• 功能: 答题提交后自动调用AI生成报告
• 时间: 通常需要10-30秒
• 状态: 页面会显示生成进度

5️⃣ 查看测评报告

• URL: http://your-server-domain/public/report.html?id={reportId}
• 功能: 查看详细的个性化测评报告
• 内容包括:
  • 五维能力雷达图
  • 错题归因分析
  • 知识掌握度评估
  • 个性化学习建议

⚙️ 抽题规则配置

默认配置

• 基础题: 10题 × 5分 = 50分
• 进阶题: 2题 × 10分 = 20分
• 竞赛题: 2题 × 15分 = 30分
• 总计: 14题，100分制

自定义配置

JSON格式示例：

{
  "基础题": 8,
  "进阶题": 3,
  "竞赛题": 3
}

标签筛选

支持按年级/册次筛选题目，例如：

• 一年级上册1-周围的植物
• 五年级上册1-光
• 八年级上册3-电路探秘

🤖 AI报告生成

系统会自动调用大语言模型生成包含以下内容的报告：

📊 核心分析

• 五维能力评估
  • 知识记忆与识别
  • 信息提取与分析
  • 科学推理与判断
  • 生活应用与关联
  • 探究思维与甄别

📈 详细报告

• 错题归因分析
• 知识体系掌握度
• 认知能力维度评估
• 学习行为推测
• 个性化学习规划

🔧 系统特色

• ✨ 响应式设计: 支持PC和移动端
• 🚀 实时进度: 答题进度实时显示
• 🔄 异步处理: 报告生成不阻塞用户操作
• 💾 数据持久化: 本地SQLite数据库存储
• 🧩 模块化架构: 代码结构清晰，易于维护
• 🤖 AI智能: 个性化专业教育评估

📱 快速开始

1. 访问 http://your-server-domain/
2. 点击"开始新的测评"
3. 填写学员信息
4. 配置抽题规则（可选）
5. 点击"开始答题"
6. 完成所有题目
7. 等待AI生成报告
8. 查看详细测评报告

🛠️ 故障排除

常见问题

Q: 点击"开始新的测评"显示404 A: 确保服务器正在运行，检查Docker容器状态或使用本地开发命令启动

Q: 报告生成失败 A: 检查网络连接和外部API是否可访问

Q: 题目加载失败 A: 确保public/questions.xlsx文件存在且格式正确，系统已升级为直接读取Excel文件

开发环境要求

• Python 3.12+
• Poetry依赖管理
• openpyxl库（用于读取Excel文件）
• 网络连接（用于AI API调用）

题库管理

系统现在直接使用Excel文件作为题库：

• 题库文件: public/questions.xlsx
• 工作表名称: "单选题"
• 字段: 序号、题干、选项A-H、解析、分数、答案、标签等
• 自动分类: 系统会根据标签自动将题目分为基础题、进阶题、竞赛题

---

🎉 现在您可以开始使用完整的学科能力测评系统了！