US-005: Free Catalog With Pro Items

[Mateus-Mannes]

Summary

Update the exercise catalog so Free and anonymous users can browse the full catalog while only the latest 18 global exercises are directly playable. Older exercises remain visible as Pro items with an inviting Pro badge and upgrade modal entry point. Pro users see all cards as playable.

Key Changes

• Extend catalog API contract:
  • Add requiresPro: boolean or accessLevel: "free" | "pro" to ExerciseListItemDto.
  • Compute free access from the latest 18 global propositions ordered by CreatedAt desc, Id desc, before filters and before visual topic/level spread reordering.
  • Keep totalCount as the full filtered catalog count.
  • This story only marks catalog access; direct detail/audio enforcement remains US-006/US-007.
• Update Angular catalog behavior:
  • Add access metadata to the local Exercise model.
  • Use US-001 session entitlement to determine whether Pro items are restricted for the current user.
  • Pro users render all exercise cards as normal links.
  • Free/anonymous users can click latest-18 free cards normally.
  • Free/anonymous users clicking Pro cards stay on the catalog and open the Pro upgrade modal.
• Update card UX:
  • Keep Pro cards readable and browsable.
  • Use a Pro/subscription-style badge or icon, not lock-focused language.
  • Suggested icon: workspace_premium or auto_awesome.
  • Suggested badge text: Pro.
  • Avoid making older cards feel disabled or hidden.
• Add Pro upgrade modal integration:
  • Modal explains briefly that Pro unlocks the full catalog and AI correction.
  • Logged-in Free users see a CTA to subscribe/start checkout.
  • Anonymous users see a CTA to log in first with returnUrl set to the current catalog URL and source=pro_catalog_modal.
  • Modal has a clear dismiss action so browsing state is preserved.
• Apply to both catalog usages:
  • /exercises gets full Pro item behavior.
  • Home “Latest Exercises” remains compatible; because it shows latest 9, those should normally render as free-accessible.

Observation / Dependency

• The Pro upgrade modal in US-005 should not define the final pricing/plans comparison UI from scratch.
• US-005 should provide the modal integration point only.
• The reusable Free vs Pro comparison component and standalone /pricing or /plans page should be handled in US-016.
• Avoid duplicating long-form Pro benefits copy in US-005; keep copy minimal until US-016 centralizes plan messaging.

Test Plan

• Backend tests:
  • Latest 18 global propositions are returned as free-accessible.
  • Older propositions are returned as Pro items.
  • Topic/level filters do not redefine the free window.
  • Newest/oldest sorting does not change which 18 items are free.
  • Pagination keeps the full filtered totalCount.
• Angular tests:
  • Free/anonymous Pro cards show Pro badge and open the modal instead of navigating.
  • Pro users see API Pro items as normal clickable cards.
  • Modal CTA starts checkout for authenticated Free users when US-002 is available.
  • Modal CTA sends anonymous users to login with return URL and source.
  • Existing free card navigation and initial proposition state still work.

Assumptions

• US-001 session entitlement exists before this starts.
• US-002 checkout start endpoint exists before the logged-in modal CTA is fully wired; otherwise use the same service contract and complete wiring with US-002.
• User-facing language should use “Pro” / “Unlock with Pro” / premium-access wording rather than “locked.”
• This is a catalog visibility story only; direct URL enforcement is handled by US-006.