feat: non-prod sample market seed endpoint

[Davichi-1]

Overview

This PR adds an admin sample-market seed endpoint to the backend so E2E suites and demos have predictable data to work against in non-production environments. It introduces POST /api/admin/seed, which inserts a small, fixed batch of sample markets. The operation is idempotent, tracks the rows it seeds, and is unavailable in production.

Related Issue

Closes #160

Changes

⚙️ Seed Service

• [ADD] src/services/seedService.ts
• Added the core seed workflow for a fixed batch of 5 sample markets.
• Idempotent: stable primary keys (seed-market-001…005) + ON CONFLICT (id) DO NOTHING, so repeat runs insert nothing and report rows as skipped.
• Tracks seeded rows by tagging metadata.seeded = true plus a seedBatchVersion; exposes listSeeded() to read them back.
• Defense-in-depth SeedNotAllowedError guard so the service can never write sample data to a production database, even if called directly.
• Emits a market.created structured log event per inserted row and writes an admin.seed_markets audit entry, both carrying a correlation id.
• Uses a repository interface (SeedRepository) with a Drizzle implementation, kept injectable for testing.

🌐 Seed API Surface

• [ADD] src/routes/admin/seed.ts

• Added POST /api/admin/seed to trigger the seed.

• Security layers (outermost first): production guard → 404 before auth (route is not even probeable); per-admin-token rate limit (30/min, IP fallback); requireAdmin JWT guard.

• Input validation at the boundary with a strict body schema; unexpected fields return 400 validation_error in the standard error envelope.

• [MODIFY] src/index.ts

• Registered the new router at /api/admin/seed.

🧪 Tests

• [ADD] tests/seedService.test.ts

• Covers fresh seed, idempotent re-run (no inserts, no events), actor propagation, the production guard, the error shape, and the Drizzle repository.

• [ADD] tests/adminSeed.test.ts

• Covers the admin guard (missing/non-admin/expired JWT), success + context forwarding, idempotent response, body validation, production 404, rate-limit 429, and error mapping.

📚 Documentation

• [ADD] docs/seed.md
• Documents the endpoint, request/response shape, non-prod behavior, idempotency, tracking, the security layers, observability, and the error envelope.

Verification Results

npm run lint            ✅ changed files clean (pre-existing repo errors/warnings are unrelated)
npx tsc --noEmit        ✅ no errors in changed files (repo has pre-existing type errors)
npx jest tests/seedService.test.ts tests/adminSeed.test.ts   ✅ 20/20 passed
coverage (changed lines)  ✅ seedService.ts 95.2% · routes/admin/seed.ts 93.2% (>90%)

Acceptance Criteria	Status
Non-prod only (404 in production, runs before auth)	✅
Idempotent (ON CONFLICT DO NOTHING, repeat = 0 inserts)	✅
Tracks seeded markets (metadata.seeded, listable)	✅
Documentation shipped (docs/seed.md)	✅
Secure (admin auth, rate limit, strict input validation)	✅
Structured logging + audit with correlation ids	✅
≥90% coverage on changed lines	✅
Seed route + service tests pass	✅

Note for reviewers: main currently has pre-existing build/test breakage that is unrelated to this change (e.g. src/utils/keyRing.ts references env.JWT_KEYS/env.JWT_ACTIVE_KID, which exist in src/config/env-schema.ts but not in src/config/env.ts; src/index.ts references undefined devicesRouter/stopIndexerHealthProbe). This PR does not touch those files and keeps its test isolated so it runs cleanly. Happy to open a separate PR for the main build fix if useful.

🤖 Generated with Claude Code

[drips-wave]

@Davichi-1 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits