# 自动登记作业

**Repository Path**: crisxie/homework-scanner

## Basic Information

- **Project Name**: 自动登记作业
- **Description**: 这是一个基于摄像头扫描二维码的作业提交管理系统，可以实时记录和统计学生的作业提交情况，并生成详细的提交报告和可视化统计图表。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-26
- **Last Updated**: 2025-03-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 作业提交系统 - QR 扫码登记工具

---

## 项目简介
本程序通过摄像头扫描学生二维码实现自动化作业登记，支持两种模式：  
✅ **登记模式**（创建新记录）  
✅ **补交模式**（追加到历史记录）  
自动生成带时间戳的 Excel 文件，并输出统计图表，适用于课堂签到、作业提交等场景。

---

## 核心功能
- **双模式切换**：支持新建记录与历史记录追加
- **实时反馈**：显示已扫描人数、学生信息及重复扫码提示
- **数据管理**：自动生成标准化 Excel 文件（含学号、姓名、提交状态和时间戳）
- **智能统计**：输出饼图与条形图，展示提交比例和学号段分布
- **历史清理**：支持手动清理 7 天前的旧记录文件
- **多设备支持**：自动检测摄像头并支持手动选择

---

## 快速开始

### 1. 安装依赖
```bash
pip install -r requirements.txt
```

### 2. 配置文件准备
创建 `students.json` 文件（格式参考下方示例）：
```json
{
  "1": "张三",
  "2": "李四",
  "3": "王五",
  ...
}
```

### 3. 启动程序
```bash
python app.py
```

---

## 使用说明

### 操作流程
1. **选择模式**  
   - 输入 `1` 进入 **登记模式**（新建记录）  
   - 输入 `2` 进入 **补交模式**（选择历史文件追加）

2. **摄像头设置**  
   - 程序自动检测可用摄像头，多设备时可手动选择编号

3. **扫码阶段**  
   - 将二维码对准画面中心白色方框区域  
   - **快捷键操作**：  
     - `Ctrl+Z`：结束扫描并保存结果  
     - `Q`：立即退出程序  

4. **结果处理**  
   - 自动生成 Excel 文件（文件名示例：`作业提交情况_20231025_153045.xlsx`）  
   - 关闭摄像头后自动弹出统计图表  

---

## 配置文件说明
- **学生名单配置**  
  修改 `students.json` 文件以同步学生信息，格式示例：  
  ```json
  {
    "学号": "姓名",
    "101": "张三",
    "102": "李四"
  }
  ```

- **记录文件规范**  
  Excel 文件包含以下字段：  
  | 学号 | 姓名 | 提交状态 | 提交时间 |

---

## 注意事项
- **摄像头要求**：支持主流 USB 摄像头（默认分辨率 640×480）
- **二维码规范**：必须包含学号信息，且与 `students.json` 中的键值匹配
- **文件权限**：确保程序对当前目录有读写权限
- **运行环境**：建议使用 Python 3.8+ 环境

---

## 常见问题

**Q1：提示「未检测到摄像头」**  
- 检查摄像头物理连接  
- 重启程序或尝试更换 USB 接口  
- 调整代码中 `select_camera()` 的检测范围（默认检测 0-9 号设备）  

**Q2：无法读取 students.json 文件**  
- 检查文件是否位于项目根目录  
- 验证 JSON 格式是否正确（可使用 [JSONLint](https://jsonlint.com/)）  

**Q3：导出的 Excel 文件损坏**  
- 确保已安装 Excel/WPS 等办公软件  
- 检查文件是否被其他程序占用  

**Q4：统计图表显示异常**  
- 确认 `matplotlib` 库已正确安装  
- 重启程序重新生成图表  

---

## 依赖库说明
| 库名称          | 用途                   |
|-----------------|------------------------|
| opencv-python   | 摄像头画面捕获与处理   |
| pyzbar          | 二维码解码核心功能     |
| pandas          | Excel 文件读写与管理   |
| matplotlib      | 统计图表生成           |
| keyboard        | 快捷键监听             |

---

📥 **反馈与支持**  
如有问题或建议，请提交 Issue 或联系项目维护者。