📷 Barcode Detection API 완벽 가이드: 무거운 라이브러리 없는 초경량·고성능 네이티브 QR·바코드 스캐너

[기존 방식의 병목 구조]
카메라 영상 (MediaStream)
  └─> <canvas>에 매 프레임 그리기 (drawImage)
        └─> getImageData()로 거대한 ImageData 픽셀 배열 추출 (메인 스레드 블로킹)
              └─> jsQR / ZXing JS 라이브러리로 픽셀 전수 분석 (CPU 100% 점유, 발열, 배터리 방전)

// feature-detection.js
export async function checkBarcodeSupport() {
  if (!('BarcodeDetector' in window)) {
    console.warn('현재 브라우저는 Barcode Detection API를 지원하지 않습니다.');
    return { supported: false, formats: [] };
  }

  try {
    const supportedFormats = await BarcodeDetector.getSupportedFormats();
    console.log('지원하는 바코드 포맷:', supportedFormats);
    return { supported: true, formats: supportedFormats };
  } catch (error) {
    console.error('지원 포맷 조회 실패:', error);
    return { supported: false, formats: [] };
  }
}

// QR 코드와 EAN-13 상품 바코드만 전문적으로 스캔하는 인스턴스
const detector = new BarcodeDetector({
  formats: ['qr_code', 'ean_13']
});

// static-scan.js
async function scanBarcodeFromImage(imageElement) {
  const detector = new BarcodeDetector({ formats: ['qr_code'] });

  try {
    // detect()는 비동기 Promise를 반환하며 감지된 결과 배열을 넘겨줍니다.
    const barcodes = await detector.detect(imageElement);

    if (barcodes.length === 0) {
      console.log('감지된 바코드가 없습니다.');
      return null;
    }

    for (const barcode of barcodes) {
      console.log(`포맷: ${barcode.format}`);
      console.log(`원시 데이터: ${barcode.rawValue}`);
      console.log('바운딩 박스:', barcode.boundingBox);
    }

    return barcodes;
  } catch (err) {
    console.error('바코드 디코딩 실패:', err);
    throw err;
  }
}

// camera-stream.js
async function startCamera(videoElement) {
  const constraints = {
    audio: false,
    video: {
      facingMode: { ideal: 'environment' }, // 후면 카메라 우선
      width: { ideal: 1280 },
      height: { ideal: 720 }
    }
  };

  const stream = await navigator.mediaDevices.getUserMedia(constraints);
  videoElement.srcObject = stream;
  await videoElement.play();
  return stream;
}

// continuous-scanner.js
export class NativeBarcodeScanner {
  constructor(videoElement, onDetected, options = {}) {
    this.video = videoElement;
    this.onDetected = onDetected;
    this.formats = options.formats || ['qr_code'];
    this.detector = new BarcodeDetector({ formats: this.formats });
    this.isScanning = false;
    this.isBusy = false; // detect() 중복 호출 방지용 락
  }

  start() {
    if (this.isScanning) return;
    this.isScanning = true;

    const processFrame = async (now, metadata) => {
      if (!this.isScanning) return;

      // 이전 디코딩 작업이 아직 진행 중이면 현재 프레임은 건너뜁니다.
      if (!this.isBusy) {
        this.isBusy = true;
        try {
          const barcodes = await this.detector.detect(this.video);
          if (barcodes.length > 0) {
            this.onDetected(barcodes, metadata);
          }
        } catch (err) {
          console.warn('프레임 감지 오류:', err);
        } finally {
          this.isBusy = false;
        }
      }

      // rVFC가 지원되면 rVFC를, 미지원 브라우저는 rAF를 폴백으로 사용
      if ('requestVideoFrameCallback' in this.video) {
        this.video.requestVideoFrameCallback(processFrame);
      } else {
        requestAnimationFrame(() => processFrame(performance.now(), {}));
      }
    };

    if ('requestVideoFrameCallback' in this.video) {
      this.video.requestVideoFrameCallback(processFrame);
    } else {
      requestAnimationFrame(() => processFrame(performance.now(), {}));
    }
  }

  stop() {
    this.isScanning = false;
  }
}

