MrleeAdmin/frontend/app/docs/mas-code-scan-iOS支持方案.md

# mas-code-scan iOS 端支持方案

> 文档状态：方案设计，尚未开始 iOS 原生实现。
>
> 目标是在不改变现有业务调用方式的前提下，为 `mas-code-scan` 增加 iOS App 支持，并与 Android 端尽量保持相同的功能、参数语义、回调顺序和错误码。

---

## 1. 背景与目标

当前 `mas-code-scan` 是 Android UTS API 插件，Android 原生层基于 CameraX + Google ML Kit 实现。对外 API 已沉淀在 `utssdk/interface.uts`，业务页面通过 `openCodeScan` 调用，因此具备扩展 iOS 实现的良好基础。

### 1.1 当前状态

| 项目 | 当前情况 |
| --- | --- |
| 对外 API | `openCodeScan(options)` |
| 公共类型 | `CodeScanOptions`、`CodeScanSuccess`、`CodeScanFail`、`ScanRegion`、`CodeScanStyle` |
| Android 实现 | `utssdk/app-android/`，CameraX + Google ML Kit |
| iOS 实现 | 暂无 `utssdk/app-ios/` 目录 |
| 业务调用 | `pages/scan/prototype.vue` 只需调用统一 API |
| 当前支持平台 | Android App（uni-app Vue2/Vue3） |

### 1.2 建设目标

1. **API 不变**：iOS 与 Android 均使用 `openCodeScan`，业务页面不增加平台分支。
2. **回调一致**：统一 `success`、`fail`、`complete` 的数据结构和触发时机。
3. **优先原生能力**：使用 iOS 系统框架，尽量不新增第三方识别库。
4. **功能分阶段交付**：先完成可真机使用的最小链路，再逐步补齐 Android 已有能力。
5. **平台差异显式处理**：对系统不支持或实现成本较高的能力，明确降级或延后，不以静默不生效代替。

### 1.3 非目标

本期方案不包含：

- 鸿蒙、H5、小程序、nvue 支持；
- 修改 Android 识别链路；
- 将扫码页改造为 Vue 组件；
- 为尚未经过真机验证的 iOS 能力提前修改 README 平台声明。

---

## 2. 总体架构

### 2.1 目录规划

在保持现有 Android 目录不变的基础上新增 iOS 实现：

```text
frontend/scanapp/uni_modules/mas-code-scan/
├── package.json
├── readme.md
├── changelog.md
└── utssdk/
    ├── interface.uts                 # Android / iOS 共用公开类型
    ├── unierror.uts                  # Android / iOS 共用错误对象
    ├── app-android/                  # 现有 Android 实现
    │   ├── index.uts
    │   ├── CodeCaptureActivity.kt
    │   ├── MultiCodePickView.kt
    │   └── ScanFrameDecorView.kt
    └── app-ios/                      # 新增 iOS 实现
        ├── index.uts                 # UTS 桥接与回调编排
        ├── CodeCaptureViewController.swift
        ├── CodeScanner.swift
        ├── ScanOverlayView.swift
        ├── MultiCodePickView.swift
        ├── ScanStyleParser.swift
        └── Info.plist                # 或按 UTS iOS 配置规范声明权限
```

> `app-ios` 的最终配置文件和 Swift 文件参与编译方式，必须以当前 HBuilderX 版本的 UTS iOS 官方规范为准；开始编码前需要用官方最小示例验证目录结构。

### 2.2 分层职责

```text
业务页面
  ↓ openCodeScan(options)
UTS 平台入口（app-android/index.uts 或 app-ios/index.uts）
  ↓ 参数转换 / 生命周期 / 回调派发
原生扫码控制器
  ↓ 相机、识别、相册、交互
原生绘制层
  ↓ 扫描框、扫描线、多码点选、呼吸动画
```

- `interface.uts`：作为跨端 API 契约，不应写入 Android 或 iOS 私有字段。
- `app-ios/index.uts`：负责将 `CodeScanOptions` 转为原生配置，处理单次与连续扫码回调。
- `CodeCaptureViewController`：负责页面展示、权限、相机生命周期、工具栏和结果模式。
- `CodeScanner`：负责相机帧分析、Vision 识别、格式过滤、区域过滤和缩放策略。
- `ScanOverlayView`：负责 `scanStyle` 与 `scanRegion` 的视觉绘制。
- `MultiCodePickView`：负责多码定格、点选和绿色呼吸波纹。

