feat: add project recommendation service for freelancers

[Muhd010]

Overview

This PR adds a Project Recommendation Service (issue #185) that recommends relevant open projects to freelancers based on their profile. The recommendation engine uses a weighted scoring algorithm combining skills, budget preferences, category affinity, and recency to surface the most relevant projects.

Related Issue

Closes #185

Changes

📈 Recommendation Engine

• [ADD] lib/projectRecommendations.ts

  • Weighted scoring algorithm: skill match (40%), budget fit (25%), category affinity (20%), recency (15%).
  • Pagination with metadata (totalCount, hasMore).
  • Fallback logic: when insufficient scored results exist, pads with recent/trending open projects.
  • In-memory cache (5-minute TTL) to reduce DB load for repeated requests.
  • Query parameter parsing and validation with structured error responses.

• [ADD] app/api/projects/recommendations/route.ts

  • GET /api/projects/recommendations — authenticated REST endpoint.
  • Requires JWT via withAuth middleware (only freelancers can request).
  • Resolves user.id from wallet address, returns paginated recommendations.

• [ADD] scripts/012-project-recommendation-columns.sql

  • Adds skills TEXT[] and category VARCHAR(100) columns to projects table.
  • GIN index on skills for array overlap queries.
  • Composite partial index on (category, budget_usdc) for open projects.

• [ADD] __tests__/api/project-recommendations.test.ts

  • 40 tests covering scoring functions, parameter parsing, and integration flow.

Verification Results

TypeScript typecheck:
✅ No type errors in new files (tsc --noEmit)

Build:
✅ pnpm build succeeds; /api/projects/recommendations route appears in output

Unit/Integration tests:
✅ npx vitest run __tests__/api/project-recommendations.test.ts — 40/40 passed

Test Suite	Tests	Status
computeSkillScore	5	✅
computeBudgetScore	8	✅
computeCategoryScore	4	✅
computeRecencyScore	3	✅
scoreProject	3	✅
parseRecommendationParams	8	✅
getRecommendations	9	✅
Total	40	✅

Acceptance Criteria

Criteria	Status
Paginated recommendations — API returns results with metadata (totalCount, hasMore)	✅
Efficient database queries — GIN index on skills, composite index on (category, budget_usdc)	✅
Fallback to recent projects when insufficient matching data exists	✅
Consistent results across sessions — deterministic scoring algorithm	✅
Secure access control — only authenticated freelancers can request recommendations (withAuth)	✅
Unit/integration tests — 40 tests validating algorithm correctness and edge cases	✅