# QSJNIC SystemService 集成与部署指南

## 系统要求
- Android 8.0+ (API 26+)
- arm64-v8a
- 系统需预置 QsmwService.apk 到 `/system/priv-app/QsmwService/`

## 权限
- 生产环境: `signature|privileged`
- 开发环境: 可降级为 `normal`（修改 service AndroidManifest）

## App 依赖
```gradle
dependencies {
    implementation(files("libs/qsmw-sdk.aar"))
    implementation(files("libs/qsmw-contract.aar"))
}
```

## AndroidManifest.xml
```xml
<uses-permission android:name="cn.qsjnic.permission.MCU_ACCESS"/>
```

## 初始化
```java
McuClient.getInstance().init(applicationContext);
McuClient.getInstance().addReadyListener(() -> {
    // Service 已连接，可调用 API
});
```

## 监听器注册
```java
McuClient.getInstance().vehicle().addListener(new VehicleListener() { ... });
```

## 混淆
```proguard
-keep class com.qsjnic.mcu.contract.** { *; }
-keep class com.qsjnic.mcu.sdk.** { *; }
```

## 多用户说明
本版本（beta6 起）在 `QsMcuSystemService` 和 `BootCompletedReceiver` 中增加了 `android:singleUser="true"` 声明，确保服务仅运行于 user 0，防止多用户并发访问 `/dev/ttyS7` 导致串口竞争。系统集成时无需额外配置，但需确认系统支持 `singleUser` 属性（Android 5.0+ 默认支持）。

beta7 变更：Key 域键值定义从 MC3 标准切换为帕杰罗映射表（Key.xlsx "其它项目"），新增 5 个扩展键值（0x0E/0x0F/0x18/0x19/0x25），校验范围放宽至 0x00-0x25。配套 MCU 固件更新至 PAJERO69XZA0120018 (SW: 0302_20260527)。

## Key 域系统集成说明

Key 域采用 **Framework 层 `InputManager.injectInputEvent` 注入方案**（方案三），而非 Linux 驱动层（方案一）或 VHAL（方案二）。这意味着：

1. **事件分发**：MCU 方控事件被转换为标准 Android `KeyEvent` 后注入 Input 子系统，所有应用均可通过 `onKeyDown`/`onKeyUp` 或 `dispatchKeyEvent` 接收。
2. **权限要求**：Service 必须持有 `android.permission.INJECT_EVENTS`，该权限仅限 `signature|privileged` 系统应用。请务必以系统签名预置到 `/system/priv-app/QsmwService/`。
3. **KeyEvent 映射**：Service 内部维护帕杰罗键值 → Android `KeyEvent.KEYCODE_*` 的映射表（如 `0x03` → `KEYCODE_VOICE_ASSIST`、`0x08` → `KEYCODE_VOLUME_DOWN` 等），客户侧无需关心底层映射。
4. **适用场景**：若客户系统已存在自定义 keylayout（方案一）或 VHAL 键值映射（方案二），需评估是否与本方案冲突。两种方案不能同时处理同一物理按键，否则会导致重复事件。

## 常见错误码
| 码 | 含义 |
|---|---|
| 0 | OK |
| -1 | ERR_LINK_DOWN |
| -2 | ERR_UPGRADE_BUSY |
| -3 | ERR_FILE |
| -4 | ERR_SERVICE |
| -5 | ERR_PERMISSION |
| -6 | ERR_TIMEOUT |
| -7 | ERR_INVALID_ARG |
| -8 | ERR_RECONNECTING |
| -9 | ERR_NOT_IMPLEMENTED |
| -10 | ERR_MCU_DEADLOCK |

## 验证命令

```bash
# 1. 检查包是否已安装
adb shell pm list package | grep qsjnic

# 2. 检查版本号
adb shell dumpsys package com.qsjnic.mcu.service | grep -E "versionCode|versionName"
# 期望: versionCode=107, versionName=1.0.0-beta7

# 3. 检查权限
adb shell dumpsys package com.qsjnic.mcu.service | grep -A2 "cn.qsjnic.permission.MCU_ACCESS"

# 4. 查看服务日志
adb logcat -d -s McuClient:SystemService:McuLink

# 5. 检查串口设备权限
adb shell ls -l /dev/ttyS7
```