🏠 HomeworkGuardian - 儿童作业监控系统

基于边缘计算的儿童学习监控系统，结合 AI 姿态检测、实时监控和云端深度分析。

📱 预览

┌─────────────────────────────────────────────┐
│  🏠 HomeworkGuardian                      │
├─────────────────────────────────────────────┤
│  🟢 正在监控 小明                           │
│                                             │
│  📊 学习中                                 │
│                                             │
│  ┌──────┐ ┌──────┐ ┌──────┐              │
│  │2.5h  │ │ 85%  │ │ 3次  │              │
│  │学习时长│ │专注度│ │警告  │              │
│  └──────┘ └──────┘ └──────┘              │
│                                             │
│  [摄像头]        [开始监控]                 │
└─────────────────────────────────────────────┘

🏗️ 系统架构

┌─────────────────────────────────────────────────────────────────────────┐
│                          系统架构图                                    │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   手机端 App     │     │   云端服务器     │     │   家长端        │
│  (边缘计算设备)  │────▶│   (GPU 加速)    │────▶│   (接收通知)     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │
        │ ◀─ 本地 AI 标记 ────▶│
        │ ◀─ 关键片段上传 ─────▶│
        │                       │
   摄像头采集              数据存储
   本地 AI 推理            深度分析
   智能标记                模型推理
   视频压缩                报告生成

技术选型

层级	技术	说明
手机端 UI	Flutter	跨平台 (iOS/Android)
本地 AI	CoreML (iOS) / TFLite (Android)	边缘计算加速
姿态检测	MediaPipe / Vision Framework	实时姿态分析
服务器	FastAPI + Python	REST API
GPU 加速	CUDA + PyTorch	服务端深度学习 (Linux GPU 服务器)
数据库	PostgreSQL + Redis	数据存储与缓存
推送	flutter_local_notifications	本地通知

🎯 核心功能

手机端 (Mobile App)

功能	描述
📹 实时监控	摄像头实时采集视频流
🤖 本地 AI 推理	轻量级模型检测学习/离开/玩耍状态
🏷️ 智能标记	自动为视频片段打标签
📦 数据压缩	关键帧提取，减少传输带宽
☁️ 边缘上传	只上传需要深度分析的片段
🔔 推送通知	离开/玩耍时实时提醒
💾 本地存储	SQLite 离线数据存储
⬆️ 后台上传	自动同步数据到服务器

服务器端 (Server)

功能	描述
�接收数据	接收手机端上传的标记数据和视频片段
🧠 深度分析	GPU 加速的复杂行为识别
📊 报告生成	每日/每周学习统计报告
📧 邮件推送	定时发送学习报告 + 异常提醒
📈 数据可视化	学习趋势图表

检测算法

摄像头帧 → 平台特定 AI 模型 → 行为分析 → 状态标记
    │
    ├─ [置信度 > 90%]
    │   ├─ 本地存储元数据
    │   └─ 显示状态 (学习/离开/玩耍)
    │
    └─ [置信度 < 90%]
        ├─ 标记该片段
        ├─ 压缩视频
        └─ 上传服务器深度分析

提醒规则

场景	触发条件	动作
离开提醒	离开 > 15 分钟 (可配置)	推送 + 邮件
边玩边学	玩耍 > 5 分钟 (可配置)	推送 + 邮件
学习开始	检测到学习状态	通知家长
学习结束	监控停止	发送报告

📂 项目结构

