# 儿童学习辅助 **Repository Path**: dujun_h5/childrens-learning-assistance ## Basic Information - **Project Name**: 儿童学习辅助 - **Description**: 66666666776 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-01 - **Last Updated**: 2026-07-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 暑假学习小管家 StudyBuddy > 一款面向小学二年级儿童的暑假学习监督系统，帮助家长为孩子规划每日学习计划， > 并通过摄像头实时监督学习过程，培养孩子自主学习习惯。 后端基于 **Python Flask + SQLite**，前端采用 **原生 HTML / CSS / JavaScript**（不依赖任何前端框架）， 整体轻量、易部署，可打包为 Windows 桌面程序（EXE）与 Android 应用（APK）。 --- ## 目录 - [功能特性](#功能特性) - [技术栈](#技术栈) - [项目结构](#项目结构) - [开发环境运行](#开发环境运行) - [EXE 打包（Windows）](#exe-打包windows) - [APK 打包（Android）](#apk-打包android) - [API 接口文档](#api-接口文档) - [默认任务数据说明](#默认任务数据说明) --- ## 功能特性 - **52 天暑假计划**：覆盖 2026 年 7 月 11 日 ~ 8 月 31 日，每天动态生成 11 项任务。 - **每日学习计划**：按上午 / 下午 / 晚间三个时段组织任务，时间线式展示，支持日期切换。 - **上午 5 项基础任务**： - 字帖练一张（附页1，50 页循环） - 数学练习（前 15 天「快乐一练」必做，第 16 天起「每日一练」） - 背诵闯关（附件2，23 关，**艾宾浩斯遗忘曲线**排程：新学 + 第 1/2/4/7/15 天复习） - 语文阅读（附件3，28 篇范文循环） - 英语阅读（「一起学习」APP） - **下午渐进式课程**：52 套不重复课程，分 5 阶段（基础入门→进阶巩固→综合应用→创意拓展→挑战总结）。 - **晚间任务**：观看纪录片（52 部清单，每天 1 部）+ 绘本阅读 20 分钟。 - **多学科分类**：支持语文、数学、英语、电脑应用、智能体认知、少儿纪录片分类筛选。 - **三种完成方式**： - `manual` 手动打勾 —— 孩子自行勾选完成。 - `auto` 自动验证 —— 电脑答题类任务，按进度自动判定完成（0~100%）。 - `parent` 家长确认 —— 需家长点击「家长确认」按钮通过。 - **暑假日历**：52 天日历网格，每格显示当天完成度，点击切换查看任意一天。 - **键盘练习**：可视化键盘交互训练，支持**真实键盘 keydown** 与点击双模式。 - **智能体认知**：15 个 AI 主题知识探索，配套 `wiki/ai-agent.md` 学习文档。 - **学习监督**：书房视频画面（展示用）。 - **学习进度统计**： - 顶部统计条：今日待办、已完成、学习时长、连续打卡天数。 - 总进度环形图与各学科完成进度。 - **待办管理**：弹窗新增任务（名称、学科、时段、开始时间、时长、完成方式）。 - **端口自动检测**：默认 5000，被占用自动切换 5001~5009。 - **响应式布局**：适配桌面与移动端屏幕。 - **跨平台打包**：支持 PyInstaller 打包 EXE、Buildozer 打包 APK。 --- ## 技术栈 | 层级 | 技术 | 说明 | | ---- | ---- | ---- | | 后端框架 | Python Flask | 轻量 Web 框架，提供 API 与静态文件服务 | | 数据存储 | SQLite | 嵌入式数据库，存储任务与统计数据，无需额外服务 | | 模板引擎 | Jinja2 | Flask 内置，用于渲染页面（可选） | | 前端 | 原生 HTML / CSS / JavaScript | 无框架依赖，纯静态资源 | | 桌面打包 | PyInstaller | 将 Flask 应用打包为单文件 Windows EXE | | 移动打包 | Buildozer + python-for-android | 构建 Android APK | **核心依赖**（`requirements.txt`）： ``` flask ``` > Flask 会自动安装 `werkzeug`、`jinja2`、`markupsafe`、`click`、`itsdangerous`、`blinker`。 > `sqlite3` 为 Python 标准库模块，无需额外安装。 --- ## 项目结构 ``` childrens-learning-assistance/ ├── run.py # Flask 应用入口（端口自动检测 5000~5009） ├── requirements.txt # Python 依赖清单 ├── README.md # 项目说明文档（本文件） ├── .gitignore # Git 忽略规则 │ ├── app/ # Flask 应用包 │ ├── __init__.py # 包标识 │ ├── main.py # Flask 应用与 REST API 路由 │ ├── database.py # SQLite 数据访问层 + 52 天任务生成器 │ └── static/ # 前端静态资源（Flask 直接服务） │ ├── index.html # 单页前端 │ ├── css/style.css # 样式（含日历/键盘/AI 弹窗） │ ├── js/app.js # 前端逻辑（含键盘 keydown 监听） │ └── wiki/ # 智能体认知 MD 文档 │ └── ai-agent.md # 什么是智能体（AI 小助手） │ ├── 附件/ # 暑假作业原始资料 │ ├── 附页1.pdf # 字帖（50 页） │ ├── 附件2.pdf # 背诵闯关表（23 关） │ ├── 附件3.pdf # 语文写作范文（28 篇） │ └── 附件4.docx # 数学快乐一练（15 篇） │ └── packaging/ # 打包相关配置与脚本 ├── build_exe.spec # PyInstaller 打包配置（EXE） ├── build_exe.py # EXE 自动打包脚本 ├── buildozer.spec # Buildozer 配置（APK） └── build_apk.sh # APK 构建脚本 ``` > 运行时生成的 SQLite 数据库文件默认位于 `data/` 目录，已被 `.gitignore` 忽略。 --- ## 开发环境运行 ### 1. 环境要求 - Python 3.9 及以上 - pip（随 Python 安装） ### 2. 克隆并安装依赖 ```bash cd childrens-learning-assistance # （推荐）创建并激活虚拟环境 python -m venv venv # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate # 安装依赖 pip install -r requirements.txt # 或直接安装 pip install flask ``` ### 3. 启动应用 ```bash python run.py ``` 启动成功后控制台输出类似： ``` * Serving Flask app 'app' * Running on http://127.0.0.1:5000 ``` 浏览器访问 即可使用。 ### 4. 开发模式 如需修改代码后自动重载，可设置环境变量： ```bash # Linux / macOS export FLASK_ENV=development export FLASK_DEBUG=1 python run.py # Windows (PowerShell) $env:FLASK_ENV="development" $env:FLASK_DEBUG=1 python run.py ``` --- ## EXE 打包（Windows） 将应用打包为单文件 Windows 可执行程序，无需安装 Python 即可运行。 ### 前置条件 ```bash pip install pyinstaller flask ``` ### 方式一：直接使用 spec 文件（推荐） ```bash cd packaging pyinstaller build_exe.spec ``` ### 方式二：使用打包脚本（自动校验与清理） ```bash cd packaging # 常规打包 python build_exe.py # 打包前清理上一次的 build/ 与 dist/ 目录 python build_exe.py --clean # 禁用 UPX 压缩 python build_exe.py --clean --no-upx ``` ### 打包结果 打包完成后，产物位于： ``` packaging/dist/StudyBuddy.exe ``` 双击 `StudyBuddy.exe` 即可启动应用，浏览器访问 。 > `build_exe.spec` 已配置： > - 单文件（onefile）模式 > - windowed 模式（无控制台黑窗） > - 自动收集 `app/static`、`app/templates` 数据文件 > - 收集 Flask 及其依赖的数据文件（datas） > - 显式声明 hidden imports，避免运行时 `ImportError` > - 图标（icon）留空，后续可在 spec 中 `icon='assets/studybuddy.ico'` 指定 --- ## APK 打包（Android） 将应用打包为 Android 安装包。 ### 重要环境要求 - **必须运行在 Linux 环境**（推荐 Ubuntu 20.04 / 22.04），**不支持** Windows / macOS 直接构建。 - 需安装系统依赖： ```bash sudo apt update sudo apt install -y autoconf automake libtool pkg-config zip unzip \ ccache git openjdk-17-jdk ``` - 安装 buildozer： ```bash pip install buildozer ``` - 首次构建会自动下载 Android SDK / NDK 与 python-for-android，耗时约 30~60 分钟；后续构建使用缓存，速度较快。 ### 构建步骤 ```bash cd packaging # 赋予执行权限（首次） chmod +x build_apk.sh # 执行构建 ./build_apk.sh ``` 脚本会： 1. 检查 buildozer 是否安装； 2. 检查 buildozer.spec 与 Java 环境； 3. 执行 `buildozer android debug`； 4. 输出 APK 文件路径。 ### 打包结果 ``` packaging/bin/StudyBuddy-0.1-debug.apk ``` ### 安装到设备 ```bash adb install packaging/bin/StudyBuddy-0.1-debug.apk ``` > `buildozer.spec` 已配置： > - 应用名 `StudyBuddy`，包名 `com.dujun.studybuddy`，版本 `0.1` > - 基于 Python 3，依赖 `flask` > - 包含 `app/` 下所有 .py 源码与 `run.py`，以及 static 资源 > - 竖屏（portrait）方向 > - 目标 Android API 31，最低 API 21 > - 权限：`INTERNET`（网络/本地服务）、`CAMERA`（学习监督摄像头功能） > > **提示**：python-for-android 默认从 `main.py` 启动。本项目入口为 `run.py`， > 建议在项目根目录放置 `main.py` 包装器（内容如 `import run; run.main()`）， > 或在打包前将 `run.py` 复制为 `main.py`，以确保 APK 可正常启动。 --- ## API 接口文档 所有接口均以 `/api` 为前缀，返回 JSON 格式数据。任务对象字段定义见下文 [默认任务数据说明](#默认任务数据说明)。 ### 1. 获取任务列表 ``` GET /api/tasks ``` **查询参数（可选）** | 参数 | 类型 | 说明 | | ---- | ---- | ---- | | `block` | string | 按时段筛选：`morning` / `afternoon` / `evening` | | `subj` | string | 按学科筛选：`yu` / `shu` / `ying` / `pc` / `ai` / `doc` | **响应示例** ```json { "code": 0, "data": [ { "id": 1, "block": "morning", "time": "08:30", "dur": 30, "subj": "yu", "title": "晨读 · 古诗背诵《咏柳》", "type": "manual", "done": false, "auto": 0 } ] } ``` ### 2. 获取单个任务 ``` GET /api/tasks/ ``` 返回对应 `id` 的任务对象，未找到时返回 `404`。 ### 3. 新增任务 ``` POST /api/tasks Content-Type: application/json ``` **请求体** ```json { "block": "morning", "time": "09:00", "dur": 30, "subj": "shu", "title": "完成数学口算第 5 页", "type": "manual" } ``` | 字段 | 类型 | 必填 | 说明 | | ---- | ---- | ---- | ---- | | `title` | string | 是 | 任务名称 | | `subj` | string | 是 | 学科：`yu`/`shu`/`ying`/`pc`/`ai`/`doc` | | `block` | string | 是 | 时段：`morning`/`afternoon`/`evening` | | `time` | string | 是 | 开始时间，`HH:MM` | | `dur` | int | 是 | 时长（分钟） | | `type` | string | 是 | 完成方式：`manual`/`auto`/`parent` | **响应**：返回新建任务（含自动分配的 `id`），`done=false`，`auto` 按类型初始化。 ### 4. 更新任务 ``` PUT /api/tasks/ Content-Type: application/json ``` **请求体（部分字段即可）** ```json { "done": true, "auto": 100 } ``` 可更新字段：`title`、`subj`、`block`、`time`、`dur`、`type`、`done`、`auto`。 **响应**：返回更新后的完整任务对象。 ### 5. 删除任务 ``` DELETE /api/tasks/ ``` **响应** ```json { "code": 0, "message": "deleted" } ``` ### 6. 获取统计信息 ``` GET /api/stats ``` **响应示例** ```json { "code": 0, "data": { "total": 10, "done": 3, "percent": 30, "study_hours": 1.2, "streak_days": 7, "subjects": { "yu": { "done": 1, "total": 3 }, "shu": { "done": 1, "total": 2 }, "ying": { "done": 1, "total": 1 }, "pc": { "done": 0, "total": 4 }, "doc": { "done": 0, "total": 1 } } } } ``` | 字段 | 说明 | | ---- | ---- | | `total` | 今日待办总数 | | `done` | 已完成数 | | `percent` | 总完成百分比 | | `study_hours` | 已完成任务累计学习时长（小时） | | `streak_days` | 连续打卡天数 | | `subjects` | 各学科完成情况（`pc` 含电脑应用与智能体） | ### 7. 今日纪录片 ``` GET /api/documentary ``` **响应示例** ```json { "code": 0, "data": { "title": "《地球脉动》极地之美", "category": "自然地理 · 第 3 部", "duration": 25, "description": "跟随镜头走进南北极，看企鹅如何在冰天雪地中生存……", "watched": false } } ``` 标记为已观看： ``` PUT /api/documentary Content-Type: application/json { "watched": true } ``` --- ## 默认任务数据说明 系统首次启动时会写入 10 条默认任务（二年级暑假学习计划），对应前端 `tasks` 数组。任务对象（Task）字段定义如下： | 字段 | 类型 | 说明 | 取值示例 | | ---- | ---- | ---- | ---- | | `id` | int | 任务唯一标识 | `1` | | `block` | string | 所属时段 | `morning` 上午 / `afternoon` 下午 / `evening` 晚间 | | `time` | string | 开始时间（24h） | `"08:30"` | | `dur` | int | 时长（分钟） | `30` | | `subj` | string | 学科分类 | `yu` 语文 / `shu` 数学 / `ying` 英语 / `pc` 电脑应用 / `ai` 智能体 / `doc` 纪录片 | | `title` | string | 任务名称 | `"晨读 · 古诗背诵《咏柳》"` | | `type` | string | 完成方式 | `manual` 手动 / `auto` 自动验证 / `parent` 家长确认 | | `done` | bool | 是否完成 | `false` | | `auto` | int | 自动验证进度（仅 `auto` 类型有效） | `0`~`100` | ### 默认 10 条任务清单 | id | 时段 | 时间 | 学科 | 任务名称 | 完成方式 | | -- | ---- | ---- | ---- | -------- | -------- | | 1 | 上午 | 08:30 | 语文 | 晨读 · 古诗背诵《咏柳》 | 手动打勾 | | 2 | 上午 | 09:10 | 数学 | 数学口算闯关（电脑答题） | 自动验证 | | 3 | 上午 | 10:00 | 英语 | 英语单词跟读 + 拼写练习 | 家长确认 | | 4 | 上午 | 10:50 | 语文 | 看图写话 · 暑假里的一件事 | 家长确认 | | 5 | 下午 | 14:00 | 电脑应用 | 电脑基础 · 认识键盘与鼠标操作 | 自动验证 | | 6 | 下午 | 14:45 | 电脑应用 | Excel 小课堂 · 制作我的零花钱表 | 家长确认 | | 7 | 下午 | 15:40 | 电脑应用 | PPT 小课堂 · 做一张春节贺卡 | 家长确认 | | 8 | 下午 | 16:30 | 智能体 | 智能体初识 · 什么是 AI 小助手 | 手动打勾 | | 9 | 晚间 | 19:00 | 纪录片 | 观看纪录片《地球脉动》 | 手动打勾 | | 10 | 晚间 | 19:35 | 语文 | 课外阅读 · 绘本 20 分钟 | 手动打勾 | ### 学科分类对照 | 字段值 | 名称 | 说明 | | ------ | ---- | ---- | | `yu` | 语文 | 晨读、看图写话、课外阅读 | | `shu` | 数学 | 口算闯关 | | `ying` | 英语 | 单词跟读、拼写练习 | | `pc` | 电脑应用 | 键盘鼠标、Excel、PPT 基础 | | `ai` | 智能体认知 | AI 小助手启蒙 | | `doc` | 少儿纪录片 | 自然地理纪录片 | ### 完成方式说明 - **`manual` 手动打勾**：孩子点击勾选框即可标记完成/取消。 - **`auto` 自动验证**：电脑答题类任务，系统按 `auto` 进度判定，达到 `100`% 自动标记完成。 - **`parent` 家长确认**：需家长点击「家长确认」按钮方可通过。 --- ## 许可与说明 本项目为家庭学习辅助工具，供个人学习与使用。如需二次开发或商用，请自行评估相关依赖的开源协议。