trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/projects/backlog_views.py

@@ -0,0 +1,302 @@
+"""Views for the program backlog (ADR-0069 Erratum, #737 / #739).
+
+``BacklogItem`` is a program-scoped CRUD resource nested under a program, plus a
+``pull`` action that converts a PROPOSED item into a project-backlog Task. The
+project-backlog *read* (Task with ``status=BACKLOG``, ``sprint=NULL``) is served
+by the existing ``TaskViewSet`` filters (``?status=BACKLOG&sprint=none``) — no
+separate endpoint is added here.
+
+Permission matrix (ADR-0069 Erratum §4):
+  list / retrieve         — IsProgramMember (Viewer+)
+  create / update / destroy — IsProgramEditor (Team Member+)
+  pull                    — IsProgramEditor **and** write role on the target project
+"""
+
+from __future__ import annotations
+
+from django.contrib.postgres.search import TrigramSimilarity
+from django.core.exceptions import ValidationError as DjangoValidationError
+from django.db.models import QuerySet
+from django.shortcuts import get_object_or_404
+from drf_spectacular.utils import OpenApiResponse, extend_schema, inline_serializer
+from rest_framework import mixins, serializers, status, viewsets
+from rest_framework.decorators import action
+from rest_framework.permissions import BasePermission, IsAuthenticated
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.serializers import BaseSerializer
+
+from trueppm_api.apps.access.models import Role
+from trueppm_api.apps.access.permissions import (
+    IsProgramEditor,
+    IsProgramMember,
+    IsProgramNotClosed,
+    McpReadableViewMixin,
+    McpScope,
+    _membership_role,
+    assert_project_not_archived,
+)
+from trueppm_api.apps.idempotency.mixins import IdempotencyMixin
+from trueppm_api.apps.projects.backlog_services import (
+    BacklogItemNotPullable,
+    CrossProgramPullError,
+    pull_to_project_backlog,
+)
+from trueppm_api.apps.projects.models import (
+    BacklogItem,
+    BacklogItemStatus,
+    Program,
+    Project,
+)
+from trueppm_api.apps.projects.serializers import BacklogItemSerializer, TaskSerializer
+from trueppm_api.core.request_body import object_body
+
+
+class BacklogItemViewSet(
+    McpReadableViewMixin,
+    IdempotencyMixin,
+    mixins.ListModelMixin,
+    mixins.CreateModelMixin,
+    mixins.RetrieveModelMixin,
+    mixins.UpdateModelMixin,
+    mixins.DestroyModelMixin,
+    viewsets.GenericViewSet[BacklogItem],
+):
+    """CRUD + pull for program backlog items.
+
+    URL: ``/api/v1/programs/<program_pk>/backlog-items/[<pk>/]``
+         ``/api/v1/programs/<program_pk>/backlog-items/<pk>/pull/``
+
+    ``McpReadableViewMixin`` (ADR-0186 §E) additively exposes the list/retrieve
+    reads to a personal ``mcp:read`` API token — it powers the MCP
+    ``list_program_backlog`` tool. Because this viewset overrides
+    ``get_permissions`` with a per-action list, the MCP token guards are appended
+    from that wrapper (via ``mcp_token_guards()``) rather than the mixin's default
+    ``get_permissions``, so no branch — including the write branches — can leak a
+    token past ``TokenReadOnlyMethods`` / ``TokenHasScope`` / ``TokenIsOwnerScoped``.
+    """
+
+    # ADR-0678 (#2482): program-level intake pool. BacklogItem has no project FK,
+    # so the central filter reaches it through the `program` branch — a child
+    # project's opt-out does not withhold intake data the project does not own.
+    mcp_scope = McpScope.AGGREGATE
+
+    serializer_class = BacklogItemSerializer
+
+    def get_permissions(self) -> list[BasePermission]:
+        # ADR-0186 §E: append the read-only MCP token guards around the
+        # action-specific RBAC list so a mcp:read token is confined to safe
+        # methods on every action (no write-branch leak); human auth passes both.
+        return [*self._rbac_permissions(), *self.mcp_token_guards()]
+
+    def _rbac_permissions(self) -> list[BasePermission]:
+        if self.action in ("list", "retrieve"):
+            return [IsAuthenticated(), IsProgramMember(), IsProgramNotClosed()]
+        # create / update / partial_update / destroy / pull all require program
+        # write (Team Member+). The pull action additionally checks project-write
+        # on the resolved target inside the handler.
+        return [IsAuthenticated(), IsProgramEditor(), IsProgramNotClosed()]
+
+    def get_queryset(self) -> QuerySet[BacklogItem]:
+        """Program-scoped backlog.
+
+        The list view layers on item_type / status / tags / ``?q=`` filters and
+        defaults ``status`` to PROPOSED (the active pool). Those filters are
+        **list-only** — detail operations (retrieve / update / destroy) must be
+        able to reach an item in *any* status (e.g. PATCH an item to ARCHIVED,
+        or fetch a PULLED item), so they get the unfiltered program-scoped set.
+        """
+        program_pk = str(self.kwargs["program_pk"])
+        qs = BacklogItem.objects.filter(program_id=program_pk, is_deleted=False).select_related(
+            # pulled_task__project powers the serializer's pulled_task_project_*
+            # wayfinding fields (#1994) without an extra query per pulled row.
+            "pulled_task__project",
+            "created_by",
+            "pulled_by",
+        )
+
+        if self.action != "list":
+            return qs
+
+        item_type = self.request.query_params.get("item_type")
+        if item_type:
+            qs = qs.filter(item_type=item_type)
+
+        # status: explicit value filters; a present-but-empty value means "all";
+        # absent means the default active pool (PROPOSED).
+        if "status" in self.request.query_params:
+            status_filter = self.request.query_params.get("status")
+            if status_filter:
+                qs = qs.filter(status=status_filter)
+        else:
+            qs = qs.filter(status=BacklogItemStatus.PROPOSED)
+
+        # tags: repeatable ?tags=foo&tags=bar — match items carrying ALL given tags.
+        tags = self.request.query_params.getlist("tags")
+        for tag in tags:
+            if tag:
+                qs = qs.filter(tags__contains=[tag])
+
+        # Trigram fuzzy search on title (#739). Combines with the filters above;
+        # an empty/absent q is a no-op (other filters + default ordering apply).
+        #
+        # The FILTER uses the ``%`` operator (``__trigram_similar``) — this is the
+        # form the ``gin_trgm_ops`` GIN index (backlogitem_title_trgm) accelerates,
+        # so search scales as the ADR intends rather than seq-scanning a computed
+        # similarity per row. The ``%`` operator honours pg_trgm's
+        # ``similarity_threshold`` (default 0.3). We additionally annotate the
+        # whole-string similarity and order by it desc so the closest title ranks
+        # first, overriding the model's default priority_rank ordering for searches.
+        q = (self.request.query_params.get("q") or "").strip()
+        if q:
+            qs = (
+                qs.annotate(similarity=TrigramSimilarity("title", q))
+                .filter(title__trigram_similar=q)
+                .order_by("-similarity")
+            )
+
+        return qs
+
+    def _resolve_program(self) -> Program:
+        program = get_object_or_404(Program, pk=self.kwargs["program_pk"], is_deleted=False)
+        # DRF skips has_object_permission on create/custom actions — enforce the
+        # program role gate against the resolved program before any write.
+        self.check_object_permissions(self.request, program)
+        return program
+
+    def perform_create(self, serializer: BaseSerializer[BacklogItem]) -> None:
+        program = self._resolve_program()
+        # status is forced to PROPOSED on create regardless of payload — a new
+        # item always enters the active pool; PULLED/ARCHIVED are reached later
+        # via the pull action / archive PATCH.
+        serializer.save(
+            program=program,
+            created_by=self.request.user,
+            status=BacklogItemStatus.PROPOSED,
+        )
+
+    def perform_destroy(self, instance: BacklogItem) -> None:
+        # Soft-delete so the sync protocol ships a tombstone rather than the row
+        # vanishing silently (VersionedModel contract).
+        instance.soft_delete()
+
+    # Surfaced by the #2840 conformance guard, which scans every module under
+    # ``apps/`` rather than ``views.py`` alone. Every part of the inferred contract
+    # was wrong: the fallback declared a full BacklogItemRequest body (the real
+    # body is ``{"project_id": …}``) and a bare ``200 BacklogItem`` response (the
+    # handler returns ``201`` with a two-key envelope carrying the created Task
+    # *and* the transitioned item).
+    @extend_schema(
+        summary="Pull a backlog item into a project's backlog",
+        request=inline_serializer(
+            name="BacklogItemPullRequest",
+            fields={"project_id": serializers.UUIDField()},
+        ),
+        responses={
+            201: inline_serializer(
+                name="BacklogItemPullResult",
+                fields={
+                    "task": TaskSerializer(),
+                    "backlog_item": BacklogItemSerializer(),
+                },
+            ),
+            400: OpenApiResponse(
+                description="project_id missing, or the target project is not in this program."
+            ),
+            403: OpenApiResponse(
+                description=(
+                    "Caller lacks Team Member+ on the target project, **or** the target "
+                    "project is archived. The archived case is not a role problem and no "
+                    "role clears it — unarchive the project and retry (#3354)."
+                )
+            ),
+            409: OpenApiResponse(description="The item is no longer PROPOSED."),
+        },
+    )
+    @action(detail=True, methods=["post"], url_path="pull")
+    def pull(self, request: Request, program_pk: str, pk: str) -> Response:
+        """Pull a PROPOSED item into a project's backlog (ADR-0069 Erratum §5).
+
+        Body: ``{"project_id": "<uuid>"}``. Creates a Task (status=BACKLOG,
+        sprint=NULL) in the target project and transitions the item to PULLED.
+        Requires program-write (gated by ``get_permissions``) **and** write role
+        on the target project (checked here). Never assigns a sprint.
+
+        Returns ``201`` with the created task and the updated backlog item.
+        ``400`` if project_id is missing / not in this program; ``403`` if the
+        caller lacks project-write **or the target project is archived** (the
+        latter clears for no role — the project must be unarchived); ``409`` if
+        the item is no longer PROPOSED.
+        """
+        # Confirm the program exists and the caller holds program-write.
+        self._resolve_program()
+
+        project_id = object_body(request).get("project_id")
+        if not project_id:
+            return Response(
+                {"detail": "project_id is required."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        # Resolve the target project, scoped to this program. A project_id that
+        # is not in the program returns 404-as-400 (cross-program pull rejected).
+        try:
+            project = Project.objects.get(pk=project_id, program_id=program_pk, is_deleted=False)
+        except (Project.DoesNotExist, ValueError, DjangoValidationError):
+            return Response(
+                {"detail": "Target project not found in this program."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        # Project-level write gate: program-write alone is not enough to drop a
+        # Task into a project — the caller must also be Team Member+ on it.
+        role = _membership_role(request, project.pk)
+        if role is None or role < Role.MEMBER:
+            return Response(
+                {"detail": "You need at least Team Member role on the target project."},
+                status=status.HTTP_403_FORBIDDEN,
+            )
+        # Archived target projects take no writes, and a pull creates a Task (#3354).
+        # `IsProgramNotClosed` in `get_permissions` gates the *program*; nothing was
+        # checking the project's own lifecycle. `IsProjectNotArchived` cannot cover
+        # this route: the target project comes from the request body, so there is no
+        # `project_pk` kwarg for `has_permission` and `get_object()` returns the
+        # `BacklogItem` — the same blind spot as `ProjectTemplateViewSet.apply`, and
+        # it needs the same explicit assert. Placed after the role check so a caller
+        # without project-write still gets the role refusal first.
+        assert_project_not_archived(project.pk)
+
+        try:
+            task = pull_to_project_backlog(item_id=str(pk), project=project, actor=request.user)
+        except BacklogItem.DoesNotExist:
+            return Response(
+                {"detail": "Backlog item not found."},
+                status=status.HTTP_404_NOT_FOUND,
+            )
+        except CrossProgramPullError as exc:
+            # False positive: domain exception with a curated, client-safe message
+            # (single-program pull boundary, ADR-0069) — no server internals.
+            return Response(
+                {"detail": str(exc)},  # codeql[py/stack-trace-exposure]
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        except BacklogItemNotPullable as exc:
+            # False positive: curated domain message (item no longer PROPOSED).
+            return Response(
+                {"detail": str(exc)},  # codeql[py/stack-trace-exposure]
+                status=status.HTTP_409_CONFLICT,
+            )
+
+        # Re-fetch with the FK joins the serializer reads (pulled_task__project,
+        # created_by, pulled_by) so the pull response doesn't fire lazy per-FK
+        # queries — including the pulled_task_project_* wayfinding fields (#1994).
+        item = BacklogItem.objects.select_related(
+            "pulled_task__project", "created_by", "pulled_by"
+        ).get(pk=pk)
+        return Response(
+            {
+                "task": TaskSerializer(task).data,
+                "backlog_item": BacklogItemSerializer(item).data,
+            },
+            status=status.HTTP_201_CREATED,
+        )

trueppm_api/apps/projects/batch_operation_views.py

@@ -0,0 +1,264 @@
+"""Read + undo endpoints for the schedule outline's batch operation ledgers (ADR-0810, #2756).
+
+Mirrors ``template_views.py``'s ``TemplateApplicationViewSet`` shape exactly:
+read-only (these are server-written ledger rows, no client create/update/delete
+door), scoped to the caller's project memberships, one ``undo`` POST action per
+viewset. See ``task_batch_services.py`` for the actual undo logic — these views
+are a thin RBAC + status-guard layer over it, same division of labor as the
+template application endpoint.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from django.db.models import QuerySet
+from drf_spectacular.utils import OpenApiResponse, extend_schema, extend_schema_field
+from rest_framework import serializers, status, viewsets
+from rest_framework.decorators import action
+from rest_framework.exceptions import PermissionDenied, ValidationError
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.request import Request
+from rest_framework.response import Response
+
+from trueppm_api.apps.access.permissions import (
+    IsProjectNotArchived,
+    _membership_role,
+    role_can_undo_batch_operation,
+)
+from trueppm_api.apps.idempotency.mixins import IdempotencyMixin
+from trueppm_api.apps.projects.models import (
+    CascadeClassificationOperation,
+    PasteManyOperation,
+    SyncBatchOperationStatus,
+)
+from trueppm_api.apps.projects.task_batch_services import (
+    undo_cascade_classification_operation,
+    undo_paste_many_operation,
+)
+from trueppm_api.core.openapi import state_refusal_400, undo_summary_schema
+
+#: Both ``undo`` actions refuse for two unrelated reasons that share a status code.
+#: Spelling them out is the difference between a client retrying usefully and a
+#: client retrying forever (#3354).
+ARCHIVED_403 = (
+    "Two causes, and a client must tell them apart: the caller is below the role "
+    "floor for this action, **or** the project is archived. The archived case clears "
+    "for no role — including Owner — so escalating the caller will never succeed; "
+    "the project has to be unarchived (#3354)."
+)
+
+
+def _caller_project_ids(request: Request) -> QuerySet[Any]:
+    from trueppm_api.apps.access.models import ProjectMembership
+
+    return ProjectMembership.objects.filter(
+        user=cast("Any", request.user), is_deleted=False
+    ).values_list("project_id", flat=True)
+
+
+def _require_admin(request: Request, project_id: Any) -> None:
+    """⌘Z on a batch write is Admin+, the same bar as undoing a template apply
+    (ADR-0773's "who may reverse a plan-shaping batch write" matrix). A plain
+    Member may have authored the paste/cascade under Author mode and still not
+    clear this floor.
+
+    **The floor is open at #3355 and the reason once given for it was wrong.** This
+    docstring used to say undo "removes work other collaborators may already be
+    building on top of". It does not: ``undo_paste_many_operation`` and its cascade
+    and import-fix siblings (all in ``projects.task_batch_services``) partition on
+    ``server_version`` via ``_partition_touched`` and act only on the untouched rows,
+    returning the rest as ``kept``. Nothing another collaborator wrote is removed.
+    ADR-0880 §4 rejects the same premise for structural undo and implements
+    actor-or-Admin instead.
+
+    Defers the comparison to :func:`role_can_undo_batch_operation` rather than
+    testing the ordinal here, because the cascade's apply endpoint reports the
+    same rule to the client as ``can_undo`` and the two must not drift (#3304).
+    """
+    if not role_can_undo_batch_operation(_membership_role(request, project_id)):
+        raise PermissionDenied("You need at least Project Manager role to undo this.")
+
+
+class PasteManyOperationSerializer(serializers.ModelSerializer[PasteManyOperation]):
+    class Meta:
+        model = PasteManyOperation
+        fields = [  # noqa: RUF012
+            "id",
+            "project",
+            "applied_by",
+            "status",
+            "created_task_versions",
+            "result_summary",
+            "created_at",
+            "undone_at",
+        ]
+        read_only_fields = fields
+
+
+class PasteManyOperationUndoSerializer(PasteManyOperationSerializer):
+    """The ledger row **plus** the ``undo`` summary the action returns (#3416).
+
+    The handler builds its body as ``data = serializer.data`` then ``data["undo"] =
+    summary``, so declaring the bare ``PasteManyOperationSerializer`` as the ``200``
+    would publish a document with no ``undo`` field — the one value the endpoint
+    exists to report, missing from every generated SDK. See
+    :func:`undo_summary_schema` for why that is worse than declaring nothing.
+    """
+
+    undo = serializers.SerializerMethodField()
+
+    class Meta(PasteManyOperationSerializer.Meta):
+        fields = [*PasteManyOperationSerializer.Meta.fields, "undo"]  # noqa: RUF012
+
+    @extend_schema_field(
+        undo_summary_schema(
+            "What the undo did to the rows this paste created.",
+            deleted="Rows removed — created by the paste and untouched since.",
+            kept="Rows left in place because someone has edited them since the paste.",
+        )
+    )
+    def get_undo(self, obj: PasteManyOperation) -> dict[str, int]:
+        """The persisted summary, for a caller that serializes a row outside the action.
+
+        The action itself returns the summary the service just computed rather than
+        this — see its handler. They agree on every path that persists one.
+        """
+        return dict((obj.result_summary or {}).get("undo") or {})
+
+
+class PasteManyOperationViewSet(
+    IdempotencyMixin, viewsets.ReadOnlyModelViewSet[PasteManyOperation]
+):
+    serializer_class = PasteManyOperationSerializer
+    # `undo` hard-deletes task rows, so this route is a write path and carries the
+    # archived floor every sibling in the family carries (`StructuralOperationViewSet`,
+    # `CsvImportUndoView`, `TaskBulkView`, `TaskClassificationView`). Reads are
+    # unaffected — `IsProjectNotArchived` passes every SAFE_METHOD, so polling a
+    # ledger row on an archived project still works (#3354).
+    #
+    # It resolves the project from the *object*, not a URL kwarg: this viewset is
+    # router-registered at the top level, so `has_permission` finds no `project_pk`
+    # and returns True, and the real check runs in `has_object_permission` off the
+    # operation's `project_id` during `get_object()`. Role authority stays in
+    # `_require_admin` below — this class enforces lifecycle state only.
+    permission_classes = [IsAuthenticated, IsProjectNotArchived]  # noqa: RUF012
+
+    def get_queryset(self) -> QuerySet[PasteManyOperation]:
+        qs = PasteManyOperation.objects.filter(project_id__in=_caller_project_ids(self.request))
+        project_id = self.request.query_params.get("project")
+        if project_id:
+            qs = qs.filter(project_id=project_id)
+        return qs
+
+    @extend_schema(
+        request=None,
+        responses={
+            200: PasteManyOperationUndoSerializer,
+            400: state_refusal_400(
+                "This batch has already been undone. Verified against the status "
+                "guard in ``undo`` (#3319)."
+            ),
+            403: OpenApiResponse(description=ARCHIVED_403),
+        },
+        description=(
+            "Undo this paste-many batch — removes the rows it created that nobody has edited."
+        ),
+    )
+    @action(detail=True, methods=["post"], url_path="undo")
+    def undo(self, request: Request, pk: str | None = None) -> Response:
+        operation = self.get_object()
+        _require_admin(request, operation.project_id)
+        if operation.status == SyncBatchOperationStatus.UNDONE:
+            raise ValidationError({"detail": "This batch has already been undone."})
+        summary = undo_paste_many_operation(operation)
+        operation.refresh_from_db()
+        data: dict[str, Any] = self.get_serializer(operation).data
+        data["undo"] = summary
+        return Response(data, status=status.HTTP_200_OK)
+
+
+class CascadeClassificationOperationSerializer(
+    serializers.ModelSerializer[CascadeClassificationOperation]
+):
+    class Meta:
+        model = CascadeClassificationOperation
+        fields = [  # noqa: RUF012
+            "id",
+            "project",
+            "applied_by",
+            "subtree_id",
+            "status",
+            "task_snapshots",
+            "result_summary",
+            "created_at",
+            "undone_at",
+        ]
+        read_only_fields = fields
+
+
+class CascadeClassificationOperationUndoSerializer(CascadeClassificationOperationSerializer):
+    """The ledger row **plus** the ``undo`` summary the action returns (#3416).
+
+    Same defect and same fix as :class:`PasteManyOperationUndoSerializer`; the counts
+    differ because a cascade undo writes prior values back rather than deleting rows.
+    """
+
+    undo = serializers.SerializerMethodField()
+
+    class Meta(CascadeClassificationOperationSerializer.Meta):
+        fields = [*CascadeClassificationOperationSerializer.Meta.fields, "undo"]  # noqa: RUF012
+
+    @extend_schema_field(
+        undo_summary_schema(
+            "What the undo did to the rows this cascade reclassified.",
+            reverted="Rows restored to their pre-cascade classification.",
+            kept="Rows left as the cascade set them because someone has edited them since.",
+        )
+    )
+    def get_undo(self, obj: CascadeClassificationOperation) -> dict[str, int]:
+        """The persisted summary — see :meth:`PasteManyOperationUndoSerializer.get_undo`."""
+        return dict((obj.result_summary or {}).get("undo") or {})
+
+
+class CascadeClassificationOperationViewSet(
+    IdempotencyMixin, viewsets.ReadOnlyModelViewSet[CascadeClassificationOperation]
+):
+    serializer_class = CascadeClassificationOperationSerializer
+    # Same reasoning as `PasteManyOperationViewSet` above — `undo` writes
+    # classification fields back onto existing rows, so it is a write path and takes
+    # the archived floor (#3354).
+    permission_classes = [IsAuthenticated, IsProjectNotArchived]  # noqa: RUF012
+
+    def get_queryset(self) -> QuerySet[CascadeClassificationOperation]:
+        qs = CascadeClassificationOperation.objects.filter(
+            project_id__in=_caller_project_ids(self.request)
+        )
+        project_id = self.request.query_params.get("project")
+        if project_id:
+            qs = qs.filter(project_id=project_id)
+        return qs
+
+    @extend_schema(
+        request=None,
+        responses={
+            200: CascadeClassificationOperationUndoSerializer,
+            400: state_refusal_400(
+                "This cascade has already been undone. Verified against the status "
+                "guard in ``undo`` (#3319)."
+            ),
+            403: OpenApiResponse(description=ARCHIVED_403),
+        },
+        description="Undo this cascade — restores each untouched row's prior classification.",
+    )
+    @action(detail=True, methods=["post"], url_path="undo")
+    def undo(self, request: Request, pk: str | None = None) -> Response:
+        operation = self.get_object()
+        _require_admin(request, operation.project_id)
+        if operation.status == SyncBatchOperationStatus.UNDONE:
+            raise ValidationError({"detail": "This cascade has already been undone."})
+        summary = undo_cascade_classification_operation(operation)
+        operation.refresh_from_db()
+        data: dict[str, Any] = self.get_serializer(operation).data
+        data["undo"] = summary
+        return Response(data, status=status.HTTP_200_OK)