---

## 3. iOS 技术选型

| 能力 | 推荐技术 | 选择理由 |
| --- | --- | --- |
| 相机预览与帧采集 | `AVFoundation` | 系统原生、稳定、无需新增依赖 |
| 条码识别 | `Vision` 的 `VNDetectBarcodesRequest` | 覆盖常见二维码与条形码，识别结果可获取码制和边界框 |
| 相册选图 | `PHPickerViewController` | iOS 14+ 可按用户选择读取图片，通常无需完整相册权限 |
| 低版本相册兼容 | `UIImagePickerController` | 仅在确认最低系统版本低于 iOS 14 时补充 |
| 扫描线动画 | `CAShapeLayer` + `CABasicAnimation` | 使用 Core Animation，避免定时器逐帧重绘 |
| 多码呼吸动画 | `CAShapeLayer` + `CABasicAnimation` | 与 Android 绿点呼吸波纹实现保持视觉一致 |
| 手势缩放 | `UIPinchGestureRecognizer` | 对应 Android 双指捏合 |
| 震动反馈 | `UIImpactFeedbackGenerator` | 适配 iOS 系统触感反馈 |

### 3.1 不引入第三方扫码库

首版不建议接入 ZXing、ML Kit iOS 等第三方库，原因：

- 系统 `Vision` 已能覆盖主要码制；
- 避免 CocoaPods/SPM 与 UTS iOS 构建的额外集成风险；
- 减少安装包和维护成本；
- 便于优先验证 UTS + Swift 桥接与相机链路。

若后续测试确认某些业务关键码制在 `Vision` 上识别率不足，再单独评估第三方引擎，不在首版预置依赖。

---

## 4. 公共 API 与行为约束

### 4.1 保持现有 API

现有 `CodeScanOptions` 不新增必填字段，iOS 端识别并实现以下参数：

| 参数 | iOS 首版目标 | 说明 |
| --- | --- | --- |
| `formats` | 支持 | 映射到 Vision 支持的 symbology；不支持值忽略 |
| `vibrate` | 支持 | 识别成功后触发轻触感反馈 |
| `fromAlbum` | 支持 | 打开扫码页后直接进入相册选择 |
| `scanRegion` | 支持 | 控制实时识别区域与扫描框；相册识图不受限制 |
| `scanStyle` | 支持 | 控制遮罩、边框、扫描线及动画 |
| `resultMode` | 支持 | `immediate`、`confirm`、`pause` |
| `continuous` | 支持 | 多次 `success`，关闭时 `complete` |
| `showPauseButton` | 支持 | 仅连续扫码时展示暂停/继续控制 |
| `torch: 'off'` | 支持 | 默认关闭 |
| `torch: 'on'` | 支持 | 设备支持时尝试开启 |
| `smartZoom` | 第二阶段 | 首版可读取但不自动变焦，后续补齐 |
| `torch: 'auto'` | 第二阶段 | 需要基于视频帧亮度策略验证 |

### 4.2 成功数据

iOS 识别结果必须统一转换为：

```ts
{
  content: string,
  format: string,
  fromAlbum: boolean
}
```

格式名称与 Android 对齐，至少包括：

```text
QR_CODE
EAN_13
EAN_8
UPC_A
UPC_E
CODE_128
CODE_39
CODE_93
ITF
CODABAR
PDF417
AZTEC
DATA_MATRIX
```

当 Vision 不支持某个 Android 已支持的格式时：

1. `formats` 中的该值不参与 Vision 请求；
2. 不因单个非法或不支持值使整个调用失败；
3. 若过滤后没有任何 iOS 支持的格式，可按全格式或返回 `9021004`，最终策略需在编码前固定，并同步文档；
4. 推荐与 Android 保持一致：过滤为空时退回全格式识别。

### 4.3 回调一致性

