feat: Add Rating sample (alongside Archive sample)

Backend:
- UnitRating (per-user 1-5 star rating of a unit; uses opaque_keys
  UsageKeyField) and CourseAverageRating (cached per-course aggregate
  kept in sync incrementally on writes, fully recomputed on full course
  publish).
- DRF endpoints at /api/v1/unit-rating/ and /api/v1/course-average-rating/.
- Second filter pipeline step on Learner Home /init injects averageStars
  and ratingCount onto each courseRun, alongside the existing
  isArchivedByLearner.
- XBLOCK_PUBLISHED handler recomputes only when block_type == "course"
  so unit/section publishes don't re-aggregate.
- Admin registrations for both new models.

Frontend:
- RateThisContent: per-unit star widget for frontend-app-learning's
  sequence_container.v1 slot.
- CourseCardRating: per-course average display, embedded inside the
  Archive CourseList card (rather than the platform course-card slot).
  Renders "(N ratings)" even at 0 so the wiring is visibly working
  before any ratings exist.

Tutor plugin:
- Second PLUGIN_SLOTS entry registers RateThisContent in the learning
  MFE, next to the existing learner-dashboard course_list slot.

Frontend README:
- env.config.jsx instructions rewritten around a single shared file
  that covers both slots and gets copied into each MFE root.

A handful of @@todos remain in-code for follow-up POC cleanup.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: kdmccormick

backend-plugin-sample/src/openedx_plugin_sample/admin.py

@@ -13,7 +13,11 @@
 
 from django.contrib import admin
 
-from openedx_plugin_sample.models import CourseArchiveStatus
+from openedx_plugin_sample.models import (
+    CourseArchiveStatus,
+    CourseAverageRating,
+    UnitRating,
+)
 
 
 @admin.register(CourseArchiveStatus)
@@ -53,3 +57,48 @@ def course_key(self, obj: CourseArchiveStatus) -> str:
         operators recognize.
         """
         return str(obj.course_run.course_key)
+
+
+@admin.register(UnitRating)
+class UnitRatingAdmin(admin.ModelAdmin):
+    """Admin for individual user-by-unit ratings."""
+
+    list_display = ("usage_key", "user", "stars", "course_key", "updated_at")
+    list_filter = ("stars",)
+    search_fields = (
+        "usage_key",
+        "course_run__course_key",
+        "user__username",
+        "user__email",
+    )
+    raw_id_fields = ("course_run", "user")
+    readonly_fields = ("created_at", "updated_at")
+    ordering = ("-updated_at",)
+
+    @admin.display(description="Course key", ordering="course_run__course_key")
+    def course_key(self, obj: UnitRating) -> str:
+        return str(obj.course_run.course_key)
+
+
+@admin.register(CourseAverageRating)
+class CourseAverageRatingAdmin(admin.ModelAdmin):
+    """Admin for the cached per-course rating aggregate."""
+
+    list_display = (
+        "course_key",
+        "average_stars",
+        "rating_count",
+        "sum_stars",
+        "updated_at",
+    )
+    search_fields = ("course_run__course_key",)
+    raw_id_fields = ("course_run",)
+    # @@TODO: Right now sum/count/average are editable, which is useful for POC
+    # debugging but in production they should be readonly so operators don't
+    # accidentally desync them from the underlying UnitRating rows.
+    readonly_fields = ("updated_at",)
+    ordering = ("-updated_at",)
+
+    @admin.display(description="Course key", ordering="course_run__course_key")
+    def course_key(self, obj: CourseAverageRating) -> str:
+        return str(obj.course_run.course_key)

backend-plugin-sample/src/openedx_plugin_sample/migrations/0002_courseaveragerating_unitrating.py

@@ -0,0 +1,46 @@
+# Generated by Django 5.2.13 on 2026-05-14 19:28
+
+import django.core.validators
+import django.db.models.deletion
+import opaque_keys.edx.django.models
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('openedx_catalog', '0001_initial'),
+        ('openedx_plugin_sample', '0001_initial'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='CourseAverageRating',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('sum_stars', models.PositiveIntegerField(default=0)),
+                ('rating_count', models.PositiveIntegerField(default=0)),
+                ('average_stars', models.FloatField(blank=True, help_text='Null when rating_count == 0.', null=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('course_run', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, related_name='average_rating', to='openedx_catalog.courserun')),
+            ],
+        ),
+        migrations.CreateModel(
+            name='UnitRating',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('usage_key', opaque_keys.edx.django.models.UsageKeyField(db_index=True, help_text="e.g. 'block-v1:edX+DemoX+Demo_Course+type@vertical+block@abc123'", max_length=255)),
+                ('stars', models.PositiveSmallIntegerField(validators=[django.core.validators.MinValueValidator(1), django.core.validators.MaxValueValidator(5)])),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('course_run', models.ForeignKey(help_text='Denormalized from usage_key so we can aggregate per course cheaply.', on_delete=django.db.models.deletion.CASCADE, related_name='unit_ratings', to='openedx_catalog.courserun')),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='unit_ratings', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'ordering': ['-updated_at'],
+                'constraints': [models.UniqueConstraint(fields=('user', 'usage_key'), name='unique_user_unit_rating')],
+            },
+        ),
+    ]

backend-plugin-sample/src/openedx_plugin_sample/models.py

@@ -1,9 +1,20 @@
 """
 Database models for openedx_plugin_sample.
+
+Two independent features live side-by-side in this app:
+
+* ``CourseArchiveStatus`` -- per-learner "this course is archived" flag,
+  consumed by the Learner Dashboard course-card listing.
+* ``UnitRating`` + ``CourseAverageRating`` -- learners optionally rate units
+  1-5 stars; we keep a cached per-course average that is updated incrementally
+  on each write and fully recomputed when a course is republished.
 """
 
 from django.contrib.auth import get_user_model
-from django.db import models
+from django.core.validators import MaxValueValidator, MinValueValidator
+from django.db import models, transaction
+from django.db.models import Count, Sum
+from opaque_keys.edx.django.models import UsageKeyField
 from openedx_catalog.models import CourseRun
 
 
@@ -68,3 +79,135 @@ class Meta:
                 fields=["course_run", "user"], name="unique_user_course_archive_status"
             )
         ]
+
+
+class UnitRating(models.Model):
+    """
+    A single learner's 1-5 star rating of one unit (vertical block).
+
+    .. no_pii: Stores no PII directly, only FKs to user and course_run.
+    """
+
+    user = models.ForeignKey(
+        get_user_model(),
+        on_delete=models.CASCADE,
+        related_name="unit_ratings",
+    )
+    course_run = models.ForeignKey(
+        CourseRun,
+        on_delete=models.CASCADE,
+        related_name="unit_ratings",
+        help_text="Denormalized from usage_key so we can aggregate per course cheaply.",
+    )
+    usage_key = UsageKeyField(
+        max_length=255,
+        db_index=True,
+        help_text="e.g. 'block-v1:edX+DemoX+Demo_Course+type@vertical+block@abc123'",
+    )
+    stars = models.PositiveSmallIntegerField(
+        validators=[MinValueValidator(1), MaxValueValidator(5)],
+    )
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        constraints = [
+            models.UniqueConstraint(
+                fields=["user", "usage_key"],
+                name="unique_user_unit_rating",
+            ),
+        ]
+        ordering = ["-updated_at"]
+
+    def __str__(self):
+        return f"{self.user.username} rated {self.usage_key}: {self.stars}*"
+
+
+class CourseAverageRating(models.Model):
+    """
+    Cached aggregate of all UnitRatings for a CourseRun.
+
+    Kept in sync incrementally by ``apply_rating_delta`` (called from the API on
+    create/update/destroy) and fully recomputed by ``recompute_from_scratch``
+    on course publish.
+
+    .. no_pii: Aggregate only, no per-user data.
+    """
+
+    course_run = models.OneToOneField(
+        CourseRun,
+        on_delete=models.CASCADE,
+        related_name="average_rating",
+    )
+    # Stored sum + count enables O(1) incremental updates without re-aggregating.
+    sum_stars = models.PositiveIntegerField(default=0)
+    rating_count = models.PositiveIntegerField(default=0)
+    average_stars = models.FloatField(
+        null=True,
+        blank=True,
+        help_text="Null when rating_count == 0.",
+    )
+    updated_at = models.DateTimeField(auto_now=True)
+
+    def __str__(self):
+        if self.rating_count == 0:
+            return f"{self.course_run.course_key}: no ratings yet"
+        return (
+            f"{self.course_run.course_key}: {self.average_stars:.2f}* "
+            f"({self.rating_count} ratings)"
+        )
+
+    def _refresh_average(self):
+        """Recompute ``average_stars`` from current ``sum_stars`` / ``rating_count``."""
+        if self.rating_count == 0:
+            self.average_stars = None
+        else:
+            self.average_stars = self.sum_stars / self.rating_count
+
+    def recompute_from_scratch(self, allowed_usage_keys=None):
+        """
+        Rebuild sum/count/average by scanning UnitRating rows for this course_run.
+
+        Args:
+            allowed_usage_keys: Optional iterable of usage_keys to restrict the
+                aggregation to. Intended for the publish handler so that
+                ratings for units that have since been removed are excluded.
+                If None, all UnitRating rows for the course_run are included.
+        """
+        qs = UnitRating.objects.filter(course_run=self.course_run)
+        if allowed_usage_keys is not None:
+            qs = qs.filter(usage_key__in=list(allowed_usage_keys))
+        agg = qs.aggregate(total=Sum("stars"), n=Count("id"))
+        self.sum_stars = agg["total"] or 0
+        self.rating_count = agg["n"] or 0
+        self._refresh_average()
+        self.save()
+
+
+def apply_rating_delta(course_run, *, old_stars, new_stars):
+    """
+    Update the cached CourseAverageRating to reflect a single rating change.
+
+    Pass ``old_stars=None`` for a brand-new rating, ``new_stars=None`` for a
+    deletion, or both non-None for an update.
+
+    Wrapped in ``transaction.atomic`` + ``select_for_update`` so concurrent
+    rating writes against the same course don't race on the cached aggregate.
+    """
+    if old_stars is None and new_stars is None:
+        return
+
+    with transaction.atomic():
+        avg, _ = CourseAverageRating.objects.select_for_update().get_or_create(
+            course_run=course_run,
+        )
+        if old_stars is None:
+            avg.sum_stars += new_stars
+            avg.rating_count += 1
+        elif new_stars is None:
+            avg.sum_stars = max(0, avg.sum_stars - old_stars)
+            avg.rating_count = max(0, avg.rating_count - 1)
+        else:
+            avg.sum_stars = max(0, avg.sum_stars - old_stars) + new_stars
+        avg._refresh_average()
+        avg.save()

backend-plugin-sample/src/openedx_plugin_sample/pipeline.py

@@ -42,7 +42,7 @@
 import crum
 from openedx_filters.filters import PipelineStep
 
-from .models import CourseArchiveStatus
+from .models import CourseArchiveStatus, CourseAverageRating
 
 logger = logging.getLogger(__name__)
 
@@ -89,3 +89,50 @@ def run_filter(self, serialized_courserun, **kwargs):  # pylint: disable=argumen
                 "isArchivedByLearner": is_archived_by_learner,
             },
         }
+
+
+class AddAverageRatingToLearnerHomeCourseRun(PipelineStep):
+    """
+    Decorate each courseRun in the Learner Home /init response with the cached
+    average rating, so the Archive course-card display can render stars without
+    a second API call.
+
+    Filter name: ``org.openedx.learning.home.courserun.api.rendered.started.v1``
+    """
+
+    def run_filter(self, serialized_courserun, **kwargs):  # pylint: disable=arguments-differ
+        """
+        Args:
+            serialized_courserun (dict): One courseRun from the /init serializer.
+                Reads ``courseId``; passes all other fields through unchanged.
+
+        Returns:
+            dict: ``{"serialized_courserun": <updated dict>}`` with two new keys
+                added:
+                  - ``averageStars`` (float or None) -- None when no ratings exist
+                  - ``ratingCount`` (int)            -- 0 when no ratings exist
+        """
+        course_id = serialized_courserun.get("courseId")
+        if not course_id:
+            return {"serialized_courserun": serialized_courserun}
+
+        # @@TODO: looking up one row per courseRun is fine for a dashboard with a
+        # handful of courses but will N+1 on long course lists. A prefetch in
+        # the upstream serializer (or a bulk lookup here) would be the prod fix.
+        try:
+            avg = CourseAverageRating.objects.get(
+                course_run__course_key=course_id,
+            )
+            average_stars = avg.average_stars
+            rating_count = avg.rating_count
+        except CourseAverageRating.DoesNotExist:
+            average_stars = None
+            rating_count = 0
+
+        return {
+            "serialized_courserun": {
+                **serialized_courserun,
+                "averageStars": average_stars,
+                "ratingCount": rating_count,
+            },
+        }