ebaysnipeextension/.kiro/specs/amazon-product-bar-extension/design.md

# Design Document: Amazon Product Bar Extension

## Overview

Diese Browser-Extension injiziert eine visuelle Leiste unter jedem Produktbild auf Amazon-Suchergebnisseiten und erweitert das bestehende StaggeredMenu um Produktspeicher-Funktionalität. Die Extension nutzt Content Scripts für DOM-Manipulation, Local Storage für Datenpersistierung und zeigt gespeicherte Produkte mit visuellen Indikatoren an.

## Architecture

```mermaid
graph TD
    A[Browser Extension] --> B[Manifest V3]
    B --> C[Content Script]
    B --> D[Existing StaggeredMenu]
    C --> E[DOM Observer]
    C --> F[Product Card Detector]
    C --> G[Bar Injector]
    D --> H[Items Panel Content]
    H --> I[Product Storage]
    H --> J[Product List UI]
    I --> K[Local Storage]
    E --> F
    F --> G
    G --> L[List Icon Manager]
    I --> L
```

Die Extension besteht aus:
1. **Manifest** - Konfiguration und Berechtigungen
2. **Content Script** - Hauptlogik für DOM-Manipulation
3. **Existing StaggeredMenu** - Bereits vorhandenes Menüsystem
4. **Items Panel Content** - Neue Inhalte für den Items-Bereich
5. **Product Storage** - Datenpersistierung in Local Storage
6. **List Icon Manager** - Visuelle Markierung gespeicherter Produkte
7. **Styles** - CSS für Product Bar und Items Panel Content

## Components and Interfaces

### 1. Manifest (manifest.json)

```json
{
  "manifest_version": 3,
  "name": "Amazon Product Bar",
  "version": "2.0.0",
  "description": "Adds a bar below product images with save functionality",
  "permissions": ["storage"],
  "content_scripts": [{
    "matches": ["*://*.amazon.de/*", "*://*.amazon.com/*"],
    "js": ["content.js"],
    "css": ["styles.css"]
  }]
}
```

### 2. URL Pattern Matcher

```typescript
interface UrlMatcher {
  isSearchResultsPage(url: string): boolean;
  extractProductId(url: string): string | null;
}
```

Erkennt Amazon-Suchergebnisseiten und extrahiert Produkt-ASINs aus URLs.

### 3. Product Card Detector

```typescript
interface ProductCardDetector {
  findAllProductCards(container: Element): Element[];
  findImageContainer(productCard: Element): Element | null;
  extractProductUrl(productCard: Element): string | null;
}
```

Findet Produktkarten und extrahiert Produktinformationen.

### 4. Product Storage Manager

```typescript
interface ProductStorageManager {
  saveProduct(product: SavedProduct): Promise<void>;
  getProducts(): Promise<SavedProduct[]>;
  deleteProduct(productId: string): Promise<void>;
  isProductSaved(productId: string): Promise<boolean>;
}

interface SavedProduct {
  id: string;           // ASIN oder URL-Hash
  url: string;          // Amazon-Produkt-URL
  title: string;        // Produkttitel
  imageUrl: string;     // Produktbild-URL
  savedAt: Date;        // Speicherzeitpunkt
}
```

### 5. Items Panel Content Manager

```typescript
interface ItemsPanelManager {
  createItemsContent(): HTMLElement;
  showItemsPanel(): void;
  hideItemsPanel(): void;
  renderProductList(products: SavedProduct[]): void;
}
```

Erstellt und verwaltet den Inhalt für das Items-Panel im bestehenden StaggeredMenu.

### 6. Bar Injector (erweitert)

```typescript
interface BarInjector {
  injectBar(imageContainer: Element, productId?: string): void;
  hasBar(productCard: Element): boolean;
  addListIcon(productBar: Element): void;
  removeListIcon(productBar: Element): void;
}
```

Erstellt Product Bars und verwaltet Listen-Icons für gespeicherte Produkte.

### 7. List Icon Manager

```typescript
interface ListIconManager {
  updateAllIcons(): Promise<void>;
  addIconToProduct(productId: string): void;
  removeIconFromProduct(productId: string): void;
}
```

Verwaltet die visuellen Indikatoren für gespeicherte Produkte.

## Data Models

### SavedProduct

```typescript
interface SavedProduct {
  id: string;           // ASIN oder URL-Hash für eindeutige Identifikation
  url: string;          // Vollständige Amazon-Produkt-URL
  title: string;        // Produkttitel aus der Seite extrahiert
  imageUrl: string;     // URL des Produktbildes
  savedAt: Date;        // Zeitstempel der Speicherung
}
```

### ProductBar Element

```html
<div class="amazon-ext-product-bar" data-ext-processed="true" data-product-id="B08N5WRWNW">
  <div class="list-icon" style="display: none;">
    <svg><!-- Liste Icon SVG --></svg>
  </div>
</div>
```

### Items Panel Structure

```html
<div class="amazon-ext-items-content">
  <div class="items-header">
    <h2>Saved Products</h2>
    <div class="add-product-form">
      <input type="url" placeholder="Amazon-Produkt-URL eingeben..." />
      <button class="save-btn">Speichern</button>
    </div>
  </div>
  <div class="product-list">
    <!-- Dynamisch generierte Produktliste -->
  </div>
</div>
```

### CSS Styling (erweitert)