| 场景 | `success` | `fail` | `complete` |
| --- | --- | --- | --- |
| 单次扫码成功 | 调用一次 | 不调用 | 紧随成功调用一次，参数为成功结果 |
| 单次取消/关闭 | 不调用 | `9021003` | 紧随失败调用一次 |
| 相机权限拒绝 | 不调用 | `9021002` | 紧随失败调用一次 |
| 无有效扫码结果的异常结束 | 不调用 | `9021004` | 紧随失败调用一次 |
| 连续扫码单次命中 | 每次命中调用 | 不调用 | 页面未关闭前不调用 |
| 连续扫码关闭且已有命中 | 不再调用 | 不调用 | `complete({ closed: true, hitCount })` |
| 连续扫码关闭且无命中 | 不调用 | `9021003` | 紧随失败调用一次 |

所有业务回调必须在主线程派发，控制器关闭、权限回调和异步识别完成之间要有会话状态保护，确保不会重复回调。

### 4.4 错误码复用

继续使用 `unierror.uts` 中的错误码：

| 错误码 | 语义 | iOS 对应场景 |
| --- | --- | --- |
| `9021001` | 当前无法获取页面 Activity | 无法获取当前 `UIViewController` 或不能展示扫码页 |
| `9021002` | 相机权限被拒绝 | `.denied` / `.restricted` 或用户拒绝授权 |
| `9021003` | 用户取消扫码 | 点击关闭、系统返回或取消图片选择 |
| `9021004` | 未获取到有效的扫码结果 | 扫码处理异常结束、相册图片无有效条码后由调用方选择结束 |

---

## 5. 核心功能设计

### 5.1 相机权限与页面生命周期

流程：

```text
openCodeScan
  ↓
获取当前 UIViewController
  ↓
检查 AVCaptureDevice 相机权限
  ├─ 已授权 → 初始化扫码控制器与会话
  ├─ 未决定 → 请求授权 → 成功后初始化
  └─ 拒绝/受限 → fail(9021002) → complete
```

控制器生命周期要求：

- 页面展示时创建并启动 `AVCaptureSession`；
- 页面进入后台时暂停会话；
- 页面恢复前台时，未完成且未暂停时恢复会话；
- 页面关闭、成功返回或发生不可恢复错误时停止会话；
- 释放 `AVCaptureVideoDataOutput` 委托、图片引用、动画图层和 UTS 回调引用；
- 防止异步 Vision 回调在页面关闭后再提交结果。

### 5.2 实时扫码链路

```text
AVCaptureVideoDataOutput
  ↓ CMSampleBuffer
Vision VNDetectBarcodesRequest
  ↓ VNBarcodeObservation 列表
formats 过滤
  ↓
scanRegion 区域过滤
  ↓
单码 / 多码 / 连续扫码 / 结果模式处理
```

性能策略：

- 使用串行 `DispatchQueue` 处理 Vision 请求，避免同一时间处理多帧；
- 在上一帧识别尚未结束时丢弃新帧；
- 多码定格、确认弹窗、暂停状态、页面关闭后停止提交识别请求；
- 连续扫码需按 `content + format` 做短时间去重，建议冷却窗口 `800ms ~ 1200ms`；
- 不在 Vision 回调线程直接更新 UIKit，统一回主线程更新界面。

### 5.3 formats 映射

新增 iOS 私有映射表：

```text
QR_CODE     → VNBarcodeSymbologyQR
EAN_13      → VNBarcodeSymbologyEAN13
EAN_8       → VNBarcodeSymbologyEAN8
UPC_A       → VNBarcodeSymbologyUPCE（需以实际 Vision 结果确认映射）
UPC_E       → VNBarcodeSymbologyUPCE
CODE_128    → VNBarcodeSymbologyCode128
CODE_39     → VNBarcodeSymbologyCode39
CODE_93     → VNBarcodeSymbologyCode93
ITF         → VNBarcodeSymbologyI2of5
CODABAR     → VNBarcodeSymbologyCodabar
PDF417      → VNBarcodeSymbologyPDF417
AZTEC       → VNBarcodeSymbologyAztec
DATA_MATRIX → VNBarcodeSymbologyDataMatrix
```

