feat: Extend Search to Beneficiaries with Filters, Pagination.....

[Oluwatos94]

What

Extends search to beneficiaries with filtering, pagination, sorting, and faceted aggregation.

Closes #74.

Endpoint

GET /api/v1/search/beneficiaries — Admin/Verifier only (returns PII).

Params: q, country, city, needsCategory, verificationStatus, riskScoreMin/Max, ageMin/Max, familySizeMin/Max, page, limit, sortBy, sortOrder.

Response: { data, pagination: { page, limit, total, totalPages }, facets }.

Highlights

• Validated zod DTO; sortBy/verificationStatus are enum-checked before hitting Prisma.
• Age filter/sort derived from dateOfBirth; relevance falls back to recency.
• Facets: countries, cities, needsCategories, verificationStatuses, riskScore/age/familySize ranges; with
  drill-down semantics (each facet excludes its own active filter).
• Results + count + facets run in a single $transaction for a consistent snapshot.
• Stable pagination via id tiebreaker on every sort.
• New needsCategory field; B-tree indexes on search fields + pg_trgm GIN indexes for q text search.

Migration required

Run prisma migrate dev before deployment; it enables pg_trgm and adds the new indexes/field.

Tests

Unit tests for filters, pagination, sort, drill-down facets, and bucketing. Full suite green (pre-existing
sharp-missing storage suite excepted).

[BarryArinze]

CI/CD Pipeline test failed. Please resolve it

[Oluwatos94]

Hi @BarryArinze, pls check now. Do you have to trigger the pipeline yourself? No Job is running automatically.

[BarryArinze]

Yes I will trigger it by myself. Please resolve cothe conflicts so I can

[Oluwatos94]

@BarryArinze, conflicts resolved.

[GBOYEE]

I'd like to work on this.

Approach:

• I'll add the CI config and test it locally before pushing
• Verify with existing tests + add new ones if needed

Estimated effort: ~1-2 hours. PR incoming shortly.

[Oluwatos94]

@BarryArinze, pls kind check this PR. I have resolved the conflicts again.