# mas-code-scan 功能与设置规划

> 本文用于整理 `mas-code-scan` 当前已有能力、可继续增加的功能，以及建议的开发优先级。
>
> 状态说明：
>
> - **已实现**：当前插件代码已经支持；
> - **建议增加**：功能方向已经明确，但尚未实现；
> - **后续评估**：需要结合实际业务、设备兼容性和实现成本再决定。

---

## 1. 插件当前能力

| 功能 | 状态 | 说明 |
|---|---|---|
| Android 相机扫码 | 已实现 | 基于 CameraX + Google ML Kit |
| 全格式识别 | 已实现 | 未传 `formats` 时按全格式识别 |
| 指定码制识别 | 已实现 | 通过 `formats` 限定二维码、条形码等格式 |
| 单次扫码 | 已实现 | 成功后自动返回结果 |
| 连续扫码 | 已实现 | `continuous: true`，识别后继续停留在扫码页 |
| 相册识图 | 已实现 | 支持打开后直接进入相册，也支持扫码页内打开相册 |
| 多码识别 | 已实现 | 同屏多个码时进入点选逻辑 |
| 智能变焦 | 已实现 | `smartZoom: true` 时对较小条码自动放大 |
| 双指手势缩放 | 已实现 | 扫码页内手动调整相机倍率 |
| 手电筒 | 已实现 | 扫码页右下角手动开关 |
| 成功震动 | 已实现 | 通过 `vibrate` 控制 |
| 自定义有效区域 | 已实现 | 通过 `scanRegion` 控制识别区域 |
| 二维码正方形区域 | 已实现 | `width` 与 `height` 使用相同值，锁定 1:1 |
| 横向条码区域 | 已实现 | 默认宽度较大、高度可调 |
| 条码框上下位置 | 已实现 | 支持上、中、下、自定义位置 |
| 条码框高度选择 | 已实现 | 原型页支持 24%、32%、40% 三档 |
| 全屏识别模式 | 已实现 | `scanRegion: { fullScreen: true }`，整画面识别且不显示扫描框 |
| 扫描框直角样式 | 已实现 | 当前不绘制圆角 |

---

## 2. 当前 API 概览

### 2.1 基础调用

```ts
import { openCodeScan } from '@/uni_modules/mas-code-scan'

openCodeScan({
  smartZoom: true,
  vibrate: true,
  success: (res) => {
    console.log(res.content, res.format)
  },
  fail: (err) => {
    console.log(err.errCode, err.errMsg)
  },
  complete: () => {
    console.log('扫码结束')
  }
})
```

### 2.2 全屏识别

```ts
openCodeScan({
  scanRegion: {
    fullScreen: true
  },
  success: (res) => {
    console.log(res.content)
  }
})
```

全屏模式的行为：

- 整个相机预览区域均可识别；
- 不显示扫描框；
- 不显示扫描框遮罩；
- 不过滤扫描框外的条码；
- 不影响 `formats`、`smartZoom`、`vibrate`、`continuous` 等其他设置。

### 2.3 二维码正方形区域

```ts
openCodeScan({
  formats: ['QR_CODE'],
  scanRegion: {
    width: 0.74,
    height: 0.74,
    centerX: 0.5,
    centerY: 0.5
  }
})
```

二维码区域要求：

- `width` 和 `height` 使用相同值；
- 严格保持 1:1 正方形比例；
- 扫描框使用直角，不使用圆角。

### 2.4 横向条码区域

```ts
openCodeScan({
  formats: ['CODE_128', 'EAN_13'],
  scanRegion: {
    width: 0.96,
    height: 0.24,
    centerX: 0.5,
    centerY: 0.5
  }
})
```

其中：

- `width` 控制横向宽度；
- `height` 控制扫描框内高度；
- `centerY` 控制扫描框上下位置；
- 目前原型页提供 24%、32%、40% 三档高度；
- 框内条码才会进入有效识别结果。

---

## 3. 建议优先增加的功能

以下功能对仓库、设备管理、物料盘点等场景最有价值。

### 3.1 手电筒 API 控制

当前已经有扫码页手电筒按钮，建议继续增加调用参数，用于控制打开扫码页时的默认状态。

建议接口：

```ts
torch?: 'auto' | 'on' | 'off'
```

建议行为：

| 值 | 行为 |
|---|---|
| `auto` | 使用系统或插件默认状态，不强制打开 |
| `on` | 打开扫码页后自动开启手电筒 |
| `off` | 打开扫码页后保持关闭 |

适用场景：弱光仓库、货架底部、设备背面标签、夜间扫码。

---

### 3.2 连续扫码去重策略

连续扫码时建议开放更明确的去重配置。

建议接口：

```ts
openCodeScan({
  continuous: true,
  duplicatePolicy: 'cooldown',
  duplicateCooldown: 1500
})
```

建议支持：

| 策略 | 行为 |
|---|---|
| `allow` | 同一个码可以重复回调 |
| `ignore` | 同一次扫码会话中，相同内容只回调一次 |
| `cooldown` | 相同内容在指定时间内不重复回调 |

建议参数：

- `duplicatePolicy`：去重策略；
- `duplicateCooldown`：去重时间，单位毫秒；
- `maxResults`：连续扫码最多保存的结果数量。

这是批量盘点场景中最值得增加的功能之一。

---

### 3.3 多码识别策略

当前同屏多个条码时可以进入点选。建议增加自动选择策略，减少用户额外操作。

建议接口：

```ts
openCodeScan({
  multiCodeMode: 'nearestCenter'
})
```

建议取值：

| 值 | 行为 |
|---|---|
| `select` | 保持当前交互，暂停画面并由用户点选 |
| `first` | 取 ML Kit 返回的第一个有效条码 |
| `nearestCenter` | 选择距离扫描框中心最近的条码 |
| `largest` | 选择画面中面积最大的条码 |
| `all` | 一次返回全部有效条码 |

建议默认使用 `nearestCenter`，更符合扫描框交互习惯。

---

### 3.4 扫码结果确认模式

目前单次扫码识别成功后会自动返回。建议增加确认模式，避免误扫。

建议接口：

```ts
openCodeScan({
  resultMode: 'confirm'
})
```

建议取值：

| 值 | 行为 |
|---|---|
| `immediate` | 识别成功后立即返回，保持当前行为 |
| `confirm` | 显示结果，用户确认后返回 |
| `pause` | 识别成功后暂停相机，用户可确认或继续扫描 |

适用场景：设备绑定、物料入库、资产登记等不能容忍误扫的业务。

---

### 3.5 前后摄像头切换

建议支持默认摄像头和扫码页内切换。

建议接口：

```ts
openCodeScan({
  camera: 'back'
})
```

建议取值：

- `back`：后置摄像头，默认；
- `front`：前置摄像头；
- `auto`：由插件选择可用摄像头。

扫码页可以增加一个左下角或右上角切换按钮。

---

## 4. 识别准确率和性能设置

### 4.1 稳定识别帧数

要求同一个条码连续出现在若干帧后才判定成功。

```ts
openCodeScan({
  stableFrames: 2
})
```

优点：

- 减少模糊画面误触发；
- 减少条码刚进入画面时的误扫；
- 对连续扫码更稳定。

注意：数值过高会增加识别延迟，建议默认 1 或 2。

---

### 4.2 智能变焦参数

当前只有开关，后续可以细化为：

```ts
openCodeScan({
  smartZoom: true,
  smartZoomMaxRatio: 2.5,
  smartZoomTriggerSize: 0.12
})
```

建议参数：

- `smartZoomMaxRatio`：最大自动变焦倍率；
- `smartZoomTriggerSize`：条码小于指定比例时触发；
- `smartZoomResetAfterSuccess`：识别成功后是否恢复倍率。

---

### 4.3 最小条码尺寸过滤

用于忽略过远或过小的无关条码。

```ts
openCodeScan({
  minBarcodeWidth: 0.08,
  minBarcodeHeight: 0.03
})
```

