chore: archive v2.3 milestone files

Archive setup sharing, currency system, and i18n foundation milestone. Reorganize ROADMAP.md with v2.3 details block, update PROJECT.md, MILESTONES.md, STATE.md deferred items, and RETROSPECTIVE.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-19 17:05:21 +02:00
parent beaea46e92
commit 1733fe8cfb
7 changed files with 305 additions and 28 deletions
--- a/.planning/milestones/v2.3-REQUIREMENTS.md
+++ b/.planning/milestones/v2.3-REQUIREMENTS.md
@@ -0,0 +1,78 @@
+# Requirements Archive: GearBox v2.3 Global & Social Ready
+
+**Archived:** 2026-04-19
+**Milestone shipped:** v2.3
+
+> Note: The active REQUIREMENTS.md at close was scoped to v2.1 Public Discovery requirements (all complete).
+> v2.3-specific requirements (sharing, currency, i18n) were tracked as decisions in STATE.md and active items in PROJECT.md.
+
+---
+
+# Requirements: GearBox v2.1 Public Discovery
+
+**Defined:** 2026-04-09
+**Core Value:** Help people make better gear decisions — discover what others use, compare real-world data, and see how a potential buy affects your setup before committing.
+
+## v2.1 Requirements
+
+### Public Access
+
+- [x] **PUBL-01**: User can browse the global item catalog without logging in
+- [x] **PUBL-02**: User can view public setups without logging in
+- [x] **PUBL-03**: User can view user profiles without logging in
+- [x] **PUBL-04**: Anonymous visitors see the landing page without auth spinner or redirect
+- [x] **PUBL-05**: Login is only required when user attempts to create/edit/delete their own data
+
+### Discovery
+
+- [x] **DISC-01**: Landing page displays an always-visible catalog search bar at the top
+- [x] **DISC-02**: Landing page shows a feed of popular setups below the search
+- [x] **DISC-03**: Landing page shows recently added catalog items
+- [x] **DISC-04**: Landing page shows trending categories
+- [x] **DISC-05**: Authenticated users see a "Go to Collection" entry point from the landing page
+
+### Catalog Enrichment
+
+- [x] **CATL-01**: Global items have attribution fields (sourceUrl, manufacturer, imageCredit, imageSourceUrl)
+- [x] **CATL-02**: Global items have a unique constraint on (brand, model) preventing duplicates
+- [x] **CATL-03**: Catalog detail pages display image attribution with credit and source link
+- [x] **CATL-04**: Bulk import API endpoint accepts multiple catalog items in one request
+- [x] **CATL-05**: Bulk import uses upsert semantics (ON CONFLICT update, not fail)
+
+### Agent Seeding Tools
+
+- [x] **SEED-01**: MCP server has a dedicated `upsert_catalog_item` tool that writes to globalItems (not user-scoped)
+- [x] **SEED-02**: MCP server has a `bulk_upsert_catalog` tool for batch catalog population
+- [x] **SEED-03**: Catalog MCP tools include attribution fields (sourceUrl, manufacturer, imageCredit) as parameters
+
+### Infrastructure
+
+- [x] **INFR-01**: Public API endpoints are rate-limited to prevent abuse
+- [x] **INFR-02**: Discovery feed endpoint uses cursor pagination for scalability
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| PUBL-01 | Phase 24 | Complete |
+| PUBL-02 | Phase 24 | Complete |
+| PUBL-03 | Phase 24 | Complete |
+| PUBL-04 | Phase 24 | Complete |
+| PUBL-05 | Phase 24 | Complete |
+| INFR-01 | Phase 24 | Complete |
+| CATL-01 | Phase 25 | Complete |
+| CATL-02 | Phase 25 | Complete |
+| CATL-03 | Phase 25 | Complete |
+| CATL-04 | Phase 25 | Complete |
+| CATL-05 | Phase 25 | Complete |
+| SEED-01 | Phase 25 | Complete |
+| SEED-02 | Phase 25 | Complete |
+| SEED-03 | Phase 25 | Complete |
+| DISC-01 | Phase 26 | Complete |
+| DISC-02 | Phase 26 | Complete |
+| DISC-03 | Phase 26 | Complete |
+| DISC-04 | Phase 26 | Complete |
+| DISC-05 | Phase 26 | Complete |
+| INFR-02 | Phase 26 | Complete |
+
+**Coverage:** 20/20 v2.1 requirements complete.
--- a/.planning/milestones/v2.3-ROADMAP.md
+++ b/.planning/milestones/v2.3-ROADMAP.md
@@ -0,0 +1,111 @@
+# Milestone v2.3: Global & Social Ready
+
+**Status:** ✅ SHIPPED 2026-04-19
+**Phases:** 32-34
+**Total Plans:** 18
+
+## Overview
+
+Made GearBox work for a global audience. Setup sharing with fine-grained visibility control, a full multi-currency pricing system with ECB exchange rates and community price aggregation, and an i18n foundation with English + German translations — all delivered in 6 days across 3 phases and 18 plans.
+
+## Phases
+
+### Phase 32: Setup Sharing System
+
+**Goal**: Setup owners can toggle visibility between private, link-shared, and public, with schema designed for future likes, friends, and collaborative editing
+**Depends on**: Phase 28 (profiles working)
+**Plans**: 4 plans
+
+Plans:
+- [x] 32-01-PLAN.md — Schema migration (isPublic to visibility) + shares table + full-stack update
+- [x] 32-02-PLAN.md — Share link service, API routes, and short URL redirect
+- [x] 32-03-PLAN.md — Share modal UI component with visibility picker and link management
+- [x] 32-04-PLAN.md — Shared setup viewer with token detection and read-only mode
+
+**Details:**
+- `visibility` text column (private/link/public) replaces `isPublic` boolean on setups table
+- `shares` table with token, permission, expiresAt, userId, revokedAt — schema future-proofed for person-specific shares and write permissions
+- Share tokens use randomBytes(16).toString("base64url") — 128-bit entropy, URL-safe
+- Visibility→private deactivates share links; switching back reactivates non-expired ones
+- `/s/:token` short URL redirects to `/setups/:id?share=token`; `/api/shared/:token` returns setup data without auth
+- ShareModal replaces old globe toggle — Google Docs-style with visibility picker + link management
+- Three-way data source in setup detail page: share token > authenticated owner > public viewer
+
+### Phase 33: Currency System
+
+**Goal**: Users can select their preferred currency (USD/EUR/GBP) and all prices display accordingly — full market-aware pricing system with community price data
+**Depends on**: Phase 32
+**Plans**: 6 plans
+
+Plans:
+- [x] 33-01-PLAN.md — Schema (market_prices, community_prices tables) + currency conversion service
+- [x] 33-02-PLAN.md — Database migration generation and push
+- [x] 33-03-PLAN.md — Market prices API, exchange rates endpoint, item/candidate currency context
+- [x] 33-04-PLAN.md — Community price service (ownership validation, median aggregation) + setup totals
+- [x] 33-05-PLAN.md — Formatter evolution, market/currency selector, auto-suggestion, conversion toggle
+- [x] 33-06-PLAN.md — Catalog detail market prices, comparison table normalization, MCP tool updates
+
+**Details:**
+- `market_prices` and `community_prices` tables with unique constraints
+- `priceCurrency` column on items; `foundPriceCents/Currency/Date` on thread_candidates
+- Exchange rates fetched daily from ECB via frankfurter.app with 24h module-level cache
+- Community price aggregation: PERCENTILE_CONT(0.5) median with 3-report minimum, ownership-validated submissions
+- Converted prices labeled with ~ prefix and dual display format
+- `CurrencyContext` interface (currency, market, showConversions) from `useCurrency()`
+- Market-aware MSRP section on catalog detail page with collapsible "Other Markets"
+
+### Phase 34: i18n Foundation
+
+**Goal**: Translation framework in place with string extraction, locale-aware formatting, and at least English + one additional language
+**Depends on**: Phase 33
+**Plans**: 8 plans
+
+Plans:
+- [x] 34-01-PLAN.md — i18next + react-i18next setup, English namespace JSON files
+- [x] 34-02-PLAN.md — German translations for all 6 namespaces
+- [x] 34-03-PLAN.md — Component wiring (collection, threads, setups namespaces)
+- [x] 34-04-PLAN.md — Settings and onboarding namespace wiring
+- [x] 34-05-PLAN.md — Language picker component in settings
+- [x] 34-06-PLAN.md — Locale-aware formatting (dates, numbers)
+- [x] 34-07-PLAN.md — catalog namespace for global-items/discover page
+- [x] 34-08-PLAN.md — Final wiring and verification
+
+**Details:**
+- react-i18next with i18next-browser-languagedetector
+- 6 namespaces: common, collection, threads, setups, onboarding, settings (+ catalog added in 34-07)
+- Detection order: localStorage (key: gearbox-language) then navigator.language
+- Static lookup tables (icons, CSS) kept at module level; only label strings moved inside components for t() access
+- English + German locales, language picker in settings
+
+---
+
+## Milestone Summary
+
+**Key Decisions:**
+- isPublic boolean replaced with visibility text column (private/link/public) — RESOLVED
+- shares table future-proofed for person-specific shares and write permissions — RESOLVED
+- Share tokens: randomBytes(16).toString("base64url") — 128-bit entropy, URL-safe — RESOLVED
+- Visibility→private deactivates share links; switching back reactivates non-expired ones — RESOLVED
+- EUR as default price currency matching existing data assumption — RESOLVED
+- Module-level caching for exchange rates (simple, effective for single-process) — RESOLVED
+- Community price aggregation uses PERCENTILE_CONT(0.5) with 3-report minimum — RESOLVED
+- Detection order for locale: localStorage first, then navigator.language — RESOLVED
+- defaultNS is common; escapeValue: false (React handles XSS) — RESOLVED
+
+**Issues Resolved:**
+- isPublic boolean → visibility text migration handled with data migration SQL
+- Dynamic import in setup.service.ts to avoid circular dependency with share.service.ts
+
+**Issues Deferred:**
+- ComparisonTable currency normalization (hooks available, deferred pending real multi-currency test data)
+- MCP tool currency updates (existing priceCents responses work with currency context client-side)
+- E2E tests rewrite for OIDC auth (backlog 999.1)
+
+**Technical Debt Incurred:**
+- 6 pending todos deferred to v2.4 (cursor pointers, image loading, auth redirect, add-candidate modal)
+
+**Known deferred items at close:** 6 (see STATE.md Deferred Items)
+
+---
+
+_For current project status, see .planning/ROADMAP.md_