# m-permission-manager 权限配置说明

本文档说明集成本插件时，**各端需要修改哪些文件**、**如何配置权限**，以及插件内置配置文件的作用。

---

## 1. 配置总览

| 平台 | 配置文件 | 配置方 | 说明 |
| --- | --- | --- | --- |
| **Android** | 宿主 `manifest.json` | 集成者 | 声明 `android.permission.*` |
| **iOS** | 宿主 `manifest.json` | 集成者 | 声明 `NS*UsageDescription` |
| **Harmony** | 插件 `utssdk/app-harmony/module.json5`（可选：`harmony-configs/entry/src/main/module.json5`） | 插件内置为主，集成者可切换 full 版或宿主覆盖 |

> 插件负责**运行时检查与申请**；Android / iOS 的**静态声明**必须由宿主项目在 manifest 中完成。Harmony 权限由插件 module 合并进宿主包，集成者按需切换 normal / full 版本。

---

## 2. Android 配置

### 2.1 配置文件

**路径**：项目根目录 `manifest.json`  
**节点**：`app-plus.distribute.android.permissions`

```json
{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.CAMERA\"/>",
          "<uses-permission android:name=\"android.permission.RECORD_AUDIO\"/>",
          "<uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\"/>",
          "<uses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\"/>",
          "<uses-permission android:name=\"android.permission.READ_CONTACTS\"/>",
          "<uses-permission android:name=\"android.permission.BLUETOOTH_CONNECT\"/>",
          "<uses-permission android:name=\"android.permission.BLUETOOTH_SCAN\"/>",
          "<uses-permission android:name=\"android.permission.READ_MEDIA_IMAGES\"/>",
          "<uses-permission android:name=\"android.permission.READ_MEDIA_VIDEO\"/>"
        ]
      }
    }
  }
}
```

### 2.2 统一 Key 与 Android 权限映射

| 插件 Key | Android 权限 | 备注 |
| --- | --- | --- |
| `camera` | `CAMERA` | |
| `photoLibrary` | `READ_MEDIA_IMAGES`（API 33+）或 `READ_EXTERNAL_STORAGE` | 插件按 SDK 自动选择 |
| `storage` | `READ_MEDIA_IMAGES` + `READ_MEDIA_VIDEO`（API 33+）或 `WRITE/READ_EXTERNAL_STORAGE` | |
| `readStorage` | 同 `photoLibrary` / 媒体读权限 | |
| `location` | `ACCESS_FINE_LOCATION` | |
| `coarseLocation` | `ACCESS_COARSE_LOCATION` | |
| `microphone` | `RECORD_AUDIO` | |
| `contacts` | `READ_CONTACTS` | |
| `writeContacts` | `WRITE_CONTACTS` | |
| `bluetooth` | `BLUETOOTH_CONNECT` + `BLUETOOTH_SCAN`（API 31+）或 `BLUETOOTH` + `BLUETOOTH_ADMIN` | |
| `phone` | `CALL_PHONE` | |
| `phoneState` | `READ_PHONE_STATE` | |
| `sms` | `SEND_SMS` | |
| `readSms` | `READ_SMS` | |
| `receiveSms` | `RECEIVE_SMS` | |
| `overlay` | 无 manifest 条目 | 通过 `Settings.canDrawOverlays` 检查 |
| `writeSettings` | 无 manifest 条目 | 通过 `Settings.System.canWrite` 检查 |

### 2.3 注意

- 只声明业务使用的权限，避免过度申请
- Android 13+ 媒体权限使用 `READ_MEDIA_*`；插件仅在 **targetSdkVersion >= 33** 时动态申请新媒体权限，否则回退 `READ_EXTERNAL_STORAGE`（兼容 targetSdk 偏低的自定义基座）
- `overlay`、`writeSettings` 需在 manifest 声明对应 capability 后，通过插件跳转系统设置页授权

---

## 3. iOS 配置

### 3.1 配置文件

**路径**：项目根目录 `manifest.json`  
**节点**：`app-plus.distribute.ios.privacyDescription`

```json
{
  "app-plus": {
    "distribute": {
      "ios": {
        "privacyDescription": {
          "NSCameraUsageDescription": "需要使用相机进行拍照",
          "NSMicrophoneUsageDescription": "需要使用麦克风进行录音",
          "NSPhotoLibraryUsageDescription": "需要访问相册以选择图片",
          "NSPhotoLibraryAddUsageDescription": "需要保存图片到相册",
          "NSLocationWhenInUseUsageDescription": "需要获取位置信息",
          "NSContactsUsageDescription": "需要访问通讯录",
          "NSBluetoothAlwaysUsageDescription": "需要使用蓝牙连接周边设备"
        }
      }
    }
  }
}
```

