feat(api): delete-confirmation preview endpoint — Django admin parity (#153 backend) (#164)

Adds GET /api/v1/<app>/<model>/<pk>/delete-preview/ — the cascade /
protected / perms-needed preview the legacy admin's delete_view shows
before a destructive delete. Without it, a single SPA Delete click can
silently cascade-delete related rows the operator never saw.

- `api/views/delete_preview.py` (NEW) — `DeletePreviewView`. Reuses
  `django.contrib.admin.utils.get_deleted_objects([obj], request,
  admin_site)` (the exact function delete_view uses), so cascade /
  protected / perms_needed match the HTML admin 1:1. Read-only: never
  deletes. `can_delete = not protected and not perms_needed`.
- `api/urls.py` — `delete-preview/` route before the instance pattern.

Gates mirror the DELETE endpoint exactly: staff → resolve_model →
object via get_queryset → has_delete_permission. 404 (no oracle) on
missing; 403 on lacking delete perm.

Wire shape: {object, cascade:[{model,count}], protected:[...],
perms_needed:[...], can_delete}.

Tests: tests/test_delete_preview.py — full auth matrix + leaf-object
shape + read-only assertion (preview never deletes). 7 cases.
Full suite 303 → 311.

Backend half of #153; the SPA confirm-modal is the frontend slot.
Parity: ACCEPTANCE.md §2.9 E-16 (proposed in #153).

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

@@ -24,6 +24,7 @@
 from django_admin_react.api.views.autocomplete import AutocompleteView
 from django_admin_react.api.views.bulk import BulkUpdateView
 from django_admin_react.api.views.create import CreateView
+from django_admin_react.api.views.delete_preview import DeletePreviewView
 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
@@ -121,6 +122,13 @@ def delete(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpRespons
         HistoryView.as_view(),
         name="history",
     ),
+    # Delete-preview sub-resource (#153) — cascade / protected preview
+    # before the destructive DELETE. Same ordering caveat as above.
+    path(
+        "<str:app_label>/<str:model_name>/<str:pk>/delete-preview/",
+        DeletePreviewView.as_view(),
+        name="delete_preview",
+    ),
     path(
         "<str:app_label>/<str:model_name>/<str:pk>/",
         InstanceView.as_view(),

django_admin_react/api/views/delete_preview.py

@@ -0,0 +1,107 @@
+"""``GET /api/v1/<app>/<model>/<pk>/delete-preview/`` — cascade preview.
+
+Wire contract: ``docs/api-contract.md`` §5.3 (delete preview sub-resource).
+
+Django's HTML admin shows a confirmation interstitial before a delete:
+what cascades, what's protected, what extra permissions are needed. The
+SPA's Delete button should open the same preview before invoking the
+DELETE endpoint — otherwise a single click can silently cascade-delete
+related rows the operator never saw. Parity (#153).
+
+Reuses ``django.contrib.admin.utils.get_deleted_objects`` — the exact
+function the HTML admin's ``delete_view`` uses — so the cascade,
+protected, and perms-needed sets match the legacy admin 1:1.
+
+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_delete_permission`` gate.
+- Rule 10: Object loaded through ``ModelAdmin.get_queryset(request)``.
+- CSRF:    GET is safe; this endpoint never deletes — it only previews.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.contrib.admin.utils import get_deleted_objects
+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
+
+
+class DeletePreviewView(View):
+    """``GET /api/v1/<app_label>/<model_name>/<pk>/delete-preview/``."""
+
+    http_method_names = ["get"]
+
+    def get(
+        self,
+        request: HttpRequest,
+        app_label: str,
+        model_name: str,
+        pk: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> HttpResponse:
+        """Return the cascade / protected / perms-needed preview.
+
+        Gates mirror the DELETE endpoint exactly (``has_delete_permission``)
+        so the preview never reveals cascade structure for an object the
+        user couldn't delete anyway. 404 (no oracle) on missing /
+        unviewable; 403 on lacking delete permission.
+
+        This endpoint **never** mutates — it only computes the preview.
+        The actual delete still goes through ``DELETE`` →
+        ``ModelAdmin.delete_model`` (rule 7).
+        """
+        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_delete_permission(request, obj):
+            return forbidden_response(request)
+
+        # Django's own delete_view machinery. Returns:
+        #   deletable  — nested list of str reprs (display tree)
+        #   model_count— {verbose_name_plural: count}
+        #   perms_needed — set of verbose_names the user can't delete
+        #   protected  — list of str reprs blocking the delete (PROTECT)
+        _deletable, model_count, perms_needed, protected = get_deleted_objects(
+            [obj], request, admin_site
+        )
+
+        body = {
+            "object": {"pk": obj.pk, "label": label_for(obj)},
+            "cascade": [
+                {"model": str(model_label), "count": int(count)}
+                for model_label, count in model_count.items()
+            ],
+            "protected": [str(p) for p in protected],
+            "perms_needed": sorted(str(p) for p in perms_needed),
+            # The delete proceeds only when nothing is PROTECT-blocked and
+            # the user holds delete permission on every cascading model.
+            "can_delete": not protected and not perms_needed,
+        }
+        response = JsonResponse(body, status=200)
+        response["Cache-Control"] = "no-store"
+        return response

tests/test_delete_preview.py

@@ -0,0 +1,75 @@
+"""Tests for ``GET /api/v1/<app>/<model>/<pk>/delete-preview/`` (#153).
+
+The endpoint mirrors the legacy admin's delete-confirmation interstitial:
+cascade counts, protected objects, perms-needed, and a ``can_delete``
+verdict — without performing the delete.
+"""
+
+from __future__ import annotations
+
+import pytest
+from django.contrib.auth.models import Group
+from django.test import Client
+
+from tests.helpers import admin_override
+
+COLLECTION_URL = "/admin-react/api/v1/auth/group/"
+
+
+def _url(pk: int) -> str:
+    return f"{COLLECTION_URL}{pk}/delete-preview/"
+
+
+@pytest.mark.django_db
+def test_anonymous_unauthorized(anon_client: Client) -> None:
+    g = Group.objects.create(name="g")
+    assert anon_client.get(_url(g.pk)).status_code in (302, 403)
+
+
+@pytest.mark.django_db
+def test_non_staff_forbidden(user_client: Client) -> None:
+    g = Group.objects.create(name="g")
+    assert user_client.get(_url(g.pk)).status_code == 403
+
+
+@pytest.mark.django_db
+def test_unregistered_model_not_found(superuser_client: Client) -> None:
+    assert (
+        superuser_client.get("/admin-react/api/v1/auth/nope/1/delete-preview/").status_code == 404
+    )
+
+
+@pytest.mark.django_db
+def test_bogus_pk_not_found(superuser_client: Client) -> None:
+    assert superuser_client.get(_url(999999)).status_code == 404
+
+
+@pytest.mark.django_db
+def test_without_delete_permission_forbidden(superuser_client: Client) -> None:
+    g = Group.objects.create(name="g")
+    with admin_override(Group, has_delete_permission=lambda self, request, obj=None: False):
+        assert superuser_client.get(_url(g.pk)).status_code == 403
+
+
+@pytest.mark.django_db
+def test_preview_shape_for_leaf_object(superuser_client: Client) -> None:
+    g = Group.objects.create(name="leaf")
+    response = superuser_client.get(_url(g.pk))
+    assert response.status_code == 200
+    body = response.json()
+    assert body["object"] == {"pk": g.pk, "label": "leaf"}
+    assert isinstance(body["cascade"], list)
+    # The object's own model appears in the cascade count.
+    assert any("group" in c["model"].lower() for c in body["cascade"])
+    assert body["protected"] == []
+    assert body["perms_needed"] == []
+    assert body["can_delete"] is True
+    assert response["Cache-Control"] == "no-store"
+
+
+@pytest.mark.django_db
+def test_preview_does_not_delete(superuser_client: Client) -> None:
+    g = Group.objects.create(name="survivor")
+    superuser_client.get(_url(g.pk))
+    # Preview is read-only — the object must still exist.
+    assert Group.objects.filter(pk=g.pk).exists()