`FEATURES.md`

314 lines
# Omega Watch Price History - Feature Guide

## Quick Access
- **Live Application**: http://45.61.58.125:7600
- **API Documentation**: http://45.61.58.125:7600/api/docs
- **Server Health**: http://45.61.58.125:7600/api/health

---

## Key Features & How to Use

### 1. Dark Mode
**Location**: Header (top right)
**Usage**: Click the sun/moon icon to toggle between light and dark themes
**Auto-detect**: Automatically uses your system preference on first visit
**Persistence**: Your choice is saved and remembered

### 2. Advanced Filtering
**Location**: Watch List page, top of screen
**Usage**:
- Click "Advanced Filters" to expand
- Select series (Speedmaster, Seamaster, etc.)
- Select movement types (Automatic, Manual, Quartz)
- Drag price range sliders ($0 - $100,000+)
- Drag year range sliders (1948 - 2024)
- Choose sorting (appreciation, price, year, name)
- Click "Clear All" to reset

### 3. Search
**Location**: Inside Advanced Filters
**Usage**: Type to search across:
- Watch model names
- Reference numbers
- Series names
- Specifications (movement, material, size)
**Fuzzy**: Tolerates typos and partial matches

### 4. View Modes
**Location**: Watch List page, top right
**Options**: Grid view or List view
**Grid**: Beautiful card layout with images
**List**: Compact table with quick comparison

### 5. Favorites/Watchlist
**Location**: Heart icon on each watch card
**Usage**:
- Click heart to add/remove from favorites
- Toggle "Favorites Only" button to filter
**Persistence**: Saved to your browser

### 6. Watch Comparison
**Location**: Compare tab in navigation
**Usage**:
1. Go to Compare tab
2. Select watches from the grid
3. Click "Compare X Watches" button
4. View side-by-side comparison with charts
5. Add/remove watches (max 3)
**Features**:
- Price history chart overlay
- Specification comparison
- Appreciation comparison

### 7. Share Watches
**Location**: Share icon on watch cards
**Usage**: Click to copy shareable link
**Result**: URL with watch ID (e.g., ?watch=speedmaster-moonwatch-1957)
**Share via**: Native share menu or clipboard

### 8. Export Data
**Location**: Download icon on watch cards (list view)
**Formats**: CSV or JSON
**Usage**: Click to download watch price history

### 9. Deep Linking
**Usage**: Share URLs with specific watches
**Example**: http://45.61.58.125:7600?watch=seamaster-300-1957
**Result**: Automatically opens that watch's detail view

### 10. Skeleton Loaders
**Location**: Throughout app during loading
**Purpose**: Shows loading state instead of blank screen
**Animation**: Smooth pulse effect

---

## Dashboard Features

### Statistics Cards
- Total Watches (32)
- Watch Series (9)
- Average Appreciation (%)
- Average Current Price

### Charts
1. **Collection Distribution** - Doughnut chart showing watches per series
2. **Price by Year** - Bar chart of average prices by introduction year
3. **Price vs Appreciation** - Scatter plot analyzing correlation
4. **Top Performers** - Ranked list of highest appreciation watches

---

## Watch List Features

### Card Information
- High-quality watch image
- Model name and series
- Reference number
- Year introduced
- Case size, movement, material, water resistance
- Original price vs current price
- Appreciation percentage
- Action buttons (favorite, share, export)

### Sorting Options
1. Highest Appreciation
2. Lowest Appreciation
3. Highest Price
4. Lowest Price
5. Newest First
6. Oldest First
7. Name (A-Z)
8. Name (Z-A)

### Filtering Options
- **Series**: Speedmaster, Seamaster, De Ville, Constellation, etc.
- **Movement**: Automatic, Manual, Quartz
- **Price Range**: Any range from $0 to $100,000+
- **Year Range**: 1948 to 2024

---

## Mobile Features

