From 59deaea95a090647ec8843779b65dbdabf5f33d3 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sun, 5 Apr 2026 20:51:26 +0200 Subject: [PATCH] docs(19-02): complete item and thread service COALESCE merge plan - SUMMARY.md with task commits, decisions, and verification results - STATE.md updated with position, progress, and decisions - ROADMAP.md updated with plan progress --- .planning/ROADMAP.md | 8 +- .planning/STATE.md | 23 ++-- .../19-02-SUMMARY.md | 101 ++++++++++++++++++ 3 files changed, 117 insertions(+), 15 deletions(-) create mode 100644 .planning/phases/19-reference-item-model-tags-schema/19-02-SUMMARY.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index da6bd1f..7b0ecc4 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -184,10 +184,10 @@ 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:** 3 plans +**Plans:** 2/3 plans executed Plans: -- [ ] 19-01-PLAN.md — Schema, migration, Zod schemas, types, seed script -- [ ] 19-02-PLAN.md — Item service COALESCE merge, thread resolution, route cleanup +- [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 ### Phase 20: FAB & Full-Screen Catalog Search @@ -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 | 0/3 | Not started | - | +| 19. Reference Item Model & Tags Schema | v2.0 | 2/3 | In Progress| | | 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 7e46721..7da072c 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,16 +2,16 @@ gsd_state_version: 1.0 milestone: v1.3 milestone_name: Research & Decision Tools -status: planning -stopped_at: Completed 19-01-PLAN.md -last_updated: "2026-04-05T11:22:25.312Z" +status: executing +stopped_at: Completed 19-02-PLAN.md +last_updated: "2026-04-05T18:51:11.895Z" last_activity: 2026-04-05 progress: - total_phases: 12 + total_phases: 13 completed_phases: 11 - total_plans: 33 - completed_plans: 31 - percent: 0 + total_plans: 36 + completed_plans: 33 + percent: 3 --- # Project State @@ -26,8 +26,8 @@ See: .planning/PROJECT.md (updated 2026-04-03) ## Current Position Phase: 19 of 19 (Reference Item Model & Tags Schema) -Plan: 1 of 3 -Status: Executing +Plan: 2 of 3 +Status: Ready to execute Last activity: 2026-04-05 Progress: [#---------] 3% (v2.0 milestone) @@ -58,6 +58,7 @@ Key decisions made during v2.0 planning: - [Phase 19]: Direct globalItemId FK on items replaces itemGlobalLinks junction table - [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 ### Pending Todos @@ -70,6 +71,6 @@ None active. ## Session Continuity -Last session: 2026-04-05T18:28:00Z -Stopped at: Completed 19-01-PLAN.md +Last session: 2026-04-05T18:51:11.893Z +Stopped at: Completed 19-02-PLAN.md Resume file: None diff --git a/.planning/phases/19-reference-item-model-tags-schema/19-02-SUMMARY.md b/.planning/phases/19-reference-item-model-tags-schema/19-02-SUMMARY.md new file mode 100644 index 0000000..c557641 --- /dev/null +++ b/.planning/phases/19-reference-item-model-tags-schema/19-02-SUMMARY.md @@ -0,0 +1,101 @@ +--- +phase: 19-reference-item-model-tags-schema +plan: 02 +subsystem: services +tags: [item-service, thread-service, coalesce, reference-items, catalog-link] + +requires: + - phase: 19-reference-item-model-tags-schema + plan: 01 + provides: globalItemId FK on items and threadCandidates, tags tables +provides: + - COALESCE merge pattern in item service for transparent reference item data + - Branched thread resolution (reference vs standalone items) + - Catalog-linked candidates with merged global item display data + - Cleaned items route without link/unlink endpoints +affects: [19-03, client-hooks, mcp-tools] + +tech-stack: + added: [] + patterns: + - "COALESCE merge: LEFT JOIN globalItems with CASE WHEN for name, weight, price, image" + - "Branched resolution: candidate.globalItemId determines reference vs standalone item creation" + +key-files: + created: [] + modified: + - src/server/services/item.service.ts + - src/server/services/thread.service.ts + - src/server/routes/items.ts + - tests/services/item.service.test.ts + - tests/services/thread.service.test.ts + +key-decisions: + - "COALESCE with CASE WHEN pattern ensures standalone items are unaffected by globalItems JOIN" + - "Reference item resolution omits weight/price/productUrl - those come from global item via COALESCE on read" + - "Image fallback: item's own imageFilename takes precedence, global imageUrl used as fallback" + +patterns-established: + - "Reference items: service layer transparently merges global data via SQL COALESCE, clients see unified shape" + - "Branched resolution: resolveThread checks candidate.globalItemId to determine item creation strategy" + +requirements-completed: [CATFLOW-03, CATFLOW-04, CATFLOW-05, CATFLOW-06] + +duration: 8min +completed: 2026-04-05 +--- + +# Phase 19 Plan 02: Item & Thread Service COALESCE Merge Summary + +**COALESCE merge pattern in item/thread services for transparent reference item data, branched thread resolution, and link/unlink endpoint removal** + +## Performance + +- **Duration:** 8 min +- **Started:** 2026-04-05T18:31:23Z +- **Completed:** 2026-04-05T18:39:00Z +- **Tasks:** 2 +- **Files modified:** 5 + +## Accomplishments + +- Item service getAllItems and getItemById use LEFT JOIN + COALESCE to transparently merge global item data for reference items +- createItem accepts globalItemId, looks up global item for brand+model fallback name (items.name is NOT NULL) +- duplicateItem preserves globalItemId and purchasePriceCents from source +- Thread service getThreadWithCandidates merges global item data for catalog-linked candidates +- createCandidate stores globalItemId on candidate row +- resolveThread branches: reference items get globalItemId set with no weight/price copy; standalone items get full data copy +- Removed link/unlink endpoints from items route (replaced by direct globalItemId FK) + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Item service COALESCE merge + reference item creation + tests** - `d1ffd79` (feat) +2. **Task 2: Thread service candidate globalItemId + branched resolution + route cleanup + tests** - `8a5ee73` (feat) + +## Files Created/Modified + +- `src/server/services/item.service.ts` - LEFT JOIN globalItems with COALESCE in getAllItems/getItemById, globalItemId in createItem/duplicateItem/updateItem +- `src/server/services/thread.service.ts` - LEFT JOIN globalItems in getThreadWithCandidates, globalItemId in createCandidate, branched resolveThread +- `src/server/routes/items.ts` - Removed link/unlink endpoints and imports of linkItemToGlobal, unlinkItemFromGlobal, linkItemSchema +- `tests/services/item.service.test.ts` - 10 new tests for reference item creation, merged data retrieval, purchasePriceCents +- `tests/services/thread.service.test.ts` - 6 new tests for catalog-linked candidates and branched resolution + +## Decisions Made + +- Used COALESCE with CASE WHEN pattern (not simple COALESCE) to ensure standalone items are completely unaffected by the LEFT JOIN +- Reference item resolution intentionally omits weight, price, and productUrl from the insert - those come from the global item via COALESCE on read +- Image fallback order: item's own imageFilename first, global item's imageUrl second (user uploads override catalog images) + +## Deviations from Plan + +None - plan executed exactly as written. + +## Known Stubs + +None - all data paths are fully wired. + +--- +*Phase: 19-reference-item-model-tags-schema* +*Completed: 2026-04-05*