From 4548780e5f4692384327926792595ff663998af9 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sun, 19 Apr 2026 18:40:49 +0200 Subject: [PATCH] docs: start milestone v2.4 Admin Foundation Co-Authored-By: Claude Sonnet 4.6 --- .planning/PROJECT.md | 26 +++++++-- .planning/REQUIREMENTS.md | 95 +++++++++++++++++++++++++++++++++ .planning/STATE.md | 109 ++++++++++++++------------------------ 3 files changed, 156 insertions(+), 74 deletions(-) create mode 100644 .planning/REQUIREMENTS.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index 24fdadb..4587c1a 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -8,6 +8,14 @@ A gear management and discovery platform. Users catalog their gear collections ( 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. +## Current Milestone: v2.4 Admin Foundation + +**Goal:** Clear the v2.3 bug backlog and ship a catalog admin panel as the foundation for managing global catalog content in future milestones. + +**Target features:** +- Bug fixes: wrong add-candidate modal, missing item images on collection overview, slow image loading, auth prompt direct Logto redirect, cursor-pointer on all clickable elements +- Catalog admin panel: admin-gated route, global item management (browse/edit/delete), tag management (create/rename/parent-child hierarchy/delete), admin role flag on users + ## Requirements ### Validated @@ -72,14 +80,22 @@ Help people make better gear decisions — discover what others use, compare rea - ✓ Community price aggregation: ownership-validated submissions, median with 3-report minimum, market-aware MSRP on catalog detail — v2.3 - ✓ i18n foundation: react-i18next, 7 namespaces, English + German translations, language picker, locale-aware formatting — v2.3 -### Active +### Active (v2.4) -- [ ] Freeform reviews with moderation system -- [ ] Comments on setups -- [ ] Follow users / activity feeds +- [ ] Fix wrong modal on Add Candidate button (thread page) — v2.4 +- [ ] Fix item images not showing on collection overview — v2.4 +- [ ] Resolve slow image loading — v2.4 +- [ ] Auth prompt sign-in redirects directly to Logto — v2.4 +- [ ] Cursor pointer on all clickable/interactive elements — v2.4 +- [ ] Admin role flag on users table — v2.4 +- [ ] Admin-gated /admin panel route — v2.4 +- [ ] Admin: browse/edit/delete global catalog items — v2.4 +- [ ] Admin: create/rename/delete tags with parent-child hierarchy — v2.4 ### Future +- [ ] Tag-based spec schemas on global items (key/value typed specs per category, sub-tag hierarchy) — v2.5 +- [ ] Global item engagement stats (view count, likes/saves, setup appearances) — v2.5 - [ ] Freeform reviews with moderation system - [ ] Comments on setups - [ ] Follow users / activity feeds @@ -188,4 +204,4 @@ This document evolves at phase transitions and milestone boundaries. 4. Update Context with current state --- -*Last updated: 2026-04-19 after v2.3 milestone — Global & Social Ready* +*Last updated: 2026-04-19 after v2.4 milestone start — Admin Foundation* diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 0000000..4779c27 --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,95 @@ +# Requirements: GearBox v2.4 + +**Defined:** 2026-04-19 +**Milestone:** v2.4 Admin Foundation +**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.4 Requirements + +### Bug Fixes + +- [ ] **FIX-01**: User clicking "Add Candidate" on a thread page opens the add-candidate modal (not the wrong modal) +- [ ] **FIX-02**: Item images display correctly on collection overview cards (no broken/missing images) +- [ ] **FIX-03**: Catalog and collection images load without noticeable delay (slow image loading resolved) +- [ ] **FIX-04**: Clicking the sign-in button on an auth prompt redirects the user directly to the Logto login page +- [ ] **FIX-05**: All clickable and interactive elements show a pointer cursor on hover throughout the app + +### Admin Role + +- [ ] **ROLE-01**: The users table has an isAdmin boolean flag that identifies admin users +- [ ] **ROLE-02**: Admin can set another user's isAdmin flag via a server-side mechanism (CLI or seed, not public UI) + +### Admin Panel — Global Items + +- [ ] **ADMN-01**: Admin user can navigate to an /admin route that is inaccessible to non-admin users +- [ ] **ADMN-02**: Admin can browse all global catalog items with search and tag filtering +- [ ] **ADMN-03**: Admin can edit a global catalog item's details (name, brand, model, weight, price, tags, image, attribution fields) +- [ ] **ADMN-04**: Admin can delete a global catalog item from the catalog (with confirmation) + +### Admin Panel — Tag Management + +- [ ] **ADMN-05**: Admin can browse all tags with item counts and parent/child relationships displayed +- [ ] **ADMN-06**: Admin can create a new tag with a name +- [ ] **ADMN-07**: Admin can rename an existing tag +- [ ] **ADMN-08**: Admin can assign a parent tag to a tag (enabling sub-tag hierarchy, e.g. "down" under "sleeping-bag") +- [ ] **ADMN-09**: Admin can remove a tag's parent assignment (making it a top-level tag again) +- [ ] **ADMN-10**: Admin can delete a tag, with a warning if items are currently using it + +## Future Requirements (v2.5+) + +### Catalog Spec System + +- **SPEC-01**: Tags can have typed spec field definitions (key, label, unit, type: number/text/image) +- **SPEC-02**: Sub-tags inherit the spec schema of their parent tag +- **SPEC-03**: Admin can create, edit, and delete spec field definitions for a tag via the admin panel +- **SPEC-04**: Global catalog items can have spec values filled in for their tag's spec schema +- **SPEC-05**: Catalog item detail page displays spec values in a structured spec sheet section +- **SPEC-06**: Items are filterable/comparable by numeric spec values (e.g. R-value, comfort temp) + +### Engagement Stats + +- **STAT-01**: Global catalog item detail pages track view counts +- **STAT-02**: Authenticated users can like/save a catalog item (wishlist-style) +- **STAT-03**: Catalog item detail page shows owner count, view count, like count, and public setup appearances +- **STAT-04**: User can view their list of saved/liked catalog items + +## Out of Scope + +| Feature | Reason | +|---------|--------| +| User management in admin panel | Not needed until user base grows; Logto handles account lifecycle | +| Moderation queue / content flagging | Deferred — requires freeform UGC first | +| Sub-items / component attachment to items | High complexity, needs dedicated discussion and milestone | +| Freeform reviews or comments | No moderation infrastructure yet | +| Social login providers | Logto handles this externally | + +## Traceability + +| Requirement | Phase | Status | +|-------------|-------|--------| +| FIX-01 | Phase 35 | Pending | +| FIX-02 | Phase 35 | Pending | +| FIX-03 | Phase 35 | Pending | +| FIX-04 | Phase 35 | Pending | +| FIX-05 | Phase 35 | Pending | +| ROLE-01 | Phase 36 | Pending | +| ROLE-02 | Phase 36 | Pending | +| ADMN-01 | Phase 36 | Pending | +| ADMN-02 | Phase 37 | Pending | +| ADMN-03 | Phase 37 | Pending | +| ADMN-04 | Phase 37 | Pending | +| ADMN-05 | Phase 38 | Pending | +| ADMN-06 | Phase 38 | Pending | +| ADMN-07 | Phase 38 | Pending | +| ADMN-08 | Phase 38 | Pending | +| ADMN-09 | Phase 38 | Pending | +| ADMN-10 | Phase 38 | Pending | + +**Coverage:** +- v2.4 requirements: 17 total +- Mapped to phases: 17 +- Unmapped: 0 ✓ + +--- +*Requirements defined: 2026-04-19* +*Last updated: 2026-04-19 — initial definition for v2.4* diff --git a/.planning/STATE.md b/.planning/STATE.md index 9564baf..d0d995b 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -1,34 +1,34 @@ --- gsd_state_version: 1.0 -milestone: v2.3 -milestone_name: Global & Social Ready -status: executing -stopped_at: context exhaustion at 90% (2026-04-19) -last_updated: "2026-04-19T14:11:38.116Z" -last_activity: 2026-04-18 +milestone: v2.4 +milestone_name: Admin Foundation +status: planning +stopped_at: milestone initialized +last_updated: "2026-04-19T00:00:00.000Z" +last_activity: 2026-04-19 progress: - total_phases: 16 - completed_phases: 7 - total_plans: 29 - completed_plans: 29 - percent: 100 + total_phases: 0 + completed_phases: 0 + total_plans: 0 + completed_plans: 0 + percent: 0 --- # Project State ## Project Reference -See: .planning/PROJECT.md (updated 2026-04-09) +See: .planning/PROJECT.md (updated 2026-04-19) **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. -**Current focus:** Phase 34 — i18n-foundation +**Current focus:** Milestone v2.4 — Admin Foundation ## Current Position -Phase: 999.1 -Plan: Not started -Status: Ready to execute -Last activity: 2026-04-18 +Phase: Not started (defining requirements) +Plan: — +Status: Defining requirements +Last activity: 2026-04-19 — Milestone v2.4 started Progress: [░░░░░░░░░░] 0% @@ -36,9 +36,8 @@ Progress: [░░░░░░░░░░] 0% **Velocity:** -- Total plans completed: 81 (all milestones through v2.0) -- v1.3: 6 plans across 4 phases (2026-03-16 to 2026-04-08) -- v2.0: 32 plans across 10 phases (2026-03-17 to 2026-04-08) +- Total plans completed: 110+ (all milestones through v2.3) +- v2.3: 18 plans across 3 phases (2026-04-13 → 2026-04-19) *Updated after each plan completion* @@ -46,49 +45,31 @@ Progress: [░░░░░░░░░░] 0% ### Decisions -Key decisions carried forward from v2.0: +Key decisions carried forward from v2.3: - External auth provider: Logto (self-hosted OIDC) — RESOLVED - Structured UGC only — ratings and predefined fields, no freeform text — ACTIVE - Separate globalItems table — not a flag on user items table — RESOLVED - COALESCE merge for reference items — RESOLVED - Detail pages replacing slide-out panels — RESOLVED +- Setup visibility: private/link/public column + shares table — RESOLVED +- Multi-currency: market_prices + community_prices + ECB rates — RESOLVED +- i18n: react-i18next, 7 namespaces, English + German — RESOLVED -v2.1 decisions: +v2.4 decisions: -- Product images: manufacturer images with attribution and source link, honor takedown requests — RESOLVED -- Catalog data: open datasets + manufacturer specs + agent MCP enrichment — RESOLVED -- Public-first: auth model rework before content features — RESOLVED -- Phase 999.3 (Public Access Auth Model backlog item) is now Phase 24 — PROMOTED -- [Phase 24-public-access-infrastructure]: createRateLimit factory pattern for configurable rate limiting per endpoint tier -- [Phase 24-public-access-infrastructure]: Browse tier 120/min, detail tier 60/min — same limits for auth and anon users -- [Phase 24]: Both auth prompt CTAs go to /login — Logto handles sign-in and sign-up at the same OIDC endpoint -- [Phase 24]: Soft navigate() replaces hard window.location.href for private route redirect — defers until auth resolves -- [Phase 25-catalog-enrichment-agent-tools]: Three-way tag sync: undefined=leave untouched, []=clear all, [names]=replace — enables selective tag updates from catalog agents -- [Phase 25-catalog-enrichment-agent-tools]: unique(brand, model) constraint on globalItems: enables safe ON CONFLICT DO UPDATE for catalog enrichment agents -- [Phase 25-catalog-enrichment-agent-tools]: Catalog MCP tools use registerCatalogTools(db) without userId — shared catalog needs no user scoping -- [Phase 25-catalog-enrichment-agent-tools]: Attribution spacing: image div removes mb-6, attribution paragraph takes mb-6, fallback div ensures consistent spacing -- [Phase 26-discovery-landing-page]: Composite cursor for setups uses itemCount_id format filtered post-query in JS for simplicity with grouped SQL -- [Phase 26-discovery-landing-page]: No cursor pagination for getTrendingCategories — bounded small list, simple limit is sufficient -- [Phase 26]: discoveryRoutes registered with browseTier rate limiting (120 req/min) for all GET discovery endpoints -- [Phase 26-discovery-landing-page]: PublicSetupCard itemCount/creatorName fields are optional for backward compatibility with users/$userId usage -- [Phase 26-discovery-landing-page]: Discovery sections hide entirely (return null) when not loading and data is empty — avoids empty grid layouts -- [Phase 27]: Setups elevated to top-level /setups route; Collection page reduced to Gear and Planning tabs with .catch(gear) fallback for legacy URLs -- [Phase 27]: Wave 0 tests use test.fixme for removed dashboard cards — preserves test intent for future reference -- [Phase 27]: Old setups tab test replaced with fallback-to-gear assertion matching the Zod .catch('gear') behavior planned in Plans 01-03 -- [Phase 27]: Used 'house' icon instead of plan-specified 'home': lucide-react has no Home icon, only House — prevents Package fallback rendering in navigation -- [Phase 32]: isPublic boolean replaced with visibility text column (private/link/public) on setups table — RESOLVED -- [Phase 32]: shares table with token, permission, expiresAt, userId, revokedAt — schema future-proofed for person-specific shares and write permissions -- [Phase 32]: Share tokens use randomBytes(16).toString("base64url") — 128-bit entropy, URL-safe -- [Phase 32]: Visibility→private deactivates share links; switching back reactivates non-expired ones -- [Phase 32]: /s/:token short URL redirects to /setups/:id?share=token; /api/shared/:token returns setup data without auth -- [Phase 32]: ShareModal replaces old globe toggle — Google Docs-style with visibility picker + link management -- [Phase 34]: Created catalog namespace for global-items/discover page -- [Phase 34]: Static lookup tables (icons, CSS) kept at module level; only label strings moved inside components for t() access +- Admin role: isAdmin boolean flag on users table (simplest, no Logto role claims needed) +- Sub-items/component attachment: explicitly deferred to a future milestone +- Catalog spec system (typed specs per tag): deferred to v2.5 +- Engagement stats (views/likes/saves/appearances): deferred to v2.5 ### Pending Todos - Fix Add Candidate button shows wrong modal on thread page (ui) +- Fix item image not showing on collection overview +- Investigate slow image loading +- Auth prompt sign-in button should redirect directly to Logto +- Cursor pointer on all clickable links ### Blockers/Concerns @@ -96,28 +77,18 @@ None. ## Deferred Items -Items acknowledged and deferred at milestone close on 2026-04-19: +Items carried forward from v2.3: | Category | Item | Status | |----------|------|--------| -| quick_task | 260406-j44-comprehensive-dev-seed-script-for-bikepa | missing tracking marker (work complete) | -| todo | 2026-04-10-add-cursor-pointer-to-all-clickable-links | pending | -| todo | 2026-04-10-fix-item-image-not-showing-on-collection-overview | pending | -| todo | 2026-04-10-investigate-slow-image-loading | pending | -| todo | 2026-04-13-auth-prompt-sign-in-button-should-redirect-directly-to-logto | pending | -| todo | 2026-04-13-fix-add-candidate-button-shows-wrong-modal-on-thread-page | pending | - -### Quick Tasks Completed - -| # | Description | Date | Commit | Directory | -|---|-------------|------|--------|-----------| -| 260411-022 | Fix global items search bar layout - too tall and hard to navigate back | 2026-04-10 | ef48891 | [260411-022-fix-global-items-search-bar-layout-too-t](./quick/260411-022-fix-global-items-search-bar-layout-too-t/) | -| 260411-0zq | Redesign search UX — real nav search bar navigating to /global-items?q= | 2026-04-10 | 334bf33 | [260411-0zq-redesign-search-ux-bigger-nav-search-bar](./quick/260411-0zq-redesign-search-ux-bigger-nav-search-bar/) | -| 260411-1h2 | Rebuild global items page with sticky toolbar and inline filters | 2026-04-10 | ee3b6f7 | [260411-1h2-rebuild-global-items-page-with-sticky-se](./quick/260411-1h2-rebuild-global-items-page-with-sticky-se/) | -| Phase 34 P02 | 122 | 5 tasks | 25 files | +| todo | 2026-04-10-add-cursor-pointer-to-all-clickable-links | promoted to v2.4 FIX-05 | +| todo | 2026-04-10-fix-item-image-not-showing-on-collection-overview | promoted to v2.4 FIX-02 | +| todo | 2026-04-10-investigate-slow-image-loading | promoted to v2.4 FIX-03 | +| todo | 2026-04-13-auth-prompt-sign-in-button-should-redirect-directly-to-logto | promoted to v2.4 FIX-04 | +| todo | 2026-04-13-fix-add-candidate-button-shows-wrong-modal-on-thread-page | promoted to v2.4 FIX-01 | ## Session Continuity -Last session: 2026-04-19T14:11:38.113Z -Stopped at: context exhaustion at 90% (2026-04-19) +Last session: 2026-04-19 +Stopped at: milestone v2.4 initialized — roadmap pending Resume file: None