collective-lists/docs/history/fase-15-common-items.md

# Fase 15 — Common items management (weighted suggestions + exclude-on-list)

**MVP2 · 7/7. Re-opened the cycle after Fase 14 with two concrete asks on the "add item" flow.**

**Status: ✅ Shipped 2026-05-18.**

Two user-driven additions on top of the existing `item_frequency` table from migration 006:

1. **Promote items** — admins can boost specific names so they always lead the suggestion strip, regardless of historical `use_count`.
2. **Hide items already on the list** — the dropdown no longer nudges the user to re-add names that are already present in the active list.

Plan: `plan/fase-15-common-items.md`. Migration: `supabase/migrations/026_item_frequency_weight.sql`. pgTAP: `supabase/tests/018_item_frequency_weight.sql`.

## What changed

### 15.1 — `item_frequency.weight` + admin RPCs

- `weight integer NOT NULL DEFAULT 0` added to `item_frequency`. No CHECK constraint — the column stays open so future tiers ("strong boost", "soft hide") don't force another schema diff. The UI is the contract for the 3-way mapping, not the DB.
- `item_frequency_collective_count_idx` dropped, replaced by `item_frequency_collective_order_idx (collective_id, weight DESC, use_count DESC, last_used_at DESC)` so the suggestion query scans in order without a sort step.
- Two SECURITY DEFINER RPCs gate writes:
  - `public.set_item_frequency_weight(p_collective_id uuid, p_name text, p_weight integer)` — upsert: if the row doesn't exist, inserts with `use_count = 0`; if it does, sets `weight`. Raises `P0002` for non-admins, `P0001` for unauthenticated / empty name.
  - `public.purge_item_frequency(p_collective_id uuid, p_name text)` — deletes the row from `item_frequency` only. Does NOT touch `shopping_items` (the modal copy explicitly says this; existing items on lists are unaffected). The next time someone adds that name to a list, the existing trigger recreates the row with `weight = 0`.
- The deny-all INSERT/UPDATE/DELETE policies from migration 006 are preserved; the RPCs are the only write path. Both `GRANT EXECUTE ... TO authenticated` so PostgREST will call them.

### 15.2 — Store + query

- `fetchSuggestions(collectiveId, prefix, options?)` in `apps/web/src/lib/stores/lists.ts` extended with `{ excludeNames?: string[]; limit?: number }`. Ordering switches from `.order('use_count')` to `weight DESC, use_count DESC, last_used_at DESC`. `excludeNames` is lowercased + trimmed + deduped before being sent; when empty, the `.not()` filter is skipped entirely (PostgREST renders an empty `(...)` list as a SQL error, and zero entries would mean zero effect anyway). When the list exceeds `EXCLUDE_NAMES_HARD_CAP = 200`, the filter degrades to a no-op rather than fail the whole query — past that point we'd risk hitting Kong's ~16 KiB request URI cap (see "Gotchas" below).
- New `apps/web/src/lib/stores/commonItems.ts` is the unbounded counterpart used by the manage view: `loadCommonItems` (full catalogue, same ordering, no `LIMIT`), `setWeight` (RPC + optimistic in-store update), `purge` (RPC + optimistic remove).

### 15.3 — Manage UI

`apps/web/src/routes/(app)/collective/manage/+page.svelte` gains a new "Common items" subsection visible to admins + members (guests see nothing):

- Table per row: name, last_used + use_count blurb, a 3-way **Hide / Normal / Boost** segmented control that writes `weight = -50 / 0 / 50`, a small "Remove" button that opens a confirmation modal explaining "items already in lists are not touched".
- Members see the same table but every action button is disabled with a tooltip "Only admins can manage common items".
- "Add common item" button (admin only) — opens a modal with a name input + the same 3-way control, defaulting to **Boost**. Useful for seeding the catalogue before lists actually mention an item.
- Client-side substring search filters the table; empty / filtered-empty states have their own copy.
- `data-weight-state` attribute on each `<li>` exposes the current visual state to the e2e suite so the segmented control is testable without scraping classnames.
- The segmented control is a row of three `<button>` elements — visually distinct from the existing section-visibility toggles (which are `<input type="checkbox">`), so there's no ambiguity at a glance.

### 15.4 — Exclude-on-list wiring

`apps/web/src/routes/(app)/lists/[id]/+page.svelte`:

- New `excludedItemNames = $derived(items.map((i) => i.name))` recomputes the moment an optimistic insert lands.
- Both the cold-load `fetchSuggestions` call and the keystroke-debounced `updateSuggestions` now pass `{ excludeNames: ... }`. The `$effect` reads the `$derived` directly so adding an item to the list drops it from the strip on the next keystroke.

`apps/web/src/lib/components/ItemSuggestions.svelte`:

- Added `data-testid="item-suggestions-strip"` on the container + `data-testid="item-suggestion-{name}"` on each chip so the e2e suite can address them without fragile text matching.
- The component still hides itself entirely when `suggestions.length === 0` — the dropdown was already gated on the array being non-empty, so 15.4.3 ("don't show the dropdown when the post-filter result is empty") needed no new code.

### 15.5 — Tests

