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

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)

{
  "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

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

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

3. Product Card Detector

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

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

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)

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

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

Verwaltet die visuellen Indikatoren für gespeicherte Produkte.

Data Models

SavedProduct

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

<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

<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)

.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