Design.md formát (volitelný)

Kdy vytvářet design.md

• Cross-cutting změna (více modulů)
• Nová externí závislost
• Bezpečnostní implikace
• Performance-critical komponenta
• Architekturální rozhodnutí

---

Struktura dokumentu

# Technical Design: Barcode Scanning

## Architecture Overview

graph TD
    subgraph "Client (PWA)"
        A[Camera API] --> B[Barcode Detector]
        B --> C[Scan Queue]
        C --> D[Sync Service]
    end

    subgraph "Backend (EspoCRM)"
        E[API Gateway] --> F[Barcode Service]
        F --> G[Product Repository]
        G --> H[(Database)]
    end

    D -->|HTTPS| E
    D -->|Offline| I[(IndexedDB)]
    I -->|Online| D

## Component Details

### 1. PWA Application

**Tech Stack:**
- Vue 3 + TypeScript
- Quasar Framework (PWA support)
- quagga2 (barcode detection)

**Key Decisions:**

| Decision | Options Considered | Chosen | Rationale |
|----------|-------------------|--------|-----------|
| Framework | React, Vue, Svelte | Vue 3 | Team experience, Quasar ecosystem |
| Barcode lib | quagga2, zxing, dynamsoft | quagga2 | Open source, good performance |
| State mgmt | Vuex, Pinia | Pinia | Modern, TypeScript-first |

### 2. API Design

**Endpoint:** `GET /api/v1/Product/barcode/{ean}`

**Response (200):**
{
  "id": "abc123",
  "name": "Produkt ABC",
  "ean": "8590000001234",
  "code": "PRD-001",
  "unitPrice": 199.00,
  "stockLevel": 42
}

**Response (404):**
{
  "error": "PRODUCT_NOT_FOUND",
  "message": "Produkt s EAN 8590000001234 nebyl nalezen",
  "suggestion": "create_product"
}

### 3. Security Considerations

- Camera permission pouze po user interaction
- EAN validace (checksum kontrola)
- Rate limiting (100 req/min)
- Audit logging všech skenů
- Šifrování IndexedDB (sensitive data)

### 4. Performance Requirements

| Metric | Target | Measurement |
|--------|--------|-------------|
| Scan to result | < 500ms | Time from scan to product display |
| Camera init | < 1s | Time to activate camera |
| Offline sync | < 2s per item | Time to sync queued item |
| Bundle size | < 500KB | Gzipped JS bundle |

## Alternatives Considered

### Native App vs PWA

| Aspect | Native | PWA |
|--------|--------|-----|
| Development cost | High (2 platforms) | Low (1 codebase) |
| Performance | Best | Good enough |
| Distribution | App stores | Direct URL |
| Updates | Store review | Instant |
| Offline | Full support | Service worker |

**Decision:** PWA - nižší náklady, rychlejší iterace, dostatečný výkon.

## Migration Plan

1. **Phase 1:** Deploy API endpoint (backward compatible)
2. **Phase 2:** Release PWA (opt-in for users)
3. **Phase 3:** Add scan button to desktop UI
4. **Phase 4:** Training and rollout
5. **Phase 5:** Deprecate manual search (optional)

## Rollback Plan

1. Disable PWA via feature flag
2. Remove scan button from UI
3. API endpoint remains (no breaking change)
4. Restore previous workflow

---

➡️ Pokračujte na Delta specifikace.