# Temporal Product Tracking Features

This document describes the new historical product tracking functionality that allows you to track product changes over time.

## Features

### 1. Historical Product Versioning
- Products now maintain a complete history of changes
- When product attributes (name, weight, category, etc.) are updated, the old version is automatically saved
- Each version has `valid_from` and `valid_to` dates indicating when it was active

### 2. Manual Effective Dates
- When creating or editing products, you can specify a custom "Effective From" date
- If not specified, the current date is used
- This allows you to retroactively record product changes or schedule future changes

### 3. Shopping Event Historical Accuracy
- Shopping events now show products exactly as they were when purchased
- Even if a product's weight or name has changed since purchase, the historical data is preserved

## Database Changes

### New Tables
- `products_history` - Stores old versions of products when they're updated

### New Columns
- `products.valid_from` (DATE) - When this product version became effective
- `products.valid_to` (DATE) - When this product version was superseded (9999-12-31 for current versions)

## API Endpoints

### New Endpoints
- `GET /current-date` - Get current date for form prefilling
- `GET /products/{id}/history` - Get all historical versions of a product
- `GET /products/{id}/at/{date}` - Get product as it existed on a specific date (YYYY-MM-DD)
- `GET /shopping-events/{id}/products-as-purchased` - Get products as they were when purchased

### Updated Endpoints
- `POST /products/` - Now accepts optional `valid_from` field
- `PUT /products/{id}` - Now accepts optional `valid_from` field for manual versioning

## Frontend Changes

### Product Forms
- Added "Effective From" date field to product create/edit forms
- Date field is pre-filled with current date
- Required field with helpful description

### API Integration
- ProductCreate interface now includes optional `valid_from` field
- New utilityApi for fetching current date
- Proper form validation and error handling

## Migration

Run `temporal_migration.sql` to:
1. Add temporal columns to existing products table
2. Create products_history table
3. Set up automatic versioning trigger
4. Initialize existing products with baseline date (2025-05-01)

## Usage Examples

### Creating a Product with Custom Date
```json
POST /products/
{
  "name": "Organic Milk",
  "category_id": 1,
  "weight": 1000,
  "weight_unit": "ml",
  "valid_from": "2025-03-15"
}
```

### Updating a Product with Future Effective Date
```json
PUT /products/123
{
  "weight": 1200,
  "valid_from": "2025-04-01"
}
```

### Getting Historical Product Data
```bash
# Get product as it was on January 15, 2025
GET /products/123/at/2025-01-15

# Get all versions of a product
GET /products/123/history

# Get shopping event with historical product data
GET /shopping-events/456/products-as-purchased
```

## Benefits

1. **Complete Audit Trail** - Never lose track of how products have changed over time
2. **Accurate Historical Data** - Shopping events always show correct product information
3. **Flexible Dating** - Record changes retroactively or schedule future changes
4. **Automatic Versioning** - No manual effort required for basic updates
5. **Cross-Database Compatibility** - Uses standard DATE fields that work with PostgreSQL, SQLite, MySQL, etc.

## Technical Notes

- Versioning is handled automatically by database triggers
- Manual versioning is used when custom `valid_from` dates are specified
- Date format: YYYY-MM-DD (ISO 8601)
- Far future date (9999-12-31) represents current/active versions
- Temporal fields are not displayed in regular product lists (by design)