人工智能辅助实验教学实施案例——初中python项目简易“考务系统v2.0”
孔子曰：“勿意，勿必，勿固，勿我。学而不思则罔，思而不学则殆。”
人工智能辅助实验教学实施案例——初中python项目简易“考务系统v2.0”考务处理系统 V2.0 文档
文档一：用户使用手册
1. 系统简介
考务处理系统是一个面向考试机构的全栈Web应用，提供考生在线报名、准考证生成、成绩管理、通知单推送及统计分析等功能。系统采用浏览器/服务器架构，管理员通过认证后台进行数据管理。
2. 系统访问
· 普通用户入口：http://服务器IP:8000/
· 管理员登录：http://服务器IP:8000/login
默认管理员账号：admin
默认密码：exam2026（首次使用后请通过环境变量修改）
3. 考生操作指南
3.1 在线报名
1. 访问首页，点击“考生报名”。
2. 填写信息：姓名、身份证号（18位）、报考科目（数学/英语/物理/化学）、电子邮箱。
3. 提交后系统自动审核：
· 合格：立即生成准考证并跳转查询页。
· 不合格：页面提示原因（如身份证号重复、格式错误等），需联系管理员处理。
3.2 查询准考证及成绩
1. 点击“查询中心”，输入准考证号或考生编号。
2. 系统显示：
· 考生基本信息
· 准考证（考场、座位号、考试时间）
· 各科成绩及状态（正常/缺考/作弊）
· 通知单（合格结论）
注意：成绩发布后，管理员会生成通知单，考生方可查询到结论。
4. 管理员操作指南
管理员必须登录后台（/login）后访问 /admin 面板。
4.1 报名审核
· 系统自动完成大部分审核，不合格记录保存在“无效报名列表”。
· 管理员可手动将“待审核”或“不合格”考生改为“合格”，并触发准考证生成。
4.2 准考证管理
· 单个生成：考生合格后自动生成，无需干预。
· 批量生成：在后台点击“生成所有准考证”，系统异步处理（可查看任务状态）。
4.3 成绩导入
1. 准备Excel或CSV文件，必须包含列：准考证号、科目、成绩。
2. 在管理页面上传文件，可选择批次号（默认时间戳）。
3. 系统返回导入汇总（成功数、错误行），错误记录存入日志表。
4.4 合格标准设置
为每个科目设置合格分数线（默认60分），用于通知单的合格判定。
4.5 生成通知单
点击“生成通知单”后，系统后台为所有已有成绩的考生生成结论通知（合格/不合格），并存入通知表。
4.6 统计分析
· 查看各科目报名人数、实考人数、合格人数及合格率。
· 导出Excel格式的统计报表。
4.7 任务监控
在后台可查看异步任务（批量生成准考证、通知单）的执行状态和结果消息。
5. 常见问题（Q&A）
Q1：报名时提示“身份证号已存在”怎么办？
A：系统禁止重复报名。若确需修改信息，请联系管理员删除原记录或手动修改数据库。
Q2：成绩导入报“准考证号不存在”如何处理？
A：请先确保考生已合格并生成准考证。可通过“导出准考证模板”获取有效准考证号列表。
Q3：通知单未生成怎么办？
A：确认已完成成绩导入并设置合格标准，然后重新执行“生成通知单”。若任务失败，查看任务记录中的错误信息。
Q4：管理员密码忘记如何重置？
A：停止服务，设置环境变量 ADMIN_PASSWORD=新密码，重启即可。若未设置环境变量，默认密码为 exam2026。
---
文档二：技术维护与部署指南
1. 技术架构概览
· 后端框架：FastAPI (Python 3.8+)
· 数据库：SQLite（可替换为PostgreSQL/MySQL）
· ORM：SQLAlchemy（连接池：QueuePool，池大小10，最大溢出20）
· 模板引擎：Jinja2
· 异步任务：内置ThreadPoolExecutor（4线程）
· 认证：Session + Cookie（基于itsdangerous令牌）
· 文件处理：pandas读取Excel/CSV
2. 系统目录结构
```
exam_system/
├── main.py # 应用主文件（含所有路由、模型）
├── templates/ # Jinja2模板目录
│ ├── index.html
│ ├── register.html
│ ├── query.html
│ ├── login.html
│ └── admin.html
├── static/ # 可选静态资源（CSS/JS）
├── exam_system.db # SQLite数据库文件（自动生成）
└── requirements.txt # 依赖清单
```
3. 数据库设计
核心表说明：
表名 作用
examinee_list 考生基本信息，状态（待审核/合格/不合格）
admission_ticket 准考证号、考场、座位号、考试时间
score_list 成绩记录，关联准考证号，含成绩状态
notification 通知单内容及发送状态
pass_standard 各科目合格分数线
sequence_counter 自增序列（考生编号、准考证号）
invalid_registration 无效报名原因日志
error_score_log 成绩导入错误行记录
async_task 异步任务状态跟踪
重要关系：
· 一个考生 → 多个准考证（实际业务为1对1，但模型支持一对多）
· 一个准考证 → 多个成绩（按科目）
· 考生与通知单一对多（每次生成可产生多条）
4. 环境配置
4.1 依赖安装
```bash
pip install fastapi uvicorn sqlalchemy pandas openpyxl itsdangerous python-multipart
```
或使用 requirements.txt：
```
fastapi==0.104.1
uvicorn[standard]==0.24.0
sqlalchemy==2.0.23
pandas==2.1.3
openpyxl==3.1.2
itsdangerous==2.1.2
python-multipart==0.0.6
```
4.2 环境变量
变量名 默认值 说明
ADMIN_PASSWORD exam2026 管理员密码（建议生产环境修改）
SECRET_KEY 硬编码 会话加密密钥（生产环境必须更换）
修改方法（Linux）：
```bash
export ADMIN_PASSWORD="yourStrongP@ss"
```
5. 部署方式
5.1 本机部署（开发/测试）
1. 将所有文件放置于同一目录。
2. 确保 templates 文件夹存在且包含所有html文件。
3. 运行：
```bash
uvicorn main:app --reload --host 127.0.0.1 --port 8000
```
4. 访问 http://localhost:8000
--reload 仅开发模式使用，生产环境请移除。
5.2 网络部署（生产环境）
推荐使用 Nginx + Gunicorn + Uvicorn workers 或直接使用 Uvicorn 多进程。
方案一：Uvicorn + Gunicorn
```bash
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
```
方案二：Nginx反向代理 + Uvicorn
1. 启动应用（监听127.0.0.1:8000）：
```bash
uvicorn main:app --host 127.0.0.1 --port 8000
```
2. 配置Nginx（示例 /etc/nginx/sites-available/exam）：
```nginx
server {
listen 80;
server_name exam.yourdomain.com;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
```
3. 启用站点并重启Nginx。
方案三：HTTPS配置（推荐）
使用Let's Encrypt获得证书，在Nginx中添加：
```nginx
listen 443 ssl;
ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;
```
同时将HTTP重定向到HTTPS。
5.3 Docker部署（可选）
提供示例Dockerfile：
```dockerfile
FROM python:3.10-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```
构建并运行：
```bash
docker build -t exam-system .
docker run -d -p 8000:8000 -e ADMIN_PASSWORD=prodPass123 exam-system
```
6. 安全加固建议
1. 修改SECRET_KEY：将代码中的硬编码 SECRET_KEY = "your-secret-key-change-in-production" 改为从环境变量读取。
2. 数据库迁移：SQLite不适合高并发写，生产环境建议迁移至PostgreSQL。
3. 日志监控：系统日志输出到文件，定期轮转。
4. Session有效期：当前为1小时，可根据需求修改 max_age 参数。
5. HTTPS：强制启用，避免Cookie明文传输。
7. 维护与故障排查
7.1 日志查看
应用日志输出到控制台，若使用systemd或docker可重定向。日志级别为INFO，包含请求、任务执行和错误信息。
7.2 常见故障处理
现象 可能原因 解决方法
报名提示“身份证号已存在” 数据库中已有相同身份证号的记录 查询examinee_list表确认，若为误操作可删除记录
成绩导入全部失败 文件列名不匹配或准考证号类型错误 检查文件列名必须为“准考证号”“科目”“成绩”；准考证号单元格避免科学计数法
批量生成准考证任务卡住 线程池满或数据库锁 重启服务，检查AsyncTask表中状态为RUNNING的任务，可手动改为FAILED
登录后立即跳回登录页 Session过期或Cookie被浏览器拒绝 检查浏览器Cookie设置，确认服务器时间同步
SQLite数据库被锁 并发写入过多 升级为PostgreSQL；或降低连接池大小
7.3 数据库备份
定期备份 exam_system.db 文件。建议使用cron任务：
```bash
0 2 * * * cp /path/to/exam_system.db /backup/exam_$(date +\%Y\%m\%d).db
```
7.4 性能调优
· 并发提升：修改 pool_size 和 max_overflow，但SQLite并发能力有限，建议迁移至PostgreSQL。
· 模板缓存：Jinja2已启用 auto_reload=True，生产环境可设为False提升性能。
· 静态资源：使用Nginx直接托管 /static 目录。
8. API 接口概览（供二次开发）
所有API路径以 /api/ 开头，除登录和公开查询外均需管理员认证（Cookie）。
方法 端点 说明
POST /api/register 考生报名（JSON）
GET /api/query-by-ticket 凭准考证号查询
GET /api/invalid-registrations 无效报名列表
PUT /api/registration/{id}/approve 手动审核通过
POST /api/scores/upload 上传成绩文件
GET /api/scores/errors 成绩导入错误日志
POST /api/standards 设置合格标准
POST /api/notifications/generate 生成通知单（异步）
GET /api/statistics 获取统计报表
GET /api/tasks 异步任务状态列表
详细请求/响应格式请参考代码中的Pydantic模型定义。
---
文档版本：V2.0
最后更新：2026-04-17声明:此软件只供学习和教学研究之用，如商用责任自负！
|
再小的个体，也有自己的目标。
10个月宝宝每天需要喝多少奶粉？
