# app-tools

**Repository Path**: border-collie-ai/app-tools

## Basic Information

- **Project Name**: app-tools
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-27
- **Last Updated**: 2026-01-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 时间管理系统 (Time Manager Suite)

## 项目简介

时间管理系统是一个完整的解决方案，旨在帮助家长有效管理孩子在各种设备上的使用时间。该套件包括三个核心组件：

1. **桌面端时间管理器** - 监控和管理计算机上的应用程序使用时间
2. **移动端时间管理器** - 提供移动设备上的时间规划和统计功能
3. **时间管理API** - 为桌面端和移动端提供统一的后端数据支持

## 项目结构

```
app-tools/
├── desktop-time-manager/     # 桌面端应用程序
├── mobile-time-manager/      # 移动端应用程序
└── time-manager-api/         # 后端API服务
```

## 功能特性

### 桌面端时间管理器
- **应用程序监控**：实时监控计算机上运行的应用程序
- **智能分类**：将应用程序分为学习、游戏、视频音乐、购物、社交等类别
- **时间限制**：为每个类别设置每日使用时间上限
- **超时管理**：自动提醒和关闭超时应用
- **多用户支持**：管理多个孩子的账户和使用情况
- **详细报告**：生成使用统计和趋势分析

### 移动端时间管理器
- **时间规划**：创建和管理日常任务及时间安排
- **使用统计**：提供日/周/月使用时间统计和可视化图表
- **家长控制**：远程管理孩子账户和使用时间限制
- **数据同步**：与桌面端应用数据同步，云端备份
- **离线支持**：在网络不可用时仍可正常使用

### 时间管理API
- **用户认证**：安全的用户注册、登录和JWT Token认证
- **数据管理**：统一管理时间记录、分类和规则设置
- **统计服务**：提供丰富的统计接口和趋势分析
- **家长控制**：支持家长对孩子账户的管理和监控
- **RESTful API**：标准化的API接口，便于集成和扩展

## 技术栈

### 桌面端 (desktop-time-manager)
- **语言**: Python 3.8+
- **GUI框架**: Tkinter
- **进程监控**: psutil 5.9.0+
- **数据库**: SQLite (内置)
- **图表库**: matplotlib 3.5.0+
- **测试框架**: pytest 7.0.0+

### 移动端 (mobile-time-manager)
- **框架**: React Native 0.72.6
- **语言**: JavaScript/TypeScript
- **状态管理**: Redux Toolkit 1.9.7
- **UI组件库**: React Native Elements
- **图表库**: react-native-chart-kit 3.1.0
- **HTTP客户端**: axios 1.6.0
- **本地存储**: @react-native-async-storage/async-storage 1.21.0
- **路由**: @react-navigation/native 6.1.9
- **图标库**: react-native-vector-icons 10.0.2
- **日期选择器**: @react-native-community/datetimepicker 7.6.1

### 后端API (time-manager-api)
- **框架**: FastAPI 0.104.1
- **语言**: Python 3.8+
- **数据库**: SQLAlchemy 2.0.23, PostgreSQL/SQLite
- **Web服务器**: Uvicorn 0.24.0
- **认证**: JWT (python-jose 3.3.0)
- **密码加密**: passlib 1.7.4, bcrypt 4.0.1
- **配置管理**: pydantic 2.5.0, pydantic-settings 2.5.0
- **数据库迁移**: Alembic 1.12.1
- **环境变量**: python-dotenv 1.0.0
- **文件上传**: python-multipart 0.0.6

## 快速开始

### 环境要求
- Python 3.8 或更高版本（桌面端和API）
- Node.js 和 npm（移动端）
- PostgreSQL 或 SQLite（API数据库）

### 安装和运行

#### 1. 后端API服务
```bash
# 进入API目录
cd time-manager-api

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑.env文件设置数据库和其他配置

# 运行开发服务器
uvicorn app.main:app --reload
```

API文档可通过以下地址访问：
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

#### 2. 桌面端应用
```bash
# 进入桌面端目录
cd desktop-time-manager

# 安装依赖
pip install -r requirements.txt

# 运行应用
python main.py
```

#### 3. 移动端应用
```bash
# 进入移动端目录
cd mobile-time-manager

# 安装依赖
npm install

# 启动开发服务器
npm start

# 在模拟器或真机上运行
npm run android
# 或
npm run ios
```

