InkSight · AI 作文批改 / 班级作业平台

面向教学的 AI 作文平台，支持班级 / 任务 / 排行榜，AI 评分与逐条建议。

✨ 功能亮点

学生：提交作文（可关联班级任务）、查看 AI 评分与建议、收藏范文、编辑个人资料。
老师：创建班级 / 邀请码、发布作文任务、AI 批改、排行榜前三优秀范文、查看班级成员资料、删除未批改作文。
管理员：后台仪表盘、查看全站数据、管理用户角色、重置账号密码。
班级 / 任务 / 排行榜：邀请码加入；班级成员资料互查；任务详情页自动展示前三高分作文。
范文库：老师上传，学生收藏；高分作文可自动收录。
AI 深度集成：OpenAI-Compatible 接口，生成多维评分 + 逐条建议 + 改写示例。

🧩 技术栈

Flask 3.x · Jinja2 · SQLAlchemy · MySQL 8（PyMySQL）· Flask-Login · OpenAI SDK（可自定义 BASE_URL） Matplotlib 3.9.x：用于生成示例图表或基础可视化素材。

🚀 快速开始

安装依赖

python -m venv .venv
.\.venv\Scripts\Activate.ps1   # 或 source .venv/bin/activate
pip install -r requirements.txt

准备数据库

mysql -u root -p -e "CREATE DATABASE inksight CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

配置 .env（可手写或使用自动脚本）

FLASK_ENV=development
SECRET_KEY=dev
SQLALCHEMY_DATABASE_URI=mysql+pymysql://user:[email protected]:3306/inksight

LLM_PROVIDER=openai
LLM_API_KEY=your_key
LLM_MODEL=gpt-4o-mini
# 可选：LLM_BASE_URL=https://your-openai-compatible-endpoint

浏览器首配：启动后访问 /setup；或运行 python scripts/setup_db.py 按提示生成 .env。

一键迁移（自动建表/补字段）

python scripts/migrate.py

脚本会创建 classroom / classroom_member / assignment / grade_detail 表，补齐 user 的 full_name/email/bio 以及 essay.assignment_id 等缺失字段。

启动

python run.py
# 访问 http://127.0.0.1:5000

📄 主要页面

/ 首页
/dashboard 仪表盘（教师筛选/排序；学生查看自己的作文）
/classes 班级列表 / 加入 / 创建
/classes/<id> 班级详情（成员、任务、发布任务）
/assignments/<id> 任务详情与排行榜
/essays/new?assignment_id=<id> 提交任务作文
/profile 个人资料；/settings/password 修改密码
/admin 管理员仪表盘；/admin/users 用户/角色管理

🛠️ 脚本与工具

scripts/setup_db.py：交互式生成 .env 并初始化数据库。
scripts/migrate.py：自动建表、补字段（更新后建议执行）。
scripts/check_db.py：数据库连通性与配置检查。
scripts/create_admin.py：创建或提升管理员账号；可重置管理员密码。

🤖 AI 批改配置

LLM_PROVIDER=openai
LLM_API_KEY：必填
LLM_MODEL：如 gpt-4o-mini / gpt-4o / qwen-plus
LLM_BASE_URL：可选，兼容端点（如通义 / 自建代理）

❓ 常见问题

缺表/缺字段：运行 python scripts/migrate.py，重启应用。
MySQL 连接失败：确认服务启动、端口/账号/数据库名正确。
LLM 调用失败：检查 API Key、BASE_URL（使用兼容服务需填写）。

👑 管理员说明

运行 python scripts/create_admin.py 按提示创建或提升管理员账号（默认用户名 admin，留空密码默认 admin123）。
管理员登录后可访问 /admin 查看全站数据，或在 /admin/users 管理用户角色、重置密码。

🗂️ 目录结构速览

app/                 # Flask 应用（蓝图、模型、表单、视图）
docs/                # 设计/截图等文档
instance/            # 本地实例配置（如 SQLite/上传等）
scripts/             # 初始化、迁移、检查、创建管理员等工具脚本
run.py               # 应用入口
requirements.txt     # 依赖清单（含 Matplotlib）

🧠 架构与数据流

Web 层：Flask + Jinja2 渲染页面，Flask-Login 处理认证与权限。
数据访问：SQLAlchemy ORM 映射 MySQL，集中管理模型、关系与迁移脚本。
业务核心：班级/任务/作文/评分的 CRUD 与排行榜计算；AI 批改通过 OpenAI-Compatible 端点调用。
配置：.env 载入数据库与 LLM 参数，scripts/setup_db.py 辅助生成。

🗄️ 数据模型速览

user：基础信息、角色（学生/教师/管理员），含 full_name/email/bio 字段。
classroom / classroom_member：班级与成员关系。
assignment：作文任务；essay：学生提交；grade_detail：AI 评分与建议。
典型关系：classroom 1-N assignment；assignment 1-N essay；essay 1-1/1-N grade_detail。

🔧 环境要求

Python 3.10+，MySQL 8（或兼容版本）；推荐虚拟环境（venv/conda）。
Windows 开发可用 PowerShell，类 Unix 环境命令基本一致。

🧪 测试与质量检查

单元/集成测试：pytest tests/ -q。
代码格式：可使用 ruff/black（若团队已安装）；确保提交前本地跑过关键脚本（迁移、创建管理员）并检查日志无异常。

🛫 部署建议

生产环境建议使用 WSGI 容器（如 gunicorn -w 4 -b 0.0.0.0:5000 'run:app'，Windows 可选 Waitress）。
设置持久化的环境变量/.env，确保数据库与 LLM 凭证安全存储。
建议开启 HTTPS，反向代理（Nginx/Caddy）处理静态资源与超时。

📊 可视化示例（Matplotlib）

import matplotlib.pyplot as plt

scores = [86, 90, 78, 92, 88]
labels = ["A1", "A2", "A3", "A4", "A5"]
plt.bar(labels, scores)
plt.title("AI 评分示例柱状图")
plt.xlabel("作文编号")
plt.ylabel("得分")
plt.tight_layout()
plt.savefig("docs/example-score-chart.png")

用于生成教学示例或课堂展示的简单图表，可放入 docs/。

🔐 安全与权限

强制配置 SECRET_KEY、数据库凭证、LLM Key，不要提交到版本库。
管理员操作集中在 /admin，注意角色控制；定期轮换管理员密码。
如部署公网，建议在反向代理层限制管理端口/IP，开启访问日志与慢查询日志。

🔄 运行与维护小贴士

迁移后若字段不同步，优先执行 python scripts/migrate.py 并重启。
定期备份数据库（全量 + 二进制日志），尤其在大规模改动前。
观察日志：应用日志、MySQL 慢查询、LLM 请求错误码（429/401）。

🤝 贡献指南

Fork & 创建分支：git checkout -b feature/xyz
保持格式与现有风格一致，必要处添加简明注释。
补充/更新相关测试或示例（如新增模型字段时更新迁移脚本）。
提 PR 前自检：pytest、关键脚本运行、README 是否需要更新。

🗺️ Roadmap（示例）

作文评分细粒度可视化（雷达图/趋势图）。
教师批注与版本对比视图。
作文相似度检测与抄袭提醒。
通知/消息中心（邮件或站内信）。
国际化（i18n）与多模型选择的前端配置界面。

Liu-2806/InkSight

README