- pgTAP `supabase/tests/018_item_frequency_weight.sql` — 11 schema-level assertions on the new column, the recreated index, both RPCs, the SECURITY DEFINER posture, and the trigger-default-weight-zero behaviour.
- Vitest integration `packages/test-utils/tests/common-items.test.ts` — 6 specs covering admin-boost-promotes-low-use-count ordering, the `excludeNames` filter, the role gate (admin OK / member + guest get `P0002`), purge happy + denied path, and `set_item_frequency_weight` on a brand-new name inserting `use_count = 0`.
- Playwright `apps/web/tests/e2e/common-items.test.ts` — 4 specs: CI-01 (Ana boosts yogurt → it leads the dropdown ahead of higher-use-count items on a fresh empty list), CI-02 (added item disappears from the suggestion strip on the next keystroke, using fresh seeded names on a fresh list to dodge the dev-DB pollution), CI-03 (Borja sees the table, every action disabled, "Add common item" hidden), CI-04 (Ana purges → row gone from the table). Cleanup uses the admin purge RPC because the deny-all RLS from migration 006 blocks direct `DELETE` from authenticated browser sessions.

## Test deltas (Fase 15 only)

| Suite | Before | After | Δ |
|---|---|---|---|
| pgTAP (`just test-db`) | 166 | 177 | +11 (IFW-T01..T11) |
| Vitest integration (`just test-integration`) | 173 passed + 3 skipped | 179 + 3 skipped | +6 (CI-INT-01..06) |
| Vitest unit (`just test-unit`) | 47 | 47 | 0 (the plan flagged "probably no" for a client-side ordering unit test; the server `ORDER BY` is the only ordering path) |
| Playwright e2e (`just test-e2e`) | 89 | 93 | +4 (CI-01..04) |
| Gated rate-limit | 1 | 1 | 0 |

**Cumulative MVP2 + Fase 15: 497 tests + 3 skipped (177 pgTAP + 179 Vitest integration + 47 Vitest unit + 93 Playwright + 1 gated).**

All green modulo the pre-existing realtime flakes (R-E-01/02, RO-02, SV-02, TG-01) which are sensitive to dev-DB pollution but unrelated to this fase.

## Gotchas surfaced

- **Direct `DELETE FROM item_frequency` from the browser is denied by RLS.** The all-deny INSERT/UPDATE/DELETE policies from migration 006 stayed in place — the admin purge RPC is the only delete path. Tests that try to clean up via `supabase.from('item_frequency').delete().eq(...)` silently no-op (PostgREST returns 200 with empty data). The e2e suite goes through `supabase.rpc('purge_item_frequency', ...)` for all cleanup; an early version of the suite leaked rows because of this.
- **`fetchSuggestions` URL can exceed Kong's ~16 KiB request-URI cap.** A polluted seed list with 300+ items + the literal `not.in.("a","b",…)` PostgREST encoding pushed the URL over the limit, which froze the query and broke the realtime + reorder + section-visibility tests (all of which load the seed list in two browser contexts). Hard-cap at 200 names; past that the filter degrades to a no-op (the dropdown may surface a few names already on the list — acceptable UX, never a 500). For a future RPC-backed `LEFT JOIN ... WHERE shopping_items.id IS NULL` form, see the plan's "Riesgos / notas" section.
- **`set_item_frequency_weight` on a brand-new name inserts with `use_count = 0`.** The trigger fn from migration 006 only fires on `shopping_items` INSERT; it never sees an admin's curation-only seed. The upsert in the RPC has `use_count = 0` in its INSERT branch and only updates `weight` in the ON CONFLICT branch — that way a real `shopping_items` add later will increment the existing row's `use_count` from 0 to 1 without clobbering the admin-set weight.
- **The seeded `auth.users.role` migration trigger from 013 / 014 has nothing to do with this fase**, but the integration tests still need fresh JWTs whenever they're re-run after a schema-changing migration — covered by the existing per-test `await createClientAs(...)` flow.

## Deviations from plan

- The plan flagged a possible Vitest unit test for client-side ordering (15.5.1). Server `ORDER BY` is the only ordering path; no client-side ordering exists; the unit test was skipped per the plan's own "probably no".
- `EXCLUDE_NAMES_HARD_CAP = 200` was not in the original plan — added as a hot-fix after the full `just test-all` surfaced URL-length flakes in the realtime / reorder tests on the polluted dev DB. The plan's "Riesgos" section did acknowledge "para >>100 reconsiderar a un LEFT JOIN ... WHERE shopping_items.id IS NULL vía RPC"; the hard cap is the lighter-weight intermediate step.
- D-06 (existing items.test.ts) had to be re-pointed at a freshly-created empty list because the seed list pollution + new exclude-on-list filter together suppressed every assertion target. Same applies to CI-01 and CI-02 in the new e2e file.

## Out of scope (still)

- Import/export of common items between collectives.
- Tag suggestions per category.
- Server-wide common items (cross-collective).
- ML / cross-collective recommendations.
- Pre-assigned tags on promoted items.
- The audit table for "who promoted what" (`item_frequency` has no `created_by`; the trigger that owns inserts is SECURITY DEFINER).