# 项目结构说明

## 📁 整体结构

```
bBeng-HeartRate-4.66-pad/
├── app/                          # 主应用模块
├── core/                         # 核心模块（语音识别等）
├── ICDeviceManager/              # IC 设备管理模块
├── myLockView/                   # ✅ Kiosk 模式模块（本次集成重点）
├── myWIFIView/                   # ✅ WiFi 配置模块
├── uniplugin_module/             # UniApp 插件模块
├── build.gradle                  # 根项目构建配置
└── settings.gradle               # 模块配置
```

## 📦 模块详细说明

### 1. app/ - 主应用模块

```
app/
├── src/main/
│   ├── AndroidManifest.xml                              # ✅ 已修改（Application、权限、Receiver）
│   ├── assets/                                          # UniApp 资源文件
│   │   └── apps/__UNI__8D02B4B/www/                    # UniApp 编译产物
│   ├── java/com/YuyeTech/HeartRate/
│   │   ├── MyApplication.java                           # ✅ 新增（自定义 Application）
│   │   └── KioskHelper.java                             # ✅ 新增（锁屏控制辅助类）
│   └── res/
│       ├── xml/
│       │   └── device_admin.xml                         # ✅ 新增（Device Admin 配置）
│       ├── values/
│       │   ├── strings.xml
│       │   └── themes.xml
│       └── drawable/...                                 # 图标、启动图等
├── libs/                                                # AAR 依赖库
│   ├── lib.5plus.base-release.aar                       # DCloud 5+ 基础库
│   ├── uniapp-v8-release.aar                            # UniApp V8 引擎
│   └── ...                                              # 其他第三方库
└── build.gradle                                         # 应用构建配置
```

**关键文件**：
- `MyApplication.java` - 应用入口，负责自动初始化 Kiosk
- `KioskHelper.java` - 提供静态方法控制锁屏
- `AndroidManifest.xml` - 声明 Application、权限、Receiver

---

### 2. myLockView/ - Kiosk 模式模块 🔐

```
myLockView/
├── src/main/
│   ├── AndroidManifest.xml                              # 模块清单（Receiver 声明）
│   ├── java/com/ble/mylockview/
│   │   ├── admin/                                       # 设备管理
│   │   │   ├── KioskManager.java                        # 🌟 Kiosk 核心管理器
│   │   │   └── KioskDeviceAdminReceiver.java           # Device Admin 接收器
│   │   ├── boot/                                        # 开机启动
│   │   │   ├── BootReceiver.java                       # 开机广播接收器
│   │   │   ├── BootLauncher.java                       # 启动逻辑
│   │   │   └── BootActionChecker.java                  # 启动条件检查
│   │   ├── config/                                      # 配置
│   │   │   └── LaunchConfig.java                       # Activity 配置
│   │   └── service/                                     # 服务
│   │       └── StartService.java                       # 前台服务
│   └── res/xml/
│       └── device_admin.xml                             # Device Admin 策略定义
└── build.gradle                                         # 模块构建配置
```

**核心功能**：

#### KioskManager.java
- ✅ LockTask 模式（防止退出应用）
- ✅ 全屏沉浸式（隐藏状态栏、导航栏）
- ✅ 按键拦截（Home、Back、Menu）
- ✅ 五指逃生门（5 指长按 5 秒 + 密码）
- ✅ Activity 生命周期管理

**关键 API**：
```java
KioskManager.setDebug(boolean)          // 设置调试模式
KioskManager.attach(Activity)           // 绑定 Activity
KioskManager.onResume()                 // Activity onResume
KioskManager.onPause()                  // Activity onPause
KioskManager.onDestroy()                // Activity onDestroy
KioskManager.exitKiosk()                // 退出 Kiosk 模式
KioskManager.interceptKey(KeyEvent)     // 拦截按键
KioskManager.interceptTouch(MotionEvent) // 拦截触摸（逃生门）
```

#### BootReceiver.java
- 监听开机广播
- 自动启动应用
- 支持 Direct Boot（加密设备快速启动）

---

### 3. myWIFIView/ - WiFi 配置模块 📶

```
myWIFIView/
├── src/main/
│   ├── AndroidManifest.xml
│   ├── java/com/ble/mywifiview/
│   │   ├── WifiModule.java                              # 🌟 WiFi 核心模块
│   │   ├── WifiAdapter.java                            # WiFi 列表适配器
│   │   ├── WifiScanItem.java                           # WiFi 扫描项
│   │   ├── WifiCallback.java                           # 连接回调接口
│   │   ├── WifiConnector.java                          # 连接工具类
│   │   ├── WifiPasswordDialog.java                     # 密码输入对话框
│   │   └── WifiDisconnectDialog.java                   # 断开确认对话框
│   └── res/
│       ├── layout/
│       │   ├── dialog_wifi_list.xml                    # WiFi 列表对话框
│       │   ├── item_wifi.xml                           # WiFi 列表项
│       │   └── dialog_wifi_password.xml                # 密码输入对话框
│       └── drawable/                                    # WiFi 图标资源
└── build.gradle
```

