[back] feat: add the suggestions/tocompare API

[GresilleSiffle]

related issues #1785

---

Description

This PR adds the /me/suggestions/{poll}/tocompare/ API.

This endpoint aims to suggest to the logged-in user a list of entities for comparison. In the future updates, the namespace /me/suggestions/ could be extended to include new endpoints with different purposes:

# a list of entities to watch / to read / etc.
/me/suggestions/{poll}/towatch/

# a list of comparisons (or a single comparison) to make (to connect the personal graph, the collective graph, etc.)
/me/suggestions/{poll}/comparisons/

The strategies

The added endpoint is flexible and can suggest entities using different strategies. It's possible to add new strategy by creating a class inheriting from the abstract base class ContributionSuggestionStrategy and adding it to the API view. The default strategy that comes with this PR, called "classic", has several goals:

• be relatively simple
• return a list of entities the user "may want" to compare
• slightly mimic the behaviour of the front end's Auto button (while correcting its limitations)

The classic strategy is simple because it is based on simple heuristics: entities the user may want to compare are entities he/she started comparing or are in his/her rate-later list.

We suppose that the entities the user may want to compare in priority are those he/she started to compare few times, but not enough regarding the setting rate_later__auto_remove. We also suppose that the rate-later is a also good place to find those kind of entities, but we consider the rate-later slightly less reliable because depending on the users' habits it can be used as a watch-later list instead.

Finally, some flaws and limitations of the current frond end's Auto button have been fixed:

(a) We consider the compared pool as slightly more reliable than the rate-later list. The Auto button returns 75 % of entities from the rate-later list, the API returns 16 / 20 of entities from a combination of compared list and rate-later list.

(b) The complete compared list and rate-later list are queried for a better randomness, instead of just 100 enties.

(c) The recommended entities that represent 4 / 20 of the results come from the last month recommendations. Entities compared more than rate_later__auto_remove are excluded for a better experience. Future improvement: use the user's preferred languages.

to-do

serializer

• the new serializers looks very generic and may be redundant with others
  • if relevant, move them to the correct file and/or rename them

API endpoint

• choose a name (random/tocompare or suggestions/tocompare or something else)

EntityToCompare view

• document the route
• add the parameter strategy (default ToCompareStrategy.CLASSIC)
• handle empty results returned by the strategy

ClassicEntitySuggestionStrategy

• implement the pool: rate-later
• implement the pool: reco last month
  • use the setting rate_later__auto_remove
• implement the pool: reco all time
  • use the setting rate_later__auto_remove
• add randomness to determine the selected pool all pool are selected to build a list of entities

test

• add a test case for the strategy
• add a test case for the API

future improvements

Make the ClassicEntitySuggestionStrategy behave differently for new and advanced users. The user profile can be determined by his/her number of comparisons, a low number indicates a new users, and high number indicates an advance users.

The pool rate-later could be replaced by "tutorial" entities for new users. A new additional pool "to connect" could be added for advanced users.

Checklist

• I added the related issue(s) id in the related issues section (if any)
  • if not, delete the related issues section
• I described my changes and my decisions in the PR description
• I read the development guidelines of the CONTRIBUTING.md
• The tests pass and have been updated if relevant
• The code quality check pass

[amatissart]

I have minor comments about the implementation, but overall the approach looks good to me 👍