# python-kids

**Repository Path**: longcat99/python-kids

## Basic Information

- **Project Name**: python-kids
- **Description**: 儿童积分激励系统
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-12
- **Last Updated**: 2026-01-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 儿童积分激励系统 🎁

一个基于Flask的儿童行为激励系统，通过积分奖励机制帮助家长培养孩子的良好习惯。

## 项目简介

儿童积分激励系统是一个Web应用程序，旨在通过游戏化的方式激励儿童完成日常任务和学习活动。系统分为家长端和儿童端，家长可以创建任务、设置积分奖励，儿童可以通过完成任务获得积分并兑换奖励。

## 功能特性

### 家长端功能
- **用户管理**: 家长注册/登录系统
- **任务管理**: 创建、编辑、删除任务，设置积分奖励
- **儿童绑定**: 绑定多个儿童账户
- **任务审核**: 审核儿童提交的任务完成情况
- **积分管理**: 查看儿童积分余额和积分记录
- **签到设置**: 配置每日签到积分奖励
- **邀请码**: 生成邀请码供其他家长绑定儿童

### 儿童端功能
- **任务查看**: 查看家长分配的任务
- **任务提交**: 完成任务并提交证明
- **积分查看**: 查看当前积分余额和积分记录
- **每日签到**: 每日签到获取积分
- **奖励兑换**: 使用积分兑换奖励
- **语音交互**: 智能语音提示和语音合成功能
- **录音提交**: 通过录音描述购买需求

## 技术架构

- **后端框架**: Flask
- **数据库**: SQLite (使用SQLAlchemy ORM)
- **前端**: HTML + Tailwind CSS + JavaScript
- **语音合成**: Web Speech API + 外部TTS API备用
- **安全**: 密码加密存储、跨域请求保护

## 项目结构

```
python-kids/
├── app.py                 # 主应用程序文件
├── config.json           # 配置文件
├── index.html            # 首页
├── parent.html           # 家长端页面
├── child.html            # 儿童端页面（包含语音合成功能）
├── parent1.html          # 家长端页面（备用）
├── start_app.sh          # 启动脚本
├── app.log               # 日志文件
├── instance/
│   └── kids_points.db    # SQLite数据库文件
└── uploads/              # 文件上传目录
    ├── tasks/
    │   ├── images/       # 任务图片
    │   └── audio/        # 任务音频
    ├── toys/             # 玩具图片
    ├── proofs/           # 任务完成证明
    └── audio/            # 儿童提交的录音文件
```

## 数据库模型

### 核心数据表
- **User**: 用户表（家长/儿童）
- **ParentChild**: 家长-儿童绑定关系
- **Task**: 任务定义表
- **TaskRecord**: 任务完成记录
- **PointsBalance**: 积分余额表
- **PointsLog**: 积分流水记录
- **CheckInConfig**: 签到配置
- **InviteCode**: 邀请码管理

## 安装部署

### 环境要求
- Python 3.7+
- pip包管理器

### 快速开始

1. **克隆项目**
```bash
git clone https://gitee.com/longcat99/python-kids.git
cd python-kids
```

2. **安装依赖**
```bash
pip install flask flask-cors flask-sqlalchemy bcrypt pytz
```

3. **配置应用**
编辑 `config.json` 文件，根据需要修改配置：
```json
{
  "parent_registration": {
    "enabled": true,
    "password_required": true,
    "registration_password": "parent2024"
  },
  "security": {
    "max_login_attempts": 5,
    "session_timeout": 3600
  }
}
```

4. **启动应用**
```bash
python app.py
```

或者使用启动脚本：
```bash
chmod +x start_app.sh
./start_app.sh
```

5. **访问应用**
打开浏览器访问：`http://localhost:3000`

## 使用说明

### 家长端使用流程
1. 注册家长账号（需要注册密码）
2. 登录家长后台
3. 创建儿童账户
4. 设置任务和积分奖励
5. 审核儿童提交的任务
6. 查看积分统计

### 儿童端使用流程
1. 使用家长提供的账号登录
2. 查看待完成任务
3. 完成任务并提交证明
4. 查看积分余额
5. 每日签到获取积分

## API接口

### 用户认证
- `POST /api/register` - 用户注册
- `POST /api/login` - 用户登录

### 任务管理
- `POST /api/tasks` - 创建任务
- `GET /api/tasks` - 获取任务列表
- `PUT /api/tasks/<id>` - 更新任务
- `DELETE /api/tasks/<id>` - 删除任务

### 积分管理
- `GET /api/points/balance` - 获取积分余额
- `GET /api/points/log` - 获取积分记录
- `POST /api/tasks/<id>/submit` - 提交任务完成

### 绑定管理
- `POST /api/bind/child` - 绑定儿童
- `POST /api/bind/parent` - 绑定家长
- `GET /api/bind/status` - 获取绑定状态

