groceries/TEMPORAL_FEATURES.md

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

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

PUT /products/123
{
  "weight": 1200,
  "valid_from": "2025-04-01"
}

Getting Historical Product Data

# 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)