homework-guardian/
├── docs/                          # 文档
│   ├── SPEC_FULL.md              # 完整规范
│   ├── SPEC_UPDATED.md           # 更新规范
│   └── IMPLEMENTATION_PLAN.md   # 实施计划
│
├── mobile/                        # 手机端 (Flutter)
│   ├── lib/
│   │   ├── main.dart            # 主界面
│   │   ├── models/
│   │   │   └── models.dart     # 数据模型
│   │   └── services/
│   │       ├── ai_detection.dart           # AI 接口
│   │       ├── ios_ai_detection.dart       # iOS CoreML
│   │       ├── android_ai_detection.dart   # Android TFLite
│   │       ├── database_service.dart       # SQLite
│   │       ├── notification_service.dart    # 推送通知
│   │       ├── upload_service.dart          # 后台上传
│   │       ├── video_service.dart           # 视频压缩
│   │       ├── api_client.dart             # API 客户端
│   │       └── session_manager.dart        # 会话管理
│   ├── android/                  # Android 配置
│   │   └── app/build.gradle    # TFLite 依赖
│   ├── ios/                     # iOS 配置
│   │   └── Podfile             # CoreML 依赖
│   └── pubspec.yaml            # Flutter 依赖
│
└── server/                      # 服务器端 (Python)
    ├── Dockerfile               # GPU 镜像
    ├── docker-compose.yml       # 一键部署
    ├── main.py                  # FastAPI 主应用
    ├── api/routes.py            # API 路由
    ├── core/config.py           # 配置
    ├── models/schemas.py       # 数据模型
    └── services/
        ├── gpu_detector.py           # GPU 检测
        ├── pose_detector.py          # MediaPipe 姿态
        ├── analysis_service.py       # 分析服务
        ├── alert_service.py          # 提醒逻辑
        ├── email_service.py          # 邮件推送
        └── sound_alert.py           # 声音提醒

🚀 快速开始

1. 服务器端部署 (Linux GPU 服务器)

支持部署在带有 NVIDIA GPU 的 Linux 服务器上 (如家用主机、RTX 4060+/5060ti/5070ti 等)。

前置要求

Docker + Docker Compose
NVIDIA GPU (RTX 4060+ / 5060ti / 5070ti 等)
CUDA 11.8+ / 12.x

启动服务

# 1. 进入服务器目录
cd server

# 2. 构建并启动
docker compose up -d --build

# 3. 检查状态
docker ps

# 4. 查看日志
docker logs -f homework-guardian-server

配置邮件

编辑 server/.env:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your_email@gmail.com
SMTP_PASSWORD=your_app_password

2. 手机端开发

前置要求

Flutter 3.x SDK
Android Studio / Xcode
(可选) TFLite 模型文件
(可选) CoreML 模型文件

安装依赖

# 进入移动端目录
cd mobile

# 安装 Flutter 依赖
flutter pub get

运行应用

# 调试模式
flutter run

# 构建 Android APK
flutter build apk --debug

# 构建 iOS (需要 macOS)
flutter build ipa --debug

应用图标

首次构建前可生成应用图标（需已配置 assets/images/app_icon.png）：

dart run flutter_launcher_icons

项目配置

编辑 mobile/lib/services/api_client.dart:

// 修改服务器地址
final String baseUrl = 'http://192.168.1.100:8000';

🔧 配置说明

服务器配置

环境变量	默认值	说明
`DATABASE_URL`	postgresql://...	数据库连接
`REDIS_URL`	redis://...	Redis 连接
`SMTP_HOST`	smtp.gmail.com	邮件服务器
`ALERT_LEAVE_MINUTES`	15	离开提醒阈值
`ALERT_PLAY_MINUTES`	5	玩耍提醒阈值

手机端配置

配置项	默认值	说明
服务器地址	http://192.168.1.100:8000	API 服务器
离开阈值	15 分钟	触发提醒时间
玩耍阈值	5 分钟	触发提醒时间
视频质量	720p	清晰度
自动同步	5 分钟	间隔时间

📊 API 接口

上传接口

方法	路径	描述
POST	`/api/v1/upload/metadata`	上传活动元数据
POST	`/api/v1/upload/video`	上传视频片段

分析接口

方法	路径	描述
GET	`/api/v1/analysis/session/{id}`	获取会话分析
POST	`/api/v1/analysis/segment`	分析时间段

报告接口

