mercadodevida/project/specs/expiration-tracking/SPEC.md

# EXPIRATION TRACKING — SPEC.md

## 1. Concept & Vision

MercadoDeVida sells perishable goods (fresh food, supplements, cosmetics) that require expiration tracking. The platform must distinguish between **lot-level inventory** (which can expire) and **variant-level inventory** (which already exists). Expiration dates belong to inventory lots, not products. Products only declare whether they require expiration tracking. Expired lots remain visible for audit/waste tracking but contribute zero sellable units.

## 2. Design Principles

- **LOT OWNS EXPIRATION**: A product does not expire — a specific inventory arrival (lot) expires.
- **BACKEND IS AUTHORITATIVE**: Admin UX improvements are not authoritative. The backend validates all expiration requirements.
- **NO BREAKING CHANGE**: Products without expiration tracking behave exactly as before. Migration default is `expiration_tracking_enabled = false`.
- **MODULAR**: Expiration logic lives in Inventory domain, not in Checkout. Checkout calls `InventoryService.reserve()` which applies expiration rules internally.
- **AUDITABLE**: All lot mutations are tracked. Expired lots are never silently deleted.

## 3. Domain Model

### 3.1 Product — Extension

```
Product.expiration_tracking_enabled: boolean
  default: false
  note: products created before migration default to false
```

This boolean determines whether a product's inventory lots must carry expiration dates. It is **not** a computed status — admin configures it per product.

### 3.2 InventoryLot — New Entity

```
InventoryLot
  id:            uuid (PK)
  variant_id:    uuid (FK → catalog_variants.id)
  quantity:      integer (>= 0)
  expiration_date: date (nullable; required when expiration_tracking_enabled = true)
  created_at:    timestamptz
  updated_at:    timestamptz
```

Each lot represents a single inventory arrival for a variant with its own expiration date.

```
inventory_lots (table)
  CONSTRAINT expiration_date_future_or_null
    CHECK (expiration_date IS NULL OR expiration_date >= CURRENT_DATE)
```

### 3.3 Availability Calculation

For a variant with expiration tracking:

```
sum(quantity) over lots where expiration_date > today
```

Expired lots (expiration_date < today) contribute zero units.

### 3.4 Reservation Strategy (FEFO)

For expiration-tracking variants, available lots are allocated **FEFO** (First Expired First Out):

```
lots ordered by expiration_date ASC
→ reserve from earliest-expiring lot first
→ when exhausted, move to next
```

For non-expiration-tracking variants: existing variant-level behavior is preserved.

## 4. Expiration Policy

```
Product.expiration_tracking_enabled = false
→ existing variant-level stock (inventory_stock table)
→ no expiration dates required
→ no FEFO
→ backward compatible

Product.expiration_tracking_enabled = true
→ new lot-level inventory (inventory_lots table)
→ expiration_date required on receive
→ FEFO allocation
→ expired lots excluded from available stock
```

## 5. Checkout Integration

Checkout calls `InventoryService.reserve(variantId, quantity)` — it does NOT query lots directly.

The Inventory domain applies:
1. Load lots for variant, ordered by expiration_date ASC
2. Allocate from earliest-expiring first
3. Return 409 if insufficient non-expired stock
4. Return reserved lot IDs for order traceability (optional, see Section 7)

This preserves existing `InventoryServicePort` contract. A new port method `reserve(variantId, quantity, {fefo: true})` can be introduced without breaking existing callers.

## 6. Order Line Traceability (Optional)

If lot-level traceability is needed in orders:

```
OrderLine.lotIds: uuid[] (optional)
  populated at confirm time
  used for: waste reports, supplier claims, recall handling
```

This is NOT required for MVP. Document it as a future task if:
- Regulatory requirements emerge
- Supplier quality claims need lot evidence
- Recall workflows are added

## 7. Admin Requirements

### 7.1 Product Editor — General Tab
Add checkbox:
```
☐ Product has expiration-controlled inventory
```
When disabled: no expiration UI shown.
When enabled: inventory section shows lot management.

### 7.2 Inventory — Lot View

For expiration-tracking variants, replace/extend the existing stock table with:

| Lot | Quantity | Expiration | Status |
|-----|----------|-------------|--------|
| auto | 10 | 10/09/2026 | NEAR_EXPIRY |
| auto | 35 | 15/11/2026 | VALID |
| auto | 4 | 01/08/2026 | EXPIRED |

Statuses computed (not stored):
- `EXPIRED`: expiration_date < today
- `NEAR_EXPIRY`: expiration_date <= today + warning_days
- `VALID`: otherwise

### 7.3 Admin Inventory Filters

```
/admin/inventory?filter=expiring
/admin/inventory?filter=expired
/admin/inventory?filter=all
/admin/inventory?filter=no-expiry
```

Extends existing `/admin/inventory` — no separate route.

### 7.4 Admin Dashboard (Secondary)

As separate task, not MVP scope:
- Widget: "X expired lots" + "X lots expiring within 7 days"
- Link to filtered inventory view

## 8. Expiry Warning Threshold

System-wide configuration via `FLAG_EXPIRY_WARNING_DAYS` (env var, default 7).

Per-product configuration is NOT implemented in MVP. Introduce if business requirement emerges.

## 9. Notifications (Future)

Out of MVP scope but documented:
- Cron job identifies near-expiry lots daily
- Sends alert to admin email
- Generates waste report

## 10. API Contracts

### Product (extended)

```
GET /products/:id
  → includes expiration_tracking_enabled: boolean

PATCH /products/:id
  body: { expiration_tracking_enabled?: boolean }
  → updates product policy
  → if toggled ON: no migration of existing stock (admin receives instruction)
  → if toggled OFF: existing lots remain visible but no new lots require expiry
```

### Inventory Lots

```
GET /inventory/lots?variant_id=X&filter=expiring|expired|all
  → list lots for variant with status derived

POST /inventory/lots
  body: { variant_id, quantity, expiration_date }
  → creates new lot
  → 422 if variant requires expiry but expiration_date missing
  → 422 if expiration_date is in the past

PATCH /inventory/lots/:id
  body: { quantity?, expiration_date? }
  → updates lot
  → 422 if expiration_date in past

DELETE /inventory/lots/:id
  → removes lot (audit logged)
```

### Inventory Availability (extended)

```
GET /inventory/:variantId/availability
  → existing behavior
  → for expiration-tracking variants: sums non-expired lot quantities
  → for non-tracking: existing variant-level sum
```

### Inventory Reserve (extended)

```
POST /inventory/:variantId/reservations
  → existing behavior
  → for expiration-tracking variants: FEFO allocation from non-expired lots
  → returns lot allocation info (new field in response)
```

## 11. Migration Strategy

See `MIGRATION.md`.

## 12. Out of Scope

- Lot-level supplier tracking (lot_number, supplier_id, cost, received_at)
- Automatic lot expiration notifications
- Per-product expiry warning threshold
- Order line lot traceability
- Public storefront expiration display (no customer requirement)
- Lot-level pricing
- Partial lot reservations across multiple lots (future)

## 13. Feature Flag

```
expiration_tracking
  default: false (off)
  enables: lot model, FEFO logic, expiration admin UI
```

Flip to true after migration completes.

## 14. Acceptance Criteria

See `TESTS.md`.