lasse
0b42a74fe9
✅ New functionality added (soft delete system) ✅ Backward compatible (existing features unchanged) ✅ Significant enhancement (complete temporal tracking system) ✅ API additions (new endpoints, parameters) ✅ UI enhancements (new components, visual indicators)
111 lines
3.7 KiB
Markdown
111 lines
3.7 KiB
Markdown
# 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) |