docs(spec): Einkaufsliste Mengen-Konsolidierung ueber Einheiten
Design fuer g/kg + ml/l Konsolidierung in listShoppingList():
500 g + 1 kg Kartoffeln aus verschiedenen Rezepten → 1,5 kg.
- unit-consolidation.ts mit unitFamily + consolidate
- GROUP BY wechselt auf family-key (weight/volume/raw)
- formatQuantity auf toLocaleString('de-DE', ...) app-weit
- Migration 015: shopping_cart_check.unit_key → family-key,
bestehende Abhaks migriert, Duplikate dedupliziert
- Test-Coverage fuer alle Edge-Cases
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
hsiegeln
@@ -0,0 +1,208 @@
|
||||
# Einkaufsliste: Mengen-Konsolidierung über Einheiten
|
||||
|
||||
## Kontext
|
||||
|
||||
Die Einkaufsliste (`/src/lib/server/shopping/repository.ts`, `listShoppingList()`) aggregiert
|
||||
Zutaten aus allen Warenkorb-Rezepten dynamisch per `GROUP BY LOWER(TRIM(name)), LOWER(TRIM(unit))`
|
||||
und summiert die skalierten Mengen. Verschiedene Einheiten für dieselbe Zutat bleiben separate
|
||||
Zeilen — typisches Beispiel: `500 g Kartoffeln` (Rezept A) und `1 kg Kartoffeln` (Rezept B)
|
||||
erscheinen als zwei Zeilen. Gewünscht: beides konsolidiert zu `1,5 kg Kartoffeln`.
|
||||
|
||||
## Design-Entscheidungen (durch Brainstorming bestätigt)
|
||||
|
||||
- **Scope**: nur Gewicht (g ↔ kg) und Volumen (ml ↔ l). TL/EL/Tasse/Stück bleiben unverändert.
|
||||
- **Anzeige-Einheit**: Auto-Promote ab ≥ 1000 in Basis-Einheit (500 g + 1 kg → "1,5 kg",
|
||||
200 g + 300 g → "500 g", 400 ml + 0,5 l → "900 ml", 0,5 l + 0,8 l → "1,3 l").
|
||||
- **Formatter**: `formatQuantity` wechselt app-weit auf `toLocaleString('de-DE', …)` →
|
||||
deutsches Komma als Dezimaltrennzeichen überall, kein Tausender-Grouping.
|
||||
- **Check-Stabilität**: der „abgehakt"-State hängt künftig an der Unit-Family (weight / volume /
|
||||
raw-unit), nicht an einer Display-Einheit, damit Hin-und-her-Wechsel zwischen g und kg den
|
||||
Haken nicht verlieren.
|
||||
|
||||
## Sektion 1 — Unit-Konsolidierung
|
||||
|
||||
### Neue Utility: `src/lib/server/shopping/unit-consolidation.ts`
|
||||
|
||||
Zwei reine Funktionen, vollständig getestet per Unit-Tests:
|
||||
|
||||
```ts
|
||||
export type UnitFamily = 'weight' | 'volume' | string;
|
||||
|
||||
const WEIGHT_UNITS = new Set(['g', 'kg']);
|
||||
const VOLUME_UNITS = new Set(['ml', 'l']);
|
||||
|
||||
export function unitFamily(unit: string | null | undefined): UnitFamily {
|
||||
const u = (unit ?? '').trim().toLowerCase();
|
||||
if (WEIGHT_UNITS.has(u)) return 'weight';
|
||||
if (VOLUME_UNITS.has(u)) return 'volume';
|
||||
return u; // leer bleibt leer → eigene Gruppe
|
||||
}
|
||||
|
||||
export interface QuantityInUnit {
|
||||
quantity: number | null;
|
||||
unit: string | null;
|
||||
}
|
||||
|
||||
export function consolidate(rows: QuantityInUnit[]): QuantityInUnit {
|
||||
// Gewicht: in g summieren, ≥1000 → kg, sonst g
|
||||
// Volumen: in ml summieren, ≥1000 → l, sonst ml
|
||||
// Andere: quantity einfach summieren, unit vom ersten Eintrag
|
||||
// (alle rows einer Gruppe haben dieselbe Family = denselben unit-string)
|
||||
// quantity=null wird als 0 behandelt (z. B. "etwas Salz" + "1 TL Salz" → "1 TL")
|
||||
}
|
||||
```
|
||||
|
||||
**Rundung Promote-Schwelle**: Vergleich passiert auf summierter Basis-Einheit
|
||||
(z. B. 1500 g ≥ 1000 → kg). Ergebnis-Rundung: `Math.round(x * 100) / 100` (max.
|
||||
zwei Nachkommastellen), die finale Display-Formatierung macht `formatQuantity`.
|
||||
|
||||
**Edge-Cases, die expliziter Test-Fall sind**:
|
||||
- `500 g + 1 kg` → `{quantity: 1.5, unit: 'kg'}`
|
||||
- `200 g + 300 g` → `{quantity: 500, unit: 'g'}`
|
||||
- `400 ml + 0.5 l` → `{quantity: 900, unit: 'ml'}`
|
||||
- `0.5 l + 0.8 l` → `{quantity: 1.3, unit: 'l'}`
|
||||
- `2 Bund + 1 Bund` → `{quantity: 3, unit: 'Bund'}` (unchanged family)
|
||||
- `5 Stück + 3 Stück` → `{quantity: 8, unit: 'Stück'}`
|
||||
- `null + 1 TL Salz` (eine Menge unbekannt) → `{quantity: 1, unit: 'TL'}`
|
||||
- `null + null` → `{quantity: null, unit: '<leer oder erster unit>'}`
|
||||
|
||||
### Integration in `listShoppingList()`
|
||||
|
||||
Die existierende SQL-Query liefert schon skalierte Mengen pro Zutat-Zeile
|
||||
(quantity * servings / servings_default). Änderung:
|
||||
|
||||
1. **GROUP BY** der SQL-Query wechselt von `LOWER(TRIM(unit))` auf einen
|
||||
Family-Key (inline per `CASE`):
|
||||
|
||||
```sql
|
||||
GROUP BY LOWER(TRIM(name)),
|
||||
CASE LOWER(TRIM(unit))
|
||||
WHEN 'g' THEN 'weight'
|
||||
WHEN 'kg' THEN 'weight'
|
||||
WHEN 'ml' THEN 'volume'
|
||||
WHEN 'l' THEN 'volume'
|
||||
ELSE LOWER(TRIM(unit))
|
||||
END
|
||||
```
|
||||
|
||||
2. **SUM()** wird nicht mehr blind über quantity gerechnet (500 + 1 ≠ 1500
|
||||
in Basis). Stattdessen liefert SQL pro Gruppe eine Liste der einzelnen
|
||||
`(quantity, unit)`-Paare — z. B. via `json_group_array(json_object('quantity', q, 'unit', u))`.
|
||||
TypeScript ruft dann `consolidate()` pro Zeile auf.
|
||||
|
||||
Alternative: SQL liefert für Familien 'weight' und 'volume' schon die
|
||||
summierten Basis-Werte (via `SUM(q * CASE WHEN unit='kg' THEN 1000 ELSE 1 END)`),
|
||||
für andere Families die unveränderte `SUM(q)`. Spart den json_group_array-Trick,
|
||||
ist aber in SQL hässlich. **Empfehlung**: json_group_array + consolidate in TS —
|
||||
SQL bleibt lesbar, Logik testbar.
|
||||
|
||||
3. Der Rückgabewert `ShoppingListItem` bekommt zwei zusätzliche Felder (wenn
|
||||
nicht schon vorhanden):
|
||||
- `quantity: number | null` (finaler Display-Wert)
|
||||
- `unit: string | null` (finale Display-Einheit)
|
||||
- `unitFamilyKey: string` (für den Check-Lookup clientseitig)
|
||||
|
||||
## Sektion 2 — Check-Key-Stabilität
|
||||
|
||||
Aktuelle Tabelle (aus `013_shopping_list.sql`):
|
||||
|
||||
```sql
|
||||
CREATE TABLE shopping_cart_check (
|
||||
name_key TEXT NOT NULL,
|
||||
unit_key TEXT NOT NULL,
|
||||
checked_at TEXT NOT NULL DEFAULT (datetime('now')),
|
||||
PRIMARY KEY (name_key, unit_key)
|
||||
);
|
||||
```
|
||||
|
||||
### Neue Migration `015_shopping_check_family.sql`
|
||||
|
||||
```sql
|
||||
-- Unit-Key wird zum Family-Key: g/kg → 'weight', ml/l → 'volume', sonst lowercased unit.
|
||||
-- Wir migrieren bestehende Einträge damit alte Abhaks gültig bleiben.
|
||||
UPDATE shopping_cart_check SET unit_key = 'weight' WHERE unit_key IN ('g', 'kg');
|
||||
UPDATE shopping_cart_check SET unit_key = 'volume' WHERE unit_key IN ('ml', 'l');
|
||||
|
||||
-- Nach Umetikettierung können Duplikate entstehen (z. B. zwei Einträge mit
|
||||
-- 'weight' für dieselbe Zutat). Deduplizieren: jüngsten behalten.
|
||||
DELETE FROM shopping_cart_check
|
||||
WHERE rowid NOT IN (
|
||||
SELECT MAX(rowid)
|
||||
FROM shopping_cart_check
|
||||
GROUP BY name_key, unit_key
|
||||
);
|
||||
```
|
||||
|
||||
### Code-Änderungen
|
||||
|
||||
- `listShoppingList()`: beim Joinen von `shopping_cart_check` mit den aggregierten
|
||||
Zeilen matched jetzt `(name_key, unit_family_key)` statt `(name_key, unit_key)`.
|
||||
- `toggleCheck(name, unit, checked)`: speichert/löscht Check mit
|
||||
`unitFamily(unit)` statt raw unit.
|
||||
|
||||
## Sektion 3 — Display-Formatter
|
||||
|
||||
### `src/lib/quantity-format.ts`
|
||||
|
||||
```ts
|
||||
export function formatQuantity(q: number | null): string {
|
||||
if (q === null || q === undefined) return '';
|
||||
return q.toLocaleString('de-DE', {
|
||||
maximumFractionDigits: 2,
|
||||
useGrouping: false
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
Kleinere Datei, dieselbe Semantik (max. 2 Dezimalen, ganze Zahlen ohne Dezimal),
|
||||
plus deutsches Dezimalkomma app-weit.
|
||||
|
||||
### Test-Anpassung `tests/unit/quantity-format.test.ts`
|
||||
|
||||
Erwartungswerte von `"0.33"` auf `"0,33"` etc. ziehen. Bestehende 5 Tests müssen mit.
|
||||
|
||||
## Sektion 4 — Tests
|
||||
|
||||
### Neu: `tests/unit/unit-consolidation.test.ts`
|
||||
|
||||
Alle Edge-Cases aus Sektion 1 als expect-Assertions. Plus: `unitFamily`-Table-Tests.
|
||||
|
||||
### Ergänzung: `tests/integration/shopping-repository.test.ts`
|
||||
|
||||
Ein neuer `describe`-Block „konsolidiert über Einheiten":
|
||||
- Rezept A mit `500 g Kartoffeln`, Rezept B mit `1 kg Kartoffeln` → eine Zeile
|
||||
`{name: 'kartoffeln', quantity: 1.5, unit: 'kg'}`.
|
||||
- Analog Volumen mit ml + l.
|
||||
- Gemischte Units wie `2 Bund Petersilie + 1 Bund Petersilie` → eine Zeile `3 Bund`.
|
||||
- `5 Stück Eier + 500 g Eier` → **zwei** Zeilen (verschiedene Families).
|
||||
- Abhaken einer konsolidierten kg-Zeile → nach Entfernung eines Rezepts (jetzt nur
|
||||
noch 800 g) bleibt die Zeile abgehakt (Family = 'weight' stabil).
|
||||
|
||||
### Ergänzung: Migration-Test
|
||||
|
||||
Ein kleiner Test ähnlich dem Stil anderer Migration-Tests im Repo, der verifiziert:
|
||||
- Alt-Einträge `(milch, 'ml')` und `(milch, 'l')` kollabieren zu einem `(milch, 'volume')`.
|
||||
- Unveränderte Einträge wie `(petersilie, 'bund')` bleiben.
|
||||
|
||||
## Was explizit NICHT dabei ist (YAGNI)
|
||||
|
||||
- **Fuzzy-Name-Matching** (Kartoffel vs Kartoffeln, „Zwiebeln, rot" vs „rote Zwiebeln") —
|
||||
ausgeschlossen, hohe Fehlerrate.
|
||||
- **Stück-zu-Gramm-Mappings** (1 Zwiebel ≈ 80 g) — semantisch fraglich, nicht deterministisch.
|
||||
- **TL/EL/Tasse-Konvertierung** — Einkauft man nicht in.
|
||||
- **User-editierbare Custom-Units** — Overkill für eine Familien-PWA.
|
||||
- **UI-Anzeige der zugrundeliegenden Einzelmengen** („1,5 kg — aus 500 g + 1 kg") — wäre
|
||||
nett, aber nicht notwendig für die Hauptfunktion.
|
||||
|
||||
## Phase-Gliederung (für die spätere writing-plans-Phase)
|
||||
|
||||
Eine Phase reicht aus:
|
||||
1. `unit-consolidation.ts` + Unit-Tests
|
||||
2. `quantity-format.ts` auf `toLocaleString` umbauen + Tests updaten
|
||||
3. Migration `015_shopping_check_family.sql`
|
||||
4. `listShoppingList()` integriert Konsolidierung + Check-Join
|
||||
5. `toggleCheck()` auf Family-Key umstellen
|
||||
6. Integration-Tests
|
||||
|
||||
Alles in einer Phase, weil Änderungen eng verzahnt sind (Migration + Repository + Formatter
|
||||
müssen zusammen deployt werden, sonst gibt es UI-Inkonsistenzen).
|
||||
Reference in New Issue
Block a user