注意：该功能和 `scanRegion` 不同：

- `scanRegion` 解决“条码是否在有效区域内”；
- 最小尺寸过滤解决“条码是否足够大、是否值得识别”。

---

## 5. 扫描框和交互设置

### 5.1 扫描框视觉样式

目前扫描框已经支持尺寸、位置和直角样式。增加独立的视觉配置：

```ts
openCodeScan({
  scanRegion: {
    width: 0.96,
    height: 0.24,
    centerX: 0.5,
    centerY: 0.5
  },
  scanStyle: {
    showMask: true,
    showBeam: true,
    borderColor: '#19be6b',
    maskColor: 'rgba(0, 0, 0, 0.45)',
    beamColor: '#12e880'
  }
})
```

建议支持：

- `showMask`：是否显示框外遮罩；
- `showBeam`：是否显示扫描线；
- `borderColor`：边框颜色；
- `maskColor`：遮罩颜色和透明度；
- `beamColor`：扫描线颜色；
- `beamDuration`：扫描线移动周期；
- `cornerStyle`：完整边框或四角边框。

建议将这些属性放在 `scanStyle` 中，不要和识别区域参数混在一起。

---

### 5.2 扫码页提示文案

不同业务可以使用不同的引导语。

建议接口：

```ts
openCodeScan({
  title: '设备绑定',
  hint: '请将设备条码放入扫描框内'
})
```

建议支持：

- `title`：页面标题；
- `hint`：扫描框下方提示；
- `successHint`：识别成功提示；
- `emptyHint`：暂未识别到条码时的提示。

---

### 5.3 暂停与继续扫描

连续扫码可以增加暂停和继续按钮。

建议行为：

- 点击暂停后停止分析帧；
- 相机预览可以继续显示，也可以冻结画面；
- 点击继续后恢复分析；
- 连续扫码结果列表不清空。
- 实时帧中只有一条已解码条码时必须直接上报；ML Kit 额外返回的无内容候选框不能触发多码点选或跳过该单码。

建议接口：

```ts
openCodeScan({
  continuous: true,
  showPauseButton: true
})
```

---

## 6. 扫码结果增强

### 6.1 返回条码位置

当前结果主要返回内容和码制。后续可以返回条码在图像中的位置。

建议结果：

```ts
{
  content: 'EQ-12345678',
  format: 'CODE_128',
  fromAlbum: false,
  bounds: {
    left: 120,
    top: 360,
    width: 480,
    height: 96
  }
}
```

用途：

- 调试扫描框映射；
- 保存条码位置；
- 多码场景二次判断；
- 识别结果可视化。

---

### 6.2 结果校验

建议在插件外层或调用参数中增加结果校验能力。

```ts
openCodeScan({
  formats: ['CODE_128'],
  validator: {
    pattern: '^EQ-[A-Z0-9]{8}$',
    message: '请扫描有效设备编码'
  }
})
```

建议支持：

- 正则表达式；
- 固定前缀；
- 固定长度；
- 自定义校验回调；
- 校验失败后继续扫描，不关闭扫码页。

建议优先在业务层实现，避免把业务规则过度耦合到通用插件。

---

### 6.3 扫码状态回调

用于业务页面展示状态或进行调试。

建议接口：

```ts
openCodeScan({
  onStatus: (status) => {
    console.log(status)
  }
})
```

建议状态：

- `opening`：正在打开扫码页；
- `cameraReady`：相机已准备完成；
- `scanning`：正在识别；
- `paused`：已暂停；
- `result`：识别到结果；
- `closed`：扫码页关闭。

---

## 7. 相册识图增强

### 7.1 多图批量识别

```ts
openCodeScan({
  fromAlbum: true,
  albumMultiple: true,
  maxAlbumImages: 9
})
```

适用场景：

- 批量导入物料标签照片；
- 历史图片盘点；
- 一次处理多个设备照片。

### 7.2 图片裁剪后识别

相册选择图片后增加裁剪步骤：