```css
.amazon-ext-product-bar {
  width: 100%;
  min-height: 20px;
  background-color: #f0f2f5;
  border-radius: 4px;
  margin-top: 4px;
  position: relative;
}

.amazon-ext-product-bar .list-icon {
  position: absolute;
  right: 5px;
  top: 50%;
  transform: translateY(-50%);
  width: 16px;
  height: 16px;
}

.amazon-ext-items-content {
  color: white;
  padding: 2rem;
  height: 100%;
  overflow-y: auto;
}

.items-header h2 {
  margin: 0 0 1.5rem 0;
  font-size: 2rem;
  font-weight: 700;
}

.add-product-form {
  display: flex;
  gap: 1rem;
  margin-bottom: 2rem;
}

.add-product-form input {
  flex: 1;
  padding: 0.75rem;
  border: 1px solid #333;
  background: #222;
  color: white;
  border-radius: 4px;
}

.add-product-form button {
  padding: 0.75rem 1.5rem;
  background: #ff9900;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}
```

## Correctness Properties

*A property is a characteristic or behavior that should hold true across all valid executions of a system—essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*

### Property 1: Search Page Detection Consistency

*For any* URL string, the `isSearchResultsPage` function should return `true` if and only if the URL contains Amazon search patterns (`/s?` or `/s/`).

**Validates: Requirements 1.3**

### Property 2: Product Card Discovery Completeness

*For any* DOM container with N elements matching the product card selector, `findAllProductCards` should return exactly N elements.

**Validates: Requirements 2.1, 2.2, 2.3**

### Property 3: Bar Injection Idempotence

*For any* product card, calling `injectBar` multiple times should result in exactly one Product Bar being present.

**Validates: Requirements 3.1, 3.5**

### Property 4: URL Validation Consistency

*For any* URL string, the validation function should return `true` if and only if the URL is a valid Amazon product link (contains amazon domain and product identifier).

**Validates: Requirements 5.4**

### Property 5: Valid Product Saving

*For any* valid Amazon product URL entered in the Items panel, saving it should result in the product being stored in local storage and retrievable afterwards.

**Validates: Requirements 5.3**

### Property 6: Invalid URL Rejection

*For any* invalid URL entered in the Items panel, attempting to save it should trigger an error message and prevent any storage operation.

**Validates: Requirements 5.4**

### Property 7: UI State Consistency After Save

*For any* successful product save operation in the Items panel, the input field should be cleared and a confirmation message should be displayed.

**Validates: Requirements 5.6**

### Property 8: Product List Rendering Completeness

*For any* set of saved products, the Items panel should contain exactly one list item for each saved product with all required information (title, image, URL).

**Validates: Requirements 6.1, 6.2**

### Property 9: Items Panel Loading Consistency

*For any* Items panel opening event, all previously saved products should be loaded and displayed in the product list.

**Validates: Requirements 6.3**

### Property 10: Delete Button Presence

*For any* rendered product item in the Items panel, it should contain exactly one delete button that is properly functional.

**Validates: Requirements 6.4**

### Property 11: Product Deletion Completeness

*For any* saved product, deleting it from the Items panel should remove it from both local storage and the UI display.

**Validates: Requirements 6.5**

### Property 12: Saved Product Icon Display

*For any* product on the search results page that matches a saved product, the Product_Bar should display a list icon.

**Validates: Requirements 7.1**

### Property 13: Product Matching Accuracy

*For any* product comparison, the matching logic should correctly identify products as saved or not saved based on URL or ASIN comparison.

**Validates: Requirements 7.2**

### Property 14: Real-time Icon Addition

*For any* product that gets saved via the Items panel while visible on the search page, all matching Product_Bars should immediately display the list icon.

**Validates: Requirements 7.4**

### Property 15: Real-time Icon Removal

*For any* product that gets deleted from the Items panel while visible on the search page, all matching Product_Bars should immediately remove the list icon.

**Validates: Requirements 7.5**

## Error Handling

| Scenario | Handling |
|----------|----------|
| No product cards found | Silent - no action needed |
| Image container not found | Skip card, log warning |
| DOM mutation during injection | MutationObserver handles re-processing |
| Extension disabled | Content script doesn't load |
| Invalid Amazon URL entered | Display error message, prevent saving |
| Local storage quota exceeded | Display warning, suggest cleanup |
| Network error during product info fetch | Show generic product info, retry later |
| Corrupted saved product data | Remove invalid entries, log error |
| Menu already open | Prevent duplicate menu creation |
| Product already saved | Show "already saved" message |

## Testing Strategy

### Unit Tests
- URL pattern matching für verschiedene Amazon-URLs
- DOM-Selektor-Tests mit Mock-HTML
- Bar-Injection mit simulierten Produktkarten
- Product Storage CRUD-Operationen
- Menu UI-Komponenten und Event-Handling
- URL-Validierung mit verschiedenen Input-Formaten
- Product-Matching-Logik mit verschiedenen Identifikatoren

### Property-Based Tests
- **Property 1**: Generiere zufällige URLs, prüfe konsistente Erkennung
- **Property 2**: Generiere DOM-Strukturen mit variierender Anzahl Produktkarten
- **Property 3**: Mehrfache Injection-Aufrufe auf gleiche Elemente
- **Property 4-15**: Teste Speicher-, UI- und Icon-Management-Properties mit generierten Daten

### Integration Tests
- End-to-End-Workflow: URL eingeben → speichern → Icon anzeigen → löschen
- Menu-Interaktionen mit verschiedenen Produktanzahlen
- Real-time Updates zwischen Menu und Product Bars

### Testing Framework
- Jest für Unit Tests
- fast-check für Property-Based Tests
- JSDOM für DOM-Simulation
- Chrome Extension Testing Utils für Browser-spezifische Features

### Test Configuration
- Minimum 100 Iterationen pro Property Test
- Tag-Format: **Feature: amazon-product-bar-extension, Property {number}: {property_text}**
- Jede Correctness Property wird durch einen einzelnen Property-Based Test implementiert