docs(26-02): complete discovery routes and hooks plan
This commit is contained in:
@@ -122,7 +122,7 @@ Plans:
|
||||
|
||||
Plans:
|
||||
- [x] 26-01-PLAN.md — Discovery service layer with cursor pagination (TDD)
|
||||
- [ ] 26-02-PLAN.md — Discovery routes, server registration, and client hooks
|
||||
- [x] 26-02-PLAN.md — Discovery routes, server registration, and client hooks
|
||||
- [ ] 26-03-PLAN.md — Landing page UI and PublicSetupCard enhancement
|
||||
**UI hint**: yes
|
||||
|
||||
@@ -155,7 +155,7 @@ Plans:
|
||||
| 23. Manual Entry Fallback | v2.0 | 1/1 | Complete | 2026-04-06 |
|
||||
| 24. Public Access & Infrastructure | v2.1 | 2/2 | Complete | 2026-04-10 |
|
||||
| 25. Catalog Enrichment & Agent Tools | v2.1 | 1/2 | Complete | 2026-04-10 |
|
||||
| 26. Discovery Landing Page | v2.1 | 1/3 | In Progress| |
|
||||
| 26. Discovery Landing Page | v2.1 | 2/3 | In Progress| |
|
||||
|
||||
## Backlog
|
||||
|
||||
@@ -165,7 +165,7 @@ Plans:
|
||||
**Plans**: 3 plans
|
||||
|
||||
Plans:
|
||||
- [ ] 26-01-PLAN.md — Discovery service layer with cursor pagination (TDD)
|
||||
- [x] 26-01-PLAN.md — Discovery service layer with cursor pagination (TDD)
|
||||
- [ ] 26-02-PLAN.md — Discovery routes, server registration, and client hooks
|
||||
- [ ] 26-03-PLAN.md — Landing page UI and PublicSetupCard enhancement
|
||||
|
||||
|
||||
@@ -3,14 +3,14 @@ gsd_state_version: 1.0
|
||||
milestone: v2.1
|
||||
milestone_name: Public Discovery
|
||||
status: executing
|
||||
stopped_at: Completed 26-01-PLAN.md
|
||||
last_updated: "2026-04-10T12:55:01.408Z"
|
||||
stopped_at: Completed 26-02-PLAN.md
|
||||
last_updated: "2026-04-10T12:59:46.313Z"
|
||||
last_activity: 2026-04-10
|
||||
progress:
|
||||
total_phases: 6
|
||||
completed_phases: 2
|
||||
total_plans: 7
|
||||
completed_plans: 5
|
||||
completed_plans: 6
|
||||
percent: 0
|
||||
---
|
||||
|
||||
@@ -26,7 +26,7 @@ See: .planning/PROJECT.md (updated 2026-04-09)
|
||||
## Current Position
|
||||
|
||||
Phase: 26 (discovery-landing-page) — EXECUTING
|
||||
Plan: 2 of 3
|
||||
Plan: 3 of 3
|
||||
Status: Ready to execute
|
||||
Last activity: 2026-04-10
|
||||
|
||||
@@ -70,6 +70,7 @@ v2.1 decisions:
|
||||
- [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
|
||||
|
||||
### Pending Todos
|
||||
|
||||
@@ -81,6 +82,6 @@ None.
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-04-10T12:55:01.406Z
|
||||
Stopped at: Completed 26-01-PLAN.md
|
||||
Last session: 2026-04-10T12:59:46.310Z
|
||||
Stopped at: Completed 26-02-PLAN.md
|
||||
Resume file: None
|
||||
|
||||
99
.planning/phases/26-discovery-landing-page/26-02-SUMMARY.md
Normal file
99
.planning/phases/26-discovery-landing-page/26-02-SUMMARY.md
Normal file
@@ -0,0 +1,99 @@
|
||||
---
|
||||
phase: 26-discovery-landing-page
|
||||
plan: "02"
|
||||
subsystem: server/client
|
||||
tags: [discovery, http-routes, react-query, rate-limiting]
|
||||
dependency_graph:
|
||||
requires: [26-01]
|
||||
provides: [discovery-http-endpoints, discovery-react-hooks]
|
||||
affects: [server/index.ts, client/hooks]
|
||||
tech_stack:
|
||||
added: []
|
||||
patterns: [hono-route-handler, react-query-hook, cursor-pagination]
|
||||
key_files:
|
||||
created:
|
||||
- src/server/routes/discovery.ts
|
||||
- src/client/hooks/useDiscovery.ts
|
||||
- tests/routes/discovery.test.ts
|
||||
modified:
|
||||
- src/server/index.ts
|
||||
decisions:
|
||||
- "No cursor pagination needed for getTrendingCategories — bounded small list, simple limit is sufficient (carried from plan 01)"
|
||||
- "discoveryRoutes registered with browseTier rate limiting (120 req/min) for all GET discovery endpoints"
|
||||
- "Auth skip added for /api/discovery/* GET — public access without authentication"
|
||||
metrics:
|
||||
duration: "~8 minutes"
|
||||
completed: "2026-04-10"
|
||||
tasks_completed: 2
|
||||
files_created: 3
|
||||
files_modified: 1
|
||||
---
|
||||
|
||||
# Phase 26 Plan 02: Discovery HTTP Routes and React Query Hooks Summary
|
||||
|
||||
**One-liner:** Three public GET endpoints at /api/discovery/{setups,items,categories} with browseTier rate limiting, wired to discovery service from plan 01, plus matching React Query hooks with typed interfaces.
|
||||
|
||||
## What Was Built
|
||||
|
||||
### Task 1: Discovery routes, server registration, and route tests
|
||||
|
||||
Created `src/server/routes/discovery.ts` with three Hono GET handlers following the exact pattern of `global-items.ts`:
|
||||
|
||||
- `GET /setups` — calls `getPopularSetups(db, limit, cursor)`, default limit 6, max 50
|
||||
- `GET /items` — calls `getRecentGlobalItems(db, limit, cursor)`, default limit 8, max 50
|
||||
- `GET /categories` — calls `getTrendingCategories(db, limit)`, default limit 12, max 50
|
||||
|
||||
Updated `src/server/index.ts`:
|
||||
- Added `discoveryRoutes` import
|
||||
- Added `browseTier` rate limiting for `GET /api/discovery/*`
|
||||
- Added auth skip: `if (c.req.path.startsWith("/api/discovery") && c.req.method === "GET") return next()`
|
||||
- Registered `app.route("/api/discovery", discoveryRoutes)`
|
||||
|
||||
Created `tests/routes/discovery.test.ts` with 10 tests covering:
|
||||
- Response shape validation for all three endpoints
|
||||
- Empty state handling
|
||||
- Limit param enforcement
|
||||
- Cursor-based pagination for items endpoint
|
||||
- Public-only filter for setups
|
||||
|
||||
### Task 2: Client-side React Query hooks
|
||||
|
||||
Created `src/client/hooks/useDiscovery.ts` with three named hook exports:
|
||||
|
||||
- `useDiscoverySetups(limit = 6)` — queryKey `["discovery", "setups", limit]`, staleTime 2min
|
||||
- `useDiscoveryItems(limit = 8)` — queryKey `["discovery", "items", limit]`, staleTime 2min
|
||||
- `useDiscoveryCategories(limit = 12)` — queryKey `["discovery", "categories", limit]`, staleTime 5min
|
||||
|
||||
Exported interfaces: `DiscoverySetup`, `DiscoveryCategory`.
|
||||
|
||||
## Verification
|
||||
|
||||
- `bun test tests/routes/discovery.test.ts` — 10 pass, 0 fail
|
||||
- `bun run build` — clean build, no TypeScript errors
|
||||
- Full test suite: 285 pass, 15 pre-existing failures in unrelated modules (storage.service.ts export issue in setups/items/profiles/threads routes tests)
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] Fixed cursor pagination test with simultaneous timestamps**
|
||||
- **Found during:** Task 1 test writing
|
||||
- **Issue:** Two `globalItems` inserted in quick succession in PGlite got the same `defaultNow()` timestamp, making pagination impossible to test
|
||||
- **Fix:** Inserted items with explicit `createdAt` values (2024-01-01 and 2024-06-01) to ensure distinct timestamps for pagination test
|
||||
- **Files modified:** tests/routes/discovery.test.ts
|
||||
- **Commit:** 0323e0c
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None — all endpoints return live database data from the discovery service.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
Files exist:
|
||||
- FOUND: src/server/routes/discovery.ts
|
||||
- FOUND: src/client/hooks/useDiscovery.ts
|
||||
- FOUND: tests/routes/discovery.test.ts
|
||||
|
||||
Commits exist:
|
||||
- 0323e0c — feat(26-02): discovery HTTP routes, server registration, and route tests
|
||||
- 747a1c3 — feat(26-02): React Query hooks for discovery data
|
||||
Reference in New Issue
Block a user