Serve student resources from books/resources/ and match table markers by id (#1779)

FacultyResourcesSerializer omitted book_student_resources, so table cells
with resource_type 'Student' could never resolve client-side against the
resources API — os-webview had faculty resources but no student ones to
match against. Add it with the same hidden-filtering and ?x=y redaction as
the faculty rows, but flattened to resource_heading/resource_description/
resource_unlocked to match the shape os-webview already reads from the Book
page API for student resources.

Also give the table's resource_ref marker a resource_id (the through-row
pk, equal to the id books/resources/ now serializes for the same row).
Heading-only matching is fragile — punctuation differences between the CMS
and the resources API can silently miss a match — so the frontend can now
match by id first and fall back to heading only for already-cached table
JSON (up to 30 days old) that predates resource_id.

Author: mwvolo

CLAUDE.md

@@ -173,11 +173,15 @@ its file URL. The per-request `?x=y` redaction in `books/serializers.py` cannot
 work here: `get_api_representation` runs with no user and its output is cached and
 served to every visitor.
 
-The cell also carries a `resource_ref` marker (book slug/id, heading, resource
-type) that os-webview uses to swap in the real per-user resource box client-side.
-Renaming those keys breaks that override — and note os-webview camelCases every
-key of a page payload before a block sees it, so it reads them as
-`bookSlug`/`bookId`/`resourceType`.
+The cell also carries a `resource_ref` marker (book slug/id, resource id, heading,
+resource type) that os-webview uses to swap in the real per-user resource box
+client-side. It matches the marker back to a `books/resources/` row by
+`resource_id` (the through-row pk) first, falling back to heading matching when
+`resource_id` is absent — either a synthetic row (e.g. Web PDF) or already-cached
+table JSON (up to 30 days old) from before `resource_id` existed. Renaming those
+keys breaks that override — and note os-webview camelCases every key of a page
+payload before a block sees it, so it reads them as
+`bookSlug`/`bookId`/`resourceId`/`resourceType`.
 
 **Adding config to a nested StreamField block requires a migration.** Wagtail
 bakes each StreamField's full block-tree deconstruction into migration state, so

books/serializers.py

@@ -46,10 +46,36 @@ def to_representation(self, instance):
         for resource in book_video_faculty_resources:
             # remove listing of linked book data
             resource['book_video_faculty_resource'] = {}
+
+        ret['book_student_resources'] = [r for r in ret['book_student_resources'] if not r.get('hidden')]
+
+        book_student_resources = ret['book_student_resources']
+        for resource in book_student_resources:
+            # remove listing of linked book data
+            resource['book_student_resource'] = {}
+            # the resource snippet is SET_NULL, so a deleted snippet leaves this None
+            snippet = resource['resource'] or {}
+            # os-webview resolves student rows against the flat shape the Book
+            # page API emits (StudentResources.resource_heading/_description/
+            # _unlocked), not the nested `resource` dict depth=2 produces here.
+            resource['resource_heading'] = snippet.get('heading')
+            resource['resource_description'] = snippet.get('description')
+            resource['resource_unlocked'] = snippet.get('unlocked_resource')
+            # if parameter sent, clear links to locked student resources
+            if x_param and x_param == 'y':
+                if not snippet.get('unlocked_resource'):
+                    if resource['link_document'] is not None:
+                        resource['link_document']['file'] = ''
+                    if resource['link_page'] is not None:
+                        resource['link_page']['url_path'] = ''
+                    if resource['link_external'] is not None:
+                        resource['link_external'] = ''
         return ret
 
     class Meta:
         model = Book
-        fields = ('book_video_faculty_resources','book_orientation_faculty_resources','book_faculty_resources','audiobook_link')
-        read_only_fields = ('book_video_faculty_resources','book_orientation_faculty_resources','book_faculty_resources','audiobook_link')
+        fields = ('book_video_faculty_resources','book_orientation_faculty_resources','book_faculty_resources',
+                  'audiobook_link','book_student_resources')
+        read_only_fields = ('book_video_faculty_resources','book_orientation_faculty_resources','book_faculty_resources',
+                            'audiobook_link','book_student_resources')
         depth=2

books/tests.py

