MeshiTrack/docs/phases/phase-4-pharmacies-prices-refills.md

# Phase 4 — Pharmacies, Prices, Purchases & Refills

**Goal**: Track store catalog prices for medicines, record purchases (which may mix medicines and food), and get automatic refill alerts when cabinet stock is running low. The Store and PriceRecord infrastructure built here is shared with food tracking (Phase 9).

**Depends on**: Phase 0, Phase 1 (medicines), Phase 2 (cabinet), Phase 3 (regimens — for burn rate)

---

## Domain Model

### Price Records vs Purchases

These are two distinct concepts:

- **Price Record** — a catalog observation: "Product X at Store Y is listed at $Z for a pack of N units." Nothing moves. Multiple records can exist for the same product+store (different pack sizes, bulk deals, insurance tier, etc.). This is price surveillance.
- **Purchase** — recording that you actually acquired something. Can contain multiple line items mixing medicines and (Phase 9) food products from the same store.

### Purchase Status

Most purchases happen at a physical store and items are immediately in hand. Online purchases may take time to arrive. The status reflects this:

- **`in_cabinet`** — the default for physical store purchases. Items are available immediately and are added to the cabinet right away.
- **`ordered`** — used only for online purchases where the items have not yet arrived. Items in this state are counted toward pending stock in refill alerts (so the user is not repeatedly alerted to reorder something already purchased and on its way). Once items arrive, the purchase is moved to `in_cabinet` and items are added to the cabinet.

For food (Phase 9), purchases have no intermediate state — food items always go directly to pantry/fridge upon recording.

Refill alerts must account for both cabinet stock and purchases with status `ordered` so the alert reflects actual available stock.

---

## Data Model

### Store Schema (Shared — used by both medicine and food domains)

```typescript
// packages/shared/src/types/store.ts
export interface Store {
  id: string;
  householdId: string;
  name: string;
  address?: string;
  location?: { lat: number; lng: number };
  url?: string;
  notes?: string;
  tags: string[]; // e.g. 'pharmacy', 'grocery', 'online', 'bulk', 'discount'
  isActive: boolean;
  createdBy: string;
  createdAt: Date;
  updatedAt: Date;
}
```

### PriceRecord Schema (Medicine)

```typescript
// packages/shared/src/types/medicine-price.ts
export interface MedicinePriceRecord {
  id: string;
  householdId: string;
  medicineProductId: string;   // specific brand/package
  medicineProductBrand: string; // denormalized
  medicineId: string;           // generic medicine, for cross-brand comparison
  medicineName: string;         // denormalized
  storeId: string;
  storeName: string;            // denormalized
  price: number;
  currency: string;
  quantity: number;             // units in this price point (package size)
  unit: DosageUnit;
  pricePerUnit: number;         // computed: price / quantity
  isInsurancePrice: boolean;
  notes?: string;               // e.g. "bulk deal", "fast shipping tier"
  date: Date;                   // when price was observed
  createdBy: string;
  createdAt: Date;
}
```

### Purchase Schema

```typescript
// packages/shared/src/types/purchase.ts
export type PurchaseStatus = 'ordered' | 'in_cabinet';

export interface Purchase {
  id: string;
  householdId: string;
  storeId: string;
  storeName: string;        // denormalized
  status: PurchaseStatus;   // 'in_cabinet' for physical; 'ordered' for online until received
  items: PurchaseItem[];
  notes?: string;
  purchasedAt: Date;        // when the purchase was made (or order placed)
  receivedAt?: Date;        // set when status moves to in_cabinet for online orders
  createdBy: string;
  createdAt: Date;
  updatedAt: Date;
}

export interface PurchaseItem {
  id: string;               // stable item id within the purchase
  // exactly one of these is set:
  medicineProductId?: string;
  foodProductId?: string;   // reserved for Phase 9
  // denormalized display info:
  name: string;             // brand name / food product name
  quantity: number;         // units in package
  unit: string;
  actualPrice?: number;     // what was actually paid (optional)
  currency?: string;
  priceRecordId?: string;   // optionally links to a PriceRecord used as reference
  addedToCabinet: boolean;
}
```

### RefillAlert (Computed, not stored)

```typescript
// packages/shared/src/types/refill.ts
export interface RefillAlert {
  medicineId: string;
  medicineName: string;
  medicineStrength: number;
  medicineStrengthUnit: StrengthUnit;
  daysUntilEmpty: number;        // based on cabinet stock only
  daysUntilEmptyWithOrders: number; // cabinet + pending ordered items
  dailyConsumption: number;
  currentStock: number;
  pendingOrderStock: number;     // units in orders with status 'ordered'
  suggestedQuantity: number;     // enough for N days (configurable, default 30)
  cheapestOption?: {
    price: number;
    pricePerUnit: number;
    storeName: string;
    storeId: string;
    date: Date;
  };
  lastKnownPrice?: {
    price: number;
    pricePerUnit: number;
    storeName: string;
    storeId: string;
    date: Date;
  };
}

export interface RefillList {
  id: string;
  householdId: string;
  name: string;
  items: RefillListItem[];
  status: RefillListStatus;
  preferredStoreId?: string;
  totalEstimatedCost?: number;
  createdBy: string;
  createdAt: Date;
  updatedAt: Date;
}

export interface RefillListItem {
  id: string;
  medicineId: string;
  medicineName: string;
  quantity: number;
  unit: DosageUnit;
  estimatedPrice?: number;
  actualPrice?: number;
  checked: boolean;
  checkedAt?: Date;
  addedToCabinet: boolean;
  storeId?: string;
  notes?: string;
}

export enum RefillListStatus {
  ACTIVE = 'active',
  SHOPPING = 'shopping',
  COMPLETED = 'completed',
  ARCHIVED = 'archived',
}
```

