Phase 5 cleanup
This commit is contained in:
parent
5536acd67d
commit
76a516a417
136 changed files with 6322 additions and 1985 deletions
|
|
@ -16,6 +16,12 @@
|
|||
6. LLM provider interface (`ILlmProvider`) with no-op implementation
|
||||
7. "Smart Add" endpoint placeholder
|
||||
|
||||
## Design Principles
|
||||
|
||||
- **Metric-only storage**: Products store nutrition relative to a metric serving (`g`, `ml`) or a discrete unit (`piece`, `slice`). Imperial/volume cooking units (oz, cup, tbsp, tsp) are a recipe-input concern and are normalized to metric in Phase 6 before persistence. This keeps nutrition math density-free at the product level.
|
||||
- **Per-household catalog**: Every product is owned by exactly one household. There is no cross-household sharing in this phase; a global/public catalog can be added later via an explicit seed dataset.
|
||||
- **Soft delete**: Deletes set `deletedAt` rather than removing rows, so historical recipes/pantry/grocery references stay resolvable.
|
||||
|
||||
---
|
||||
|
||||
## Data Model
|
||||
|
|
@ -29,18 +35,19 @@ export interface Product {
|
|||
householdId: string;
|
||||
name: string;
|
||||
brand?: string;
|
||||
barcode?: string;
|
||||
barcode?: string; // EAN-13 / UPC-A, digits only
|
||||
category: ProductCategory;
|
||||
servingSize: number;
|
||||
servingUnit: ServingUnit;
|
||||
nutrition: NutritionInfo;
|
||||
servingSize: number; // quantity of one serving in `servingUnit`
|
||||
servingUnit: ServingUnit; // metric or discrete only
|
||||
densityGPerMl?: number; // optional, used by Phase 6 to convert volume cooking units
|
||||
nutrition: NutritionInfo; // values are PER serving (size = servingSize servingUnit)
|
||||
tags: string[];
|
||||
imageUrl?: string;
|
||||
isPublic: boolean; // Visible to all households (for shared catalog)
|
||||
source: ProductSource; // 'manual' | 'barcode_lookup' | 'llm' | 'import'
|
||||
source: ProductSource;
|
||||
createdBy: string; // userId
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
deletedAt?: Date; // soft delete
|
||||
}
|
||||
|
||||
export interface NutritionInfo {
|
||||
|
|
@ -81,14 +88,14 @@ export enum ProductCategory {
|
|||
export enum ServingUnit {
|
||||
GRAMS = 'g',
|
||||
MILLILITERS = 'ml',
|
||||
OUNCES = 'oz',
|
||||
CUPS = 'cup',
|
||||
TABLESPOONS = 'tbsp',
|
||||
TEASPOONS = 'tsp',
|
||||
PIECES = 'piece',
|
||||
SLICES = 'slice',
|
||||
}
|
||||
|
||||
// Note: imperial/volume cooking units (oz, cup, tbsp, tsp) are intentionally
|
||||
// excluded. Recipes may receive them as input in Phase 6 and convert to metric
|
||||
// before persisting. See `phase-6-recipes.md` for the conversion rules.
|
||||
|
||||
export enum ProductSource {
|
||||
MANUAL = 'manual',
|
||||
BARCODE_LOOKUP = 'barcode_lookup',
|
||||
|
|
@ -104,11 +111,13 @@ export enum ProductSource {
|
|||
{ name: 'text', brand: 'text', tags: 'text' }
|
||||
|
||||
// Compound indexes
|
||||
{ householdId: 1, category: 1 }
|
||||
{ householdId: 1, barcode: 1 } // unique within household
|
||||
{ householdId: 1, deletedAt: 1, category: 1 }
|
||||
{ householdId: 1, barcode: 1 } // partial index where barcode exists & deletedAt is null; unique within household
|
||||
{ householdId: 1, name: 1, brand: 1 } // near-unique for dedup
|
||||
```
|
||||
|
||||
All list/search queries filter `deletedAt: { $exists: false }` (or `null`).
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints
|
||||
|
|
@ -126,15 +135,22 @@ export enum ProductSource {
|
|||
| POST | `/products/import` | Bulk import from CSV/JSON | admin |
|
||||
| POST | `/products/smart-add` | LLM-powered add from text/image | member |
|
||||
|
||||
Notes:
|
||||
|
||||
- `DELETE /products/:id` is a soft delete; the product is hidden from listings but remains resolvable by id for historical references in recipes, pantry, and grocery.
|
||||
- `POST /products` rejects payloads whose `barcode` collides with an existing non-deleted product in the household (409 `ConflictError`).
|
||||
|
||||
### Query Parameters for GET `/products`
|
||||
|
||||
```
|
||||
?q=chicken # Full-text search
|
||||
?q=chicken # Full-text search (name, brand, tags)
|
||||
&category=meat # Filter by category
|
||||
&tags=organic,fresh # Filter by tags (AND)
|
||||
&cursor=abc123 # Cursor-based pagination
|
||||
&barcode=0123456789012 # Exact barcode match
|
||||
&includeDeleted=false # Default false; admins can pass true
|
||||
&cursor=abc123 # Cursor-based pagination (opaque)
|
||||
&limit=20 # Page size (max 100)
|
||||
&sort=name|-updatedAt # Sort field, prefix - for desc
|
||||
&sort=name|-updatedAt # Sort field, prefix - for desc; default -updatedAt
|
||||
```
|
||||
|
||||
### Response Shape
|
||||
|
|
@ -157,30 +173,40 @@ interface PaginatedResponse<T> {
|
|||
### 5.1 — Shared Types & Validation
|
||||
|
||||
- Add all types above to `packages/shared/src/types/product.ts`
|
||||
- Add enums to `packages/shared/src/enums/`
|
||||
- Create Zod schemas:
|
||||
- `CreateProductSchema` — validates create payload
|
||||
- `UpdateProductSchema` — partial, validates update payload
|
||||
- `ProductQuerySchema` — validates query params
|
||||
- Add enums to `packages/shared/src/enums/product.enums.ts` (`ProductCategory`, `ServingUnit`, `ProductSource`)
|
||||
- Create Zod schemas in `packages/shared/src/validation/product.validation.ts`:
|
||||
- `CreateProductSchema` — validates create payload; `servingSize > 0`; `nutrition` macros `>= 0`; `barcode` matches `/^\d{8,14}$/`
|
||||
- `UpdateProductSchema` — `CreateProductSchema.partial()`
|
||||
- `ProductQuerySchema` — validates query params; `limit` clamped to `[1, 100]`, default 20
|
||||
- `ImportProductsSchema` — array of `CreateProductSchema` (for JSON import)
|
||||
- All schemas imported from `'zod/v4'`; enums use `z.enum(Object.values(...))`.
|
||||
|
||||
### 5.2 — Mongoose Schema & Repository
|
||||
|
||||
- `packages/api/src/modules/products/schemas/product.schema.ts`
|
||||
- `packages/api/src/modules/products/schemas/product.schema.ts` — Mongoose schema with `timestamps: true`, `deletedAt` index, partial unique index on `(householdId, barcode)`.
|
||||
- `ProductRepository` with:
|
||||
- `findByHousehold(householdId, query)` — supports text search, filters, cursor pagination
|
||||
- `findByBarcode(householdId, barcode)`
|
||||
- `findByHousehold(householdId, query)` — text search, filters, cursor pagination, excludes soft-deleted
|
||||
- `findById(id, householdId)` — also returns soft-deleted (for historical resolution)
|
||||
- `findByBarcode(householdId, barcode)` — excludes soft-deleted
|
||||
- `findByIds(householdId, ids[])` — batch fetch for recipe/pantry resolution
|
||||
- `create(data)`
|
||||
- `update(id, householdId, data)`
|
||||
- `softDelete(id, householdId)`
|
||||
- `bulkCreate(items[])`
|
||||
- `softDelete(id, householdId)` — sets `deletedAt`
|
||||
- `bulkCreate(householdId, items[])` — uses `insertMany` with `ordered: false`
|
||||
- All read queries use `.lean().exec()`.
|
||||
|
||||
### 5.3 — Barcode Lookup Service
|
||||
|
||||
- `BarcodeService`:
|
||||
- First check local DB for matching barcode
|
||||
- If not found, query Open Food Facts API (`https://world.openfoodfacts.org/api/v2/product/{barcode}`)
|
||||
- Map OFF response to `Product` shape
|
||||
- Cache results in local DB with `source: 'barcode_lookup'`
|
||||
- First check local DB for matching barcode (per household)
|
||||
- If not found, call Open Food Facts API: `https://world.openfoodfacts.org/api/v2/product/{barcode}`
|
||||
- Map OFF response to `Product` shape:
|
||||
- `product_name` → `name`; `brands` (first) → `brand`; `categories_tags` → derived `ProductCategory`
|
||||
- Nutrition normalized to per-serving (`g` or `ml`) using `serving_size` / `serving_quantity` from OFF; fall back to per-100g if absent
|
||||
- Drop fields with no usable value (do not fabricate zeroes)
|
||||
- Cache result in local DB with `source: 'barcode_lookup'`, owned by the requesting household
|
||||
- Failures (network, 404, malformed): return `{ found: false }`; do not throw
|
||||
- Outbound HTTP via `undici` with a 5s timeout and a configurable User-Agent (`MeshiTrack/<version> (+self-hosted)`)
|
||||
|
||||
### 5.4 — LLM Provider Interface
|
||||
|
||||
|
|
@ -214,38 +240,46 @@ export const LLM_PROVIDER = Symbol('LLM_PROVIDER');
|
|||
|
||||
### 5.6 — Import Endpoint
|
||||
|
||||
- `POST /products/import` accepts multipart CSV or JSON file
|
||||
- Validate each row against `CreateProductSchema`
|
||||
- Return summary: `{ imported: N, skipped: M, errors: [...] }`
|
||||
- CSV column mapping: `name, brand, barcode, category, servingSize, servingUnit, calories, protein, carbs, fat, ...`
|
||||
- `POST /products/import` accepts multipart CSV or JSON file (max 5 MB, 5000 rows)
|
||||
- Validate each row against `CreateProductSchema`; reject rows with imperial `servingUnit` values with a clear error message
|
||||
- De-dup by `(householdId, barcode)` and `(householdId, name, brand)`; existing matches are reported as `skipped`
|
||||
- Return summary: `{ imported: N, skipped: M, errors: [{ row, message }] }`
|
||||
- CSV column mapping: `name, brand, barcode, category, servingSize, servingUnit, densityGPerMl, calories, protein, carbs, fat, fiber, sugar, sodium, saturatedFat, cholesterol, tags`
|
||||
- `tags` is a `;`-separated list
|
||||
- `servingUnit` ∈ `{g, ml, piece, slice}`
|
||||
|
||||
### 5.7 — Web UI: Product Library
|
||||
|
||||
- `/products` page:
|
||||
- Search bar with debounced full-text search
|
||||
- `/products` page (Server Component for initial fetch; client island for filters):
|
||||
- Search bar with debounced full-text search (300ms)
|
||||
- Category filter dropdown
|
||||
- Tag filter chips
|
||||
- Product grid/list view (toggle)
|
||||
- Each product card shows: name, brand, category icon, calories/serving
|
||||
- Product grid/list view (toggle, persisted in `localStorage`)
|
||||
- Each product card shows: name, brand, category icon, calories per serving, serving (`100 g`, `250 ml`, `1 piece`)
|
||||
- Add/Edit product modal:
|
||||
- Form fields for all product properties
|
||||
- Form fields for all product properties; `servingUnit` select limited to `g | ml | piece | slice`
|
||||
- Nutrition input section with per-serving values
|
||||
- Barcode field with "Lookup" button
|
||||
- Optional `densityGPerMl` field (only relevant for liquids/pastes)
|
||||
- Barcode field with "Lookup" button (calls `/products/barcode/:code`)
|
||||
- "Smart Add" tab (text input or image upload)
|
||||
- Import dialog: file upload with preview and error display
|
||||
- Import dialog: file upload with preview, row count, and error display
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Can create, read, update, delete products via API
|
||||
- [ ] Full-text search returns relevant results
|
||||
- [ ] Barcode lookup fetches from Open Food Facts when not in local DB
|
||||
- [ ] Bulk import processes a CSV with 100+ products
|
||||
- [ ] Can create, read, update, soft-delete products via API
|
||||
- [ ] Soft-deleted products remain resolvable by id but excluded from listings
|
||||
- [ ] `ServingUnit` is restricted to `g | ml | piece | slice`; imperial values are rejected at validation
|
||||
- [ ] Full-text search returns relevant results across name, brand, tags
|
||||
- [ ] Barcode lookup fetches from Open Food Facts when not in local DB and caches the result
|
||||
- [ ] Barcode collisions within a household return 409
|
||||
- [ ] Bulk import processes a CSV with 100+ products and reports per-row errors
|
||||
- [ ] Web UI allows searching, filtering, adding, and editing products
|
||||
- [ ] `ILlmProvider` interface is defined and injectable
|
||||
- [ ] Smart Add endpoint returns graceful "not available" with NoOp provider
|
||||
- [ ] Smart Add endpoint returns graceful `{ available: false }` with the NoOp provider
|
||||
- [ ] All product queries are scoped to `householdId`
|
||||
- [ ] Unit + integration tests meet coverage targets (100% lines/functions/statements, 90% branches)
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue