Feature Implementation Plan: Top Varieties by Bean Count

📋 Todo Checklist

• [ ] Create a new repository method in VarietyRepository to get top varieties.
• [ ] Create a new /api/varieties/top endpoint in VarietyController.
• [ ] Define the API response structure.
• [ ] Update OpenAPI documentation for the new endpoint.
• [ ] Write unit and integration tests.
• [ ] Final Review and Testing

🔍 Analysis & Investigation

Codebase Structure

• Entity: The Variety entity has a coffeeBeans collection, which is the basis for the counting and aggregation.
• Repository: A new method, findTopByAvailableBeanCount, will be added to src/Repository/VarietyRepository.php. This keeps the complex query logic isolated in the repository layer.
• Controller: A new route and method will be added to src/Controller/Api/VarietyController.php to expose the new functionality.

Current Architecture

The plan follows the existing application architecture. A new controller method will handle the API request, and a new repository method will encapsulate the database query. This maintains a clear separation of concerns. The response will be a custom structure containing the variety data and the associated bean count, which is a common pattern for aggregated data.

Dependencies & Integration Points

• NelmioApiDocBundle: Will be used to document the new /api/varieties/top endpoint, including its limit parameter and response structure.
• Doctrine: The Doctrine Query Builder will be used to construct the aggregation query, which involves a JOIN, WHERE, GROUP BY, ORDER BY, and LIMIT.

Considerations & Challenges

• Performance: The aggregation query can be expensive on large datasets. However, since it will be limited to a small number of results (e.g., top 5 or 10), the performance impact should be minimal. Caching the result of this endpoint could be a future optimization if needed.
• Response Structure: The API will return not just the Variety entities but also the beanCount. This requires a custom query result and a specific JSON structure, which will be defined in the OpenAPI documentation.

📝 Implementation Plan

Prerequisites

• No new external dependencies are required.

Step-by-Step Implementation

1. Create New Repository Method

   • Files to modify: src/Repository/VarietyRepository.php
   • Changes needed:
     • Create a new public method findTopByAvailableBeanCount(int $limit = 10): array.
     • Use the Query Builder to construct the following query:

       return $this->createQueryBuilder('v')
           ->select('v as variety', 'COUNT(cb.id) as beanCount')
           ->join('v.coffeeBeans', 'cb')
           ->where('cb.available = :available')
           ->setParameter('available', true)
           ->groupBy('v.id')
           ->orderBy('beanCount', 'DESC')
           ->setMaxResults($limit)
           ->getQuery()
           ->getResult();
       

2. Create New Controller Endpoint

   • Files to modify: src/Controller/Api/VarietyController.php
   • Changes needed:
     • Add a new public method getTopVarieties(Request $request): JsonResponse.
     • Add the #[Route('/varieties/top', name: 'varieties_top', methods: ['GET'])] annotation.
     • In the method, get the limit from the request query parameters, with a default value of 10 and a maximum of 50.
     • Call the new varietyRepository->findTopByAvailableBeanCount($limit) method.
     • Format the response to be an array of objects, each containing the variety data and the beanCount.
     • Add #[OA\Get] and #[OA\Parameter] annotations to document the endpoint, its limit parameter, and the response structure. The response should be documented as an array of objects with variety and beanCount properties.

Testing Strategy

• Unit Tests:
  • Write a unit test for the VarietyRepository::findTopByAvailableBeanCount method. This will require setting up test data with varieties and associated coffee beans (both available and unavailable) and asserting that the method returns the correct varieties in the correct order with the correct counts.
• Integration Tests:
  • Write an integration test for the /api/varieties/top endpoint.
  • Test the default limit.
  • Test with a custom limit parameter.
  • Assert that the response structure is correct and the data is as expected based on the test database state.

🎯 Success Criteria

• A GET request to /api/varieties/top returns a JSON array of the top varieties.
• Each object in the array contains the full variety data and a beanCount field.
• The list is correctly sorted by the number of available coffee beans in descending order.
• The limit parameter correctly controls the number of returned varieties.
• The new endpoint is documented in the OpenAPI specification.
• The new functionality is covered by tests.