diff --git a/SUPPLIER_PRODUCT_ASSOCIATION_PLAN.md b/SUPPLIER_PRODUCT_ASSOCIATION_PLAN.md new file mode 100644 index 00000000..3f848e28 --- /dev/null +++ b/SUPPLIER_PRODUCT_ASSOCIATION_PLAN.md @@ -0,0 +1,115 @@ +# Supplier Product/Price Association Implementation Plan + +## Critical Feature for Automatic PO Creation + +### Problem +Suppliers currently have no product/price associations. Without this data: +- ❌ Automatic Purchase Order (PO) creation cannot function +- ❌ System cannot determine which supplier to order from +- ❌ System cannot calculate PO amounts +- ❌ Procurement optimization is impossible + +### Backend Support (Already Exists) +`SupplierPriceList` model in `/services/suppliers/app/models/suppliers.py`: +```python +class SupplierPriceList(Base): + supplier_id: UUID + inventory_product_id: UUID # Reference to product + unit_price: Decimal # Price per unit + unit_of_measure: String # kg, g, L, ml, units + minimum_order_quantity: Integer + tier_pricing: JSONB # Volume discounts + effective_date: DateTime + expiry_date: DateTime + is_active: Boolean +``` + +### Frontend Implementation + +#### Phase 1: Supplier Step Enhancement +**File**: `/frontend/src/components/domain/setup-wizard/steps/SuppliersSetupStep.tsx` + +**New Features**: +1. **Product Association Section** (after supplier is created) + - Expandable "Manage Products" for each supplier + - Multi-select product picker from inventory + - Price entry form for each selected product + +2. **UI Flow**: +``` +[Supplier Card] +├─ Name, Contact, Type +├─ [Manage Products ▼] button +└─ When expanded: + ├─ [+ Add Product] button → Opens modal + ├─ Product List (if any exist): + │ └─ [Product Name] - [Price] [Unit] [Edit] [Delete] + └─ [Save Products] button +``` + +3. **Product Selector Modal**: +``` +Modal: "Add Products for [Supplier Name]" +├─ Multi-select dropdown (from inventory) +├─ For each selected product: +│ ├─ Product Name (read-only) +│ ├─ Unit Price (€) input *required +│ ├─ Unit of Measure select *required +│ └─ Min Order Qty input (optional) +└─ [Cancel] [Save Prices] +``` + +#### Phase 2: Backend Integration +**API Endpoints** (already exist): +- `POST /suppliers/{supplier_id}/price-lists` - Create price list item +- `GET /suppliers/{supplier_id}/price-lists` - Get supplier's price list +- `PUT /suppliers/{supplier_id}/price-lists/{price_list_id}` - Update price +- `DELETE /suppliers/{supplier_id}/price-lists/{price_list_id}` - Delete price + +**Frontend Services** needed: +- `useSupplierPriceLists(supplierId)` - Fetch price lists +- `useCreateSupplierPriceList()` - Create price list items +- `useUpdateSupplierPriceList()` - Update prices +- `useDeleteSupplierPriceList()` - Delete price list items + +#### Phase 3: Data Flow +``` +User creates supplier + ↓ +Supplier card shows "Manage Products" button + ↓ +Click → Expand section showing current products (if any) + ↓ +Click "Add Product" → Modal opens + ↓ +Select products from inventory + Enter prices + ↓ +Save → API call to create SupplierPriceList entries + ↓ +Modal closes, product list updates + ↓ +User can proceed to next step +``` + +### Implementation Checklist + +- [ ] Create useSupplierPriceLists hook +- [ ] Create useCreateSupplierPriceList hook +- [ ] Create useUpdateSupplierPriceList hook +- [ ] Create useDeleteSupplierPriceList hook +- [ ] Add product management UI to SuppliersSetupStep +- [ ] Create product selector modal component +- [ ] Add price entry form +- [ ] Integrate with backend API +- [ ] Add validation (price > 0, unit required) +- [ ] Test create/update/delete flow +- [ ] Test navigation (can proceed after products added) + +### Benefits After Implementation +✅ Automatic PO creation will work +✅ System knows which supplier supplies what +✅ System knows current prices +✅ Can calculate PO totals automatically +✅ Can optimize procurement based on prices +✅ Can track price changes over time +✅ Foundation for supplier performance analysis