Implement adoptions API with tests and documentation

[tinak25]

Adoptions API

This implements the Adoptions API for managing tree adoption records.

It includes:

• Create a new adoption record
• Fetch all adoption records with pagination
• Fetch a single adoption by ID
• Update adoption details
• Delete an adoption record

Improvements:

• Added Adoptions module with routes, controller, service, and index file
• Added role-based access control for Admin and Manager access
• Added validation for adoption ID, adopter ID, FOB ID, and adoption date
• Added checks to ensure the adopter exists before creating or updating an adoption
• Prevented future adoption dates
• Added proper error handling using the centralised error middleware
• Updated API documentation for the Adoptions module
• Ensured consistent API responses across endpoints

Testing:

• Added unit tests for Adoptions service logic
• Added integration tests for all Adoptions endpoints
• Verified Admin can create, update, and delete adoptions
• Verified Admin and Manager can list and fetch adoptions
• Verified restricted roles receive 403 responses
• Verified missing token returns 401
• Verified invalid payloads return 400
• Verified missing adoption/adopter records return 404
• Confirmed tests, lint, and build are passing

[AKV2703]

The overall structure and CRUD flow for the Adoptions API is implemented well, and the RBAC setup/routes generally align with the proposal. However, there are still a few important areas that should be addressed before merge. The main issues are around validation consistency, proposal compliance, and test coverage. listAdoptions() currently only supports pagination but is missing the required filters (fob_id, adopter, year). Some validation paths are using incorrect error codes, and pagination parsing in the controller silently defaults invalid values instead of rejecting them. The current delete implementation/tests also hard delete records, while the proposal expects adoption history/cancellation data to be preserved, so this behaviour should be reviewed. On the testing side, unit/integration coverage should be expanded for RBAC restrictions, filter behaviour, invalid query params, stricter validation scenarios, and cleanup of created test data. Overall the foundation is good, but these gaps should be resolved to fully align with the project specification and avoid future issues.

[AKV2703]

Reviewed the latest updates and the implementation is now in a much better state overall. The service, controller, validation flow, RBAC handling, documentation, and test coverage have all been significantly improved and the main concerns raised earlier were addressed properly. Approving this PR now.

[sandaliSS]

approved