### 3.2 统一 Key 与 Info.plist 键映射

| 插件 Key | Info.plist 键 | 备注 |
| --- | --- | --- |
| `camera` | `NSCameraUsageDescription` | |
| `photoLibrary` | `NSPhotoLibraryUsageDescription` | |
| `storage` | `NSPhotoLibraryUsageDescription` 或 `NSPhotoLibraryAddUsageDescription` | 映射到相册 |
| `readStorage` | `NSPhotoLibraryUsageDescription` | 映射到相册 |
| `location` | `NSLocationWhenInUseUsageDescription` | |
| `coarseLocation` | `NSLocationWhenInUseUsageDescription` | 与精确定位共用 |
| `microphone` | `NSMicrophoneUsageDescription` | |
| `contacts` | `NSContactsUsageDescription` | |
| `writeContacts` | `NSContactsUsageDescription` | 读写共用 |
| `bluetooth` | `NSBluetoothAlwaysUsageDescription` | **必须配置**，否则 App 设置页无蓝牙开关 |

### 3.3 iOS 蓝牙特别说明

iOS 蓝牙涉及两个独立概念：

| 概念 | 设置路径 | 配置要求 |
| --- | --- | --- |
| 系统蓝牙开关 | 设置 → 蓝牙 | 无需 manifest，用户手动打开 |
| App 蓝牙授权 | 设置 → 本 App → 蓝牙，或 设置 → 隐私与安全性 → 蓝牙 | 需 `NSBluetoothAlwaysUsageDescription` + 重新打包 + App 曾触发弹窗 |

Apple 不提供跳转到「隐私 → 蓝牙」的公开深链；插件 `openPermissionSettings('bluetooth')` 会打开 App 设置页并配合引导文案。

---

## 4. Harmony 配置

### 4.1 harmony-configs 要不要配？

**使用 m-permission-manager 时，一般不需要在 `harmony-configs/` 里重复声明权限。**

鸿蒙端权限有两种配置路径：

| 方式 | 配置文件 | 适用场景 |
| --- | --- | --- |
| **UTS 插件声明（推荐）** | `uni_modules/m-permission-manager/utssdk/app-harmony/module.json5` | 插件打包为鸿蒙子模块（HAR），权限对整个 App 生效 |
| **宿主工程覆盖** | `harmony-configs/entry/src/main/module.json5` | 插件未覆盖的权限、或希望在宿主侧集中管理 |

鸿蒙官方规则：**已在子模块中声明的权限，主工程无需重复添加**，权限在整个应用中生效。  
m-permission-manager 作为 UTS 插件，其 `module.json5` 会在编译时拷贝为插件子模块的 `src/main/module.json5`，因此**默认情况下宿主不必再配**。

当前项目的 `harmony-configs/` 主要用于：

| 文件 | 用途 |
| --- | --- |
| `AppScope/app.json5` | 包名、版本、图标（HX 4.31+ 也可在 `manifest.json` → `app-harmony` 图形界面配置） |
| `build-profile.json5` | 签名证书（`.cer` / `.p12` / `.p7b`） |
| `entry/build-profile.json5` | release 混淆等构建选项 |
| `entry/obfuscation-rules.txt` | 混淆规则 |

**若要在 harmony-configs 中配置权限**（可选，非必须）：

1. 先运行一次鸿蒙编译，从 `unpackage/dist/dev/app-harmony/entry/src/main/module.json5` 复制完整文件到 `harmony-configs/entry/src/main/module.json5`
2. **仅修改** `module.requestPermissions` 节点，其他节点不要删（uni-app 是**文件级覆盖**，不是 JSON 节点合并）
3. 不要与插件已声明的权限重复

> 集成 m-permission-manager 时，优先改插件内的 `module.json5` / `module.full.json5`，而不是 harmony-configs。

### 4.2 插件内置文件

**目录**：`uni_modules/m-permission-manager/utssdk/app-harmony/`

