docs(19-03): complete global item tag filtering and COALESCE merge plan

.planning/phases/19-reference-item-model-tags-schema/19-03-SUMMARY.md

@@ -0,0 +1,100 @@
+---
+phase: 19-reference-item-model-tags-schema
+plan: 03
+subsystem: api
+tags: [drizzle, postgresql, coalesce, global-items, tags, csv]
+
+requires:
+  - phase: 19-reference-item-model-tags-schema (plan 01)
+    provides: globalItems, tags, globalItemTags schema tables, items.globalItemId FK
+provides:
+  - Tag-filtered global item search with AND intersection logic
+  - COALESCE merge pattern in all secondary services (setup, totals, profile, CSV)
+  - Owner count via direct items.globalItemId FK
+affects: [client-catalog, client-setup-views, client-profile]
+
+tech-stack:
+  added: []
+  patterns: [COALESCE merge for reference item data across all query surfaces]
+
+key-files:
+  created: []
+  modified:
+    - src/server/services/global-item.service.ts
+    - src/server/services/setup.service.ts
+    - src/server/services/totals.service.ts
+    - src/server/services/profile.service.ts
+    - src/server/services/csv.service.ts
+    - src/server/routes/global-items.ts
+    - tests/services/global-item.service.test.ts
+
+key-decisions:
+  - "COALESCE merge pattern propagated to all 4 secondary services consistently"
+
+patterns-established:
+  - "COALESCE merge: all services reading item weight/price LEFT JOIN globalItems and COALESCE when globalItemId is set"
+  - "Tag AND filtering: subquery with GROUP BY HAVING COUNT(DISTINCT) for intersection logic"
+
+requirements-completed: [CATFLOW-04, TAG-01, TAG-02]
+
+duration: 12min
+completed: 2026-04-06
+---
+
+# Phase 19 Plan 03: Global Item Tag Filtering and Secondary Service COALESCE Merge Summary
+
+**Tag-filtered global item search with AND logic, owner count via direct FK, and COALESCE merge propagated to setup/totals/profile/CSV services**
+
+## Performance
+
+- **Duration:** 12 min
+- **Started:** 2026-04-05T22:05:16Z
+- **Completed:** 2026-04-05T22:17:00Z
+- **Tasks:** 2
+- **Files modified:** 7
+
+## Accomplishments
+- Global item search supports tag filtering with AND intersection logic via subquery GROUP BY HAVING
+- Owner count migrated from removed itemGlobalLinks to direct items.globalItemId FK
+- All 4 secondary services (setup, totals, profile, CSV) LEFT JOIN globalItems and COALESCE weight/price/name for reference items
+- Route handlers made async with tag query parameter parsing
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Global item service tag filtering + owner count migration + tests** - `ecc6ac6` (feat) -- pre-existing from wave execution
+2. **Task 2: Secondary service COALESCE merge propagation** - `0a233c7` (feat)
+
+## Files Created/Modified
+- `src/server/services/global-item.service.ts` - Tag-filtered search with ilike and AND logic, owner count via items.globalItemId
+- `src/server/services/setup.service.ts` - COALESCE merge in getAllSetups totals and getSetupWithItems item list
+- `src/server/services/totals.service.ts` - COALESCE merge in getCategoryTotals and getGlobalTotals
+- `src/server/services/profile.service.ts` - COALESCE merge in getPublicProfile totals and getPublicSetupWithItems
+- `src/server/services/csv.service.ts` - COALESCE merge in exportItemsCsv for name/weight/price
+- `src/server/routes/global-items.ts` - Async handlers, tags query param parsing
+- `tests/services/global-item.service.test.ts` - Full async PGlite tests for tag filtering and owner count
+
+## Decisions Made
+- COALESCE merge pattern applied consistently across all 4 secondary services using the same LEFT JOIN + CASE WHEN pattern established in plan 02
+
+## Deviations from Plan
+None - plan executed exactly as written. Task 1 was already completed from a prior execution wave.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Known Stubs
+None - all services fully wired with COALESCE merge pattern.
+
+## Next Phase Readiness
+- All server-side query surfaces now correctly merge global item data for reference items
+- Client components can rely on merged data from all API endpoints
+- Ready for client-side catalog and discovery UI work
+
+---
+*Phase: 19-reference-item-model-tags-schema*
+*Completed: 2026-04-06*