Worker Discovery API with Geo-Radius Search, Skill Facets & Reputation-Weighted Ranking #43

Description

This issue aims to address the implementation of Worker Discovery API with Geo-Radius Search, Skill Facets & Reputation-Weighted Ranking.

The core objective is to: Build the search endpoint the marketplace is missing — find skilled workers near a location, filter by skill and category, and rank results by a documented blend of proximity, on-chain reputation, and availability, with stable cursor pagination.

By completing this feature, we will ensure that the GuildWorkman protocol maintains its high standards for security, usability, and decentralized logic. This issue requires careful attention to the Backend architecture and adherence to the existing project conventions.

When picking up this issue, please ensure you document any new dependencies or architectural decisions made during development.

Component

Backend (Spring Boot / Java 17)

Difficulty

🔴 Hard

Current state

SkilledWorker, Skill, Address, Category, and Review models all exist, and SkilledWorkerController can register and update a worker — but there is no way to find one. A client using GuildWorkman today can only book a worker whose id they somehow already know, which means the marketplace has no front door.

Two things make this harder than a findAll with a LIKE: geo-distance filtering has to stay index-backed rather than degrading into a full-table scan with a Haversine computed per row, and the ranking signal is partly on-chain (the reputation contract's Rating aggregate), so it must be read and cached without putting an RPC call on the request path.

Tasks

• Review the existing Spring Boot structure under backend-api/src/main/java
• Implement the service and REST endpoints for: Worker Discovery API with Geo-Radius Search, Skill Facets & Reputation-Weighted Ranking
• Support filtering by geo-radius, skill, category, and availability, composed in a single query rather than filtered in application memory
• Keep geo filtering index-backed (bounding-box prefilter before exact distance, or a spatial index) and document the chosen approach
• Read the on-chain reputation aggregate off the request path — cached/materialized, with a documented staleness bound and a defined fallback when it is unavailable
• Define and document the ranking formula explicitly, with weights configurable rather than hard-coded in a comparator
• Implement stable cursor-based pagination that does not skip or duplicate rows when the underlying data changes mid-scroll
• Return facet counts alongside results so a client can render filter UI without extra round-trips
• Add or adjust JPA entities, repositories, and schema migrations as needed, including the indexes the search relies on
• Write unit and integration tests (Spring Boot Test; MockWebServer for external RPC calls), including a seeded dataset asserting ranking order and a test proving the query plan uses the intended index
• Add caching for Maven dependencies in CI
• Run ./mvnw verify and ./mvnw test to validate build and coverage

Acceptance Criteria

• Feature accurately implements the objective: Build the search endpoint the marketplace is missing — find skilled workers near a location, filter by skill and category, and rank results by a documented blend of proximity, on-chain reputation, and availability, with stable cursor pagination.
• A client can discover workers by location and skill without knowing any worker id in advance
• Geo filtering is index-backed and does not degrade into a full-table scan as the worker table grows
• Reputation data never adds a synchronous chain RPC call to the search request
• Pagination is stable: scrolling through results while data changes neither skips nor repeats a worker
• Any PR that introduces failing tests or compilation errors is automatically blocked
• Endpoints/services are covered by tests including failure and concurrency paths
• Public API is documented (OpenAPI) and errors follow a consistent response contract
• Code is properly reviewed and approved by codeowners

Estimated Time

2-3 days