> `VNBarcodeSymbology` 的实际可用范围与命名随 iOS SDK 变化。开发时必须以目标 Xcode / iOS SDK 编译结果为准，不能假定每个 Android 格式都一一对应。

### 5.4 scanRegion 坐标转换与过滤

`scanRegion` 是业务 API 中最容易出现跨平台差异的部分，iOS 必须确保“画面上显示的扫描框”与“实际允许识别的区域”一致。

处理步骤：

1. 根据 `width`、`height`、`centerX`、`centerY` 计算预览层的扫描框 `CGRect`；
2. 使用 `AVCaptureVideoPreviewLayer` 将 Vision 的归一化 `boundingBox` 转换为 UIKit 坐标；
3. 判断条码边界框中心点是否在扫描框中；
4. 仅保留区域内条码；
5. `fullScreen: true` 时不绘制扫描框且不进行区域过滤；
6. 相册识图跳过 `scanRegion` 过滤，保持 Android 行为。

验证重点：

- Vision 坐标原点与 UIKit 坐标原点不同；
- `.resizeAspectFill` 会产生裁切偏移；
- 前置镜像、横竖屏和刘海安全区可能影响坐标；
- 多码点选标记必须与真实条码中心重合。

### 5.5 scanStyle 绘制

`ScanOverlayView` 使用 `CAShapeLayer` 与 `CAGradientLayer` 绘制，配置语义与 Android 一致：

| 参数 | iOS 实现 |
| --- | --- |
| `showMask` | 显示/隐藏扫描框外遮罩层 |
| `showBeam` | 显示/隐藏扫描线图层 |
| `borderColor` | `CGColor` 边框颜色 |
| `maskColor` | 解析 `#RRGGBB`、`#AARRGGBB`、`rgba()` 后填充遮罩 |
| `beamColor` | 扫描线颜色 |
| `beamDuration` | 扫描线 `CABasicAnimation.duration`，限制 `100 ~ 60000ms` |
| `cornerStyle: 'corner'` | 绘制四角边框 |
| `cornerStyle: 'full'` | 绘制完整矩形边框 |

默认值必须沿用当前接口默认行为：

```ts
{
  showMask: true,
  showBeam: true,
  borderColor: '#19be6b',
  maskColor: 'rgba(0, 0, 0, 0.45)',
  beamColor: '#12e880',
  beamDuration: 1800,
  cornerStyle: 'corner'
}
```

颜色解析建议单独实现 `ScanStyleParser`：

- 支持 `#RRGGBB`；
- 支持 `#AARRGGBB`；
- 支持 `rgba(r,g,b,a)`；
- 解析失败时回退默认色；
- 所有回退规则与 Android `readScanStyle()` 保持一致。

### 5.6 单码、多码和点选

#### 单码

单个有效条码按 `resultMode` 处理：

- `immediate`：停止识别并立即返回；
- `confirm`：暂停识别，弹出确认框；
- `pause`：暂停识别，显示继续扫描和确认返回操作。

#### 多码

同一帧出现两个及以上有效、有内容且有边界框的条码时：

1. 停止实时识别；
2. 抓取当前预览帧；
3. 显示定格画面和半透明遮罩；
4. 把各码的边界框映射到屏幕；
5. 在中心位置绘制点选标记；
6. 显示“已识别到多个码，请选择一个”提示；
7. 用户点击最近标记后提交对应条码结果。

`MultiCodePickView` 的标记视觉与 Android 对齐：

```text
绿色中心圆点
  + 白色圆形底
  + 绿色半透明外圈
  + 周期性呼吸扩散动画
```

建议使用 `CAKeyframeAnimation` 或 `CABasicAnimation` 同步变化外圈的 `transform.scale` 与 `opacity`，周期暂定 `1500ms`。

点击策略：

- 以点位中心为基准选择最近候选；
- 设置最小可点击半径，建议约 `28pt`；
- 无命中点时继续等待选择，不直接取消；
- 用户主动关闭时按取消流程处理。

### 5.7 相册识图

优先采用 `PHPickerViewController`：

