# ParentGuard

**Repository Path**: houze/parent-guard

## Basic Information

- **Project Name**: ParentGuard
- **Description**: Slogan 备选：
「挡住沉迷，守住成长」
「盾护童心，时自分明」
「一面盾，一寸金」
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-10
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ParentGuard · 家长守护锁

一套「家长远程管控孩子平板」的双端应用。家长在手机上看到孩子平板的实时状态，
可以下发使用时长限制、就寝时段、白名单，批准或结束解锁，以及远程改动态密码。

本仓库是三端的**单一代码仓库（monorepo）**：一份源码、一次 `git init`，三个可独立构建的工程。

---

## 目录结构

```
ParentGuard/
├── child-harmony/      孩子端 · 装在孩子的平板上（被管控端）   HarmonyOS / ArkTS   v1.5.0
├── parent-harmony/     家长端 · 鸿蒙手机                       HarmonyOS / ArkTS   v1.5.0
├── parent-android/     家长端 · 安卓手机                       Android / Kotlin    v1.5.0
├── dist/               构建产物（未入库：HAP / APK 里烧进了令牌）
├── tools/              联调工具（宿主机 TCP 中继等）
└── backup/             设备存储快照（未入库：含密钥明文）
```

「家长端」有两份实现，是因为鸿蒙 NEXT 装不了 APK。两份的**协议、签名算法、云端文件格式完全一致**，
所以同一个孩子端可以配任意一份家长端。

---

## 三端关系

```
        ┌──────────────────┐        ┌──────────────────┐
        │  parent-android  │        │  parent-harmony  │
        │   (安卓家长端)    │        │  (鸿蒙家长端)     │
        └────────┬─────────┘        └────────┬─────────┘
                 │                           │
                 └───────────┬───────────────┘
                             │
              ┌──────────────┴──────────────┐
              │        两条传输通道          │
              ├─────────────────────────────┤
              │ ① 局域网（同 Wi-Fi）         │
              │   UDP 45454  发现 / 配对     │
              │   TCP 45455  命令 / 状态     │
              │ ② Gitee 云端（跨网络）        │
              │   devices/<id>.json         │
              │   devices/<id>.state.json   │
              └──────────────┬──────────────┘
                             │
                    ┌────────┴─────────┐
                    │  child-harmony   │
                    │   (孩子端平板)    │
                    └──────────────────┘
```

- **局域网通道**：不依赖外网，但要同一个局域网。用 UDP 广播发现设备，再走 TCP 下发命令。
- **云端通道**：靠 Gitee 仓库当信箱，两端只要各自能上网就行，跨网络可用。

两条通道的取舍与原理见 `child-harmony/PROTOCOL.md`。

---

## 构建

### 孩子端（HarmonyOS）

```bash
cd child-harmony
"D:/Program Files/Huawei/DevEco Studio/tools/node/node.exe" \
  "D:/Program Files/Huawei/DevEco Studio/tools/hvigor/bin/hvigorw.js" \
  assembleHap --mode module -p product=default --no-daemon
```

产物在 `child-harmony/entry/build/default/outputs/default/`。

### 鸿蒙家长端

```bash
cd parent-harmony
# 与孩子端同一条命令（本工程无 gradlew wrapper，走 DevEco 自带 hvigor）
export DEVECO_SDK_HOME="D:\\Program Files\\Huawei\\DevEco Studio\\sdk"
"D:/Program Files/Huawei/DevEco Studio/tools/node/node.exe" \
  "D:/Program Files/Huawei/DevEco Studio/tools/hvigor/bin/hvigorw.js" \
  assembleHap --mode module -p product=default --no-daemon
```

### 安卓家长端

本工程**没有 gradle wrapper**，需要本机 gradle：

```bash
cd parent-android
"C:/Users/zhengmingzhi/.wb-build/gradle-8.7/bin/gradle.bat" assembleDebug
# 跑跨端一致性单测
"C:/Users/zhengmingzhi/.wb-build/gradle-8.7/bin/gradle.bat" testDebugUnitTest
```

### 装机

```bash
# 鸿蒙（hdc；多设备时必须 -t 指定，否则报 "need connect-key"）
hdc -t 127.0.0.1:5557 install -r dist/parent-hm-v1.5.0-unsigned.hap

# 安卓
adb -s emulator-5556 install -r dist/ParentGuardParent-v1.5.0-debug.apk
```

---

## 密钥与安全（重要）

仓库里**不包含任何真实密钥**，以下文件被 `.gitignore` 排除，需要各自准备：

| 文件 | 用途 | 怎么来的 |
|---|---|---|
| `child-harmony/entry/src/main/ets/service/GiteeSecrets.ets` | 孩子端内置的 Gitee 私人令牌 | 复制同目录 `GiteeSecrets.example.ets` 后填入 |
| `child-harmony/tools/.e2e-secrets.json` | E2E 联调的设备配对密钥 | 跑 `tools/gitee-e2e.py bind` 时自动生成 |

四个安全设计要点：

1. **签名校验**：下发的配置带 HMAC-SHA1 签名，签名输入串是手工拼接的字符串，
   两端只要差一个分隔符就整份拒绝。所以 `parent-android` 里有 `GiteeCodecTest`
   用固定向量把它钉死 —— 改任一侧的拼串逻辑，单测会立刻红。
2. **防回滚**：配置带单调递增的 `rev`（家长密码另用 `pwdRev`），旧版本签名虽然有效也会被拒绝，
   防止有人拿一份「更宽松」的历史配置或旧密码派生值回滚。
   家长密码重置（FR-10）走的也是这条路：重置后 `pwdRev` **只增不减**。
3. **令牌归属**：孩子端**必然**持有令牌（它要往云端上报状态），这是方案固有属性。
   真正的防线是签名 + 防回滚，而不是藏令牌。
4. **时段规则纳入签名**：多时段控制（FR-11）的 `timeRules` 是 `config` 段签名输入串的末位字段；
   家长密码重置的 `reset` 标记同样进 `pwd` 段签名。孩子端改任一字段都会导致签名不符被整体拒绝。

> ⚠️ 历史遗留：`dist/` 里的 HAP 曾把真实令牌编译进包（`GiteeSecrets.ets` 的兜底默认值）。
> 这些二进制**不入库**；但泄露过的令牌应当**去 Gitee 上 revoke 换新**。

---

## 已知边界

- 鸿蒙 **没有系统级锁屏 API**，孩子端的锁是**应用内闸门** —— 只能盖住自己，盖不住系统设置。
  强管控（禁用系统设置、限制装应用）需要企业 MDM / Kiosk。
- 应用白名单**没有执行力**：三方应用拿不到已装应用列表（需要 system_basic 级受控权限）。

## 版本

| 端 | 版本 | versionCode |
|---|---|---|
| child-harmony | 1.5.0 | 1000008 |
| parent-android | 1.5.0 | 7 |
| parent-harmony | 1.5.0 | 1000003 |

> 版本对齐说明：`1.5.0` 对应 **FR-12（多家长连接，V1.5）+ FR-10（家长密码重置）+ FR-11（多时段控制）**。
> 三端 `PG_APP_VERSION` / `GITEE_APP_VERSION` 与各端打包版本号保持一致，协议变更记录见
> `child-harmony/PROTOCOL.md` §10 的 `v1.5.0` 行。