## 安全特性

- 密码使用bcrypt加密存储
- 跨域请求保护
- 会话超时机制
- 登录尝试次数限制
- 文件上传类型限制

## 配置说明

### 主要配置项
- **parent_registration**: 家长注册配置
- **security**: 安全相关配置
- **binding**: 绑定关系配置

### 默认配置
```json
{
  "parent_registration": {
    "enabled": true,
    "password_required": true,
    "registration_password": "parent2024"
  },
  "security": {
    "max_login_attempts": 5,
    "session_timeout": 3600
  },
  "binding": {
    "max_parents_per_child": 6
  }
}
```

## 开发说明

### 添加新功能
1. 在 `app.py` 中添加新的路由函数
2. 如果需要新的数据表，创建对应的模型类
3. 更新前端页面以支持新功能
4. 测试功能完整性

### 数据库迁移
当前使用SQLite数据库，如需迁移到其他数据库：
1. 修改 `app.config['SQLALCHEMY_DATABASE_URI']`
2. 重新初始化数据库

## 语音合成功能

### 功能特性
- **智能语音提示**: 儿童端操作时提供实时语音反馈
- **语音队列管理**: 支持语音中断和顺序播放
- **多语音源支持**: 默认使用Web Speech API，支持外部TTS API备用
- **语速调节**: 可调节语音播放速度

### 语音提示场景
- 水果选择时播放"选择了[水果名]，现在想用[积分]分"
- 积分变化时播放"现在果篮里有[积分]分积分"
- 语音开关状态变化提示
- 帮助说明语音播报
- 欢迎语音提示

### 技术实现
- **主要语音源**: 浏览器内置Web Speech API
- **备用语音源**: 外部TTS API (支持自定义语音和语速)
- **语音队列**: 智能队列管理，支持语音中断
- **错误处理**: 自动回退机制确保语音播放连续性

### 外部TTS API配置
如需使用外部TTS API，可在 `child.html` 中启用：
```javascript
// 启用外部TTS API
speakHintTTS('测试语音', true);
```

API参数说明：
- `voice`: 语音类型 (如: zh-CN-XiaoxiaoNeural)
- `rate`: 语速 (数值越大语速越快)
- `text`: 要合成的文本内容

### 调试功能
在浏览器控制台可使用以下调试函数：
```javascript
// 测试语音合成
testTTS('测试文本');

// 清空语音队列
clearVoiceQueue();
```

## 录音功能

### 功能特性
- **实时录音**: 使用浏览器MediaRecorder API进行录音
- **录音回放**: 支持录音完成后立即回放
- **重新录音**: 支持不满意时重新录音
- **智能语音管理**: 录音时自动暂停语音提示，避免干扰

### 录音使用场景
- 儿童选择积分后，通过录音描述想购买的物品
- 提交购买申请时附带语音说明
- 家长审核时可听到儿童的语音描述

### 技术实现
- **录音API**: 使用Web Audio API和MediaRecorder
- **音频格式**: 支持WAV格式音频录制
- **权限管理**: 自动请求麦克风权限
- **状态管理**: 完整的录音状态控制（开始/停止/重录）

### 录音流程
1. 儿童选择积分并点击"申请积分消费"
2. 在弹出窗口中点击"开始录音"按钮
3. 说出想购买的物品描述
4. 点击"停止录音"完成录制
5. 可回放录音确认内容
6. 不满意可重新录音
7. 提交申请给家长审核

### 录音界面组件
- **录音按钮**: 开始/停止录音控制
- **录音状态显示**: 实时显示录音状态
- **录音回放器**: 支持播放和重新录音
- **语音提示管理**: 录音时自动暂停语音播报

### 录音文件处理
- **客户端录制**: 录音在浏览器端完成
- **Blob存储**: 录音文件以Blob格式存储在内存中
- **上传提交**: 录音文件随申请一起提交到服务器
- **家长审核**: 家长可在审核时播放录音文件

## 故障排除

### 常见问题
1. **端口占用**: 修改app.py中的端口号
2. **数据库错误**: 删除instance/kids_points.db重新启动
3. **文件上传失败**: 检查uploads目录权限

### 日志查看
应用日志保存在 `app.log` 文件中，可用于调试问题。

## 许可证

本项目采用开源许可证，具体信息请查看LICENSE文件。

## 贡献指南

欢迎提交Issue和Pull Request来改进项目。

## 更新日志

### v1.0.0
- 初始版本发布
- 基础任务管理功能
- 积分系统实现
- 家长-儿童绑定机制
- 文件上传支持

---

**开发团队**: longcat99  
**项目地址**: https://gitee.com/longcat99/python-kids  
**最后更新**: 2026-01-12