### MongoDB Indexes

```javascript
// Store
{ householdId: 1, name: 1 }
{ householdId: 1, tags: 1 }

// MedicinePriceRecord
{ householdId: 1, medicineProductId: 1, storeId: 1, date: -1 }
{ householdId: 1, medicineId: 1, date: -1 }
{ householdId: 1, storeId: 1, date: -1 }

// Purchase
{ householdId: 1, status: 1, purchasedAt: -1 }
{ householdId: 1, storeId: 1 }
{ householdId: 1, 'items.medicineProductId': 1 }

// RefillList
{ householdId: 1, status: 1 }
{ householdId: 1, createdAt: -1 }
```

---

## API Endpoints

### StoresModule (Shared)

| Method | Path          | Description               | Auth   |
| ------ | ------------- | ------------------------- | ------ |
| GET    | `/stores`     | List stores for household | member |
| GET    | `/stores/:id` | Get single store          | member |
| POST   | `/stores`     | Add a store               | member |
| PATCH  | `/stores/:id` | Update store              | member |
| DELETE | `/stores/:id` | Deactivate store          | admin  |

### MedicinePricesModule

| Method | Path                                   | Description                             | Auth   |
| ------ | -------------------------------------- | --------------------------------------- | ------ |
| POST   | `/medicine-prices`                     | Record a catalog price observation      | member |
| GET    | `/medicine-prices/history/:medicineId` | Price history for a medicine            | member |
| GET    | `/medicine-prices/compare/:medicineId` | Compare stores for a medicine           | member |
| GET    | `/medicine-prices/analytics`           | Price trend analytics                   | member |

### PurchasesModule

| Method | Path                            | Description                                               | Auth   |
| ------ | ------------------------------- | --------------------------------------------------------- | ------ |
| POST   | `/purchases`                    | Record a purchase (physical → immediately in_cabinet; online → ordered) | member |
| GET    | `/purchases`                    | List purchases (filterable by status)                     | member |
| GET    | `/purchases/:id`                | Get purchase detail                                       | member |
| PATCH  | `/purchases/:id`                | Update purchase (notes, items)                            | member |
| POST   | `/purchases/:id/receive`        | Mark online purchase received — moves items to cabinet    | member |
| DELETE | `/purchases/:id`                | Delete purchase (only if status is ordered)               | member |

### RefillsModule

| Method | Path                               | Description                               | Auth   |
| ------ | ---------------------------------- | ----------------------------------------- | ------ |
| GET    | `/refills/alerts`                  | Get refill alerts (accounts for pending orders) | member |
| POST   | `/refills/lists`                   | Create refill list (manual or from alerts)| member |
| GET    | `/refills/lists`                   | List refill lists                         | member |
| GET    | `/refills/lists/:id`               | Get refill list                           | member |
| PATCH  | `/refills/lists/:id`               | Update refill list                        | member |
| PATCH  | `/refills/lists/:id/items/:itemId` | Check off / update item                   | member |

### Query Parameters

```
# GET /stores
?tags=pharmacy
&search=walgreens

# GET /medicine-prices/history/:medicineId
?storeId=abc123
&startDate=2026-01-01
&endDate=2026-03-27
&limit=50

# GET /purchases
?status=ordered
&storeId=abc123

# GET /refills/alerts
?thresholdDays=7
&userId=abc123
```

---

## Tasks

### 4.1 — Shared Types & Validation

- Store types in `packages/shared/src/types/store.ts`
- Medicine price types in `packages/shared/src/types/medicine-price.ts`
- Order types in `packages/shared/src/types/order.ts`
- Refill types in `packages/shared/src/types/refill.ts`
- Zod schemas for all create/update operations

### 4.2 — Stores CRUD (Shared Infrastructure)

- `packages/api/src/modules/stores/`
- Standard CRUD, scoped to `householdId`
- Tag-based filtering (pharmacy, grocery, online, etc.)
- Reused by both medicine and food domains

### 4.3 — Medicine Price Service

Records catalog price observations. Multiple records per product+store are allowed (different pack sizes, bulk tiers, insurance pricing).