```text
fromAlbum: true 或点击相册按钮
  ↓
系统图片选择器
  ↓
获取 UIImage / CGImage
  ↓
Vision VNDetectBarcodesRequest
  ↓
单码直接返回；多码进入点选
```

规则：

- 相册识图结果的 `fromAlbum` 固定为 `true`；
- 相册图片不受 `scanRegion` 限制；
- 用户取消图片选择：单次扫码按 `9021003` 处理；
- 图片中未识别到条码时，提示“未识别到有效条码”，并返回扫码页继续操作；
- 多码相册图片使用图片本身作为定格背景并进入点选。

### 5.8 连续扫码与暂停

`continuous: true` 时：

- 命中一次条码调用一次 `success`；
- 扫码页不关闭；
- 同一内容需通过短时冷却避免高频重复提交；
- `showPauseButton: true` 时展示暂停/继续按钮；
- 用户关闭时，若已有命中，则仅调用：

```ts
complete({ closed: true, hitCount })
```

- 用户关闭时，若没有命中，则按 `fail(9021003)` 后 `complete`；
- 多码点选确认后，在连续模式下应投递一次成功结果、清除定格层、恢复相机识别，而不是关闭控制器。

### 5.9 手电筒、缩放与震动

#### 手电筒

- 使用 `AVCaptureDevice.hasTorch` 判断设备能力；
- 使用 `lockForConfiguration()` + `torchMode` 变更状态；
- `off`：默认关闭；
- `on`：启动后尝试开启；
- 无手电筒设备隐藏或禁用页面按钮；
- 页面结束时关闭手电筒。

#### 手势缩放

- 使用 `UIPinchGestureRecognizer`；
- 映射至 `videoZoomFactor`；
- 限制在 `1.0 ... activeFormat.videoMaxZoomFactor` 的安全范围；
- 变焦期间禁止智能变焦抢占。

#### 智能变焦

作为第二阶段能力：

- 根据条码边界框占画面比例计算建议倍率；
- 设定最大尝试次数、最大倍率和平滑过渡；
- 检测到多个码时先恢复 `1.0x`，避免多码点选区域被放大裁切；
- 与手势缩放、连续扫码、定格状态互斥。

#### 震动

- `vibrate: true` 时使用 `UIImpactFeedbackGenerator(style: .light)`；
- 连续扫码每次实际成功投递时触发；
- 系统可能因“减少动态效果”、静音模式或设备策略弱化触感反馈，业务层不应依赖其作为唯一成功提示。

---

## 6. UTS 桥接设计

### 6.1 app-ios/index.uts 职责

`app-ios/index.uts` 负责：

1. 获取可展示扫码页的当前 `UIViewController`；
2. 校验当前是否已有扫码会话，避免重复打开；
3. 归一化 `CodeScanOptions` 默认值；
4. 创建并展示 `CodeCaptureViewController`；
5. 接收原生事件并转换为 `CodeScanSuccess` / `CodeScanFailImpl`；
6. 保证回调顺序和只执行一次的终止语义；
7. 连续扫码时维护 `hitCount`；
8. 控制器退出后解除事件与对象引用。

### 6.2 建议的原生事件模型

控制器向桥接层输出有限事件，不直接感知 UTS 回调：

```text
onResult(content, format, fromAlbum)
onCancel()
onPermissionDenied()
onFatalError()
onClosed(hitCount, hadHits)
```

桥接层统一决定：

- 单次成功：`success` → `complete`；
- 单次失败：`fail` → `complete`；
- 连续扫码：每次 `onResult` → `success`，关闭时再 `complete`；
- 已结束会话的后续事件全部丢弃。

### 6.3 会话状态

建议 iOS 桥接层维护：

```text
idle → presenting → scanning → paused / picking → finishing → finished
```

关键约束：

- `finished` 后不允许再次派发回调；
- 权限请求、Vision 回调、相册回调都需检查当前状态；
- 控制器 dismissal 完成后再释放强引用；
- 业务层再次调用时必须创建新会话，不复用旧回调。

---

## 7. 权限与配置

### 7.1 必需权限

iOS 必须声明：

```xml
<key>NSCameraUsageDescription</key>
<string>需要使用相机扫描二维码和条形码</string>
```

