{"id":50853229,"url":"https://github.com/2002yy/smart-calligraphy-edu","last_synced_at":"2026-06-14T16:03:58.455Z","repository":{"id":362055288,"uuid":"1255038442","full_name":"2002yy/smart-calligraphy-edu","owner":"2002yy","description":"书法教育 AI 评测系统 — 基于 Vue 3 + FastAPI + 阿里云百炼 qwen3.5-omni-plus 的视觉评测平台，教师端管理教学流程，学生端提交作品获取 AI 即时评分反馈","archived":false,"fork":false,"pushed_at":"2026-06-10T16:30:36.000Z","size":32037,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T17:07:13.927Z","etag":null,"topics":["ai","ai-vision","calligraphy","course-project","dashscope","education","fastapi","fullstack","pinia","sqlalchemy","sqlite","vite","vue3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/2002yy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-31T10:20:54.000Z","updated_at":"2026-06-10T16:35:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/2002yy/smart-calligraphy-edu","commit_stats":null,"previous_names":["2002yy/smart-calligraphy-edu"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/2002yy/smart-calligraphy-edu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2002yy%2Fsmart-calligraphy-edu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2002yy%2Fsmart-calligraphy-edu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2002yy%2Fsmart-calligraphy-edu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2002yy%2Fsmart-calligraphy-edu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/2002yy","download_url":"https://codeload.github.com/2002yy/smart-calligraphy-edu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2002yy%2Fsmart-calligraphy-edu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34326240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-vision","calligraphy","course-project","dashscope","education","fastapi","fullstack","pinia","sqlalchemy","sqlite","vite","vue3"],"created_at":"2026-06-14T16:03:57.792Z","updated_at":"2026-06-14T16:03:58.446Z","avatar_url":"https://github.com/2002yy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 智慧书法教学系统 — Smart Calligraphy Education\n\n[![CI](https://github.com/2002yy/smart-calligraphy-edu/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/2002yy/smart-calligraphy-edu/actions/workflows/ci.yml)\n\n\u003e **书法教育 AI 评测系统** — 基于 AI 视觉评测的书法教学平台\n\n---\n\n## 1. 📌 项目一句话定位\n\n**书法教育 AI 评测系统** — 教师端管理教学流程，学生端提交书法作品并获得 AI 即时评分反馈。基于 Vue 3 + FastAPI + 阿里云百炼 qwen3.5-omni-plus 构建。\n\n\u003e ⚠️ **定位说明**：书法教育 AI 评测展示系统，Vue 3 + FastAPI + AI 视觉评测全栈项目。公开课程/项目演示版。\n\n---\n\n## 2. 🖼️ Screenshots / Demo\n\n### 核心展示页面\n\n| 模块 | 截图 | 说明 |\n|------|------|------|\n| 👨‍🏫 教师端 | [教学看板](docs/demo/screenshots/01-teacher-dashboard.png) | 登录后教学看板，左侧选择课程/班级，右侧展示班级统计数据 |\n| 👨‍🏫 教师端 | [任务编排](docs/demo/screenshots/02-task-publish.png) | 发布书法练习任务、设定练习字和评分权重 |\n| 👩‍🎓 学生端 | [学习总览](docs/demo/screenshots/03-student-overview.png) | 学生登录后的学习总览，展示班级、任务和最近反馈 |\n| 👩‍🎓 学生端 | [作品提交](docs/demo/screenshots/04-student-upload.png) | 提交书法作品页面，支持拍照/上传 |\n| 📈 成长档案 | [历史记录](docs/demo/screenshots/05-growth-archive.png) | 历次评分趋势与教师评语 |\n\n![Teacher Dashboard](docs/demo/screenshots/01-teacher-dashboard.png)\n*教师端教学看板 — 班级学习状态与统计数据*\n\n![Task Publish](docs/demo/screenshots/02-task-publish.png)\n*任务编排 — 发布书法训练任务并设定评分权重*\n\n![Student Overview](docs/demo/screenshots/03-student-overview.png)\n*学生学习总览 — 当前任务与最近反馈*\n\n![Submit Upload](docs/demo/screenshots/04-student-upload.png)\n*作品上传 — 拍照/提交书法作业*\n\n![Growth Archive](docs/demo/screenshots/05-growth-archive.png)\n*成长档案 — 历次评分趋势与反馈*\n\n### 🎬 Demo 视频\n\n[![Demo Video](docs/demo/screenshots/01-teacher-dashboard.png)](docs/demo/demo-recording.mp4)\n*点击截图观看完整操作演示（教师登录 → 任务发布 → 学生上传 → AI 评分 → 成长档案）*\n\n\u003e 视频文件: [`docs/demo/demo-recording.mp4`](docs/demo/demo-recording.mp4)\n\u003e 更多截图与录制清单见 [`docs/demo/README.md`](docs/demo/README.md)\n\n---\n\n## 3. ⚡ Tech Stack\n\n| 模块 | 技术 | 说明 |\n|------|------|------|\n| **教师端** | Vue 3 + Vite + Pinia | 教学管理前端（5173） |\n| **学生端** | Vue 3 + Vite + Pinia | 学习空间前端（5174） |\n| **业务后端** | FastAPI + SQLAlchemy | API 服务（8000） |\n| **AI 评测** | qwen3.5-omni-plus (DashScope) | 书法作品智能评分 |\n| **Mock 评测** | 内置 MockEvaluator | 无 API Key 时可用本地演示 |\n| **数据库** | SQLite | 本地开发 |\n| **测试** | Playwright | 端到端烟雾测试 |\n\n---\n\n## 4. 🎯 Core Features\n\n- 👨‍🏫 **教师端** — 教学流程管理、学生作品批阅、评分查看\n- 👩‍🎓 **学生端** — 作品提交、AI 即时评分反馈\n- 🤖 **AI 书法评测** — 基于视觉大模型的书法质量评分（结构/重心/笔法三维）\n- 🔄 **前后端分离** — Vue 3 + FastAPI 标准架构\n- 🎭 **Mock Fallback** — 无 API Key 时使用内置 Mock 评分器演示\n\n---\n\n## 5. 🏗️ Architecture\n\n```\nteacher-web (5173) ─┐\n                      ├─► api-server (8000) ──► SQLite\nstudent-app (5174) ──┘       │\n                              ├──► qwen3.5-omni-plus (DashScope) AI 评测\n                              └──► MockEvaluator (本地回退)\n```\n\n### AI 评测流程\n\n```\n用户上传图片\n  → FastAPI 接收文件\n  → 读取任务/评分权重\n  → 调用 qwen3.5-omni-plus 或 Mock evaluator\n  → 返回 结构/重心/笔法 三维分数\n  → 生成问题标签和练习建议\n  → 前端展示评分和教师复盘入口\n```\n\n---\n\n## 💡 Why This Project Matters\n\n| 维度 | 说明 |\n|------|------|\n| **双端角色系统** | 教师端与学生端独立 SPA，体现真实教育业务流程 |\n| **AI 评测可降级** | Qwen provider + Mock fallback，保证演示稳定，无需 API Key |\n| **权限边界** | 学生只能访问自己的作业，教师只能访问自己课程下的数据 |\n| **工程质量** | pytest(94) + Vitest(15) + Playwright E2E + GitHub Actions CI |\n| **安全意识** | 生产环境 JWT_SECRET 检查、静态资源签名访问、路径穿越防护 |\n\n---\n\n## 6. 🚀 Quick Start\n\n### ✅ 启动前检查清单\n\n克隆后按顺序确认以下步骤：\n\n| # | 步骤 | 说明 |\n|---|------|------|\n| 1 | `cp api-server/.env.example api-server/.env` | 创建后端配置（只需做一次） |\n| 2 | `pip install -r api-server/requirements.txt` | 安装 Python 依赖 |\n| 3 | `npm install`（teacher-web + student-app） | 安装前端依赖 |\n| 4 | 启动后端 → 教师端 → 学生端 | 见下方命令 |\n\n\u003e **Mock 模式开箱即用**：无需 API Key。AI 评测默认走内置 Mock 评分器，`QWEN_EVALUATION_ENABLED=false` 即是 Mock 模式。\n\u003e 需要真实 AI 评测时再配置 Qwen（见 [.env.example](api-server/.env.example)）。\n\n### 前置条件\n- Node.js 18+\n- Python 3.10+\n\n### 本地运行\n\n```bash\n# ① 终端 1：启动后端\ncd api-server\npip install -r requirements.txt\ncp .env.example .env        # 首次只需一次\nuvicorn app.main:app --reload --port 8000\n\n# ② 终端 2：启动教师端\ncd teacher-web\nnpm install                 # 首次只需一次\nnpm run dev\n\n# ③ 终端 3：启动学生端\ncd student-app\nnpm install                 # 首次只需一次\nnpm run dev\n```\n\n### 访问地址\n\n| 端 | 地址 |\n|------|------|\n| 教师端 | http://localhost:5173 |\n| 学生端 | http://localhost:5174 |\n| API 文档 | http://localhost:8000/docs |\n\n---\n\n## 7. 🔐 Permission Matrix\n\n| 资源 | Student | Teacher | Public |\n|------|---------|---------|--------|\n| homework upload | ✅ 自己的 | ❌ | — |\n| homework submit | ✅ 自己的 | ❌ | — |\n| homework list/detail | ✅ 自己的 | ✅ 自己课程下 | — |\n| evaluation start/get | ✅ 自己的 | ✅ 自己课程下 | — |\n| review list/submit | ❌ | ✅  从 token | — |\n| course create | ❌ | ✅  从 token | — |\n| class create/join | ✅ join(自己的) | ✅ create(归属校验) | — |\n| class members | ❌ | ✅ 归属校验 | — |\n| report student | ✅ 自己的 | ✅ | — |\n| report class | ❌ | ✅  | — |\n| user/growth | ✅ 自己的 | ✅ 班级关系校验 | — |\n| static resources | — | — | ✅ 签名 token path 绑定 |\n|  | — | — | ✅ 公开 |\n\n---\n\n## 8. 🗄️ Database Migration\n\nUse Alembic for schema migration. Auto-runs on dev startup; manual for production.\n\n```bash\ncd api-server\nalembic upgrade head           # apply pending migrations\nalembic history                # view migration history\nalembic revision --autogenerate -m \"description\"  # generate from model changes\n```\n\n- **dev** environment: `init_db()` runs `alembic upgrade head`, falls back to `create_all` on failure\n- **production / staging**: migration failure blocks startup (no silent fallback)\n\nConfig in `alembic.ini` + `alembic/env.py` (auto-imports all models).\n\n---\n\n## 9. 🧪 Testing / Quality\n\n| 类型 | 覆盖范围 | 用例数 | 状态 |\n|------|---------|--------|------|\n| **pytest**（后端） | 登录认证、权限校验、Mock 评测、provider 选择、分数范围、思考链、跨用户/跨角色负例、文件存储/overlay、Qwen JSON 提取/白名单过滤 | **94** | ✅ |\n| **Vitest**（前端 store） | 登录/登出、班级、任务、提交、评测、文件选择 | **15** | ✅ |\n| **Playwright**（E2E） | API 冒烟 → 上传 → Mock 评测 → 看板回流 → UI 截图 | **全链路** | ✅ 本地可用，✅ CI 已接入 |\n| API 文档 | FastAPI `/docs` 自动生成 | — | ✅ |\n| Mock Evaluator | 无 API Key 时本地演示 | — | ✅ |\n\n---\n\n## 10. 🛡️ Production Deployment Checklist\n\n外网部署前，请确认以下安全配置（参考 [`api-server/.env.production.example`](api-server/.env.production.example)）：\n\n| # | 配置项 | 强制？ | 说明 |\n|---|--------|--------|------|\n| 1 | `APP_ENV=production` | ✅ | 启用生产模式检查（如 JWT 默认值检测） |\n| 2 | `SECURE_STATIC=true` | ✅ | 静态资源需 Bearer token 或签名路径才能访问 |\n| 3 | `CORS_ORIGINS=...` | ✅ | 限制到实际域名，禁止 `*` |\n| 4 | `JWT_SECRET` 设为随机字符串 | ✅ | 默认 `change_me` 在生产环境会阻止启动 |\n| 5 | `CALLIGRAPHY_FONT_PATH` | ⚠️ | Linux 部署建议安装 `fonts-noto-cjk` 或手动指定路径，否则结果图中文不显示 |\n| 6 | `DATABASE_URL` | ⚠️ | 生产环境建议切换 PostgreSQL/MySQL |\n| 7 | `DEMO_PASSWORD` | ⚠️ | 改默认密码 |\n\n---\n\n### License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F2002yy%2Fsmart-calligraphy-edu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F2002yy%2Fsmart-calligraphy-edu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F2002yy%2Fsmart-calligraphy-edu/lists"}