feat(api): object history read endpoint — Django admin parity (#155 read half) (#162)

Adds GET /api/v1/<app>/<model>/<pk>/history/ — the LogEntry timeline
the legacy admin's History button shows. Completes #155 backend
(the emit half landed in #158); the SPA timeline UI is the remaining
frontend slot.

- `audit.py` (NEW, top-level) — `object_log_entries(obj)` returns the
  LogEntry queryset (newest-first, user pre-fetched). Lives OUTSIDE
  `api/` on purpose: LogEntry is Django's own framework audit table,
  not a consumer model, so the `get_queryset` rule (B-2 / S-15) is
  categorically inapplicable. Django's own `history_view` reads it the
  same way. Keeping it in a dedicated single-responsibility module
  makes the distinction explicit rather than special-casing it inside
  the consumer-model API layer.
- `api/views/history.py` (NEW) — `HistoryView`: staff gate →
  resolve_model → object loaded via get_queryset → per-object
  has_view_permission → paginated timeline. 404 (no oracle) on
  missing/unviewable. `Cache-Control: no-store`.
- `api/urls.py` — `history/` route before the instance pattern (same
  ordering caveat as panel/).

Wire shape: `{object, entries:[{id, action, action_time, user,
change_message_human, change_message_structured}], page, page_size,
total, num_pages}`.

Tests: tests/test_history.py — full auth matrix (anon/non-staff/
unregistered/bogus-pk/no-view-perm) + empty history, reflects-SPA-
write, newest-first pagination, structured-message surfacing. 9 cases.
Full suite 298 → 303.

Parity: ACCEPTANCE.md §2.9 E-18 (read half).

Co-authored-by: Martin Castro Laminrs <mcastro@laminr.ai>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

django_admin_react/api/urls.py

@@ -26,6 +26,7 @@
 from django_admin_react.api.views.create import CreateView
 from django_admin_react.api.views.destroy import DestroyView
 from django_admin_react.api.views.detail import DetailView
+from django_admin_react.api.views.history import HistoryView
 from django_admin_react.api.views.list import ListView
 from django_admin_react.api.views.registry import RegistryView
 from django_admin_react.api.views.schema import SchemaView
@@ -112,6 +113,14 @@ def delete(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpRespons
         PanelView.as_view(),
         name="panel",
     ),
+    # History sub-resource (#155) — LogEntry timeline for one object.
+    # Must precede the instance pattern so ``/history/`` isn't
+    # swallowed as part of the ``<pk>`` route.
+    path(
+        "<str:app_label>/<str:model_name>/<str:pk>/history/",
+        HistoryView.as_view(),
+        name="history",
+    ),
     path(
         "<str:app_label>/<str:model_name>/<str:pk>/",
         InstanceView.as_view(),

django_admin_react/api/views/history.py

@@ -0,0 +1,164 @@
+"""``GET /api/v1/<app>/<model>/<pk>/history/`` — object history.
+
+Wire contract: ``docs/api-contract.md`` §4 (history sub-resource).
+
+Surfaces the ``django.contrib.admin.models.LogEntry`` timeline for a
+single object — the same data the legacy admin's *History* button
+shows. Parity (#155): a Django dev's audit trail must be reachable
+from the SPA, and the entries the SPA itself writes (via the create /
+update / delete endpoints, which call ``ModelAdmin.log_*``) show up
+here alongside any earlier HTML-admin entries.
+
+Hard rules (`SECURITY.md` §3):
+
+- Rule 1:  Staff + ``AdminSite.has_permission`` gate.
+- Rule 3:  Model resolved through ``admin.site._registry`` (B-7).
+- Rule 5:  Per-object ``has_view_permission`` gate — you can only read
+           the history of an object you can view.
+- Rule 10: Object loaded through ``ModelAdmin.get_queryset(request)``
+           — never ``Model.objects.all()`` (B-2).
+- CSRF:    GET is safe; no state change.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.contrib.admin.models import ADDITION
+from django.contrib.admin.models import CHANGE
+from django.contrib.admin.models import DELETION
+from django.contrib.admin.models import LogEntry
+from django.core.paginator import Paginator
+from django.http import HttpRequest
+from django.http import HttpResponse
+from django.http import JsonResponse
+from django.views.generic import View
+
+from django_admin_react.api.permissions import forbidden_response
+from django_admin_react.api.permissions import is_admin_user
+from django_admin_react.api.registry import get_admin_site
+from django_admin_react.api.registry import resolve_model
+from django_admin_react.api.serializers import label_for
+from django_admin_react.api.writes import load_object_or_none
+from django_admin_react.api.writes import not_found_response
+from django_admin_react.audit import object_log_entries
+
+_ACTION_LABELS = {ADDITION: "addition", CHANGE: "change", DELETION: "deletion"}
+
+_DEFAULT_PAGE_SIZE = 25
+_MAX_PAGE_SIZE = 200
+
+
+class HistoryView(View):
+    """``GET /api/v1/<app_label>/<model_name>/<pk>/history/``."""
+
+    http_method_names = ["get"]
+
+    def get(
+        self,
+        request: HttpRequest,
+        app_label: str,
+        model_name: str,
+        pk: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> HttpResponse:
+        """Return the paginated ``LogEntry`` timeline for one object.
+
+        Gates: ``is_admin_user`` → ``resolve_model`` → object loaded
+        through ``get_queryset`` → ``has_view_permission(obj)``. A
+        missing object or unviewable object both return the canonical
+        404 (no oracle distinguishing "doesn't exist" from "you can't
+        see it" — ``SECURITY.md`` §3 rule 12).
+        """
+        admin_site = get_admin_site()
+        if not is_admin_user(request, admin_site=admin_site):
+            return forbidden_response(request)
+
+        resolved = resolve_model(admin_site, request, app_label, model_name)
+        if resolved is None:
+            return not_found_response()
+        model, model_admin = resolved
+
+        obj = load_object_or_none(model, model_admin, request, pk)
+        if obj is None:
+            return not_found_response()
+
+        if not model_admin.has_view_permission(request, obj):
+            return forbidden_response(request)
+
+        entries = object_log_entries(obj)
+
+        paginator = Paginator(entries, _page_size(request))
+        page_number = _page_number(request)
+        page = paginator.get_page(page_number)
+
+        body = {
+            "object": {"pk": obj.pk, "label": label_for(obj)},
+            "entries": [_serialize_entry(e) for e in page.object_list],
+            "page": page.number,
+            "page_size": paginator.per_page,
+            "total": paginator.count,
+            "num_pages": paginator.num_pages,
+        }
+        response = JsonResponse(body, status=200)
+        response["Cache-Control"] = "no-store"
+        return response
+
+
+def _serialize_entry(entry: LogEntry) -> dict[str, Any]:
+    """One ``LogEntry`` → wire shape.
+
+    ``change_message_human`` is Django's own rendered summary
+    (``get_change_message``); ``change_message_structured`` is the raw
+    JSON list so a SPA can render field-level detail without re-parsing
+    the prose.
+    """
+    user = entry.user
+    return {
+        "id": entry.id,
+        "action": _ACTION_LABELS.get(entry.action_flag, "unknown"),
+        "action_time": entry.action_time.isoformat(),
+        "user": None if user is None else {"id": user.pk, "label": str(user)},
+        "change_message_human": entry.get_change_message(),
+        "change_message_structured": _structured_message(entry),
+    }
+
+
+def _structured_message(entry: LogEntry) -> Any:
+    """Return the raw structured change message, or ``[]`` if absent.
+
+    ``LogEntry.change_message`` is a JSON string for entries written by
+    modern admin; older / hand-written entries may store free text.
+    ``get_change_message`` already handles the prose rendering, so here
+    we only surface the structured form when it parses as a list.
+    """
+    import json
+
+    raw = entry.change_message or ""
+    try:
+        parsed = json.loads(raw)
+    except (ValueError, TypeError):
+        return []
+    return parsed if isinstance(parsed, list) else []
+
+
+def _page_size(request: HttpRequest) -> int:
+    """Clamp the ``page_size`` query param to ``[1, _MAX_PAGE_SIZE]``."""
+    raw = request.GET.get("page_size")
+    if raw is None:
+        return _DEFAULT_PAGE_SIZE
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        return _DEFAULT_PAGE_SIZE
+    return max(1, min(value, _MAX_PAGE_SIZE))
+
+
+def _page_number(request: HttpRequest) -> int:
+    """Read the ``page`` query param; default 1 on absent / bogus."""
+    raw = request.GET.get("page")
+    try:
+        return max(1, int(raw))
+    except (TypeError, ValueError):
+        return 1

django_admin_react/audit.py

@@ -0,0 +1,42 @@
+"""Access to Django's admin audit log (``LogEntry``).
+
+This module is deliberately **outside** ``django_admin_react/api/``.
+The ``api/`` package obeys the hard rule (``SECURITY.md`` §3 rule 10 /
+``ACCEPTANCE.md`` §3.1 B-2): every **consumer-model** queryset starts
+from ``ModelAdmin.get_queryset(request)``, never ``Model.objects.*``.
+
+``django.contrib.admin.models.LogEntry`` is **not** a consumer model —
+it is Django's own framework audit table, and Django's own
+``ModelAdmin.history_view`` reads it via ``LogEntry.objects.filter(...)``
+directly. The get_queryset rule is categorically inapplicable to it.
+Keeping the LogEntry access here, in its own single-responsibility
+module, makes that distinction explicit at the file-system level rather
+than burying a special case inside the consumer-model API layer.
+
+Public surface:
+
+- :func:`object_log_entries` — the ``LogEntry`` queryset for one object,
+  newest-first, with the acting user pre-fetched.
+"""
+
+from __future__ import annotations
+
+from django.contrib.admin.models import LogEntry
+from django.contrib.contenttypes.models import ContentType
+from django.db.models import Model
+from django.db.models import QuerySet
+
+
+def object_log_entries(obj: Model) -> QuerySet[LogEntry]:
+    """Return the ``LogEntry`` rows for ``obj``, newest action first.
+
+    Scoped by the object's ``ContentType`` + ``object_id`` — the same
+    pair Django's admin ``history_view`` uses. ``select_related("user")``
+    so the timeline serializer doesn't N+1 on the acting user.
+    """
+    content_type = ContentType.objects.get_for_model(type(obj))
+    return (
+        LogEntry.objects.filter(content_type=content_type, object_id=str(obj.pk))
+        .select_related("user")
+        .order_by("-action_time")
+    )

tests/test_history.py

@@ -0,0 +1,144 @@
+"""Tests for ``GET /api/v1/<app>/<model>/<pk>/history/`` (#155 read half).
+
+Mandatory matrix from ``CLAUDE.md`` §6 + feature-specific: the
+timeline reflects entries the SPA write endpoints emit, ordered
+newest-first, paginated, gated by per-object view permission.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from django.contrib.admin.models import CHANGE
+from django.contrib.admin.models import LogEntry
+from django.contrib.auth.models import Group
+from django.contrib.contenttypes.models import ContentType
+from django.test import Client
+
+from tests.helpers import admin_override
+
+COLLECTION_URL = "/admin-react/api/v1/auth/group/"
+
+
+def _history_url(pk: int) -> str:
+    return f"{COLLECTION_URL}{pk}/history/"
+
+
+def _log(group: Group, user, action=CHANGE, message="[]") -> None:
+    # Create the row directly — the manager's ``log_action`` is
+    # deprecated in Django 5.2 and the suite treats warnings as errors.
+    LogEntry.objects.create(
+        user_id=user.pk,
+        content_type=ContentType.objects.get_for_model(Group),
+        object_id=str(group.pk),
+        object_repr=str(group),
+        action_flag=action,
+        change_message=message,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Mandatory matrix                                                            #
+# --------------------------------------------------------------------------- #
+@pytest.mark.django_db
+def test_anonymous_unauthorized(anon_client: Client) -> None:
+    g = Group.objects.create(name="g")
+    response = anon_client.get(_history_url(g.pk))
+    assert response.status_code in (302, 403)
+
+
+@pytest.mark.django_db
+def test_non_staff_forbidden(user_client: Client) -> None:
+    g = Group.objects.create(name="g")
+    response = user_client.get(_history_url(g.pk))
+    assert response.status_code == 403
+
+
+@pytest.mark.django_db
+def test_unregistered_model_not_found(superuser_client: Client) -> None:
+    response = superuser_client.get("/admin-react/api/v1/auth/nope/1/history/")
+    assert response.status_code == 404
+
+
+@pytest.mark.django_db
+def test_bogus_pk_not_found(superuser_client: Client) -> None:
+    response = superuser_client.get(_history_url(999999))
+    assert response.status_code == 404
+
+
+@pytest.mark.django_db
+def test_staff_without_view_permission_forbidden(superuser_client: Client) -> None:
+    g = Group.objects.create(name="g")
+    with admin_override(Group, has_view_permission=lambda self, request, obj=None: False):
+        response = superuser_client.get(_history_url(g.pk))
+    assert response.status_code in (403, 404)
+
+
+# --------------------------------------------------------------------------- #
+# Feature behaviour                                                           #
+# --------------------------------------------------------------------------- #
+@pytest.mark.django_db
+def test_empty_history_returns_empty_list(superuser_client: Client) -> None:
+    g = Group.objects.create(name="fresh")
+    response = superuser_client.get(_history_url(g.pk))
+    assert response.status_code == 200
+    body = response.json()
+    assert body["object"]["pk"] == g.pk
+    assert body["entries"] == []
+    assert body["total"] == 0
+    assert response["Cache-Control"] == "no-store"
+
+
+@pytest.mark.django_db
+def test_history_reflects_spa_write(superuser_client: Client) -> None:
+    # Create through the SPA endpoint → should emit an ADDITION entry
+    # (via the create view's log_addition), visible in the timeline.
+    created = superuser_client.post(
+        COLLECTION_URL,
+        data=json.dumps({"name": "logged"}),
+        content_type="application/json",
+    )
+    pk = created.json()["pk"]
+    response = superuser_client.get(_history_url(pk))
+    assert response.status_code == 200
+    body = response.json()
+    assert body["total"] >= 1
+    assert body["entries"][0]["action"] == "addition"
+    assert body["entries"][0]["user"] is not None
+
+
+@pytest.mark.django_db
+def test_history_newest_first_and_paginated(superuser_client, django_user_model) -> None:
+    g = Group.objects.create(name="g")
+    user = django_user_model.objects.filter(is_superuser=True).first()
+    for i in range(30):
+        _log(g, user, message=json.dumps([{"changed": {"fields": [f"f{i}"]}}]))
+
+    # Page 1, default size 25.
+    r1 = superuser_client.get(_history_url(g.pk))
+    b1 = r1.json()
+    assert b1["total"] == 30
+    assert b1["page"] == 1
+    assert b1["page_size"] == 25
+    assert len(b1["entries"]) == 25
+    # Newest-first: ids are descending.
+    ids = [e["id"] for e in b1["entries"]]
+    assert ids == sorted(ids, reverse=True)
+
+    # Page 2 has the remaining 5.
+    r2 = superuser_client.get(_history_url(g.pk) + "?page=2")
+    b2 = r2.json()
+    assert b2["page"] == 2
+    assert len(b2["entries"]) == 5
+
+
+@pytest.mark.django_db
+def test_structured_message_surfaced(superuser_client, django_user_model) -> None:
+    g = Group.objects.create(name="g")
+    user = django_user_model.objects.filter(is_superuser=True).first()
+    _log(g, user, message=json.dumps([{"changed": {"fields": ["name"]}}]))
+    response = superuser_client.get(_history_url(g.pk))
+    entry = response.json()["entries"][0]
+    assert entry["change_message_structured"] == [{"changed": {"fields": ["name"]}}]
+    assert "name" in entry["change_message_human"].lower()