Evaluation

Overview (C4 Component)

Black-box description of components

Component	Responsibility (why does it exist?)	Provided interface(s)	Consumed interface(s)
EvaluationController	Entry point for writing & reading provider evaluations.	REST /api/v1/evaluations/** (OpenAPI)	—
EvaluationService	Executes use-cases (create, list, compute averages); validates categories; resolves author & provider; enforces pagination.	Spring service API	EvaluationRepository, EvaluationCategoryRepository, ProviderRepository, UserRepository, MapStruct mappers
EvaluationRepository	Persistence of the Evaluation aggregate; custom JPQL projection for per-category averages.	Spring-Data JPA	MySQL via JDBC
EvaluationCategoryRepository	CRUD for master data of evaluation categories.	Spring-Data JPA	MySQL
ProviderRepository	Look-up provider to attach an evaluation (re-use from Provider module).	Spring-Data JPA	MySQL
UserRepository	Fetch authenticated author entity.	Spring-Data JPA	MySQL
EvaluationMapper / CategoryMapper / CategoryRatingMapper	MapStruct conversion between REST DTOs and JPA entities, bidirectional wiring of ratings.	Java interface	—
Entities (Evaluation, EvaluationCategory, EvaluationCategoryRating)	ORM layer; Evaluation roots the aggregate and owns its list of category ratings.	JPA	—
JPQL projection CategoryAvgProjection	Interface-based projection returned by EvaluationRepository::findAvgPerCategory.	—	—

Important internal interfaces

Name	Signature / Protocol	Notes
addEvaluation	POST /api/v1/evaluations/{providerOpsCode} – body EvalCreateRequest	Authenticated users only; stores global + per-category ratings, comment, author email taken from JWT principal.
getEvaluations	GET /api/v1/evaluations/{providerOpsCode} – paging offset/limit, sorting sortBy, sortOrder	Returns EvaluationPageResponse = list + totals + averageGlobalRating + per-category averages.
getEvaluationCategories	GET /api/v1/evaluations/categories	Public endpoint returning the master data (EvalCategory[]).
findAvgPerCategory	EvaluationRepository::findAvgPerCategory(String opsCode) → List<CategoryAvgProjection>	Pure JPQL, re-used by service to build EvaluationPageResponse.categoryAverageRatings.

@Query("""
  select cat.id   as categoryId,
         cat.name as name,
         cat.description as description,
         coalesce(avg(r.rating),0) as avgRating
  from   EvaluationCategoryRating r
  join   r.evaluation e
  join   r.category   cat
  where  e.provider.operationalCode = :opsCode
  group  by cat.id, cat.name, cat.description
""")
List<CategoryAvgProjection> findAvgPerCategory(String opsCode);

Used by the service to build the categoryAverageRatings section without loading all evaluations in memory.