@@ -608,6 +608,68 @@ def test_hidden_faculty_resources_filtered_from_resources_api(self):
         self.assertEqual(len(response.data['book_faculty_resources']), 1)
         self.assertEqual(response.data['book_faculty_resources'][0]['link_text'], 'Visible')
 
+    def test_student_resources_available_from_resources_api(self):
+        """book_student_resources must be served with the same flat shape
+        (resource_heading/resource_description/resource_unlocked) os-webview
+        already reads from the Book page API, plus its own id, hidden filtered
+        out, and locked links redacted only when verified (?x=y)."""
+        with vcr.use_cassette('fixtures/vcr_cassettes/books_univ_physics.yaml'):
+            book_index = BookIndex.objects.all()[0]
+            root_page = Page.objects.get(title="Root")
+            book = Book(title="University Physics",
+                        slug="university-physics-student",
+                        cnx_id='031da8d3-b525-429c-80cf-6c8ed997733a',
+                        salesforce_book_id='a0ZU0000008pyvQMAQ',
+                        description="Test Book",
+                        cover=self.test_doc,
+                        title_image=self.test_doc,
+                        publish_date=datetime.date.today(),
+                        locale=root_page.locale
+                        )
+            book_index.add_child(instance=book)
+
+        locked_resource = snippets.models.StudentResource(heading="Study Guide",
+                                                           description="Solutions",
+                                                           unlocked_resource=False)
+        locked_resource.save()
+
+        hidden_resource = snippets.models.StudentResource(heading="Hidden Guide",
+                                                           description="Hidden",
+                                                           unlocked_resource=True)
+        hidden_resource.save()
+
+        row = BookStudentResources.objects.create(link_external="https://openstax.org/solutions",
+                                                   link_text="Get it", resource=locked_resource,
+                                                   book_student_resource=book)
+        BookStudentResources.objects.create(link_external="https://openstax.org/hidden",
+                                            link_text="Hidden", resource=hidden_resource,
+                                            book_student_resource=book, hidden=True)
+
+        # hidden rows filtered out, flat fields present, id present
+        response = self.client.get('/apps/cms/api/books/resources/?slug=university-physics-student')
+        student_resources = response.data['book_student_resources']
+        self.assertEqual(len(student_resources), 1)
+        resource = student_resources[0]
+        self.assertEqual(resource['id'], row.pk)
+        self.assertEqual(resource['resource_heading'], 'Study Guide')
+        self.assertEqual(resource['resource_description'], 'Solutions')
+        self.assertFalse(resource['resource_unlocked'])
+        # book back-reference cleared, matching the faculty resources shape
+        self.assertEqual(resource['book_student_resource'], {})
+        # unverified: locked resource's link stays intact
+        self.assertEqual(resource['link_external'], 'https://openstax.org/solutions')
+
+        # verified flag on a locked resource: link redacted
+        response = self.client.get('/apps/cms/api/books/resources/?slug=university-physics-student&x=y')
+        self.assertEqual(response.data['book_student_resources'][0]['link_external'], '')
+
+        # verified flag on an unlocked resource: link stays intact
+        locked_resource.unlocked_resource = True
+        locked_resource.save()
+        response = self.client.get('/apps/cms/api/books/resources/?slug=university-physics-student&x=y')
+        self.assertEqual(response.data['book_student_resources'][0]['link_external'],
+                         'https://openstax.org/solutions')
+
     def test_hidden_faculty_resources_filtered_from_pages_api(self):
         """HiddenFilterChildRelationField excludes hidden faculty resources from Wagtail Pages API."""
         with vcr.use_cassette('fixtures/vcr_cassettes/books_univ_physics.yaml'):

pages/table_sources.py

@@ -258,7 +258,10 @@ def _resource_link_cell(r):
             return {'text': '', 'url': ''}
         # Marker for os-webview's progressive-enhancement override: it resolves
         # the real per-user link client-side (where verified-instructor status
-        # is visible) and matches this cell back to a resource by heading.
+        # is visible) and matches this cell back to a resource, by id first
+        # (equal to the books/resources/ row's own id) with heading as a
+        # fallback for already-cached table JSON (up to 30 days old) that
+        # predates resource_id.
         # book_slug is computed the same way as the fallback url above, so the
         # two can never drift apart.
         return {
@@ -272,6 +275,12 @@ def _resource_link_cell(r):
                     # download-tracking record; it is absent from the
                     # books/resources/ payload, so it has to ride along here.
                     'book_id': next(iter(getattr(r, '_book_ids', [])), None),
+                    # r is the through-model row (BookFacultyResources/
+                    # BookStudentResources); its pk equals the `id` the
+                    # resources API serializes for the same row. A synthetic
+                    # row (no real pk) yields None here, and the frontend
+                    # falls back to heading matching.
+                    'resource_id': getattr(r, 'pk', None),
                     'heading': r.resource_heading if r.resource else '',
                     'resource_type': getattr(r, '_resource_type', ''),
                 },

pages/tests/test_table_sources.py

@@ -931,6 +931,9 @@ def test_locked_resource_link_points_at_book_page_no_real_url_leaks(self):
         marker = next(c for c in cta['config'] if c['type'] == 'resource_ref')
         # trackLink() needs the numeric book id; it is not in the resources API.
         self.assertEqual(marker['value']['book_id'], book.pk)
+        # resource_id is the through-row pk, matching the id the
+        # books/resources/ endpoint serializes for the same row.
+        self.assertEqual(marker['value']['resource_id'], row.pk)
         serialized = json.dumps(cell)
         self.assertNotIn(real_url, serialized)
         self.assertNotIn('Download', serialized)  # original CTA text must not leak either
@@ -939,6 +942,7 @@ def test_locked_resource_link_points_at_book_page_no_real_url_leaks(self):
         self.assertEqual(cta['config'], [{
             'type': 'resource_ref',
             'value': {'book_slug': book.slug, 'book_id': book.pk,
+                      'resource_id': row.pk,
                       'heading': 'Locked Guide',
                       'resource_type': 'Instructor'},
         }])
@@ -957,7 +961,7 @@ def test_locked_student_resource_links_to_student_tab(self):
         locked = StudentResource.objects.create(
             heading='Locked Student Guide', description='<p>x</p>',
             locale=book.locale, unlocked_resource=False)
-        BookStudentResources.objects.create(
+        row = BookStudentResources.objects.create(
             book_student_resource=book, resource=locked,
             link_external='https://example.com/secret.pdf')
         result = resolve_book_resources({
@@ -971,10 +975,40 @@ def test_locked_student_resource_links_to_student_tab(self):
         self.assertEqual(cta['config'], [{
             'type': 'resource_ref',
             'value': {'book_slug': book.slug, 'book_id': book.pk,
+                      'resource_id': row.pk,
                       'heading': 'Locked Student Guide',
                       'resource_type': 'Student'},
         }])
 
+    def test_resource_ref_marker_resource_id_matches_resources_api_row_id(self):
+        # The frontend matches a marker back to a books/resources/ row by id
+        # first (heading is only a fallback for pre-resource_id cached JSON),
+        # so the two ids must agree.
+        from books.models import BookFacultyResources
+        from snippets.models import FacultyResource
+        from pages.table_sources import resolve_book_resources
+        from books.serializers import FacultyResourcesSerializer
+        from django.test import RequestFactory
+        with vcr.use_cassette('fixtures/vcr_cassettes/books_univ_physics.yaml'):
+            book = self._make_book()
+        locked_snippet = FacultyResource.objects.create(
+            heading='Cross-checked Guide', description='<p>x</p>', locale=book.locale)
+        row = BookFacultyResources.objects.create(
+            book_faculty_resource=book, resource=locked_snippet,
+            link_external='https://example.com/g.pdf', link_text='Go')
+        result = resolve_book_resources({
+            'books': [book], 'resource_type': 'instructor', 'audience': '',
+            'columns': [{'field': 'link', 'header': '', 'type': ''}],
+        })
+        marker = result['rows'][0]['cells'][0]['cta'][0]['config'][0]['value']
+
+        request = RequestFactory().get('/apps/cms/api/books/resources/', {'slug': book.slug})
+        serializer = FacultyResourcesSerializer(book, context={'request': request})
+        api_row = serializer.data['book_faculty_resources'][0]
+
+        self.assertEqual(marker['resource_id'], row.pk)
+        self.assertEqual(marker['resource_id'], api_row['id'])
+
     def test_book_slugs_stay_aligned_with_titles_when_row_shared(self):
         # A resource shared across books merges into one row listing both books;
         # _book_slugs must track _book_titles so the link targets a real book.