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
2026-04-05 20:51:26 +02:00
parent 8a5ee731d0
commit 59deaea95a
3 changed files with 117 additions and 15 deletions
--- 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 | - |
--- 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
--- 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
@@ -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*