方法	路径	描述
GET	`/api/v1/report/daily/{child_id}`	每日报告
GET	`/api/v1/report/weekly/{child_id}`	每周报告

提醒接口

方法	路径	描述
POST	`/api/v1/alert/config`	设置提醒配置
GET	`/api/v1/alert/status/{session_id}`	提醒状态

🧪 测试

服务器端测试

# 运行模拟测试
cd server
python3 simulate_light.py

预期输出:

📊 Step 1: GPU Detection
   ✅ GPU Available: NVIDIA RTX 5070 Ti
   
📹 Step 4: Simulating Activities
   🔄 20 min - AWAY! (triggers alert at 15min)
      ⚠️  ALERT: Child away > 15 min!
      
🔔 Step 7: Alert Summary
   🚨 Total Alerts: 2

手机端测试

# 运行 Flutter 测试
cd mobile
flutter test

# 运行特定测试
flutter test test/database_test.dart

📈 性能指标

指标	目标值	实际值
本地推理延迟	< 50ms	~30ms
服务器响应	< 100ms	~50ms
视频压缩率	> 80%	~85%
内存占用 (手机)	< 200MB	~150MB
电池消耗	< 10%/hour	~5%/hour

🔐 安全考虑

数据加密传输 (HTTPS)
用户身份验证
数据加密存储
隐私合规 (GDPR/COPPA)

🤝 贡献

欢迎提交 Issue 和 Pull Request！

Fork 本项目
创建特性分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add amazing feature')
推送分支 (git push origin feature/amazing-feature)
打开 Pull Request

📋 更新日志

v1.0.0 (2026-02-22)

✨ 新增功能

开机动画：移动端添加简洁明了的开机启动动画，包含品牌 Logo 渐变淡入与缩放效果
应用图标：为移动端设计简洁的 Indigo 渐变风格应用图标（盾牌 + 书本元素）
单元测试：为复杂功能增加单元测试覆盖
- 服务端：test_analysis_service.py - 分析服务元数据处理、视频处理、报告生成
- 移动端：app_state_test.dart - App 状态管理初始状态
- 移动端：upload_service_test.dart - SyncResult、ActivityRecord 上传数据结构

🐛 Bug 修复

修复 gpu_detector.py 中 docstring 缩进错误导致的 IndentationError
修复 Analysis Service 测试在缺少 cv2 依赖时的导入问题（添加 pytest.importorskip）

🔧 改进

移动端主入口采用路由方式 (/splash → /) 以支持开机动画流畅过渡
应用图标支持 Android 与 iOS 的 Adaptive Icon

📄 许可证

Apache License 2.0 - see LICENSE for details.

🙏 致谢

tonyliugd/monitoringStudy - 监控算法参考
MediaPipe - 姿态检测
TensorFlow Lite - 边缘 AI
CoreML - iOS AI 加速

📞 联系方式

作者: Vino
GitHub: https://github.com/Riocloud

让每个孩子都能专注学习，让每位家长都能放心工作 🏠📚

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
docs		docs
mobile		mobile
server		server
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

🏠 HomeworkGuardian - 儿童作业监控系统

📱 预览

🏗️ 系统架构

技术选型

🎯 核心功能

手机端 (Mobile App)

服务器端 (Server)

检测算法

提醒规则

📂 项目结构

🚀 快速开始

1. 服务器端部署 (Linux GPU 服务器)

前置要求

启动服务

配置邮件

2. 手机端开发

前置要求

安装依赖

运行应用

应用图标

项目配置

🔧 配置说明

服务器配置

手机端配置

📊 API 接口

上传接口

分析接口

报告接口

提醒接口

🧪 测试

服务器端测试

手机端测试

📈 性能指标

🔐 安全考虑

🤝 贡献

📋 更新日志

v1.0.0 (2026-02-22)

✨ 新增功能

🐛 Bug 修复

🔧 改进

📄 许可证

🙏 致谢

📞 联系方式

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages