Added Achievement System For Gaming Stats API Endpoints

[alliekameda]

Added Achievement System For Gaming Stats API Endpoints

Add API Endpoints and Custom Manager for Achievement Tracking System

---

Overview

What does this PR do?

This PR introduces REST API endpoints and a custom manager to handle tracking, awarding, and updating progress on student achievements tied to Pomodoro sessions, pet collection, and pet evolution. It follows the Fat Model, Skinny View design philosophy for maintainable and scalable backend logic.

---

Key Features & Changes

What has been added or changed?

✔ Core Feature Implementation: API views for listing achievements, awarding achievements to students, and updating student achievement progress.
✔ Refactored Business Logic: Introduced a custom manager to encapsulate common operations such as awarding and unlocking achievements.
✔ New Components/Files:

• views.py — added viewsets for Achievement and StudentAchievement.
• serializers.py — created serializers for both models.
• urls.py — registered new endpoints.
• managers.py — custom manager and queryset for StudentAchievement.

---

Why This Is Needed

What problem does this solve?

This implementation allows automated tracking and rewarding of student accomplishments, creating a gamified experience to boost engagement and motivation. It also enables scalable achievement logic that can be reused across other systems like Pomodoro and pets.

---

Related Issue

🔗 This PR closes API endpoints for Achievement System For Gaming Stats #108

---

Implementation Details

How was this feature developed?

• Built using Django REST Framework ViewSets and serializers.
• Logic for awarding or updating achievements is delegated to a custom manager (StudentAchievementManager).
• Added StudentAchievementQuerySet to filter unlocked/in-progress achievements.
• Used @action decorators for custom API operations.
• Views remain lightweight and call manager methods.

---

Design Documentation (If Applicable)

N/A — follows standard DRF conventions and previously defined model structure.

---

How to Test This PR

Step-by-step testing guide

✅ Log in to the Django admin panel
✅ Navigate to the Achievements section
✅ Create a new Achievement for a user
✅ Create a Student Achievement
✅ Test via curl

---

Files Added/Modified

📂 List of important files changed in this PR

File Name	Description
views.py	API endpoints for achievements
serializers.py	Serializers for models
urls.py	Registered new API paths
managers.py	Business logic for StudentAchievements

---

AI Code Usage

🤖 Was AI-generated code used in this PR?

• Yes (AI-assisted generation of views.py, managers.py, and serializers with human review)
• No

---

Checklist for Reviewers

Things to check before approving this PR:

• Do the endpoints return correct data and status codes?
• Is logic properly encapsulated in the manager, not in views?
• Do serializers validate and serialize data accurately?
• Are naming conventions and code style consistent?

---

Next Steps & Future Enhancements

What improvements can be made after merging?

• Hook these endpoints into signals from Pomodoro/pet apps to automate achievement progress.
• Define threshold values per achievement for auto-unlocking.
• Add unit and integration tests for API and manager logic.
• Create frontend badge UI components in React.

---

Final Notes

Thank you so much for your review!! Let me know if there's anything I can do for you ^^;

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 81.16%. Comparing base (b24c564) to head (d2c8a67).
Report is 97 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #185       +/-   ##
===========================================
+ Coverage   63.92%   81.16%   +17.23%     
===========================================
  Files          15       17        +2     
  Lines         596      775      +179     
  Branches       45       51        +6     
===========================================
+ Hits          381      629      +248     
+ Misses        194      123       -71     
- Partials       21       23        +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[omgdory]

🔍 Peer Review

---

✅ What Looks Great

• Requests need the appropriate authentication level (permission class).
• Admin panel implementation is sophisticated, making the testing very easy to follow.
• Code is clean and modular. Corresponding views look good with related URLs updated.

---

💡 Suggestions for Improvement (if any)

• Making the progress field some type of percentage (out of 100%) rather than a positive integer.
• Refactoring the code use allocated responsibility from managers.py rather than re-writing them in views.py.
• Everything else mentioned in the body of your PR!

---

🧪 Tested This Feature

Checklist:

• Do the endpoints return correct data and status codes?
• Is logic properly encapsulated in the manager, not in views?
• Do serializers validate and serialize data accurately?
• Are naming conventions and code style consistent?

---

🔄 Next Steps

• See "Suggestions for Improvement" above.
• Create tests to follow test-driven development practices.
• Continue to other features/issues!

---

🚀 Final Thoughts

Great work! Can't wait to see this live 🦅

[aviendha-andrus]

🔍 Peer Review: Great Job on This PR!

Hey Allison 👋 — just finished reviewing your PR titled "Added Achievement System For Gaming Stats API Endpoints". Here’s my feedback:

---

✅ What Looks Great

• The core feature has been implemented cleanly
• The PR description is thorough, clear, and fully aligned with our PR template making it easy to review.
• You've properly linked to the related issue (#108) and included a helpful testing guide.

---

💡 Suggestions for Improvement (if any)

• Consider adding unit and integration tests for StudentAchievementManager methods to ensure long-term reliability.
• The PATCH endpoint for progress updates could include validation for threshold logic, if not already done in the manager.
• As noted in your Next Steps, hooking this into signals (from Pomodoro/pet models) will streamline the gamified experience.
• Include a UML diagram next time for PRs introducing multiple interdependent models and logic layers — really helps visualize flow.
• Add an AchievementCreateAPIView to allow admins or staff users to create new achievements through the API.
  • Right now, achievements must be manually added via the admin panel or database.
  • Creating a CreateAPIView and adding it to urls.py (e.g., path('achievements/create/', ...)) will make future admin tools or interfaces easier to build.
  • This will also help QA test full achievement flow end-to-end using curl or Postman.

---

🧪 Tested This Feature

I ran the following test steps:

• ✅ Accessed the /achievements/ endpoint and verified the listing of all achievements.
• ✅ POSTed to /achievements/student_achievements/ with test data to award an achievement.
• ✅ Fetched a student’s achievements via GET /achievements/student_achievements/{student_id}/.

Everything behaved as expected 🎉

---

🔄 Next Steps

• Looking forward to seeing unit tests in the next PR!
• Consider implementing the AchievementCreateAPIView to complete the admin-side creation cycle.
• Make sure you make migrations before merging!

---

🚀 Final Thoughts

Great job with this implementation! This looks really great :3