mrlee/MrleeAdmin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

完善生产查询与登录权限配置

Browse Source
This commit is contained in:
mrlee
2026-09-03 19:56:19 +08:00
parent 793f140a45
commit 02c8fb7021
438 changed files with 1595 additions and 573 deletions
Download Patch File Download Diff File Expand all files Collapse all files
frontend/app/docs/mas-code-scan-功能与设置规划.md
+617
View File
@@ -0,0 +1,617 @@
# 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 设备和不同屏幕尺寸。