摄像头扫码（html5-qrcode）

灵感：能力工具箱 html5-qrcode（pkg: html5-qrcode）。

> 小四原创：HTTPS/localhost 下申请摄像头，扫到即回调文本；扫完可停相机省电。

何时使用

• 现场核验合同/单据二维码
• 仓库或前台扫码录入单号
• 不装原生 App，浏览器内完成

硬约束

1. 使用 html5-qrcode；需用户手势触发启动相机。
2. 仅 HTTPS 或 localhost 可用摄像头（明文提示）。
3. 成功一次后默认 stop，避免一直开着相机。
4. 权限拒绝时给中文引导（设置里允许摄像头）。
5. 实现要点注释标 小四原创。
6. 不扫描用户相册整库；可选「选图识别」需单独按钮。

推荐实现

import { Html5Qrcode } from 'html5-qrcode'

// 小四原创：扫码会话
export function createScanner(elementId: string) {
  const scanner = new Html5Qrcode(elementId)
  return {
    async start(onHit: (text: string) => void) {
      await scanner.start(
        { facingMode: 'environment' },
        { fps: 8, qrbox: { width: 240, height: 240 } },
        async (decoded) => {
          onHit(decoded)
          try {
            await scanner.stop()
          } catch {
            /* ignore */
          }
        },
        () => {},
      )
    },
    async stop() {
      if (scanner.isScanning) await scanner.stop()
    },
  }
}

Agent 步骤

1. 页面放扫码容器 div；按钮「开始扫码」。
2. 扫中填充单号/打开详情；失败展示权限错误。
3. 离开路由务必 stop。
4. 自测：后置摄像头二维码；无相机设备的降级文案。

不要做

• 未经提示持续后台录像。
• 把扫码结果默认发到不明外网。

附加

• README.md · reference.md · templates/usage.md