# Kiosk 模式 - 无需 JS 调用集成方案

## 🎯 需求说明

在 UniApp 离线 Android 工程中，实现 Kiosk 模式功能（禁用锁屏、防退出等）**无需通过 JS 调用**，应用启动时自动激活。

## ✅ 解决方案

### 核心思路
通过自定义 `Application` 类，在应用启动时自动注册 Activity 生命周期监听，当主 Activity 创建时自动调用 Kiosk 相关功能。

### 实现文件

#### 1. **MyApplication.java** - 自定义 Application
- 路径：`app/src/main/java/com/YuyeTech/HeartRate/MyApplication.java`
- 作用：
  - 继承 `DCloudApplication`（保持 UniApp 功能）
  - 注册 Activity 生命周期回调
  - 在 `PandoraEntry`/`PandoraEntryActivity` 创建时自动初始化 Kiosk

#### 2. **KioskHelper.java** - 锁屏控制辅助类
- 路径：`app/src/main/java/com/YuyeTech/HeartRate/KioskHelper.java`
- 提供方法：
  - `disableLockScreen(Activity)` - 禁用锁屏
  - `keepScreenOn(Activity)` - 屏幕常亮
  - `enableLockScreen(Activity)` - 恢复锁屏

#### 3. **AndroidManifest.xml** - 配置清单
- 修改 Application 为 `com.YuyeTech.HeartRate.MyApplication`
- 添加必要权限和 Receiver

#### 4. **device_admin.xml** - Device Admin 策略
- 路径：`app/src/main/res/xml/device_admin.xml`
- 定义设备管理员权限

## 📦 涉及的模块

### myLockView 模块
提供以下功能：
- ✅ **KioskManager** - Kiosk 模式管理（LockTask、全屏、按键拦截）
- ✅ **KioskDeviceAdminReceiver** - Device Admin 接收器
- ✅ **BootReceiver** - 开机启动支持
- ✅ **五指逃生门** - 5 指长按 5 秒 + 密码 9527 退出

### myWIFIView 模块
提供 WiFi 配置功能：
- 📶 WiFi 扫描
- 🔐 WiFi 连接（支持开放/加密网络）
- 📱 WiFi 断开
- 💡 **注意**：这是交互式功能，需要通过 JS 调用 `showWifiDialogView()`

## 🔄 执行流程

```
应用启动
    ↓
MyApplication.onCreate()
    ↓
注册 ActivityLifecycleCallbacks
    ↓
PandoraEntry 创建
    ↓
onActivityCreated() 被触发
    ↓
判断是否为主 Activity
    ↓
KioskHelper.disableLockScreen(activity)  ← ✅ 自动执行（无需 JS）
    ↓
KioskHelper.keepScreenOn(activity)       ← ✅ 自动执行（无需 JS）
    ↓
KioskManager.attach(activity)            ← ✅ 自动执行（无需 JS）
    ↓
进入 Kiosk 模式
```

## 🔑 关键配置

### 1. AndroidManifest.xml 修改

```xml
<!-- 替换 Application -->
<application
    android:name="com.YuyeTech.HeartRate.MyApplication"  <!-- ← 改这里 -->
    ...>
```

```xml
<!-- 添加权限 -->
<uses-permission android:name="android.permission.DISABLE_KEYGUARD" />
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
```

```xml
<!-- 添加 Device Admin Receiver -->
<receiver
    android:name="com.ble.mylockview.admin.KioskDeviceAdminReceiver"
    android:permission="android.permission.BIND_DEVICE_ADMIN"
    android:exported="true">
    <meta-data
        android:name="android.app.device_admin"
        android:resource="@xml/device_admin" />
    <intent-filter>
        <action android:name="android.app.action.DEVICE_ADMIN_ENABLED" />
    </intent-filter>
</receiver>
```

### 2. MyApplication 核心代码

```java
@Override
public void onCreate() {
    super.onCreate();
    
    // 配置 Kiosk
    LaunchConfig.setLaunchActivity(PandoraEntry.class);
    KioskManager.setDebug(BuildConfig.DEBUG);
    
    // 注册生命周期监听
    registerActivityLifecycleCallbacks(new ActivityLifecycleCallbacks() {
        @Override
        public void onActivityCreated(@NonNull Activity activity, @Nullable Bundle savedInstanceState) {
            if (activity instanceof io.dcloud.PandoraEntry || 
                activity instanceof io.dcloud.PandoraEntryActivity) {
                
                // ✅ 自动禁用锁屏（无需 JS 调用）
                KioskHelper.disableLockScreen(activity);
                KioskHelper.keepScreenOn(activity);
                
                // ✅ 自动绑定 KioskManager
                KioskManager.attach(activity);
            }
        }
        
        @Override
        public void onActivityResumed(@NonNull Activity activity) {
            if (activity instanceof io.dcloud.PandoraEntry || 
                activity instanceof io.dcloud.PandoraEntryActivity) {
                KioskManager.onResume();
            }
        }
        
        // ... 其他生命周期回调
    });
}
```