若采用 `PHPickerViewController` 且最低系统版本为 iOS 14，一般不需要完整相册访问权限。

若最终需要 `UIImagePickerController` 或直接读取照片库，则补充：

```xml
<key>NSPhotoLibraryUsageDescription</key>
<string>需要访问相册以识别图片中的二维码和条形码</string>
```

### 7.2 最低系统版本建议

建议首版目标：

```text
iOS 14+
```

理由：

- 可以使用 `PHPickerViewController`；
- Vision 条码能力更成熟；
- 降低图片权限和兼容逻辑复杂度。

若产品必须支持 iOS 13，需要增加相册选择兼容分支，并重新评估 Vision 可识别格式集合。

### 7.3 打包与调试

iOS 原生 UTS 代码不能通过 Web 预览验证，必须使用：

- 包含插件的 iOS 自定义调试基座；或
- iOS 云打包 / 本地原生打包产物；
- 真机设备与 Xcode 控制台。

模拟器不应作为相机扫码主验收环境；可用于页面布局、权限分支和相册图片识别的部分验证。

---

## 8. 分阶段实施计划

### 阶段 0：UTS iOS 可编译性验证

目标：确认当前 HBuilderX 与项目配置可编译 `app-ios` 原生实现。

任务：

- 创建最小 `app-ios/index.uts`；
- 验证获取当前 iOS 控制器与展示原生页面的官方方式；
- 验证 Swift 文件参与 UTS iOS 编译的目录和配置；
- 在 iPhone 真机执行一个最小“打开原生页并返回”示例；
- 固化项目实际约定后再开始完整扫码实现。

验收：iOS 自定义基座可编译并成功打开、关闭原生测试页面。

### 阶段 1：最小可用扫码

范围：

- 相机权限；
- 后置相机预览；
- Vision 单码实时识别；
- `success`、`fail`、`complete`；
- 用户关闭；
- 常见二维码与条形码格式。

验收：iPhone 真机可扫描 QR Code 和 Code 128，并按既定顺序回调。

### 阶段 2：跨端核心功能对齐

范围：

- `formats`；
- `scanRegion`；
- `scanStyle`；
- 相册识图；
- 多码定格点选；
- 绿色呼吸波纹；
- `resultMode`；
- `vibrate`。

验收：Android 与 iOS 对同一配置的显示、区域过滤和数据结构一致。

### 阶段 3：会话与相机增强

范围：

- `continuous`；
- `showPauseButton`；
- `torch: 'off' | 'on'`；
- 手势缩放；
- 连续扫码去重与关闭结算。

验收：连续扫码有命中和无命中关闭时的回调行为与 Android 一致。

### 阶段 4：高级策略

范围：

- `smartZoom`；
- `torch: 'auto'`；
- 复杂机型上的性能优化；
- 必要时评估第三方识别引擎。

验收：在目标机型上无明显误触发、频繁跳变、发热或回调重复问题。

---

## 9. 验收矩阵

### 9.1 功能验收

| 场景 | 预期 |
| --- | --- |
| 单个二维码 | 返回 `QR_CODE`、`fromAlbum: false` |
| 单个 Code 128 | 返回 `CODE_128` |
| formats 过滤 | 仅接受指定码制 |
| 全屏识别 | 不显示扫描框，整画面可识别 |
| 自定义区域 | 框外条码不返回，框内条码正常返回 |
| 相册单码 | 返回 `fromAlbum: true` |
| 相册多码 | 显示定格图片与多个可点击标记 |
| 实时多码 | 显示定格画面、提示语和绿色呼吸点 |
| confirm 模式 | 确认后返回，取消后继续识别 |
| pause 模式 | 可继续扫描或确认结果 |
| 连续扫码 | 多次 success，关闭后返回正确 hitCount |
| 连续扫码无命中关闭 | fail `9021003` 后 complete |
| 相机权限拒绝 | fail `9021002` 后 complete |
| 无手电筒设备 | 不崩溃，按钮隐藏或禁用 |

### 9.2 机型与系统验收

至少覆盖：