- 用户手动裁剪识别区域；
- 使用当前扫描框比例作为裁剪建议；
- 裁剪后再交给 ML Kit 识别。

复杂照片中存在多个标签时，该功能可以明显提高识别准确率。

---

## 8. 调试和错误处理

### 8.1 调试模式

建议增加：

```ts
openCodeScan({
  debug: true
})
```

调试信息可包括：

- 预览 View 尺寸；
- 实际扫描框像素坐标；
- 输入图像尺寸；
- 图像旋转角度；
- cropRect；
- 区域过滤前后的条码数量；
- 智能变焦触发记录；
- 每帧识别耗时。

正式环境默认关闭，避免性能损耗和敏感信息泄露。

### 8.2 更细的错误码

**状态：已实现。** 现有 `9021001 ~ 9021004` 的含义保持不变，新增错误码从 `9021005` 开始：

| 错误码 | 场景 | 处理方式 |
| --- | --- | --- |
| `9021005` | 相机被其他应用占用或当前不可用 | 关闭其他相机应用后重试 |
| `9021006` | 设备没有闪光灯 | 仅在扫码页提示，不中断扫码会话 |
| `9021007` | 相机初始化失败 | 检查设备相机状态，必要时重启应用 |
| `9021008` | 相册图片无法读取 | 重新选择本地图片 |
| `9021009` | 图片中没有有效条码 | 仅打开即相册且无可用相机回退时结束会话 |
| `9021010` | 指定码制不支持 | `formats` 非空且全部不受支持时返回 |
| `9021011` | 扫描超时 | 单次扫码传入 `scanTimeout: 1000 ~ 600000` 后启用；连续扫码不启用 |

错误码增加遵循兼容原则：不修改已有错误码的含义；致命错误走 `fail` 后 `complete`；无闪光灯不会影响相机扫码，因此只提示，不触发 `fail`。

---

## 9. 横屏和平板支持

当前 Android 扫码页固定竖屏。后续可以评估：

```ts
openCodeScan({
  orientation: 'portrait'
})
```

建议取值：

- `portrait`：竖屏，当前默认行为；
- `landscape`：横屏；
- `auto`：跟随设备方向。

适用设备：

- 平板；
- 工业手持终端；
- 横向固定安装设备；
- 长条码集中扫描场景。

---

## 10. 推荐开发优先级

### 第一阶段：直接提升日常可用性

1. 手电筒默认状态 API；
2. 连续扫码去重策略；
3. 多码自动选择策略；
4. 扫码结果确认模式；
5. 前后摄像头切换。

### 第二阶段：提升业务适配能力

1. 扫码页提示文案；
2. 扫描状态回调；
3. 稳定识别帧数；
4. 扫描框视觉样式配置；
5. 结果位置 `bounds` 返回。

### 第三阶段：扩展复杂业务场景

1. 相册多图批量识别；
2. 图片裁剪后识别；
3. 横屏和平板支持；
4. 扫码结果校验器；
5. 调试模式和性能指标。

---

## 11. 开发注意事项

1. 新增功能应优先保持 `openCodeScan(options)` 的兼容性，不要破坏现有调用。
2. 识别区域参数和视觉样式参数应分开设计。
3. 全屏模式必须保持“整画面识别、不绘制扫描框、不进行区域过滤”的语义。
4. 二维码区域必须继续保持 1:1，不能因为屏幕比例或边界收敛发生变形。
5. 连续扫码新增去重策略时，不能削弱当前已有的基本去重行为。
6. 相册识图和实时相机识别应保持清晰区分，相册识图默认不受实时扫描框限制。
7. 新增 Android 原生能力后，应同步更新 UTS 类型定义、插件 README 和演示页。
8. 每次修改原生相机、图像坐标映射或区域过滤逻辑后，都需要使用 Android 真机或自定义调试基座验证。
9. 新增错误码时只能追加，不能改变已有错误码的含义。
10. 涉及权限、相机、闪光灯和设备方向的功能，需要至少验证主流 Android 设备和不同屏幕尺寸。