```typescript
class MedicinePriceService {
  recordPrice(data: CreateMedicinePriceRecord, householdId: string): Promise<MedicinePriceRecord>;
  getPriceHistory(medicineId: string, householdId: string, options?: { storeId?: string; startDate?: Date; endDate?: Date; limit?: number }): Promise<MedicinePriceRecord[]>;
  compareStores(medicineId: string, householdId: string): Promise<StoreComparison[]>;
  estimatePrice(medicineId: string, householdId: string, storeId?: string): Promise<number | null>;
  getPriceAnalytics(householdId: string, period: 'month' | 'quarter' | 'year'): Promise<PriceAnalytics>;
}
```

Analytics on this module are **price trends**, not spending — they show how prices change over time, not purchases made.

### 4.4 — Purchases Module

A purchase records that items were actually acquired. A single purchase can contain any mix of medicine products and (Phase 9) food products from the same store.

**Record physical purchase** (default flow — store visit):
- Set `status: 'in_cabinet'` at creation time
- Items are added to cabinet immediately as part of the create call
- No separate receive step needed

**Record online purchase**:
- Set `status: 'ordered'` at creation time
- Items are NOT added to cabinet yet
- Items in `ordered` purchases are counted as pending stock in refill alerts
- When items arrive, call `POST /purchases/:id/receive` to add to cabinet

**Receive flow** (`POST /purchases/:id/receive`):
1. For each item with `medicineProductId` and `addedToCabinet: false`:
   - Create a `CabinetItem` (status: active, purchaseDate: today)
   - If `actualPrice` was recorded on the item, create a `MedicinePriceRecord`
   - Mark `addedToCabinet: true`
2. Set purchase status to `in_cabinet`
3. Return summary: `{ addedCount, priceRecordsCreated }`

### 4.5 — Refill Alert Service

Refill alerts account for both current cabinet stock and pending orders (status `ordered`) so users are not prompted to reorder medicine already on its way.

```typescript
class RefillAlertService {
  /**
   * For each medicine in the user's active regimens:
   * 1. Get burn rate from BurnRateService (Phase 3)
   * 2. Sum cabinet stock + units in purchases with status 'ordered'
   * 3. If daysUntilEmpty (cabinet only) <= thresholdDays, create alert
   * 4. Attach pending purchase stock, cheapest price option, last known price
   * 5. Calculate suggested quantity (enough for configurable days, default 30)
   */
  getAlerts(householdId: string, userId: string, thresholdDays?: number): Promise<RefillAlert[]>;
}
```

### 4.6 — Refill Lists

- CRUD for refill lists
- `POST /refills/lists` with optional `fromAlerts: true` to auto-populate from current alerts
- Each item can carry an estimated price (from price history) and an actual price (entered when purchased)
- Refill lists are planning aids — actual cabinet addition goes through Purchases

### 4.7 — Price Analytics

Analytics on the medicine-prices page show **price trends across stores over time**, not spending:

```typescript
interface PriceAnalytics {
  priceOverTime: { period: string; avgPricePerUnit: number; storeName: string }[];
  cheapestByMedicine: {
    medicineId: string;
    medicineName: string;
    cheapestPricePerUnit: number;
    storeName: string;
  }[];
  priceAlerts: {
    medicineId: string;
    medicineName: string;
    storeName: string;
    previousPrice: number;
    currentPrice: number;
    changePercent: number;
  }[];
}
```

Spending analytics (total money spent) live on the Orders page, computed from order items with `actualPrice`.

### 4.8 — Web UI: Stores & Prices

- `/stores` page: store list with CRUD, filter by tags
- `/medicine-prices` page:
  - Record a price: store → medicine → product → price + quantity + currency + insurance flag + notes
  - Price history per medicine: filterable by store, shows price-per-unit over time
  - Store comparison table for selected medicine
  - Price trend analytics (price changes over time, not spending)

### 4.9 — Web UI: Purchases

- `/purchases` page:
  - List of purchases grouped by status (ordered / in cabinet)
  - Record purchase: pick store, choose physical or online, add line items (medicine products)
  - Physical purchases: items go to cabinet immediately on save
  - Online purchases: sit in `ordered` state until received; "Mark as received" bulk-adds to cabinet
  - Shows actual price paid per item (used to auto-create price records on receive)

### 4.10 — Web UI: Refill Management

- `/refills` page:
  - **Alerts section**: medicines running low, with `daysUntilEmpty` and `daysUntilEmptyWithOrders` shown separately so the user can see how much the pending order helps
  - **Refill lists section**: planning lists with check-off and estimated prices

---

## Acceptance Criteria

- [ ] Can create and manage stores with tags
- [ ] Can record catalog price observations; multiple price points per product+store allowed
- [ ] Store comparison shows cheapest observed price per medicine
- [ ] Can record a purchase (physical or online) mixing medicine and (future) food items
- [ ] Physical purchases add medicine items to cabinet immediately
- [ ] Online purchases sit in ordered state; receiving them adds items to cabinet and optionally records prices
- [ ] Refill alerts correctly factor in pending purchases (status: ordered) when computing days-until-empty
- [ ] Price analytics show price trends, not spending
- [ ] Spending analytics live on the Orders page
- [ ] Store infrastructure is reusable for food tracking (Phase 9)
- [ ] All queries scoped to `householdId`