## 开发指南

### 项目结构详解

#### 桌面端 (desktop-time-manager/)
```
desktop-time-manager/
├── main.py                 # 程序入口
├── config/
│   ├── database.py         # 数据库连接和初始化
│   └── settings.py         # 系统配置
├── models/
│   ├── application.py      # 应用程序模型
│   ├── category.py         # 分类模型
│   ├── usage_log.py        # 使用记录模型
│   ├── user.py             # 用户模型
│   └── time_rule.py        # 时间规则模型
├── services/
│   ├── monitor_service.py  # 应用监控服务
│   ├── category_service.py # 分类管理服务
│   ├── usage_service.py    # 使用统计服务
│   ├── rule_service.py     # 规则引擎服务
│   └── report_service.py   # 报告生成服务
├── ui/
│   ├── main_window.py      # 主窗口
│   ├── category_manager.py # 分类管理界面
│   ├── time_settings.py    # 时间设置界面
│   ├── reports_view.py     # 报告查看界面
│   └── user_manager.py     # 用户管理界面
├── utils/
│   ├── process_monitor.py  # 进程监控工具
│   └── time_utils.py       # 时间处理工具
├── tests/
│   └── test_basic.py       # 基本功能测试
└── requirements.txt        # 依赖包列表
```

#### 移动端 (mobile-time-manager/)
```
mobile-time-manager/
├── public/
│   ├── index.html
│   └── favicon.ico
├── src/
│   ├── assets/             # 静态资源
│   ├── components/         # 可复用组件
│   ├── pages/              # 页面组件
│   ├── services/           # API服务
│   ├── store/              # Redux状态管理
│   ├── utils/              # 工具函数
│   ├── hooks/              # 自定义Hooks
│   ├── navigation/         # 路由导航
│   ├── App.js             # 主应用组件
│   └── index.js           # 应用入口
├── package.json
└── .gitignore
```

#### 后端API (time-manager-api/)
```
time-manager-api/
├── app/
│   ├── main.py            # 应用入口
│   ├── api/               # API路由
│   │   ├── auth.py        # 认证相关API
│   │   ├── users.py       # 用户管理API
│   │   ├── categories.py   # 分类管理API
│   │   ├── time_logs.py    # 时间记录API
│   │   ├── stats.py       # 统计API
│   │   └── parent_control.py # 家长控制API
│   ├── models/            # 数据库模型
│   ├── schemas/           # Pydantic模型
│   ├── database.py        # 数据库配置
│   ├── core/              # 核心模块
│   │   └── security.py     # 安全相关功能
├── tests/                 # 测试文件
├── requirements.txt       # 依赖包
├── Dockerfile            # Docker配置
└── .env.example          # 环境变量示例
```

### 测试

#### 桌面端测试
```bash
cd desktop-time-manager
python tests/test_basic.py
```

#### API测试
```bash
cd time-manager-api
# 运行单元测试
pytest tests/
```

### 部署

#### API部署
使用Docker部署API服务：
```bash
cd time-manager-api
docker build -t time-manager-api .
docker run -p 8000:8000 time-manager-api
```