interface DetectedBarcode {
  boundingBox: DOMRectReadOnly; // 단순 직사각형 경계 (x, y, width, height)
  cornerPoints: Array<{ x: number; y: number }>; // 기울어진 4개 꼭짓점 좌표
  format: string; // 'qr_code', 'ean_13' 등
  rawValue: string; // 바코드 본문 문자열
}

// overlay-drawer.js
export function drawBarcodeOverlay(canvas, barcodes, videoWidth, videoHeight) {
  const ctx = canvas.getContext('2d');
  ctx.clearRect(0, 0, canvas.width, canvas.height);

  const scaleX = canvas.width / videoWidth;
  const scaleY = canvas.height / videoHeight;

  for (const code of barcodes) {
    const points = code.cornerPoints;
    if (!points || points.length < 4) continue;

    // 4개 코너를 연결하는 다각형 그리기
    ctx.beginPath();
    ctx.moveTo(points[0].x * scaleX, points[0].y * scaleY);
    for (let i = 1; i < points.length; i++) {
      ctx.lineTo(points[i].x * scaleX, points[i].y * scaleY);
    }
    ctx.closePath();

    ctx.lineWidth = 3;
    ctx.strokeStyle = '#279866'; // logic-phantom 테마 그린
    ctx.fillStyle = 'rgba(39, 152, 102, 0.2)';
    ctx.stroke();
    ctx.fill();

    // 바코드 내용 라벨 표시
    ctx.fillStyle = '#1E3A5F';
    ctx.font = 'bold 14px sans-serif';
    ctx.fillText(code.rawValue, points[0].x * scaleX, (points[0].y * scaleY) - 8);
  }
}

// barcode-service.js
export class UniversalBarcodeScanner {
  constructor(options = {}) {
    this.options = options;
    this.engine = null;
  }

  async init() {
    if ('BarcodeDetector' in window) {
      const supported = await BarcodeDetector.getSupportedFormats().catch(() => []);
      if (supported.includes('qr_code')) {
        console.log('⚡ 고성능 네이티브 BarcodeDetector 엔진 사용');
        this.engine = {
          type: 'native',
          detector: new BarcodeDetector({ formats: this.options.formats || ['qr_code'] })
        };
        return;
      }
    }

    // 네이티브 미지원 시에만 수백 KB의 폴백 모듈을 비동기 청크로 분할 로드
    console.log('🔄 폴백 WASM 스캐너 엔진 지연 로드 중...');
    const { ZXingWasmScanner } = await import('./fallback/zxing-wasm-scanner.js');
    this.engine = {
      type: 'wasm',
      detector: new ZXingWasmScanner(this.options)
    };
  }

  async scan(imageSource) {
    if (!this.engine) {
      await this.init();
    }

    if (this.engine.type === 'native') {
      return await this.engine.detector.detect(imageSource);
    } else {
      return await this.engine.detector.scan(imageSource);
    }
  }
}

// torch-control.js
export async function toggleTorch(mediaStream, enable) {
  const track = mediaStream.getVideoTracks()[0];
  if (!track) return false;

  const capabilities = track.getCapabilities();
  
  // 플래시 기능 지원 여부 확인
  if (!capabilities.torch) {
    console.warn('이 기기는 웹에서 플래시 제어를 지원하지 않습니다.');
    return false;
  }

  try {
    await track.applyConstraints({
      advanced: [{ torch: enable }]
    });
    return true;
  } catch (err) {
    console.error('플래시 설정 실패:', err);
    return false;
  }
}

// 줌(Zoom) 배율 조정
export async function setCameraZoom(mediaStream, zoomLevel) {
  const track = mediaStream.getVideoTracks()[0];
  const capabilities = track.getCapabilities();

  if (!capabilities.zoom) return;

  const min = capabilities.zoom.min;
  const max = capabilities.zoom.max;
  const clampedZoom = Math.min(Math.max(zoomLevel, min), max);

  await track.applyConstraints({
    advanced: [{ zoom: clampedZoom }]
  });
}

if (videoElement.readyState < 2) {
  await new Promise(resolve => {
    videoElement.addEventListener('loadeddata', resolve, { once: true });
  });
}