- iPhone 小屏机型；
- 刘海屏机型；
- 灵动岛机型；
- 无手电筒或手电筒不可用场景；
- iOS 14、16、17 及项目实际要求的最新系统；
- 深色模式；
- 权限首次授权、拒绝、设置页重新授权；
- 前后台切换、来电或控制中心打断后恢复；
- 快速打开、关闭、再次打开扫码页。

### 9.3 性能与稳定性验收

- 连续识别 5 分钟不出现明显内存持续增长；
- 多次进入、退出扫码页后相机可再次正常打开；
- 多码定格帧不会造成明显卡顿或黑屏；
- 页面关闭后不再收到 `success`；
- 不发生重复 `complete` 或 success/fail 同时触发；
- 扫描框与实际识别区域、点选标记位置对齐。

---

## 10. 风险与应对

| 风险 | 影响 | 应对措施 |
| --- | --- | --- |
| UTS iOS 原生目录/Swift 桥接规则与预期不同 | 无法编译或调用 | 阶段 0 使用官方最小示例先验证，不直接大规模开发 |
| Vision 支持的码制与 Android 不完全一致 | formats 行为差异 | 建立格式能力矩阵，过滤不支持项并在 README 明示 |
| Vision 到预览层坐标转换错误 | scanRegion、点选位置偏移 | 单独编写坐标转换测试清单，覆盖 Aspect Fill、旋转和安全区 |
| 定格帧转换开销高 | 多码时卡顿、内存上涨 | 限制图像分辨率，及时释放 `CGImage` / `UIImage`，仅保留一帧 |
| 异步回调竞争 | 重复回调、页面关闭后回调 | 使用会话状态机和主线程串行化终止事件 |
| Torch / zoom 在机型上差异大 | 功能不稳定 | 将 `auto` 与 smartZoom 放到后续阶段，先实现基础能力 |
| iOS 权限文案或 Info.plist 缺失 | 审核或运行时崩溃 | 将权限配置纳入构建前检查和真机回归 |

---

## 11. 代码与文档更新清单

### 11.1 开发完成后需要修改

| 文件 | 修改内容 |
| --- | --- |
| `utssdk/app-ios/*` | 新增 iOS UTS 桥接和 Swift 原生实现 |
| `package.json` | `displayName`、描述、关键字、`platforms.client.uni-app.app.ios` 改为支持 |
| `readme.md` | 支持平台改为 Android / iOS；补充 iOS 权限、最低版本和格式差异说明 |
| `changelog.md` | 记录 iOS 首次支持及功能范围 |
| `pages/scan/prototype.vue` | 将 Android 专属提示改为 Android / iOS App 提示 |

### 11.2 开发完成前不得修改

以下内容必须等 iOS 自定义基座成功编译且完成真机验收后再调整：

- README 的“支持 iOS”声明；
- `package.json` 中的 `ios: '√'`；
- 业务页面中“Android 专属”的运行提示；
- changelog 中的正式 iOS 发布记录。

---

## 12. 推荐实施顺序

1. 确认项目的 HBuilderX 版本、Xcode 版本和最低 iOS 版本；
2. 用官方 UTS iOS 最小原生页面验证 `app-ios` 目录与 Swift 编译方式；
3. 实现相机权限 + 单码 QR 实时识别闭环；
4. 固化 `success` / `fail` / `complete` 的 iOS 回调行为；
5. 加入 formats、scanRegion 和 scanStyle；
6. 加入相册识图和多码定格点选；
7. 加入连续扫码、暂停、手电筒和手势缩放；
8. 最后实现 smartZoom、auto torch 等设备敏感能力；
9. 真机回归通过后更新插件元信息、README、changelog 和演示页文案。

---

## 13. 结论

推荐采用 **AVFoundation + Vision + PHPickerViewController** 的原生 iOS 实现方案，并在 `utssdk/app-ios/` 中增加独立平台入口。现有 `interface.uts`、`unierror.uts` 和 `openCodeScan` 调用方式继续作为跨端契约，Android 代码无需重构。

实施上应先完成 iOS UTS 编译与原生页面呈现验证，再逐步建立单码扫码、多码点选、相册识图和连续扫码能力。这样能将最大的构建与坐标转换风险前置，同时避免在未验证前修改对外平台支持声明。