# learning_incentive

**Repository Path**: alexjunqi/learning_incentive

## Basic Information

- **Project Name**: learning_incentive
- **Description**: 打造一款孩子学习激励App,记录孩子的成功。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 学习激励系统 (Learning Incentive System)

[![Version](https://img.shields.io/badge/version-3.6.0-blue.svg)](https://gitee.com/alexjunqi/learning_incentive)
[![Frappe](https://img.shields.io/badge/Frappe-16.x-green.svg)](https://frappe.io)
[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)

> 基于 Frappe/ErpNext 框架的学生学习激励管理应用，支持学生日报、家长审核、积分兑换、错题本、AI 智能辅导与知识图谱。

## 📋 目录

- [功能特性](#功能特性)
- [技术架构](#技术架构)
- [安装部署](#安装部署)
- [使用指南](#使用指南)
- [系统截图](#系统截图)
- [API 接口](#api-接口)
- [版本历史](#版本历史)
- [下一步计划](#下一步计划)
- [贡献者](#贡献者)

---

## ✨ 功能特性

### 学生端
- 📊 **学习看板**：实时展示积分、段位、连续打卡天数、本周统计
- 📝 **每日日报**：添加学习任务、上传多张照片、自评质量等级
- 📚 **我的日报**：历史日报列表、月度趋势图表
- 🎁 **任务领取**：领取家长/老师布置的专项任务
- 🏦 **时间银行**：积分兑换奖励、查看交易历史
- 📖 **错题本**：结构化录入错题，支持照片上传
- 🔄 **遗忘曲线复习**：基于 SM-2 算法的闪卡复习，自动调度复习时间，复习参数可在「闪卡设置」中配置，答对与完成当日复习可获积分
- 🤖 **AI 智能辅导**：AI 对话解答错题、自动分析错误原因和知识点
- 🧠 **AI 知识图谱**：知识点掌握度三色图谱 + 关联网络，薄弱点一目了然
- 📷 **拍照识别**：上传错题照片，AI 视觉识别自动分类并填充题目信息
- 🃏 **卡片集**：单词卡/背诵卡闪卡复习，家长可自建卡片集，与错题共用 SM-2 调度与积分体系
- ⚔️ **习题闯关**：知识点关卡 5 题挑战，手动题库 + AI 补题，3/2/1 星评级与积分奖励
- 🆚 **异步对战**：同学间同知识点 PK，答对数定胜负（平手比用时），胜者额外奖励

### 家长端
- ✅ **逐任务审核**：查看任务照片，逐条通过/驳回并评语
- 📤 **日报提交**：所有任务审核通过后提交日报，积分即时发放
- 📋 **任务布置**：为孩子布置学习任务并设定积分奖励
- 📈 **学习统计**：查看孩子周报、科目分布、质量分布
- 🧠 **错题与知识图谱**：查看孩子错题、复习进度与知识点掌握度（多孩子可切换）

### 教师端（Desk 后台）
- 📋 **批量任务**：按班级/学生群组批量布置学习任务
- 📖 **错题记录**：工作区「错题与图谱」分组，可按学生/科目/状态筛选全部错题
- 🧠 **学生知识图谱报表**：按学生×科目×知识点汇总错题数、掌握度与薄弱标记
- 📈 **学习统计**：查看学生学习数据与积分排名

### Desk 后台管理（工作区「学习激励」）
- **日报管理**：学习日报、日报任务项
- **审核管理**：审核记录、审核项
- **学生与积分**：学生档案、积分流水、段位历史
- **错题与图谱**：错题记录、知识点、知识点关联、学生知识图谱报表、卡片集、卡片
- **闯关对战**：闯关题库、闯关记录、对战记录
- **系统设置**：赛季配置、段位阈值、AI 配置、AI 使用统计（报表）、AI 模型计费、闪卡设置

### 系统特性
- 📱 **移动端适配**：基于 Vue 3 SPA 的响应式移动端界面
- 🔐 **微信登录**：支持微信 OAuth 授权登录
- 🔔 **消息提醒**：日报提醒、家长审核提醒（定时任务）
- 🏆 **段位系统**：青铜→白银→黄金→铂金→钻石→大师
- 📅 **自动提交**：每日 22:00 自动提交未处理日报（可配置）
- 📥 **Anki 导出**：错题可导出为 .apkg 文件，导入 Anki 客户端
- 🤖 **AI 集成**：Desk「AI 配置」页面管理 API Key / 接口地址 / 模型，支持测试连接；优先于 site_config
- 💰 **AI 用量计费**：全部 AI 调用自动记账（用户/学生/模型/tokens/费用/成败），Desk「AI 使用统计」报表按日聚合，「AI 模型计费」维护各模型单价

---

## 🏗 技术架构

| 层级 | 技术栈 |
|------|--------|
| 后端框架 | Frappe 16.x + Python 3.14 |
| 前端框架 | Vue 3 + Vite + Vue Router + Pinia |
| 数据库 | MariaDB (MySQL兼容) |
| 缓存 | Redis |
| 认证 | Frappe Session + 微信 OAuth |
| 定时任务 | Frappe Scheduler |
| AI 服务 | OpenAI 兼容 API (可接 GPT/DeepSeek/文心一言等；识图需视觉模型) |
| 闪卡算法 | SM-2 遗忘曲线 |
| 图谱可视化 | 手写 SVG（无图表库依赖） |

### 核心 DocType

| DocType | 说明 |
|---------|------|
| `Learning Daily Report` | 学习日报主表 |
| `Daily Task Item` | 日报任务子表（支持多照片） |
| `Task Photo` | 任务照片子表 |
| `Assigned Task` | 布置任务表 |
| `Student Profile` | 学生档案（积分/段位/时间银行） |
| `Review Record` | 审核记录 |
| `Season Config` | 赛季配置 |
| `Season Summary` | 赛季汇总 |
| `Rank Threshold` | 段位阈值 |
| `Wrong Question` | 错题本（照片、知识点标签、遗忘曲线复习、知识点结构化关联） |
| `Wrong Question Knowledge Point` | 错题-知识点关联子表 |
| `Knowledge Point` | 知识点库（跨学生共享，支持章节层级） |
| `Knowledge Edge` | 知识点关联（AI 建议/共现） |
| `AI Settings` | AI 配置（API Key / 接口地址 / 模型，单例） |
| `AI Usage Log` | AI 调用记账（tokens/费用/成败） |
| `AI Model Price` | AI 模型单价维护（元/百万 tokens） |
| `Flashcard Settings` | 闪卡设置（复习间隔/每日上限/回退策略/积分/提醒，单例） |
| `Flashcard Deck` | 卡片集（单词卡/背诵卡/自定义，家长自建） |
| `Flashcard` | 闪卡（正面/背面/标签） |
| `Flashcard Progress` | 每生每卡复习进度（SM-2 阶段） |
| `Review Log` | 复习记录（错题/闪卡作答，含用时） |
| `Challenge Question` | 闯关题库（手动/AI，关联知识点） |
| `Quiz Session` | 闯关/对战答题记录（星级/积分/明细） |
| `Quiz Battle` | 异步对战（双方记录/胜负结算） |
| `Wechat Settings` | 微信 OAuth/JSSDK 支付配置 |
| `Weixin Openid` | 微信 OpenID 绑定 |

---

## 🚀 安装部署

### 环境要求
- Frappe Bench 环境
- Python 3.10+
- Node.js 18+
- MariaDB 10.6+
- Redis 6+

### 安装步骤

```bash
# 1. 进入 bench 目录
cd /path/to/frappe-bench

# 2. 获取应用
bench get-app https://gitee.com/alexjunqi/learning_incentive.git

# 3. 安装到站点
bench --site your-site.local install-app learning_incentive

# 4. 构建前端资源
cd apps/learning_incentive/frontend && yarn build && cd -

# 5. 重启服务
bench restart
```

### 微信登录配置
在 **Wechat Settings** 中配置：
- 微信 AppID
- 微信 AppSecret
- OAuth 回调地址（可选，默认可由请求动态生成）

### AI 功能配置
Desk → 工作区「学习激励」→ 系统设置 → **AI 配置**：
- API Base URL（如 `https://api.openai.com/v1` 或 `https://api.deepseek.com`）
- API Key（加密存储）
- 模型（如 `gpt-4o-mini`、`deepseek-chat`）
- 保存后点「测试连接」验证

说明：
- Key 留空时回退读取 `site_config.json` 的 `ai_api_key` / `ai_api_base` / `ai_model`
- 拍照识别需要**视觉模型**（如 gpt-4o-mini、deepseek-chat/flash）；纯文本/推理模型（如 deepseek-reasoner）会自动隐藏识图入口
- 在「AI 模型计费」维护单价后，「AI 使用统计」报表自动折算费用

---

## 📖 使用指南

### 学生操作流程
1. 登录系统（首页 → 学生看板）
2. 点击"添加学习任务"，填写任务内容、时长、质量等级
3. 上传任务照片（支持多选）
4. 点击"提交日报"，等待家长审核

### 错题本使用流程
1. 进入"学习平台" → "错题本"
2. 点击右下角"+"按钮录入错题
3. 可上传照片后点照片上的「AI 识图」自动识别题目（需视觉模型）；或点「AI 自动分析」填充错误分析/知识点/难度
4. 练习卷可「批量导入」：上传 PDF/图片/TXT，AI 逐题提取并自动归类建档（支持扫描版 PDF，带批改痕迹的题目标记建议收录；阅读理解等带原文题型自动保留原文写入错题正文）
5. 在"错题本"页面点击顶部「闪卡复习」卡片进入闪卡模式
6. 点击卡片翻面查看答案，选择"认识"或"不认识"
7. 系统自动按遗忘曲线调度下次复习时间

### 知识图谱使用流程
1. 进入"学习平台" → "知识图谱"
2. 选择科目查看掌握度视图：绿色（≥75）/ 黄色（45-75）/ 红色（<45）
3. 点击知识点查看关联错题；切「关联网络」查看知识点依赖关系
4. 点「✨ AI 分析关联」让 AI 生成关联建议
5. 红色薄弱知识点可一键生成「专项复习」队列（不管是否到期）

### 卡片集与 Anki 导入
1. 家长在 Desk「错题与图谱」→ 卡片集：新建单词卡/背诵卡集合并添加卡片（可指定学生或公开）
2. 学生端复习队列自动并入卡片集卡片，与错题共用每日上限与积分
3. 外部 Anki 牌组可在错题本导入（.apkg，正面/背面/错误答案/错误分析四字段，tags 自动转为知识点）

### 家长操作流程
1. 登录系统（首页 → 家长审核）
2. 查看孩子今日日报及任务照片
3. 逐条审核任务：通过 ✅ / 驳回 ❌，可添加评语
4. 所有任务审核完成后，点击"提交日报"，积分自动发放
5. 在错题本/知识图谱查看孩子学习情况（多孩子可切换）

### 管理员/教师（Desk 后台）
1. Desk → 工作区「学习激励」
2. 「错题与图谱」→ 错题记录：浏览/筛选全部学生错题
3. 「学生知识图谱」报表：按学生/科目查看知识点掌握度与薄弱点
4. 「系统设置」→ AI 配置 / AI 使用统计 / AI 模型计费：管理 AI 服务与成本

---

## 📸 系统截图

### 学生看板
- 积分、段位、连续打卡展示
- 今日日报任务列表（含照片缩略图）
- 本周学习统计、科目分布、质量分布

### 错题本
- 错题列表（支持按科目/状态/难度筛选）
- 闪卡复习界面（正面题目/背面答案）
- AI 对话辅导面板

### 知识图谱
- 知识点掌握度三色视图（按章节分组）
- 知识点关联网络（SVG 交互图）
- 点击知识点查看关联错题

### 家长审核中心
- 待审核日报列表
- 逐任务照片查看与放大
- 通过/驳回操作与评语
- 孩子学习统计图表

### 时间银行
- 当前余额展示
- 兑换商品列表
- 交易历史记录

---

## 🔌 API 接口

### 学生接口
| 接口 | 方法 | 说明 |
|------|------|------|
| `learning_incentive.api.student_api.get_or_create_today_report` | POST | 获取/创建今日日报 |
| `learning_incentive.api.student_api.submit_task` | POST | 添加/更新任务（支持多照片） |
| `learning_incentive.api.student_api.submit_daily_report` | POST | 学生提交日报（待审核状态） |
| `learning_incentive.api.student_api.get_pending_assigned_tasks` | GET | 获取待领取任务 |
| `learning_incentive.api.student_api.claim_assigned_task` | POST | 领取任务 |
| `learning_incentive.api.student_api.get_my_reports` | GET | 获取历史日报列表 |
| `learning_incentive.api.student_api.get_monthly_stats` | GET | 获取月度统计 |
| `learning_incentive.api.student_api.get_weekly_breakdown` | GET | 获取本周科目/质量分布 |
| `learning_incentive.api.student_api.get_streak_calendar` | GET | 获取打卡日历 |
| `learning_incentive.api.student_api.get_rejected_tasks` | GET | 获取被驳回任务 |
| `learning_incentive.api.student_api.get_leaderboard` | GET | 获取排行榜 |

### 家长接口
| 接口 | 方法 | 说明 |
|------|------|------|
| `learning_incentive.api.spa_api.get_parent_review_data` | GET | 获取审核页数据 |
| `learning_incentive.api.spa_api.get_parent_review_report` | GET | 获取日报详情 |
| `learning_incentive.api.spa_api.parent_review_task` | POST | 审核单条任务 |
| `learning_incentive.api.spa_api.parent_submit_daily_report` | POST | 家长提交日报 |
| `learning_incentive.api.spa_api.get_child_weekly_stats` | GET | 获取孩子周统计 |
| `learning_incentive.api.parent_api.create_assigned_task` | POST | 布置任务 |
| `learning_incentive.api.parent_api.get_my_assigned_tasks` | GET | 查看已布置任务 |

### 错题本接口
| 接口 | 方法 | 说明 |
|------|------|------|
| `learning_incentive.api.wrong_question_api.create_wrong_question` | POST | 创建错题（支持 `kp_titles` 知识点数组） |
| `learning_incentive.api.wrong_question_api.update_wrong_question` | POST | 更新错题（支持 `kp_titles`） |
| `learning_incentive.api.wrong_question_api.delete_wrong_question` | POST | 删除错题 |
| `learning_incentive.api.wrong_question_api.get_wrong_questions` | GET | 获取错题列表 |
| `learning_incentive.api.wrong_question_api.get_wrong_question_detail` | GET | 获取错题详情（含 `kp_links`） |
| `learning_incentive.api.wrong_question_api.mark_reviewed` | POST | 标记已复习 |
| `learning_incentive.api.wrong_question_api.get_wrong_question_stats` | GET | 获取错题统计 |
| `learning_incentive.api.wrong_question_api.export_wrong_questions` | GET | 导出 JSON 供 AI 分析 |
| `learning_incentive.api.wrong_question_api.get_today_review_questions` | GET | 获取今日待复习错题 |
| `learning_incentive.api.wrong_question_api.submit_review_result` | POST | 提交复习结果（SM-2 调度） |
| `learning_incentive.api.wrong_question_api.get_review_stats` | GET | 获取复习统计 |
| `learning_incentive.api.wrong_question_api.export_to_anki_apkg` | GET | 导出 Anki .apkg 文件 |
| `learning_incentive.api.wrong_question_api.import_anki_apkg` | POST | 导入 Anki .apkg 为错题（tags 转知识点） |

### 闪卡接口
| 接口 | 方法 | 说明 |
|------|------|------|
| `learning_incentive.api.flashcard_api.get_decks` | GET | 卡片集列表（学生/家长视角，含卡数与今日待复习） |
| `learning_incentive.api.flashcard_api.create_deck` | POST | 创建卡片集（家长/教师） |
| `learning_incentive.api.flashcard_api.update_deck` | POST | 更新卡片集（owner） |
| `learning_incentive.api.flashcard_api.delete_deck` | POST | 删除卡片集（连带卡片与进度） |
| `learning_incentive.api.flashcard_api.get_deck_cards` | GET | 卡片集详情与卡片（学生视角带进度） |
| `learning_incentive.api.flashcard_api.save_card` | POST | 新建/更新卡片 |
| `learning_incentive.api.flashcard_api.delete_card` | POST | 删除卡片（连带进度） |
| `learning_incentive.api.flashcard_api.get_flashcard_review` | GET | 学生闪卡复习队列（含答对/答错间隔提示） |
| `learning_incentive.api.flashcard_api.submit_flashcard_review` | POST | 提交闪卡复习（SM-2 调度+积分+复习记录） |
| `learning_incentive.api.flashcard_api.get_review_weekly_stats` | GET | 本周复习统计（次数/正确率/用时/天数） |

### 闯关对战接口
| 接口 | 方法 | 说明 |
|------|------|------|
| `learning_incentive.api.quiz_api.get_quiz_levels` | GET | 闯关关卡列表（弱 KP 优先，含库存题数/最佳星级） |
| `learning_incentive.api.quiz_api.start_quiz` | GET | 开始闯关取题（手动优先，AI 补齐，不带答案） |
| `learning_incentive.api.quiz_api.submit_quiz` | POST | 提交答卷判分（星级/积分/明细，对战自动结算） |
| `learning_incentive.api.quiz_api.create_battle` | POST | 发起对战（随机 5 题，通知对方） |
| `learning_incentive.api.quiz_api.get_my_battles` | GET | 我的对战（待我应战/待对方/已完成） |
| `learning_incentive.api.quiz_api.accept_battle` | GET | 接受对战并取题 |

### 知识图谱接口
| 接口 | 方法 | 说明 |
|------|------|------|
| `learning_incentive.api.knowledge_api.get_knowledge_graph_data` | GET | 获取图谱数据（科目列表/节点/边/掌握度） |
| `learning_incentive.api.knowledge_api.list_kp_questions` | GET | 获取某知识点关联的错题 |

### AI 接口
| 接口 | 方法 | 说明 |
|------|------|------|
| `learning_incentive.api.ai_api.get_ai_config` | GET | 获取 AI 配置状态（enabled/model/vision） |
| `learning_incentive.api.ai_api.test_ai_connection` | POST | 测试 AI 连接（仅 System Manager） |
| `learning_incentive.api.ai_api.chat_with_ai` | POST | 就错题与 AI 对话 |
| `learning_incentive.api.ai_api.analyze_question` | POST | AI 自动分析错题（文本） |
| `learning_incentive.api.ai_api.analyze_question_photo` | POST | AI 视觉识别错题照片（需视觉模型） |
| `learning_incentive.api.ai_api.generate_knowledge_graph` | POST | AI 生成知识点关联建议 |

### 公共接口
| 接口 | 方法 | 说明 |
|------|------|------|
| `learning_incentive.api.common.get_home_data` | GET | 获取首页数据 |
| `learning_incentive.api.common.consume_time_bank` | POST | 消费时间银行 |
| `learning_incentive.api.common.get_student_time_bank` | GET | 获取时间银行余额 |
| `learning_incentive.api.common.get_pending_reviews_for_parent` | GET | 家长获取待审核列表 |
| `learning_incentive.api.spa_api.get_my_notifications` | GET | 我的站内通知（最近 20 条） |
| `learning_incentive.api.spa_api.mark_notification_read` | POST | 标记通知已读 |

---

## 📝 版本历史

### v3.1.0 (2026-09-24)
- ✅ **AI 知识图谱**：掌握度三色图谱 + 关联网络（SVG），AI 生成关联建议，共享知识点库
- ✅ **拍照识别**：AI 视觉识别错题照片，自动填充题目/科目/难度/知识点
- ✅ **AI 用量与计费**：全量调用记账、模型单价维护、Desk「AI 使用统计」报表
- ✅ **Desk 错题与图谱管理**：错题记录列表、知识点库、学生知识图谱报表
- ✅ **闪卡入口常显**：无待复习时也可进入自主复习
- ✅ **AI 配置页面**：Desk 单例页面管理 Key/Base/模型，支持测试连接

### v3.0.0 (2026-05-10)
- ✅ **错题本系统**：结构化录入、照片上传、知识点标签
- ✅ **遗忘曲线复习**：SM-2 算法自动调度，闪卡式复习界面
- ✅ **AI 智能辅导**：AI 对话解答、自动分析错误原因和知识点
- ✅ **Anki 导出**：错题可导出为 .apkg 文件
- ✅ **学习看板增强**：周报图表、科目分布、质量分布、打卡日历
- ✅ **我的日报**：历史日报列表、月度趋势
- ✅ **代码重构**：提取公共工具函数、统一 SQL 参数格式

### v2.0.0 (2026-05-02)
- ✅ 前端架构重构（Vue 3 SPA）
- ✅ 统一登录重定向
- ✅ 学生逐任务填写、家长逐任务审核
- ✅ 被驳回任务可修改后重新提交
- ✅ 照片上传与保存优化

### v1.0.0 (2025-04)
- ✅ 学生日报管理
- ✅ 家长审核功能
- ✅ 积分与段位系统
- ✅ 时间银行兑换
- ✅ 任务布置与领取
- ✅ 赛季配置

---

## 🗺 下一步计划

### 闪卡设置中心 ✅（v3.2.0 已完成）
- ✅ **复习参数可配置**：新增「闪卡设置」单例（Desk 系统设置），支持自定义复习间隔序列（默认 0/1/2/4/7/15/30 天）、每日复习上限、答错回退策略
- ✅ **复习积分联动**：答对/完成今日复习自动发放积分（接入积分流水），激励连续性
- ✅ **复习提醒**：每日到点未复习时站内提醒（每 30 分钟检查，每生每天一次）

### 闪卡应用深化
- ✅ **薄弱点专项闪卡组**（v3.3.0）：红色薄弱知识点一键生成专项复习队列（`get_weak_review_questions`）
- ✅ **卡片类型扩展**（v3.3.0）：英语单词卡、语文背诵卡（正面词/背面释义），家长可自建卡片集
- ✅ **Anki 导入**（v3.3.0）：与现有 .apkg 导出互逆，外部牌组一键导入
- ✅ **复习数据统计**（v3.3.0）：正确率/时长/连续天数进入周报图表（Review Log + `get_review_weekly_stats`）

### 其他
- ✅ **习题闯关 / 对战模式**（v3.4.0 已完成）：手动题库 + AI 补题闯关、异步对战自动结算
- ✅ **应用内周报**（v3.4.0 已完成）：每周一中文周报站内推送（学生+家长）
- ✅ **文件批量导入错题**（v3.5.0）：PDF/图片/TXT 上传，AI 提取题目、标记错题、批量归类建档，阅读原文自动保留
- ✅ **前端体验批次 A**（v3.6.0）：全局 Toast/确认弹窗、二级页沉浸导航、刘海屏适配、401 自动跳登录、照片客户端压缩
- AI 模型计费价格持续维护

### 待做（前端体验批次 B）
- 闪卡滑动手势 + 键盘快捷键
- LaTeX 公式 / Markdown 渲染（理科错题与 AI 辅导）
- 家长审核「一键全过」+ 快捷评语 + 图片旋转缩放
- 表单草稿自动保存（LocalStorage）
- 对战实时化（socketio 已具备条件）、周报微信模板消息推送

---

## 👥 贡献者

- **开发者**: alexjunqi
- **联系方式**: [Gitee](https://gitee.com/alexjunqi)

---

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

---

> 🌟 如果本项目对您有帮助，请给个 Star！