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

```mermaid
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

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

```typescript
// 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

```html
<!-- 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

```css
/* 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:**
```css
/* 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)