ebaysnipeextension/.kiro/specs/enhanced-item-management/design.md

Design Document: Enhanced Item Management

Overview

Diese Erweiterung baut auf der bestehenden Amazon Product Bar Extension auf und fügt automatische Produktdatenextraktion, KI-basierte Titel-Customization mit Mistral-AI und erweiterte Item-Verwaltung hinzu. Das System extrahiert automatisch Titel und Preis von Amazon-Produkten, generiert drei KI-Titelvorschläge über Mistral-AI und ermöglicht die Auswahl per Klick. Titel und Preis werden als Fremdschlüssel für weitere Aktionen bereitgestellt.

Architecture

graph TD
    A[Enhanced Item Management] --> B[Settings Panel]
    A --> C[Product Extractor]
    A --> D[Mistral AI Service]
    A --> E[Title Selection UI]
    A --> F[Enhanced Storage]
    
    B --> H[API Key Manager]
    C --> I[Amazon Page Parser]
    C --> J[Price Extractor]
    C --> K[Title Extractor]
    
    D --> L[API Client]
    D --> M[Response Parser]
    D --> N[Error Handler]
    
    E --> O[Suggestion Renderer]
    E --> P[Selection Handler]
    
    F --> Q[Enhanced Item Model]
    F --> R[Local Storage Manager]
    
    H --> R
    I --> J
    I --> K
    L --> M
    M --> O
    P --> Q
    Q --> R

Die Architektur erweitert die bestehende Extension um:

1. Settings Panel - API-Key-Verwaltung und Konfiguration
2. Product Extractor - Automatische Datenextraktion von Amazon
3. Mistral AI Service - KI-Integration für Titel-Generierung
4. Title Selection UI - Interface für Titelauswahl
5. Enhanced Storage - Erweiterte Datenspeicherung

Components and Interfaces

1. Enhanced Item Model

interface EnhancedItem {
  id: string;                    // Eindeutige Item-ID
  amazonUrl: string;             // Amazon-Produkt-URL
  originalTitle: string;         // Ursprünglich extrahierter Titel
  customTitle: string;           // Ausgewählter KI-generierter Titel
  price: string;                 // Extrahierter Preis
  currency: string;              // Währung (EUR, USD, etc.)
  titleSuggestions: string[];    // Drei KI-generierte Vorschläge
  createdAt: Date;               // Erstellungszeitpunkt
  updatedAt: Date;               // Letzte Aktualisierung
}

2. Product Extractor

interface ProductExtractor {
  extractProductData(url: string): Promise<ProductData>;
  extractTitle(htmlContent: string): string | null;
  extractPrice(htmlContent: string): PriceData | null;
  validateAmazonUrl(url: string): boolean;
}

interface ProductData {
  title: string;
  price: string;
  currency: string;
  imageUrl?: string;
  asin?: string;
}

interface PriceData {
  amount: string;
  currency: string;
  formatted: string;
}

3. Mistral AI Service

interface MistralAIService {
  generateTitleSuggestions(originalTitle: string, apiKey: string): Promise<string[]>;
  validateApiKey(apiKey: string): Promise<boolean>;
  testConnection(apiKey: string): Promise<ConnectionStatus>;
}

interface ConnectionStatus {
  isValid: boolean;
  error?: string;
  responseTime?: number;
}

interface MistralRequest {
  model: string;
  messages: MistralMessage[];
  max_tokens: number;
  temperature: number;
}

interface MistralMessage {
  role: 'system' | 'user';
  content: string;
}

interface MistralResponse {
  choices: {
    message: {
      content: string;
    };
  }[];
}

4. Settings Panel Manager

interface SettingsPanelManager {
  createSettingsPanel(): HTMLElement;
  showSettings(): void;
  hideSettings(): void;
  saveApiKey(apiKey: string): Promise<void>;
  getApiKey(): Promise<string | null>;
  testApiKey(apiKey: string): Promise<boolean>;
  maskApiKey(apiKey: string): string;
}

interface SettingsData {
  mistralApiKey?: string;
  autoExtractEnabled: boolean;
  defaultTitleSelection: 'first' | 'original';
  maxRetries: number;
  timeoutSeconds: number;
}

5. Title Selection UI Manager

interface TitleSelectionManager {
  createSelectionUI(suggestions: string[], originalTitle: string): HTMLElement;
  showTitleSelection(container: HTMLElement): void;
  hideTitleSelection(): void;
  onTitleSelected(callback: (selectedTitle: string) => void): void;
  highlightSelection(index: number): void;
}