或者直接部署：
```bash
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

#### 移动端构建
Android:
```bash
cd mobile-time-manager
npm run build:android
```

iOS:
```bash
cd mobile-time-manager
npm run build:ios
```

## 验证和测试

### 功能验证

#### 桌面端时间管理器验证
1. **应用程序监控功能**：
   - 启动桌面端应用
   - 运行不同类型的应用程序（学习、游戏、视频等）
   - 验证应用能否正确识别和分类这些应用程序
   - 检查使用时间是否被正确记录

2. **时间限制功能**：
   - 为特定分类设置较短的时间限制（如1分钟）
   - 启动该分类下的应用程序
   - 验证系统是否能在时间到达后发出提醒并可选关闭应用

3. **多用户支持**：
   - 创建多个用户账户
   - 切换用户并验证各自的使用记录独立保存
   - 验证不同用户的设置互不干扰

#### 移动端时间管理器验证
1. **时间规划功能**：
   - 在移动端创建任务和时间安排
   - 验证任务能否正确显示在对应的时间段
   - 检查任务的编辑和删除功能

2. **数据同步**：
   - 在桌面端和移动端分别记录使用时间
   - 验证两端数据能否通过API正确同步
   - 检查离线模式下数据的本地保存和网络恢复后的同步

#### API服务验证
1. **用户认证**：
   - 注册新用户账户
   - 使用正确和错误的凭证尝试登录
   - 验证JWT token的生成和验证功能

2. **数据管理**：
   - 创建、读取、更新和删除时间记录
   - 验证分类管理功能
   - 检查时间规则的设置和应用

3. **统计服务**：
   - 请求日、周、月统计数据
   - 验证数据的准确性和一致性
   - 检查趋势分析功能

### 集成测试

1. **端到端流程测试**：
   - 从用户注册开始，完整测试整个使用流程
   - 验证桌面端、移动端和API之间的数据流
   - 检查异常情况下的系统稳定性

2. **性能测试**：
   - 测试大量时间记录情况下的查询性能
   - 验证多用户并发访问API的响应能力
   - 检查长时间运行下的内存和CPU使用情况

### 部署验证

1. **Docker部署验证**：
   - 构建API的Docker镜像
   - 运行容器并验证API功能正常
   - 检查环境变量配置是否正确应用

2. **移动端构建验证**：
   - 构建Android APK并安装到设备
   - 验证基本功能在真机上正常运行
   - 检查iOS构建过程是否顺利

## 故障排除

### 常见问题

1. **API无法启动**：
   - 检查数据库连接配置
   - 验证环境变量是否正确设置
   - 确认端口未被占用

2. **桌面端无法监控应用**：
   - 检查psutil依赖是否正确安装
   - 验证管理员权限（Windows系统可能需要）
   - 确认防火墙未阻止应用运行

3. **移动端数据同步失败**：
   - 检查API地址配置是否正确
   - 验证网络连接状态
   - 确认认证token是否有效

### 支持资源

- **官方文档**：各组件的README文件包含详细使用说明
- **社区支持**：在GitHub Issues中提交问题和建议
- **API文档**：启动API服务后可通过Swagger UI访问详细API文档

## 项目维护

### 版本管理

- **语义化版本控制**：项目遵循语义化版本控制规范 (SemVer)
- **发布周期**：主要版本每季度发布一次，次要版本和补丁按需发布
- **向后兼容性**：尽可能保持API向后兼容，在必要时提供迁移指南

### 更新日志

每个版本都会包含详细的更新日志，说明：
- 新增功能
- 修复的Bug
- 已知问题
- 升级注意事项

### 依赖管理

- **定期更新**：每月审查和更新项目依赖
- **安全审计**：使用自动化工具检查依赖的安全漏洞
- **兼容性测试**：重大依赖更新后进行全面测试

## 已完成的功能

### 2026年1月28日更新

#### 桌面端 - 白名单/黑名单功能 ✅
- **数据模型** (`models/app_list.py`): 支持白名单/黑名单的CRUD操作
- **业务服务** (`services/app_list_service.py`): 智能访问控制、缓存优化
- **监控服务增强** (`services/monitor_service.py`): 集成访问检查、自动阻止黑名单应用
- **GUI界面** (`ui/app_list_manager.py`): 完整的白名单/黑名单管理界面
- **数据库集成** (`config/database.py`): 新增 `app_lists` 表

**使用方式**:
```bash
cd desktop-time-manager
python main.py
# 选择 1. 启动图形界面 (GUI)
```

#### 移动端 - 代码优化 ✅
- **Redux状态管理完善**: 创建 `timeSlice.js`、`statsSlice.js`、`parentSlice.js`
- **认证流程集成**: 登录/注册与真实API对接，移除模拟数据
- **API服务修复**: 使用 `AsyncStorage` 替换不支持的 `localStorage`
- **性能优化**: 组件使用 `React.memo` 包装，优化 `useCallback`/`useMemo`
- **路由安全**: 添加 `authGuard` 导航守卫，未登录自动跳转
- **错误处理**: 添加loading states和错误提示
- **网络状态检测**: 创建 `network.js` 工具
- **新页面**: 添加家长控制页面、设置页面

---

## 未来规划

### 短期目标（1-3个月）

1. **功能增强**：
   - ~~桌面端增加白名单/黑名单功能~~ ✅
   - 移动端添加奖励机制
   - ~~移动端代码优化~~ ✅
   - API增加数据分析仪表板

2. **用户体验改进**：
   - ~~桌面端添加图形用户界面~~ ✅
   - 移动端优化交互设计
   - API文档完善和示例丰富

3. **性能优化**：
   - 数据库查询优化
   - API响应速度提升
   - 移动端资源占用减少

### 移动端应用监控功能 ✅

#### Android（已完成）
- **框架**: UsageStatsManager (Android 5.0+ / API 21+)
- **实现文件**:
  - `mobile-time-manager/android/app/src/main/java/com/mobiletimemanager/ScreenTimeModule.kt` - Kotlin 原生模块
  - `mobile-time-manager/android/app/src/main/java/com/mobiletimemanager/ScreenTimePackage.kt` - React Package 注册
  - `mobile-time-manager/src/services/androidScreenTime.js` - React Native 服务层
- **权限**: `PACKAGE_USAGE_STATS` (用户手动在系统设置中开启)
- **功能**:
  - 获取前台应用使用时长
  - 应用分类识别（社交/游戏/娱乐/生产力等）
  - 日/周使用报告
  - 应用使用排行榜
  - 总使用时间统计

#### iOS（已完成）
- **框架**: DeviceActivity + FamilyControls (iOS 15+)
- **实现文件**:
  - `mobile-time-manager/ios/ScreenTimeBridge.swift` - Swift 原生模块
  - `mobile-time-manager/src/services/iosScreenTime.js` - React Native 服务层
  - `mobile-time-manager/ios/MobileTimeManager.entitlements` - 权限配置
- **权限**: 需要向 Apple 申请 `com.apple.developer.family-controls`
- **功能**:
  - 获取前台应用使用时长
  - 应用分类识别（社交/游戏/娱乐等）
  - 日/周/月使用报告

#### 统一跨平台服务
- **实现文件**: `mobile-time-manager/src/services/screenTimeService.js`
- **功能**:
  - 自动检测平台并使用对应实现
  - 统一 API 接口，无需关心平台差异
  - 权限请求和处理封装
  - 数据聚合和分类汇总
  - 统一的统计接口
  - **前台运行时长获取**: 支持获取设备前台运行时长（今日/指定时间段）

#### 前台运行时长功能 ✅
- **功能**: 获取用户 actively 使用设备的总时间
- **API 接口**:
  - `getTodayTotalTime()`: 获取今日总前台时长
  - `getTotalTime(startTime, endTime)`: 获取指定时间段的前台时长
  - `getTodayStats()`: 获取今日详细使用统计
- **数据格式**:
  ```javascript
  {
    totalForegroundTime: 3600000,      // 总前台时间（毫秒）
    formattedTotalTime: "1h 0m",       // 格式化的时间字符串
    appCount: 15,                      // 使用的应用数量
    categorySummary: { social: ..., gaming: ..., ... }, // 分类汇总
    leaderboard: [...],                // 使用排行榜
  }
  ```

### 中期目标（3-6个月）

1. **平台扩展**：
   - 支持Linux桌面环境
   - 开发Web管理界面
   - 增加对更多移动平台的支持

2. **功能深化**：
   - AI驱动的使用模式分析
   - 智能时间分配建议
   - 家庭组和权限管理

3. **生态系统建设**：
   - 插件系统支持第三方扩展
   - 开发者文档和API参考
   - 社区建设和支持

### 长期愿景（6个月以上）

1. **智能化管理**：
   - 基于机器学习的个性化时间管理
   - 预测性使用模式识别
   - 自适应时间限制调整

2. **跨平台整合**：
   - 统一的跨设备时间管理
   - 云同步和备份服务
   - 第三方应用集成

3. **社区和商业发展**：
   - 开源社区壮大
   - 商业支持和服务
   - 教育机构合作

## 贡献指南

我们欢迎任何形式的贡献！如果你想为此项目做出贡献，请遵循以下步骤：

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 贡献类型

- **代码贡献**：实现新功能、修复Bug、性能优化
- **文档贡献**：改进文档、添加示例、翻译内容
- **测试贡献**：编写测试用例、报告Bug、改善测试覆盖率
- **设计贡献**：UI/UX设计、图标制作、用户体验改进

### 代码规范

- 遵循各技术栈的最佳实践
- 保持代码风格一致
- 编写清晰的提交信息
- 添加必要的注释和文档

## 许可证

本项目采用 MIT 许可证。详细信息请参见 [LICENSE](LICENSE) 文件。