## 🚀 部署步骤

### 第 1 步：设置 Device Owner（必需）

⚠️ **完整 Kiosk 功能需要 Device Owner 权限**

```bash
# 1. 恢复出厂设置（移除所有账号）
# 2. 安装 APK
adb install app-release.apk

# 3. 设置为 Device Owner
adb shell dpm set-device-owner com.YuyeTech.HeartRate/com.ble.mylockview.admin.KioskDeviceAdminReceiver

# 4. 验证
adb shell dumpsys device_policy | grep "Device Owner"
```

### 第 2 步：编译测试

```bash
# Debug 版本（宽松模式）
./gradlew assembleDebug

# Release 版本（严格模式）
./gradlew assembleRelease
```

### 第 3 步：验证功能

```bash
# 查看日志
adb logcat | grep -E "MyApplication|KioskHelper|KioskManager"

# 期望看到：
# D MyApplication: Application 初始化
# D MyApplication: ✅ 绑定 Kiosk 到: PandoraEntry
# D KioskHelper: ✅ 锁屏已禁用
# D KioskHelper: ✅ 屏幕保持常亮
# D KioskManager: ✅ LockTask 启用（一次）
```

## 📊 功能对比

| 功能 | Device Owner | 非 Device Owner |
|------|-------------|----------------|
| 自动初始化 | ✅ | ✅ |
| 屏幕常亮 | ✅ | ✅ |
| 全屏沉浸 | ✅ | ✅ |
| 禁用锁屏 | ✅ | ❌ |
| LockTask 模式 | ✅ | ❌ |
| 拦截 Home/Back | ✅ | ⚠️ 部分 |
| 五指逃生门 | ✅ | ✅ |

## 🐛 常见问题

### Q1: 日志显示 "⚠️ 不是 Device Owner"
**A**: 应用可以运行，但 Kiosk 功能受限。需要按照"部署步骤"设置 Device Owner。

### Q2: 无法设置 Device Owner
**A**: 
1. 确保设备恢复出厂设置
2. 移除所有账号（包括 Google 账号）
3. 不要在初始设置中登录账号
4. 重新执行 `dpm set-device-owner` 命令

### Q3: 应用启动后没有进入 Kiosk 模式
**A**: 检查：
1. `AndroidManifest.xml` 中 Application 是否改为 `MyApplication`
2. 查看日志是否有 `✅ 绑定 Kiosk 到: PandoraEntry`
3. 确认是否设置为 Device Owner

### Q4: 如何退出 Kiosk 模式？
**A**: 
- **运维人员**：5 指长按 5 秒 → 输入密码 9527
- **开发者**：
  ```bash
  adb shell am task lock stop
  # 或
  adb shell am force-stop com.YuyeTech.HeartRate
  ```

## 🔧 自定义配置

### 修改管理员密码
```java
// myLockView/src/main/java/com/ble/mylockview/admin/KioskManager.java
private static final String ADMIN_PASSWORD = "您的新密码";
```

### 修改逃生门条件
```java
private static final int ADMIN_FINGER_COUNT = 5;      // 手指数量
private static final long ADMIN_HOLD_TIME = 5000;     // 长按时间（毫秒）
```

### 禁用开机自启动
```xml
<!-- AndroidManifest.xml -->
<receiver
    android:name="com.ble.mylockview.boot.BootReceiver"
    android:enabled="false"  <!-- 改为 false -->
    ...>
```

## 📚 相关文档

- **KIOSK_SETUP_GUIDE.md** - 详细配置指南
- **QUICK_TEST_GUIDE.md** - 快速测试指南（无需 Device Owner）

## 💡 最佳实践

1. **开发阶段**：
   - 使用 Debug 模式（`BuildConfig.DEBUG = true`）
   - 不设置 Device Owner，方便调试
   - 保留 ADB 访问权限

2. **测试阶段**：
   - 在测试设备上设置 Device Owner
   - 验证完整 Kiosk 功能
   - 测试五指逃生门

3. **生产部署**：
   - 使用 Release 模式
   - 批量配置 Device Owner（NFC/QR Code）
   - 修改默认管理员密码
   - 准备应急恢复方案

## 📞 技术支持

查看详细日志：
```bash
adb logcat -v time | grep -E "KioskManager|MyApplication|KioskHelper|BootLauncher"
```

检查 Device Owner 状态：
```bash
adb shell dumpsys device_policy
```

移除 Device Owner（应急）：
```bash
adb shell dpm remove-active-admin com.YuyeTech.HeartRate/com.ble.mylockview.admin.KioskDeviceAdminReceiver
```

---

**创建时间**：2026-01-22  
**适用版本**：UniApp 离线打包 + Android 8.0+  
**核心优势**：✅ 无需 JS 调用，应用启动自动激活 Kiosk 模式