# KidTime-Guard

**Repository Path**: cmw/kid-time-guard

## Basic Information

- **Project Name**: KidTime-Guard
- **Description**: 童时守:童时守是一套面向家庭共享 Android 设备的儿童屏幕时间管理工具。家长为每个孩子设置独立的单次观看时长、每日总额度和可用时段；孩子刷脸后开始使用，系统记录其使用过的 App，在时间即将结束时发出声音提醒，到时停止本次会话并进入锁定页。下一位有剩余额度的孩子可重新刷脸继续使用。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-24
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KidTime-Guard

#### 介绍
童时守:童时守是一套面向家庭共享 Android 设备的儿童屏幕时间管理工具。家长为每个孩子设置独立的单次观看时长、每日总额度和可用时段；孩子刷脸后开始使用，系统记录其使用过的 App，在时间即将结束时发出声音提醒，到时停止本次会话并进入锁定页。下一位有剩余额度的孩子可重新刷脸继续使用。

#### 软件架构

本仓库采用单仓库、契约驱动架构：

- `apps/parent_app`：Flutter 家长端，Riverpod + Dio + 安全存储。
- `apps/cloud_service`：Spring Boot 3 + Java 21 模块化单体，默认端口 `9025`。
- `apps/child_app`：Kotlin + Jetpack Compose + Hilt + Room 儿童端。
- `contracts/openapi`：三端共享 API 契约。
- `harness`：统一构建、静态检查、测试和证据链。
- `document/architecture`：架构决策。
- `document/prototype`：原型工作区与产品待确认项。

当前重构实现状态、PRD/UI 复盘和正式发布门禁见 `document/testing/reports/REFACTOR_V1_FINAL_PRODUCTION_AUDIT.md`；`document/architecture/PRD_P0_TRACEABILITY.md` 仅保留早期 P0 历史追溯。


#### 安装教程

1. 安装 Java 21、Flutter 3.38+ 与 Android SDK 36；PATH 中存在旧 Java 时，将 `KIDTIME_JAVA_HOME` 指向 Java 21+。
2. 在根目录配置 `local.properties` 中的 `sdk.dir`。
3. 参考 `.env.example` 通过进程环境或密钥管理器注入 MySQL 8.0、Redis 与应用密钥；仓库不提供 H2 回退。隔离 `dev` 环境可使用空数据库/Redis 密码，`prod` 环境拒绝空密码。
4. 运行 `powershell -ExecutionPolicy Bypass -File .\harness\run-all.ps1`。
5. 连接 Android Studio 模拟器或实体设备后运行 `powershell -ExecutionPolicy Bypass -File .\harness\run-device-acceptance.ps1 -Serial <设备序列号>`。

#### 使用说明

1. 云端开发启动：使用 `dev` Profile 运行 `.\gradlew.bat :cloud-service:bootRun`，默认访问 `http://127.0.0.1:9025`。
2. 家长端启动：在 `apps/parent_app` 运行 `flutter run`。
3. 儿童端安装：构建后安装 `apps/child_app/build/outputs/apk/debug/child-app-debug.apk`。
4. 家长可选择短信验证码登录、帐号密码登录，或直接注册帐号密码；注册手机号和昵称可选，短信验证成功但手机号不存在时会自动注册并登录；密码不会下发儿童端。
5. 真机检查项与证据要求见 `document/testing/DEVICE_ACCEPTANCE_CHECKLIST.md`。
6. 生产环境一键发布与回滚说明见 `deploy/cloud_service/README.md`。

#### 云端生产运维

```bash
# 重启
systemctl restart kid-time-guard-cloud.service

# 查看状态
systemctl status kid-time-guard-cloud.service --no-pager --full

# 正常停止
systemctl stop kid-time-guard-cloud.service

# 强制 kill，仅限正常停止超时时使用
systemctl kill --kill-whom=all --signal=SIGKILL kid-time-guard-cloud.service

# 查看最近 200 行并持续跟踪实时日志
journalctl -u kid-time-guard-cloud.service --follow --lines=200 --no-pager
```

更完整的端口、健康检查和回滚命令见 `deploy/cloud_service/README.md`。

#### 参与贡献

1. 在修改业务规则前同步更新 OpenAPI 契约与领域测试。
2. 提交前执行 `harness/run-all.ps1`；其中包含三端单函数 50 行、圈复杂度 4 上限及全部测试，任何失败均不得绕过。
3. 禁止提交密钥、人脸帧、人脸向量、PIN 或用户截图。