### Optimizations
- Touch-friendly buttons (44px minimum)
- Swipe gestures supported
- No horizontal scrolling
- Responsive images
- Prevents iOS auto-zoom on inputs
- Hamburger menu on small screens

### Performance
- Lazy loads images as you scroll
- Caches data in browser
- Smooth 60fps animations
- Fast initial load (<3 seconds)

---

## Accessibility Features

### Keyboard Navigation
- Tab through all interactive elements
- Enter/Space to activate buttons
- Arrow keys in lists
- Escape to close modals

### Screen Readers
- ARIA labels on all controls
- Semantic HTML structure
- Alt text on images
- Descriptive link text

### Visual
- High contrast ratios (WCAG AA)
- Focus indicators (red outline)
- Reduced motion option
- Scalable text

---

## Data Visualizations

### Price History Charts
**Location**: Click any watch card → Detail view
**Shows**: Complete price evolution over time
**Interactive**: Hover for exact values
**Zoomable**: Click and drag to zoom into date ranges

### Comparison Charts
**Location**: Compare mode
**Shows**: Multiple watches overlaid on same chart
**Colors**: Red, Gold, Navy for each watch
**Legend**: Click to show/hide individual watches

---

## Performance Tips

### For Best Experience
1. Use modern browser (Chrome, Firefox, Safari, Edge)
2. Enable JavaScript
3. Clear cache if issues occur
4. Use WiFi for faster image loading
5. Enable system dark mode for automatic theming

### Troubleshooting
- **Blank screen**: Hard refresh (Ctrl+Shift+R)
- **Images not loading**: Check internet connection
- **Filters not working**: Clear browser localStorage
- **Slow loading**: Server may be under load, wait 5 seconds

---

## API Access

For developers who want to integrate with the data:

### Get All Watches
```bash
curl http://45.61.58.125:7600/api/watches
```

### Get Statistics
```bash
curl http://45.61.58.125:7600/api/statistics
```

### Search Watches
```bash
curl "http://45.61.58.125:7600/api/search?q=speedmaster"
```

### Get Watch Details
```bash
curl http://45.61.58.125:7600/api/watches/{watch-id}/history
```

### Compare Watches
```bash
curl -X POST http://45.61.58.125:7600/api/compare \
  -H "Content-Type: application/json" \
  -d '{"watchIds": ["speedmaster-moonwatch-1957", "seamaster-300-1957"]}'
```

### Export Data
```bash
curl http://45.61.58.125:7600/api/export/csv > watches.csv
curl http://45.61.58.125:7600/api/export/json > watches.json
```

---

## Browser Compatibility

### Fully Supported
- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+
- Chrome Android 90+
- Safari iOS 14+

### Degraded Experience
- Older browsers may not show animations
- IE11 not supported (use Edge)

---

## Shortcuts & Tips

### Power User Tips
1. **Quick Filter**: Type in search instead of clicking filters
2. **Bulk Compare**: Select multiple from Compare tab grid
3. **Share Collection**: Export to JSON, share file
4. **Track Changes**: Favorite watches to monitor
5. **Print Reports**: Use browser print, PDF export

### Keyboard Shortcuts
- **/** - Focus search
- **Esc** - Close modals
- **Tab** - Navigate elements
- **Enter** - Select/activate

---

## Privacy & Data

### What's Stored Locally
- Dark mode preference
- Filter preferences
- Favorite watches
- View mode (grid/list)

### What's NOT Stored
- No personal information
- No tracking cookies
- No analytics
- No user accounts

### Data Source
- All data is historical and publicly available
- Prices are estimates for educational purposes
- Not for investment advice

---

## Support & Feedback

### System Status
Check health: http://45.61.58.125:7600/api/health

### Documentation
Full docs: http://45.61.58.125:7600/api/docs

### Technical Details
Enhancement docs: `/root/Projects/watches/ENHANCEMENTS.md`

---

**Last Updated**: November 17, 2025
**Version**: 2.0 Enhanced