From 1b7b005c837c39b10ecb70262e422027a7464b15 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Mon, 6 Apr 2026 00:27:14 +0200 Subject: [PATCH] docs(19-03): complete global item tag filtering and COALESCE merge plan --- .planning/REQUIREMENTS.md | 12 +-- .planning/ROADMAP.md | 8 +- .planning/STATE.md | 15 +-- .../19-03-SUMMARY.md | 100 ++++++++++++++++++ 4 files changed, 118 insertions(+), 17 deletions(-) create mode 100644 .planning/phases/19-reference-item-model-tags-schema/19-03-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index faf877e..df1eeea 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -52,7 +52,7 @@ Requirements for this milestone. Each maps to roadmap phases. - [ ] **CATFLOW-01**: FAB shows mini menu with "Add to Collection" and "Start Thread" globally, plus "New Setup" on setups page - [ ] **CATFLOW-02**: Full-screen catalog search with tag chip filtering - [ ] **CATFLOW-03**: User can add a catalog item to collection as a reference item with personal fields (category, notes, purchase price, image, quantity) -- [ ] **CATFLOW-04**: Collection items referencing global items display merged data (global base + personal overlay) +- [x] **CATFLOW-04**: Collection items referencing global items display merged data (global base + personal overlay) - [ ] **CATFLOW-05**: Thread candidates can be added from catalog with global item link - [ ] **CATFLOW-06**: Thread resolution with catalog-linked candidate creates reference item with auto-link - [ ] **CATFLOW-07**: Manual entry fallback when item not in catalog @@ -60,8 +60,8 @@ Requirements for this milestone. Each maps to roadmap phases. ### Tags -- [ ] **TAG-01**: Tags table seeded with curated tag set for outdoor/adventure gear -- [ ] **TAG-02**: Global items have multiple tags, searchable and filterable via API +- [x] **TAG-01**: Tags table seeded with curated tag set for outdoor/adventure gear +- [x] **TAG-02**: Global items have multiple tags, searchable and filterable via API ### User Profiles & Sharing @@ -166,13 +166,13 @@ Which phases cover which requirements. Updated during roadmap creation. | CATFLOW-01 | Phase 20 | Pending | | CATFLOW-02 | Phase 20 | Pending | | CATFLOW-03 | Phase 19, 21 | Pending | -| CATFLOW-04 | Phase 19 | Pending | +| CATFLOW-04 | Phase 19 | Complete | | CATFLOW-05 | Phase 19, 21 | Pending | | CATFLOW-06 | Phase 19, 21 | Pending | | CATFLOW-07 | Phase 22 | Pending | | CATFLOW-08 | Phase 22 | Pending | -| TAG-01 | Phase 19 | Pending | -| TAG-02 | Phase 19 | Pending | +| TAG-01 | Phase 19 | Complete | +| TAG-02 | Phase 19 | Complete | **Coverage:** - v2.0 requirements: 40 total diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 7b0ecc4..fffe0b9 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -55,7 +55,7 @@ - [ ] **Phase 16: Multi-User Data Model** — Add user ownership to all entities with cross-user data isolation - [ ] **Phase 17: Object Storage** — Move images from local filesystem to MinIO (S3-compatible) - [x] **Phase 18: Global Items & Public Profiles** — Global item catalog, user profiles, and public setup sharing (completed 2026-04-05) -- [ ] **Phase 19: Reference Item Model & Tags Schema** — Collection items as references to global catalog, tag system for discovery +- [x] **Phase 19: Reference Item Model & Tags Schema** — Collection items as references to global catalog, tag system for discovery (completed 2026-04-05) - [ ] **Phase 20: FAB & Full-Screen Catalog Search** — Global FAB with mini menu, full-screen catalog search with tag filtering - [ ] **Phase 21: Add-from-Catalog & Thread Integration** — Add catalog items to collection and threads, resolution creates reference items - [ ] **Phase 22: Manual Entry Fallback** — Manual add for items not in catalog, non-functional submission prompt @@ -184,11 +184,11 @@ Plans: 2. Global items can have multiple tags, searchable via API 3. Thread candidates can link to a global item via globalItemId 4. Resolving a thread with a catalog-linked candidate creates a reference item with auto-link -**Plans:** 2/3 plans executed +**Plans:** 3/3 plans complete Plans: - [x] 19-01-PLAN.md — Schema, migration, Zod schemas, types, seed script - [x] 19-02-PLAN.md — Item service COALESCE merge, thread resolution, route cleanup -- [ ] 19-03-PLAN.md — Global item tag filtering, secondary service merge propagation +- [x] 19-03-PLAN.md — Global item tag filtering, secondary service merge propagation ### Phase 20: FAB & Full-Screen Catalog Search **Goal**: Users discover and add gear through a catalog-first search experience with tag filtering @@ -247,7 +247,7 @@ Plans: | 16. Multi-User Data Model | v2.0 | 0/? | Not started | - | | 17. Object Storage | v2.0 | 0/? | Not started | - | | 18. Global Items & Public Profiles | v2.0 | 4/5 | Complete | 2026-04-05 | -| 19. Reference Item Model & Tags Schema | v2.0 | 2/3 | In Progress| | +| 19. Reference Item Model & Tags Schema | v2.0 | 3/3 | Complete | 2026-04-05 | | 20. FAB & Full-Screen Catalog Search | v2.0 | 0/? | Not started | - | | 21. Add-from-Catalog & Thread Integration | v2.0 | 0/? | Not started | - | | 22. Manual Entry Fallback | v2.0 | 0/? | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 7da072c..7d2e852 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,14 +3,14 @@ gsd_state_version: 1.0 milestone: v1.3 milestone_name: Research & Decision Tools status: executing -stopped_at: Completed 19-02-PLAN.md -last_updated: "2026-04-05T18:51:11.895Z" +stopped_at: Completed 19-03-PLAN.md +last_updated: "2026-04-05T22:27:05.589Z" last_activity: 2026-04-05 progress: total_phases: 13 - completed_phases: 11 + completed_phases: 12 total_plans: 36 - completed_plans: 33 + completed_plans: 34 percent: 3 --- @@ -26,7 +26,7 @@ See: .planning/PROJECT.md (updated 2026-04-03) ## Current Position Phase: 19 of 19 (Reference Item Model & Tags Schema) -Plan: 2 of 3 +Plan: 3 of 3 Status: Ready to execute Last activity: 2026-04-05 @@ -59,6 +59,7 @@ Key decisions made during v2.0 planning: - [Phase 19]: Data migration SQL: UPDATE items before DROP TABLE item_global_links - [Phase 19]: Flat tags system without type categorization per D-16 - [Phase 19-reference-item-model-tags-schema]: COALESCE merge pattern for transparent reference item data in item/thread services +- [Phase 19-reference-item-model-tags-schema]: COALESCE merge pattern propagated to all secondary services (setup, totals, profile, CSV) ### Pending Todos @@ -71,6 +72,6 @@ None active. ## Session Continuity -Last session: 2026-04-05T18:51:11.893Z -Stopped at: Completed 19-02-PLAN.md +Last session: 2026-04-05T22:27:05.587Z +Stopped at: Completed 19-03-PLAN.md Resume file: None diff --git a/.planning/phases/19-reference-item-model-tags-schema/19-03-SUMMARY.md b/.planning/phases/19-reference-item-model-tags-schema/19-03-SUMMARY.md new file mode 100644 index 0000000..1ef33bb --- /dev/null +++ b/.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*