Roadmap Item: Release 0.4 — Retailer-Aware Planning¶

Status¶

PROPOSED

Date: 2026-02-07

Changelog¶

Context¶

Users shop at different retailers for different items — produce from the local market, packaged goods from the supermarket, specialty items from ethnic grocery stores. Currently all items go on a single trip regardless of retailer type. This release adds sourcing preferences that map ingredients or categories to preferred retailers, with automatic trip splitting to generate per-retailer shopping lists.

Proposal¶

Overview¶

Sourcing preferences per ingredient/category with automatic trip splitting into per-retailer shopping lists.

Goals¶

• Sourcing preferences linking ingredient or category to preferred retailer type
• Fallback behavior when preferred retailer is unavailable (defer, allow any, skip)
• Auto-split a shopping plan into per-retailer trip lists
• Category-level defaults with ingredient-level overrides

Non-Goals¶

• Online ordering or catalog item mapping (v0.6)
• Price comparison across retailers (v0.6)
• Retailer-specific product catalogs (v0.6)

Technical Details¶

Approach¶

• New SourcingPreference entity (ingredient_id or category → retailer_type + fallback)
• Trip-splitting service that partitions a generated shopping plan by retailer
• Each split creates a separate ShoppingTrip linked to the original plan

Dependencies¶

• v0.3 must be complete (shopping plan generation)
• Existing RetailerType enum from v0.1

TDs¶

• TD-004: Retailer-Aware Planning (planned)

Backwards Compatibility¶

• New endpoints and entities only
• Manual trip creation unchanged; splitting is opt-in via plan generation

Implementation Plan¶

Phase 1: Sourcing Preferences¶

• SourcingPreference entity + repository
• CRUD endpoints for preference management
• Category defaults + ingredient overrides resolution
• Migration

Phase 2: Trip Splitting¶

• Trip-splitting service
• Integration with plan generation from v0.3
• POST /trip/generate gains split_by_retailer flag
• Tests

Open Questions¶

• Should the user confirm the split before trips are created?
• How to handle items with no sourcing preference?
• Should trips from the same plan be linked for grouped display?

References¶

• TBD