chore: initialize project repository with core extension files
- Add .gitignore to exclude node_modules, dist, logs, and system files - Add comprehensive project documentation including README, deployment guide, and development setup - Add .kiro project specifications for amazon-product-bar-extension, appwrite-cloud-storage, appwrite-userid-repair, blacklist-feature, and enhanced-item-management - Add .kiro steering documents for product, structure, styling, and tech guidelines - Add VSCode settings configuration for consistent development environment - Add manifest.json and babel/vite configuration for extension build setup - Add complete source code implementation including AppWrite integration, storage managers, UI components, and services - Add comprehensive test suite with Jest configuration and 30+ test files covering all major modules - Add test HTML files for integration testing and validation - Add coverage reports and build validation scripts - Add AppWrite setup and repair documentation for database schema management - Add migration guides and responsive accessibility implementation documentation - Establish foundation for Amazon product bar extension with full feature set including blacklist management, enhanced item workflows, and real-time synchronization
This commit is contained in:
375
.kiro/specs/amazon-product-bar-extension/design.md
Normal file
375
.kiro/specs/amazon-product-bar-extension/design.md
Normal file
@@ -0,0 +1,375 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user