Feature Implementation Plan: Add Sort Order to Species and Processing Methods

📋 Todo Checklist

• [ ] Add a sortOrder field to the Species entity.
• [ ] Add a sortOrder field to the ProcessingMethod entity.
• [ ] Create a database migration for the schema changes.
• [ ] Update the SpeciesRepository to sort by the new field.
• [ ] Update the ProcessingMethodRepository to sort by the new field.
• [ ] Update the admin CRUD controllers for both entities to allow managing the sortOrder.
• [ ] Write a data migration or fixture to populate the initial sort order values.
• [ ] Final Review and Testing

🔍 Analysis & Investigation

Codebase Structure

• Entities: The src/Entity/Species.php and src/Entity/ProcessingMethod.php files will be modified.
• Repositories: The src/Repository/SpeciesRepository.php and src/Repository/ProcessingMethodRepository.php will be updated to change their default sorting.
• Admin: The corresponding CRUD controllers in src/Controller/Admin/ will be updated to make the new field editable.

Current Architecture & Problem

• Problem: The API endpoints for Species and ProcessingMethod return lists sorted alphabetically by name. This is not always the desired order for presentation in a user interface.
• Solution: This plan follows the pattern already established by the FlavorWheelNode entity. By adding a nullable integer sortOrder field to both Species and ProcessingMethod, we can explicitly control their display order. The API will then return the items pre-sorted, simplifying frontend logic.

Dependencies & Integration Points

• Doctrine: Will be used to add the new column to the database tables and to update the ORDER BY clauses in the repository queries.
• EasyAdminBundle: The admin interface will be updated using a NumberField to allow easy management of the sort order.

Considerations & Challenges

• Data Population: After adding the sortOrder column, existing records will have a NULL value. A data migration or a fixture is required to populate these fields with a sensible default order. NULL values should be sorted last.
• Admin UI: The sortOrder field should be added to the list view in the admin panel to make it easy to see and manage the current order.

📝 Implementation Plan

Prerequisites

• No new external dependencies are required.

Step-by-Step Implementation

1. Update the Entities

   • Files to modify: src/Entity/Species.php, src/Entity/ProcessingMethod.php
   • Changes needed for both entities:
     • Add a new private property: #[ORM\Column(nullable: true)] private ?int $sortOrder = null;
     • Add an index for performance: #[ORM\Index(columns: ['sort_order'])] (at the class level).
     • Add the appropriate serialization group: #[Groups(['...'])] (e.g., species:read, processing:read).
     • Add a public getter and setter for the new property.

2. Create Database Migration

   • Action: Run symfony console make:migration to generate a new migration file.
   • Changes needed: Verify that the generated migration correctly adds the sort_order column and an index to both the species and processing_method tables.

3. Update Repositories to Use New Sorting

   • Files to modify: src/Repository/SpeciesRepository.php, src/Repository/ProcessingMethodRepository.php
   • SpeciesRepository.php Changes:
     • In the findByFilters method (and any other list-finding methods), change the orderBy clause from 's.commonName' to 's.sortOrder'. Use ASC and handle NULLs by sorting them last (ORDER BY s.sortOrder ASC NULLS LAST).
   • ProcessingMethodRepository.php Changes:
     • In findAllHierarchical and findByFiltersWithPagination, change the orderBy clause from 'p.name' to 'p.sortOrder'.

4. Update Admin CRUD Controllers

   • Files to modify: src/Controller/Admin/SpeciesCrudController.php, src/Controller/Admin/ProcessingMethodCrudController.php
   • Changes needed for both controllers:
     • In the configureFields method, add a NumberField for sortOrder.
     • Add the sortOrder field to the index page view as well, so it's visible in the list.

5. Populate Initial Sort Order Data

   • Action: Create a new Doctrine data fixture (src/DataFixtures/SortOrderFixture.php).
   • Changes needed:
     • The fixture should load all Species and ProcessingMethod entities.
     • It should iterate through them and assign a default sortOrder based on a predefined list or alphabetically. For example, for Species, you might want "Arabica" to be 1, "Canephora (Robusta)" to be 2, etc.
     • Run the fixture to populate the database.

Testing Strategy

• Unit Tests:
  • Update unit tests for the repositories to ensure their query builders are now sorting by sortOrder.
• Integration Tests:
  • Update the integration tests for the /api/species and /api/processing-methods endpoints.
  • Before the test, use fixtures or direct entity manipulation to set a specific sortOrder for a few items.
  • Call the API endpoint and assert that the items are returned in the exact order you specified, not alphabetically.

🎯 Success Criteria

• The Species and ProcessingMethod entities have a functional sortOrder field.
• The API endpoints for listing these entities now return them sorted by the sortOrder field by default.
• The admin panel allows for easy viewing and editing of the sortOrder for both entity types.
• All existing records have a default sortOrder value populated.
• The new sorting logic is covered by tests.