**核心功能**：

#### WifiModule.java
- ✅ WiFi 扫描（支持 Android 8 ~ 14）
- ✅ WiFi 连接（开放/加密网络）
- ✅ WiFi 断开
- ✅ 已保存网络管理
- ✅ 权限请求（位置权限）
- ✅ 自动处理 Android 10+ 限制

**关键 API**：
```java
WifiModule.showWifiDialogView(Context, WifiCallback)  // 显示 WiFi 列表对话框
WifiModule.scan(Context)                              // 扫描 WiFi
WifiModule.connect(Context, ssid, password, callback) // 连接 WiFi
WifiModule.disconnect(Context)                        // 断开 WiFi
WifiModule.isWifiReallyConnected(Context)            // 检查 WiFi 连接状态
WifiModule.getConnectedWifiSsid(Context)             // 获取当前连接的 SSID
WifiModule.openWifiSettings(Context)                  // 跳转系统 WiFi 设置
```

**使用方式**：
```java
// 从 JS 调用（需要交互）
WifiModule.showWifiDialogView(activity, new WifiCallback() {
    @Override
    public void onConnecting() {
        // 正在连接
    }
    
    @Override
    public void onConnected() {
        // 连接成功
    }
    
    @Override
    public void onFailed(String reason) {
        // 连接失败
    }
    
    @Override
    public void onDisconnected() {
        // 已断开
    }
});
```

---

### 4. uniplugin_module/ - UniApp 插件模块

```
uniplugin_module/
├── src/main/
│   ├── AndroidManifest.xml
│   └── java/io/dcloud/uniplugin/
│       ├── HeartRateModule.java                         # 心率模块（JS 接口）
│       ├── ICDeviceModule.java                          # IC 设备模块（JS 接口）
│       ├── TestModule.java                              # 测试模块
│       ├── NativePageActivity.java                      # 原生页面
│       ├── permission.java                              # 权限管理
│       └── db800/                                       # DB800 心率设备 SDK
│           ├── HeartRateSdkManager.java
│           ├── BluetoothUtils.java
│           ├── HearRateManagerCallbacks.java
│           └── ScannerPacket.java
└── build.gradle
```

**说明**：
- 这是 UniApp 和原生模块的桥接层
- 通过 `uni.requireNativePlugin()` 从 JS 调用原生功能
- 包含心率设备、IC 设备等业务模块

---

### 5. core/ - 核心模块

```
core/
├── src/main/
│   ├── AndroidManifest.xml
│   ├── java/...                                         # 百度语音识别相关
│   └── jniLibs/                                         # 原生 .so 库
└── libs/
    └── bdasr_V3_20210628_cfe8c44.jar                    # 百度 ASR SDK
```

---

## 🔗 模块依赖关系

```
app (主应用)
 ├─→ core                        (语音识别)
 ├─→ ICDeviceManager             (IC 设备)
 ├─→ myLockView                  (Kiosk 模式) ✅
 ├─→ myWIFIView                  (WiFi 配置) ✅
 └─→ uniplugin_module            (UniApp 插件)
```

**在 `app/build.gradle` 中声明**：
```gradle
dependencies {
    implementation project(':core')
    implementation project(':ICDeviceManager')
    implementation project(':myLockView')        // ✅
    implementation project(':myWIFIView')        // ✅
    implementation project(':uniplugin_module')
    
    // UniApp 核心库
    implementation fileTree(dir: 'libs', include: ['*.aar', '*.jar'])
}
```

---

## ⚙️ 配置文件说明

### 1. settings.gradle
```gradle
include ':app'
include ':core'
include ':ICDeviceManager'
include ':myLockView'           // ✅
include ':myWIFIView'           // ✅
include ':uniplugin_module'
```

### 2. build.gradle（项目级）
```gradle
buildscript {
    ext.kotlin_version = '1.8.0'
    
    repositories {
        google()
        mavenCentral()
    }
    
    dependencies {
        classpath 'com.android.tools.build:gradle:7.4.2'
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}
```

### 3. build.gradle（app 模块）
```gradle
android {
    compileSdkVersion 33
    
    defaultConfig {
        applicationId "com.YuyeTech.HeartRate"
        minSdkVersion 26
        targetSdkVersion 33
        versionCode 1
        versionName "4.66"
    }
    
    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}
```

---

## 📝 本次修改文件清单

### ✅ 新增文件
1. `app/src/main/java/com/YuyeTech/HeartRate/MyApplication.java`
2. `app/src/main/java/com/YuyeTech/HeartRate/KioskHelper.java`
3. `app/src/main/res/xml/device_admin.xml`
4. `KIOSK_SETUP_GUIDE.md`
5. `QUICK_TEST_GUIDE.md`
6. `README_KIOSK_INTEGRATION.md`
7. `PROJECT_STRUCTURE.md` (本文件)