interface TitleOption {
  text: string;
  type: 'ai-generated' | 'original';
  index: number;
  isSelected: boolean;
}

6. Enhanced Storage Manager

interface EnhancedStorageManager {
  saveEnhancedItem(item: EnhancedItem): Promise<void>;
  getEnhancedItems(): Promise<EnhancedItem[]>;
  getEnhancedItem(id: string): Promise<EnhancedItem | null>;
  updateEnhancedItem(id: string, updates: Partial<EnhancedItem>): Promise<void>;
  deleteEnhancedItem(id: string): Promise<void>;
  findItemByTitleAndPrice(title: string, price: string): Promise<EnhancedItem | null>;
  migrateFromBasicItems(): Promise<void>;
}

7. Enhanced Storage Manager

Enhanced Item Storage Structure

{
  "enhancedItems": {
    "item_12345": {
      "id": "item_12345",
      "amazonUrl": "https://amazon.de/dp/B08N5WRWNW",
      "originalTitle": "Samsung Galaxy S21 Ultra 5G Smartphone 128GB",
      "customTitle": "Samsung Galaxy S21 Ultra - Premium 5G Flagship",
      "price": "899.99",
      "currency": "EUR",
      "titleSuggestions": [
        "Samsung Galaxy S21 Ultra - Premium 5G Flagship",
        "Galaxy S21 Ultra: High-End Android Smartphone",
        "Samsung S21 Ultra - Professional Mobile Device"
      ],
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  },
  "settings": {
    "mistralApiKey": "encrypted_api_key_here",
    "autoExtractEnabled": true,
    "defaultTitleSelection": "first",
    "maxRetries": 3,
    "timeoutSeconds": 10
  }
}

Mistral AI Integration

// Prompt Template für Titel-Generierung
const TITLE_GENERATION_PROMPT = `
Du bist ein Experte für E-Commerce-Produkttitel. 
Erstelle 3 alternative, prägnante Produkttitel für folgendes Amazon-Produkt:

Original-Titel: "{originalTitle}"

Anforderungen:
- Maximal 60 Zeichen pro Titel
- Klar und beschreibend
- Für deutsche Kunden optimiert
- Keine Sonderzeichen oder Emojis
- Fokus auf wichtigste Produktmerkmale

Antworte nur mit den 3 Titeln, getrennt durch Zeilenwechsel.
`;

// API-Konfiguration
const MISTRAL_CONFIG = {
  baseUrl: 'https://api.mistral.ai/v1',
  model: 'mistral-small-latest',
  maxTokens: 200,
  temperature: 0.7,
  timeout: 10000
};

UI Components Structure

<!-- Settings Panel -->
<div class="enhanced-settings-panel">
  <div class="settings-header">
    <h2>Enhanced Item Management Settings</h2>
    <button class="close-btn">×</button>
  </div>
  
  <div class="settings-content">
    <div class="api-key-section">
      <label for="mistral-api-key">Mistral AI API Key:</label>
      <div class="api-key-input-group">
        <input type="password" id="mistral-api-key" placeholder="API Key eingeben...">
        <button class="test-key-btn">Test</button>
      </div>
      <div class="api-key-status"></div>
    </div>
    
    <div class="extraction-settings">
      <label>
        <input type="checkbox" id="auto-extract"> 
        Automatische Extraktion aktivieren
      </label>
    </div>
    
    <div class="title-settings">
      <label for="default-selection">Standard-Titelauswahl:</label>
      <select id="default-selection">
        <option value="first">Erster KI-Vorschlag</option>
        <option value="original">Original-Titel</option>
      </select>
    </div>
  </div>
  
  <div class="settings-footer">
    <button class="save-settings-btn">Speichern</button>
    <button class="cancel-btn">Abbrechen</button>
  </div>
</div>

<!-- Title Selection UI -->
<div class="title-selection-container">
  <div class="title-selection-header">
    <h3>Titel auswählen:</h3>
    <div class="loading-indicator" style="display: none;">
      <span>KI generiert Vorschläge...</span>
    </div>
  </div>
  
  <div class="title-options">
    <div class="title-option ai-suggestion selected" data-index="0">
      <span class="option-label">KI-Vorschlag 1:</span>
      <span class="option-text">Samsung Galaxy S21 Ultra - Premium 5G Flagship</span>
    </div>
    <div class="title-option ai-suggestion" data-index="1">
      <span class="option-label">KI-Vorschlag 2:</span>
      <span class="option-text">Galaxy S21 Ultra: High-End Android Smartphone</span>
    </div>
    <div class="title-option ai-suggestion" data-index="2">
      <span class="option-label">KI-Vorschlag 3:</span>
      <span class="option-text">Samsung S21 Ultra - Professional Mobile Device</span>
    </div>
    <div class="title-option original-title" data-index="3">
      <span class="option-label">Original:</span>
      <span class="option-text">Samsung Galaxy S21 Ultra 5G Smartphone 128GB</span>
    </div>
  </div>
  
  <div class="selection-actions">
    <button class="confirm-selection-btn">Auswahl bestätigen</button>
    <button class="skip-ai-btn">Ohne KI fortfahren</button>
  </div>
</div>

<!-- Enhanced Item List -->
<div class="enhanced-item-list">
  <div class="item-header">
    <h2>Gespeicherte Items</h2>
    <div class="add-item-form">
      <input type="url" placeholder="Amazon-URL eingeben...">
      <button class="extract-btn">Extrahieren</button>
    </div>
  </div>
  
  <div class="items-container">
    <div class="enhanced-item" data-item-id="item_12345">
      <div class="item-image">
        <img src="product-image.jpg" alt="Product">
      </div>
      <div class="item-details">
        <div class="item-title">Samsung Galaxy S21 Ultra - Premium 5G Flagship</div>
        <div class="item-price">€899.99</div>
        <div class="item-url">
          <a href="https://amazon.de/dp/B08N5WRWNW" target="_blank">Amazon Link</a>
        </div>
        <div class="item-meta">
          <span class="original-title-toggle">Original anzeigen</span>
          <span class="created-date">15.01.2024</span>
        </div>
      </div>
      <div class="item-actions">
        <button class="edit-btn">Bearbeiten</button>
        <button class="delete-btn">Löschen</button>
      </div>
    </div>
  </div>
</div>

CSS Styling

/* Settings Panel */
.enhanced-settings-panel {
  position: fixed;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  width: 500px;
  background: #1a1a1a;
  border: 1px solid #333;
  border-radius: 8px;
  color: white;
  z-index: 10000;
  box-shadow: 0 4px 20px rgba(0,0,0,0.5);
}

.settings-header {
  padding: 1.5rem;
  border-bottom: 1px solid #333;
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.api-key-input-group {
  display: flex;
  gap: 0.5rem;
  margin-top: 0.5rem;
}

.api-key-input-group input {
  flex: 1;
  padding: 0.75rem;
  background: #2a2a2a;
  border: 1px solid #444;
  border-radius: 4px;
  color: white;
}

.test-key-btn {
  padding: 0.75rem 1rem;
  background: #007acc;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

/* Title Selection */
.title-selection-container {
  background: #f8f9fa;
  border: 1px solid #ddd;
  border-radius: 8px;
  padding: 1.5rem;
  margin: 1rem 0;
}

.title-option {
  padding: 1rem;
  border: 2px solid #e9ecef;
  border-radius: 6px;
  margin-bottom: 0.5rem;
  cursor: pointer;
  transition: all 0.2s ease;
}

.title-option:hover {
  border-color: #007acc;
  background: #f0f8ff;
}

.title-option.selected {
  border-color: #007acc;
  background: #e3f2fd;
}

.title-option .option-label {
  font-weight: 600;
  color: #666;
  display: block;
  margin-bottom: 0.25rem;
}

.title-option .option-text {
  font-size: 1.1rem;
  color: #333;
}

.ai-suggestion .option-label {
  color: #007acc;
}

.original-title .option-label {
  color: #28a745;
}

/* Enhanced Item List */
.enhanced-item {
  display: flex;
  gap: 1rem;
  padding: 1.5rem;
  border: 1px solid #333;
  border-radius: 8px;
  margin-bottom: 1rem;
  background: #2a2a2a;
}

.item-image img {
  width: 80px;
  height: 80px;
  object-fit: cover;
  border-radius: 4px;
}

.item-details {
  flex: 1;
}

.item-title {
  font-size: 1.2rem;
  font-weight: 600;
  color: white;
  margin-bottom: 0.5rem;
}

.item-price {
  font-size: 1.1rem;
  color: #ff9900;
  font-weight: 600;
  margin-bottom: 0.5rem;
}

.item-url a {
  color: #007acc;
  text-decoration: none;
}

.item-meta {
  display: flex;
  gap: 1rem;
  margin-top: 0.5rem;
  font-size: 0.9rem;
  color: #aaa;
}

.original-title-toggle {
  color: #007acc;
  cursor: pointer;
  text-decoration: underline;
}

.item-actions {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
}

.item-actions button {
  padding: 0.5rem 1rem;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-size: 0.9rem;
}

.edit-btn {
  background: #007acc;
  color: white;
}

.delete-btn {
  background: #dc3545;
  color: white;
}

/* Loading States */
.loading-indicator {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  color: #007acc;
}

.loading-indicator::before {
  content: '';
  width: 16px;
  height: 16px;
  border: 2px solid #007acc;
  border-top: 2px solid transparent;
  border-radius: 50%;
  animation: spin 1s linear infinite;
}

@keyframes spin {
  to { transform: rotate(360deg); }
}

/* Error States */
.error-message {
  background: #f8d7da;
  color: #721c24;
  padding: 0.75rem;
  border-radius: 4px;
  border: 1px solid #f5c6cb;
  margin: 0.5rem 0;
}

.success-message {
  background: #d4edda;
  color: #155724;
  padding: 0.75rem;
  border-radius: 4px;
  border: 1px solid #c3e6cb;
  margin: 0.5rem 0;
}

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: Product Data Extraction Completeness

For any valid Amazon product URL, the Product_Extractor should successfully extract both title and price data or return appropriate error messages for inaccessible content. Validates: Requirements 1.1, 1.2, 1.3, 1.4, 1.5

Property 2: API Key Validation Consistency

For any API key input, the Settings_Panel should correctly validate the format and provide appropriate feedback (save for valid keys, error for invalid keys). Validates: Requirements 2.2, 2.3, 2.4, 2.6

Property 3: Mistral-AI Integration Reliability

For any extracted product title with a valid API key, the Extension should either receive exactly three title suggestions from Mistral-AI or gracefully handle failures with appropriate fallbacks. Validates: Requirements 3.1, 3.2, 3.3, 3.4, 3.5, 3.6

Property 4: Title Selection Mechanism

For any set of title suggestions (including original), the UI should display all options as selectable items and correctly handle user selection with visual feedback. Validates: Requirements 4.1, 4.2, 4.3, 4.4, 4.5, 4.6

Property 5: Enhanced Item Storage Completeness

For any item being saved, the Extension should store all required data (URL, custom title, original title, price) and validate completeness before saving. Validates: Requirements 5.1, 5.2, 5.3, 5.4, 5.5

Property 6: Item List Display Completeness

For any collection of saved items, the display should show all required information (custom title, price, URL, original title access) in chronological order. Validates: Requirements 6.1, 6.2, 6.3, 6.4, 6.5

Property 7: Error Handling and Fallback Robustness

For any system failure (AI unavailable, extraction failure, network error), the Extension should provide appropriate fallbacks and never lose user data. Validates: Requirements 7.1, 7.2, 7.3, 7.4, 7.5, 7.6

Property 8: Beautiful User Interface Design

For any user interface element, the system should display modern glassmorphism design with consistent styling, smooth animations, and proper visual hierarchy. Validates: Requirements 8.1, 8.2, 8.3, 8.4, 8.5, 8.6, 8.7, 8.8

Property 9: Enhanced Interactivity and User Guidance

For any user interaction, the system should provide clear visual feedback, contextual help, and intuitive navigation with proper accessibility support. Validates: Requirements 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7, 9.8

Property 10: Responsive Design and Accessibility

For any screen size or accessibility preference, the interface should adapt appropriately and provide full functionality with proper accessibility features. Validates: Requirements 10.1, 10.2, 10.3, 10.4, 10.5, 10.6, 10.7, 10.8

Interface Design Enhancements

Modern Glassmorphism Design System

The interface uses a modern glassmorphism design approach with:

Color Palette:

• Primary: Amazon Orange (#ff9900) with gradients
• Secondary: Tech Blue (#007acc) for links and actions
• Success: Green (#28a745) for positive actions
• Error: Red (#dc3545) for warnings and errors
• Background: Dark theme with glass effects

Glass Effect Implementation:

/* Glass morphism base */
background: rgba(255, 255, 255, 0.08);
border: 1px solid rgba(255, 255, 255, 0.15);
backdrop-filter: blur(10px);
border-radius: 12px;

/* Hover states */
background: rgba(255, 255, 255, 0.12);
border-color: rgba(255, 255, 255, 0.25);

Typography Hierarchy:

• Headers: 1.8rem, font-weight 700, letter-spacing -0.5px
• Subheaders: 1.25rem, font-weight 600
• Body text: 1rem, line-height 1.5
• Small text: 0.85rem for meta information
• Monospace: For URLs and technical data

Enhanced Visual Components

Progress Indicator Design:

• Step-by-step visual progress with icons (🔍📦🤖✏️💾)
• Smooth transitions between states (active, completed, error)
• Color-coded status indicators with animations
• Contextual help text for each step

Item Card Layout:

┌─────────────────────────────────────────────────────┐
│ [Custom Title]                           [€29.99]   │
│ 🔗 amazon.de/dp/...                                 │
│ Erstellt: 11.01.2026, 13:58  [KI-Titel]           │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Original: ROCKBROS Balaclava Herbst/Winter...  │ │
│ └─────────────────────────────────────────────────┘ │
│                                    [👁️] [✏️] [🗑️] │
└─────────────────────────────────────────────────────┘

Interactive Elements:

• Hover effects with subtle transformations (translateY(-2px))
• Button gradients with glow effects on hover
• Smooth transitions (0.2s ease) for all interactions
• Focus indicators for keyboard navigation

Animation and Transition System

Micro-interactions:

• Button hover: Scale and glow effect
• Card hover: Lift effect with shadow
• Form focus: Border color transition with glow
• Loading states: Pulse animation for progress indicators

Page Transitions:

• Slide-in animations for new content (slideInUp, slideInDown)
• Fade transitions for state changes
• Stagger animations for list items

Performance Considerations:

• CSS transforms for animations (GPU accelerated)
• Respect prefers-reduced-motion for accessibility
• Optimized animation timing (60fps target)

Responsive Breakpoints

Mobile (≤ 480px):

• Single column layout
• Full-width buttons
• Larger touch targets (44px minimum)
• Simplified navigation

Tablet (481px - 768px):

• Optimized spacing for medium screens
• Flexible grid layouts
• Touch-friendly interactions

Desktop (≥ 769px):

• Multi-column layouts where appropriate
• Hover states and detailed interactions
• Keyboard navigation support

Accessibility Features

Screen Reader Support:

• Semantic HTML structure with proper headings
• ARIA labels for interactive elements
• Live regions for dynamic content updates
• Descriptive alt text for icons

Keyboard Navigation:

• Logical tab order through all interactive elements
• Visible focus indicators with high contrast
• Keyboard shortcuts for common actions
• Skip links for navigation

Visual Accessibility:

• High contrast mode support
• Scalable text (up to 200% zoom)
• Color-blind friendly palette
• Sufficient color contrast ratios (WCAG AA)

Error Handling

Scenario	Handling
Mistral-AI API unavailable	Use original title, continue with saving
Invalid API key	Display clear error with setup instructions
Product extraction failure	Allow manual title/price input
Network timeout	Retry up to 3 times, then use fallback
Malformed Amazon URL	Show validation error, prevent processing
Missing title or price data	Use fallback values, log warning
Local storage quota exceeded	Show warning, suggest cleanup
Corrupted item data	Remove invalid entries, preserve valid data
AI response parsing error	Use original title, log error

Testing Strategy

Unit Tests

• Amazon URL validation with various formats
• Product data extraction from mock HTML content
• API key format validation and masking
• Title selection UI interactions and state management
• Local storage operations (save, load, delete, update)
• Error message display and user feedback
• Settings panel functionality and persistence

Property-Based Tests

• Property 1: Generate random valid/invalid Amazon URLs, test extraction completeness
• Property 2: Generate various API key formats, test validation consistency
• Property 3: Test Mistral-AI integration with random titles and API states
• Property 4: Test title selection with various suggestion sets
• Property 5: Test item storage with random complete/incomplete data
• Property 6: Test display rendering with random item collections
• Property 7: Test error handling with simulated failure conditions

Integration Tests

• End-to-end workflow: URL input → extraction → AI processing → selection → saving
• Settings configuration and API key management
• Real Mistral-AI API integration (with test key)
• Cross-component data flow and state synchronization
• Migration from basic items to enhanced items

Testing Framework

• Jest für Unit Tests
• fast-check für Property-Based Tests
• JSDOM für DOM-Simulation
• Mock Service Worker für API-Simulation
• Chrome Extension Testing Utils für Browser-spezifische Features

Test Configuration

• Minimum 100 Iterationen pro Property Test
• Tag-Format: Feature: enhanced-item-management, Property {number}: {property_text}
• Jede Correctness Property wird durch einen einzelnen Property-Based Test implementiert
• Test API key: GP1CD0e0TrGJvt6ERDyjhaUy5w4Q4Wqr (für Mistral-AI Integration Tests)