| 文件 | 权限数量 | APL 等级 | 用途 |
| --- | --- | --- | --- |
| `module.json5` | 5 项 | normal | **默认生效**，调试证书可直接安装 |
| `module.normal.json5` | 5 项 | normal | 与 `module.json5` 相同，备份参考 |
| `module.full.json5` | 9 项 | normal + system_basic | 含相册 / 通讯录，需 ACL 签名 |

**权限说明文案**：`resources/base/element/string.json`

### 4.3 默认 module.json5（5 项 normal）

| 插件 Key | ohos.permission | 说明 |
| --- | --- | --- |
| `camera` | `CAMERA` | |
| `microphone` | `MICROPHONE` | |
| `location` | `LOCATION` | |
| `coarseLocation` | `APPROXIMATELY_LOCATION` | |
| `bluetooth` | `ACCESS_BLUETOOTH` | |

### 4.4 module.full.json5 额外 4 项（system_basic，需 ACL）

| 插件 Key | ohos.permission | APL | 说明 |
| --- | --- | --- | --- |
| `photoLibrary` / `readStorage` | `READ_IMAGEVIDEO` | system_basic | 需 ACL |
| `storage` | `WRITE_IMAGEVIDEO` | system_basic | 需 ACL |
| `contacts` | `READ_CONTACTS` | system_basic | 需 ACL |
| `writeContacts` | `WRITE_CONTACTS` | system_basic | 需 ACL |

### 4.5 如何切换 full 版本

1. 将 `module.full.json5` 的内容**覆盖** `module.json5`
2. 在 AppGallery Connect 配置 ACL 白名单
3. 使用正式 Profile 重新签名打包
4. 重新制作自定义基座或云打包

### 4.6 未声明 ACL 权限时的插件行为

| 场景 | 检查 status | 申请结果 |
| --- | --- | --- |
| 相册 / 通讯录等未在 module.json5 声明 | `restricted` | 9020003，附未声明说明 |
| 系统设置 | 无对应开关 | 引导使用 `uni.chooseImage` 或切换 full 版本 |

### 4.7 安装报 9568289

说明 `module.json5` 中含有未签名的 system_basic 权限。请确认使用默认 5 项 normal 版本；若已合并 full 版本，需先完成 ACL 与 Profile 签名。

### 4.8 鸿蒙不支持的功能

以下插件 Key 在鸿蒙返回 `unsupported`：`phone`、`phoneState`、`sms`、`readSms`、`receiveSms`、`overlay`、`writeSettings`。

---

## 5. 配置示例（按业务场景）

### 5.1 仅需相机 + 麦克风

**Android** manifest：

```json
"permissions": [
  "<uses-permission android:name=\"android.permission.CAMERA\"/>",
  "<uses-permission android:name=\"android.permission.RECORD_AUDIO\"/>"
]
```

**iOS** privacyDescription：

```json
"privacyDescription": {
  "NSCameraUsageDescription": "需要使用相机",
  "NSMicrophoneUsageDescription": "需要使用麦克风"
}
```

**Harmony**：默认 `module.json5` 已包含，无需修改。

### 5.2 需要蓝牙

**Android** manifest 增加：

```json
"<uses-permission android:name=\"android.permission.BLUETOOTH_CONNECT\"/>",
"<uses-permission android:name=\"android.permission.BLUETOOTH_SCAN\"/>"
```

**iOS** privacyDescription 增加：

```json
"NSBluetoothAlwaysUsageDescription": "需要使用蓝牙连接周边设备"
```

**Harmony**：默认 `module.json5` 已包含 `ACCESS_BLUETOOTH`。

### 5.3 需要相册读写（Harmony 完整权限）

1. 用 `module.full.json5` 覆盖 `module.json5`
2. 配置 ACL 签名
3. Android 增加 `READ_MEDIA_IMAGES` / `READ_MEDIA_VIDEO`
4. iOS 增加 `NSPhotoLibraryUsageDescription`

> 若仅需选图不上传，推荐使用 `uni.chooseImage`，三端均无需媒体读写权限。

---

## 6. 配置后必做

1. **重新制作自定义基座**或云打包（UTS 插件 + manifest 变更均须重新打包）
2. iOS 修改 `privacyDescription` 后建议删除旧 App 重装，以重新触发授权弹窗
3. Harmony 切换 `module.json5` 后需重新签名安装

---

## 7. 相关文档

- [readme.md](./readme.md) — API 与权限 Key 对照表
- [使用规范.md](./使用规范.md) — 集成流程与审核注意事项
- [发布指南.md](./发布指南.md) — 插件市场发布填写参考