Add usage analytics scopes for admin dashboards

[rameerez]

Summary

• Add scopes for analyzing API key usage patterns in admin dashboards
• never_used, used, by_requests, by_last_used, stale(period), inactive_for_30_days
• Add friendly aliases: most_used, recently_used

Test plan

• All 214 tests pass locally
• CI passes
• Verify scopes work with Madmin admin framework

🤖 Generated with Claude Code

[claude]

Pull Request Review: Add usage analytics scopes for admin dashboards

Overall Assessment

This is a well-implemented PR that adds valuable analytics capabilities for admin dashboards. The code quality is high, tests are comprehensive, and the feature is well-documented. All CI tests pass successfully. ✅

---

Code Quality & Best Practices ✅

Strengths:

• Clear, well-documented scopes with helpful comments
• Proper use of ActiveRecord scope chaining
• Follows Rails naming conventions
• Good use of class methods (aliases) for improved DX
• Code is DRY and maintainable

Minor suggestions:

1. Database compatibility: The by_last_used scope uses Arel.sql with a CASE statement for NULLS LAST behavior. This works well but could benefit from an inline comment explaining the database compatibility approach.

---

Test Coverage ✅

Excellent test coverage:

• 125 new test lines for 34 new code lines (3.7:1 ratio)
• All edge cases covered: null handling, ordering behavior, time-based filtering, active vs inactive key filtering, alias methods
• Tests are clear and descriptive
• Good use of fixtures and test data setup

---

Performance Considerations ⚠️

Recommendations for production use:

1. N+1 queries: When using these scopes in admin dashboards with associations, remember to eager load: ApiKeys::ApiKey.stale.includes(:owner)

2. Index recommendations: For optimal performance, consider adding database indexes in a future migration:

   • add_index :api_keys_api_keys, :last_used_at
   • add_index :api_keys_api_keys, :requests_count

3. Large dataset performance: Monitor query performance on large tables with the stale scope.

---

Security Concerns ✅

No security issues identified:

• Scopes don't expose sensitive data
• No SQL injection risks (proper use of parameterization)
• Respects existing access controls (works with active scope)

---

Potential Bugs/Issues 🔍

Minor consideration:

The .stale scope includes never-used keys (where last_used_at IS NULL) in results. This means a brand new key created 1 hour ago that has never been used will be marked as stale. This makes sense for cleanup purposes (find keys that aren't being used), but verify this aligns with product requirements.

---

Documentation & Naming ✅

Well done:

• Inline comments clearly explain the purpose of each scope
• Helpful section header
• Scope names are intuitive
• Aliases provide alternative naming that matches common admin framework conventions

Suggestion:

• Consider adding these new scopes to the README.md documentation under a "Usage Analytics" section for discoverability

---

Recommendations

1. Add README documentation with usage examples
2. Consider database indexes for last_used_at and requests_count in a follow-up PR
3. Monitor performance in production on large datasets
4. Verify stale behavior matches product requirements

---

Conclusion

This is a high-quality PR that's ready to merge. The implementation is solid, tests are comprehensive, and the feature adds valuable functionality for admin dashboards. The suggestions above are minor optimizations and considerations for future enhancements.

Recommendation: ✅ Approve and merge

Great work! 🎉