### ✏️ 修改文件
1. `app/src/main/AndroidManifest.xml`
   - 修改 Application 为 `MyApplication`
   - 添加 Kiosk 相关权限
   - 添加 Device Admin Receiver
   - 添加 Boot Receiver

---

## 🔍 关键代码位置

### Kiosk 自动初始化
**文件**：`app/src/main/java/com/YuyeTech/HeartRate/MyApplication.java`
**位置**：`onCreate()` → `registerActivityLifecycleCallbacks()` → `onActivityCreated()`
```java
@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.attach(activity);
    }
}
```

### 锁屏禁用实现
**文件**：`app/src/main/java/com/YuyeTech/HeartRate/KioskHelper.java`
**方法**：`disableLockScreen(Activity)`
```java
public static void disableLockScreen(Activity activity) {
    // 1. 解锁当前屏幕
    activity.getWindow().addFlags(
        WindowManager.LayoutParams.FLAG_DISMISS_KEYGUARD |
        WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED |
        WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON
    );
    
    // 2. 作为 Device Owner 禁用锁屏
    DevicePolicyManager dpm = ...;
    if (dpm.isDeviceOwnerApp(packageName)) {
        dpm.setKeyguardDisabled(adminComponent, true);
    }
}
```

### Kiosk 核心逻辑
**文件**：`myLockView/src/main/java/com/ble/mylockview/admin/KioskManager.java`
**关键方法**：
- `attach(Activity)` - 初始化（第 69 行）
- `enableLockTask()` - 启用 LockTask（第 107 行）
- `hideSystemUI()` - 隐藏系统 UI（第 165 行）
- `interceptTouch(MotionEvent)` - 五指逃生门（第 236 行）

---

## 📊 数据流向

### Kiosk 模式启动流程
```
System Boot
    ↓
MyApplication.onCreate()
    ↓
LaunchConfig.setLaunchActivity(PandoraEntry.class)
KioskManager.setDebug(BuildConfig.DEBUG)
    ↓
ActivityLifecycleCallbacks 注册
    ↓
User Launch App / BootReceiver 启动
    ↓
PandoraEntry.onCreate()
    ↓
onActivityCreated() 回调
    ↓
KioskHelper.disableLockScreen()     [禁用锁屏]
KioskHelper.keepScreenOn()          [屏幕常亮]
KioskManager.attach()               [进入 Kiosk]
    ↓
hideSystemUI()                      [隐藏状态栏]
enableLockTask()                    [锁定任务]
    ↓
Kiosk Mode Active ✅
```

### WiFi 配置流程
```
JS 调用
    ↓
uni.requireNativePlugin('myWIFIView')
    ↓
WifiModule.showWifiDialogView()
    ↓
检查权限 → 扫描 WiFi
    ↓
显示列表对话框
    ↓
用户点击 WiFi
    ↓
输入密码（如需）
    ↓
WifiModule.connect()
    ↓
Android 10+: NetworkRequest
Android 9-:  WifiConfiguration
    ↓
回调：onConnected() / onFailed()
```

---

## 🎯 关键技术点

### 1. UniApp 架构
- **DCloudApplication** - UniApp 基础 Application
- **PandoraEntry** - UniApp 启动 Activity（Launcher）
- **PandoraEntryActivity** - UniApp 主 Activity

### 2. Activity 生命周期监听
- `Application.ActivityLifecycleCallbacks` - 监听所有 Activity 生命周期
- 在 `onActivityCreated()` 中自动初始化 Kiosk

### 3. Device Owner 模式
- `DevicePolicyManager.setKeyguardDisabled()` - 禁用锁屏
- `DevicePolicyManager.setLockTaskPackages()` - 设置 LockTask 白名单
- `Activity.startLockTask()` - 进入 LockTask 模式

### 4. Android 版本兼容
- WiFi 模块兼容 Android 8 ~ 14
- Android 10+ 使用 `WifiNetworkSpecifier`
- Android 9- 使用 `WifiConfiguration`

---

## 🛠️ 开发工具链

### 构建工具
- **Gradle** 7.5
- **Android Gradle Plugin** 7.4.2
- **Kotlin** 1.8.0

### SDK 版本
- **compileSdkVersion** 33 (Android 13)
- **minSdkVersion** 26 (Android 8.0)
- **targetSdkVersion** 33 (Android 13)

### IDE
- Android Studio / Cursor
- HBuilderX（UniApp 开发）

---

## 📚 参考文档

- [Android Device Administration](https://developer.android.com/guide/topics/admin/device-admin)
- [LockTask Mode](https://developer.android.com/work/dpc/dedicated-devices/lock-task-mode)
- [WiFi Network Management](https://developer.android.com/reference/android/net/wifi/WifiManager)
- [UniApp 离线打包](https://nativesupport.dcloud.net.cn/AppDocs/README)

---

**最后更新**：2026-01-22  
**文档版本**：1.0