trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/msproject/serializers.py

@@ -0,0 +1,136 @@
+"""Serializers for MS Project import provenance (#799)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rest_framework import serializers
+
+from trueppm_api.apps.msproject.models import ImportRequest
+from trueppm_api.apps.taskruns.models import TaskRun
+
+
+class ImportRequestProvenanceSerializer(serializers.ModelSerializer[ImportRequest]):
+    """Read-only audit view of an `ImportRequest` for the project history list.
+
+    Marcus (PMO persona) wants the import itself to be part of the project's
+    record: who imported, from what file, when, and what was the outcome.
+    `ImportRequest` already holds the durable who/what/when/status fields;
+    this serializer joins in the linked `TaskRun.result_summary` to surface
+    the imported task count alongside the audit fields.
+
+    `ImportRequest` rows are purged after 7 days by the
+    ``purge_old_import_requests`` cleanup task, so this surface is
+    intentionally an at-a-glance recent-activity view, not a long-lived
+    audit log — enterprise overlays consume the `history_record_created`
+    signal for compliance-grade retention (out of scope here).
+    """
+
+    initiated_by_username = serializers.SerializerMethodField()
+    task_count = serializers.SerializerMethodField()
+    warnings = serializers.SerializerMethodField()
+
+    class Meta:
+        model = ImportRequest
+        fields = (
+            "id",
+            "filename",
+            "status",
+            "creates_project",
+            "requested_at",
+            "initiated_by",
+            "initiated_by_username",
+            "task_count",
+            "warnings",
+        )
+        read_only_fields = fields
+
+    def get_initiated_by_username(self, obj: ImportRequest) -> str | None:
+        """Display username; absent when the row's user was deleted."""
+        if obj.initiated_by_id is None:
+            return None
+        return obj.initiated_by.username if obj.initiated_by else None
+
+    def _task_run(self, obj: ImportRequest) -> TaskRun | None:
+        """Resolve the linked TaskRun, memoized across the rows of one response.
+
+        Returns ``None`` when the import is still in flight (no TaskRun yet) or
+        when the run failed before writing its summary. The TaskRun link is by
+        `celery_task_id` — the import view sets it once Celery dispatch succeeds,
+        so PENDING / DEAD rows reliably resolve to ``None``.
+
+        Shared by every summary-derived field so a second one cannot double the
+        query count: the view pre-seeds a mutable `_taskrun_cache` dict in context
+        and we only ever read from `self.context` here (the type is
+        `Mapping[str, Any]` under stricter django-stubs builds in CI, so indexed
+        assignment is not safe). When invoked outside the list view (e.g.
+        single-instance detail use), no cache is present and each row issues its
+        own query.
+        """
+        if not obj.celery_task_id:
+            return None
+        cache: dict[str, TaskRun | None] | None = self.context.get("_taskrun_cache")
+        if cache is not None and obj.celery_task_id in cache:
+            return cache[obj.celery_task_id]
+        run = TaskRun.objects.filter(celery_task_id=obj.celery_task_id).first()
+        if cache is not None:
+            cache[obj.celery_task_id] = run
+        return run
+
+    def get_task_count(self, obj: ImportRequest) -> int | None:
+        """Pull the imported task count from the linked TaskRun summary."""
+        run = self._task_run(obj)
+        if run is None or not run.result_summary:
+            return None
+        value: Any = run.result_summary.get("task_count")
+        try:
+            return int(value) if value is not None else None
+        except (TypeError, ValueError):
+            return None
+
+    def get_warnings(self, obj: ImportRequest) -> list[str]:
+        """Everything the import did not carry over, in the parser's order (#2891).
+
+        The importer has always written these into ``TaskRun.result_summary``, and
+        nothing has ever read them back out — so "the parser warns" was true and
+        useless at the same time. Losing an MS Project constraint, deadline or
+        baseline is a correctness event, not a log line, and the operator has to be
+        able to reach it. This is the API-side half; a wizard surface for it is
+        tracked separately (#2714).
+
+        Empty for a queued or dead import, the same contract as ``task_count``.
+        """
+        run = self._task_run(obj)
+        if run is None or not run.result_summary:
+            return []
+        warnings: Any = run.result_summary.get("warnings")
+        if not isinstance(warnings, list):
+            return []
+        return [str(w) for w in warnings]
+
+
+class ImportProvenancePageSerializer(serializers.Serializer[dict[str, object]]):
+    """The paginated envelope ``GET /projects/{id}/imports/`` actually returns (#2942).
+
+    Declared explicitly rather than left to ``OpenApiTypes.OBJECT``, which generates
+    ``{"type": "object", "additionalProperties": {}}`` — machine-readable for nothing.
+    An SDK generated from that schema hands the caller an untyped bag: not ``results``,
+    not the pagination envelope, not ``task_count``, not ``warnings``. Every accuracy
+    problem #2942 lists exists *because* prose was the only description, so the fix is
+    to make the shape checkable rather than to write better prose.
+
+    This is a schema-only serializer — the view returns
+    ``paginator.get_paginated_response(...)``, so nothing instantiates it at runtime.
+    It exists so ``responses={200: ...}`` has something faithful to point at, and it
+    must be kept in step with :class:`ImportProvenancePagination`'s envelope by hand;
+    there is no gate that compares a declared response shape to the real one.
+    """
+
+    count = serializers.IntegerField(help_text="Total rows across all pages.")
+    next = serializers.URLField(
+        allow_null=True, help_text="URL of the next page, or null on the last page."
+    )
+    previous = serializers.URLField(
+        allow_null=True, help_text="URL of the previous page, or null on the first page."
+    )
+    results = ImportRequestProvenanceSerializer(many=True)

trueppm_api/apps/msproject/services.py

@@ -0,0 +1,58 @@
+"""Service layer for MS Project import outbox operations.
+
+Call sites:
+  - ``msproject.views`` — deferred via ``transaction.on_commit`` after the
+    ImportRequest row is committed
+  - ``msproject.tasks._do_import_drain`` — for each PENDING row the drain
+    picks up
+"""
+
+from __future__ import annotations
+
+import logging
+
+from django.utils import timezone
+
+logger = logging.getLogger(__name__)
+
+
+def enqueue_import(import_request_id: str) -> None:
+    """Attempt to dispatch a PENDING ImportRequest row to Celery.
+
+    Reads the row by ID and tries to call ``import_msproject.delay()``.
+    On success the row is flipped to DISPATCHED.  On broker failure the row
+    stays PENDING so ``drain_import_queue`` picks it up within 30 seconds.
+
+    Safe to call from ``transaction.on_commit()`` callbacks and from the
+    drain task body.  If the row is no longer PENDING (already dispatched by
+    a concurrent call) the function is a no-op.
+    """
+    from trueppm_api.apps.msproject.models import ImportRequest, ImportRequestStatus
+    from trueppm_api.apps.msproject.tasks import import_msproject
+
+    try:
+        req = ImportRequest.objects.get(id=import_request_id, status=ImportRequestStatus.PENDING)
+    except ImportRequest.DoesNotExist:
+        return
+
+    try:
+        result = import_msproject.delay(
+            project_id=str(req.project_id),
+            file_content_b64=req.file_content_b64,
+            filename=req.filename,
+            initiated_by_id=req.initiated_by_id,
+            import_request_id=str(req.id),
+            creates_project=req.creates_project,
+        )
+    except Exception:
+        logger.warning(
+            "enqueue_import: could not dispatch ImportRequest %s — drain will retry",
+            import_request_id,
+        )
+        return
+
+    ImportRequest.objects.filter(id=req.id, status=ImportRequestStatus.PENDING).update(
+        status=ImportRequestStatus.DISPATCHED,
+        celery_task_id=result.id,
+        dispatched_at=timezone.now(),
+    )

trueppm_api/apps/msproject/tasks.py

@@ -0,0 +1,439 @@
+"""Celery tasks for MS Project import."""
+
+from __future__ import annotations
+
+import base64
+import logging
+from collections.abc import Generator
+from contextlib import contextmanager
+from datetime import timedelta
+from typing import TYPE_CHECKING, Any
+
+from celery import shared_task
+from celery.exceptions import SoftTimeLimitExceeded
+
+from trueppm_api.core.idempotent import idempotent_task
+
+if TYPE_CHECKING:
+    from trueppm_api.apps.msproject.dataclasses import ProjectData
+
+logger = logging.getLogger(__name__)
+
+# An import task running longer than this is considered orphaned by the drain.
+# Slightly longer than soft_time_limit (540 s = 9 min) to let the task time
+# out and record its own failure before drain resets the row.
+_IMPORT_ORPHAN_MINUTES = 15
+
+
+class _NoOpTracker:
+    """Fallback when TaskRunTracker is not available."""
+
+    task_run_id = None
+
+    def update(self, pct: int, msg: str = "") -> None:
+        logger.info("import.msproject progress: %d%% -- %s", pct, msg)
+
+    def set_result(self, result: dict[str, Any]) -> None:
+        logger.info("import.msproject result: %s", result)
+
+
+@contextmanager
+def _get_tracker(
+    celery_task: Any,
+    project_id: str,
+    initiated_by_id: int | None,
+) -> Generator[Any, None, None]:
+    """Try to use TaskRunTracker; fall back to no-op if not available."""
+    try:
+        from trueppm_api.apps.taskruns.tracker import TaskRunTracker
+
+        with TaskRunTracker(
+            celery_task,
+            project_id=project_id,
+            task_name="import.msproject",
+            initiated_by_id=initiated_by_id,
+        ) as tracker:
+            yield tracker
+    except ImportError:
+        yield _NoOpTracker()
+
+
+def _parse_import_bytes(file_content: bytes, ext: str) -> ProjectData:
+    """Parse ``.mpp``/``.xml`` bytes into the importer's project-data shape.
+
+    Defined above ``import_msproject`` rather than inside it so the ``@shared_task``
+    decorator below binds to the task and nothing else.
+    """
+    if ext == "mpp":
+        from trueppm_api.apps.msproject.parser import parse_mpp
+
+        return parse_mpp(file_content)
+    if ext == "xml":
+        from trueppm_api.apps.msproject.parser import parse_xml
+
+        return parse_xml(file_content)
+    raise ValueError(f"Unsupported file format: .{ext}. Expected .mpp or .xml")
+
+
+def _reject_infeasible_graph(
+    project_data: ProjectData, filename: str, import_request_id: str | None
+) -> None:
+    """Raise if the file's dependency graph is infeasible, before any write (ADR-0259).
+
+    A hand-maintained .mpp/.xml routinely carries a cyclic or self-referential
+    predecessor link, and the importer persists links with ``bulk_create`` — which
+    bypasses ``DependencySerializer``'s per-edge cycle check, the only other gate.
+    Without this the file writes an infeasible network that then crashes the CPM
+    engine on the next recalc: the exact bug ADR-0259 was written for.
+
+    Validated in the file's own uid space so a bad file is rejected while the project
+    is still empty rather than rolled back. The caller runs this OUTSIDE its
+    ``atomic()`` block: raising inside would roll the outbox claim back to
+    DISPATCHED, so the orphan drain would re-dispatch a deterministically bad file
+    forever (ADR-0092) — the same reason a parse failure marks the row DEAD.
+    """
+    from trueppm_api.apps.msproject.importer import (
+        collect_dependency_edges,
+        describe_bad_graph,
+    )
+    from trueppm_api.apps.scheduling.graph_guard import (
+        InfeasibleGraphError,
+        validate_task_graph,
+    )
+
+    try:
+        validate_task_graph(collect_dependency_edges(project_data))
+    except InfeasibleGraphError as exc:
+        # ImportRequest has no result_summary column to persist the detail on
+        # (unlike CsvImportRequest), so the TaskRunTracker's FAILED message is the
+        # only surface that outlives the worker — log the human-readable form for
+        # the operator as well (#2714).
+        logger.warning(
+            "import.msproject: rejected %s — %s",
+            filename,
+            describe_bad_graph(project_data, exc),
+        )
+        if import_request_id:
+            _mark_import_dead(import_request_id)
+        raise
+
+
+@shared_task(  # type: ignore[untyped-decorator]
+    bind=True,
+    name="msproject.import_file",
+    soft_time_limit=540,
+    time_limit=600,
+    acks_late=True,
+    reject_on_worker_lost=True,
+)
+def import_msproject(
+    self: Any,
+    project_id: str,
+    file_content_b64: str,
+    filename: str,
+    initiated_by_id: int | None = None,
+    import_request_id: str | None = None,
+    creates_project: bool = False,
+) -> dict[str, Any]:
+    """Import an MS Project file (.mpp or .xml) into a project.
+
+    The file content is passed as base64-encoded string to avoid binary
+    issues with the Celery/Redis message broker.
+
+    When dispatched via the ImportRequest outbox, import_request_id is set
+    so the row can be marked DONE on success (or DEAD on a terminal parse
+    failure).
+
+    When ``creates_project`` is True (create-from-import, ADR-0092) the project
+    shell was created synchronously named from the filename; the file header
+    overwrites its name/start_date once parsing succeeds, and the import wipes
+    any prior partial attempt so an orphan-drain re-dispatch is idempotent.
+
+    After import, triggers a CPM recalculation via the scheduling outbox.
+    """
+    with _get_tracker(self, project_id, initiated_by_id) as tracker:
+        file_content = base64.b64decode(file_content_b64)
+        ext = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
+
+        tracker.update(5, f"Parsing {filename}...")
+
+        try:
+            project_data = _parse_import_bytes(file_content, ext)
+        except Exception:
+            # A parse/format error is deterministic: retrying the same bytes will
+            # always fail. Mark the outbox row DEAD (terminal) so the orphan drain
+            # stops re-dispatching it forever (ADR-0092). The TaskRunTracker records
+            # the run FAILED with this message so the UI can surface it. Infra errors
+            # (broker, timeout, transient DB) happen later and leave the row
+            # DISPATCHED for the normal drain/retry path.
+            if import_request_id:
+                _mark_import_dead(import_request_id)
+            raise
+
+        # Runs OUTSIDE the atomic() block below — see the helper's docstring for
+        # why raising inside it would re-dispatch a bad file forever.
+        tracker.update(15, "Validating dependency graph...")
+        _reject_infeasible_graph(project_data, filename, import_request_id)
+
+        if creates_project:
+            _apply_header_to_project(project_id, project_data)
+
+        from django.db import transaction
+
+        from trueppm_api.apps.msproject.importer import (
+            broadcast_import_project_record_change,
+            import_project,
+        )
+
+        # Make the additive import-into-existing path idempotent under
+        # re-dispatch (#1673). The outbox row is the idempotency token: claim it
+        # (DISPATCHED -> DONE) and run the bulk_create in ONE transaction. A
+        # duplicate delivery — a drain re-dispatch after a worker-death window,
+        # or an acks_late / reject_on_worker_lost redelivery of an already
+        # completed message — finds no DISPATCHED row to claim, so it skips the
+        # import instead of bulk-creating the whole network again (which
+        # duplicated tasks and FS dependencies). The claim's row lock also
+        # serializes any concurrent delivery onto one winner. Because the claim
+        # and the import share the transaction, a mid-import failure rolls the
+        # claim back too, returning the row to DISPATCHED for a clean retry.
+        # (TaskRunTracker.update writes and broadcasts are already atomic-safe —
+        # see its docstring.)
+        with transaction.atomic():
+            if import_request_id and not _claim_import(import_request_id):
+                logger.info(
+                    "import.msproject: request %s already completed — skipping duplicate delivery",
+                    import_request_id,
+                )
+                return {"skipped": True, "tasks_created": 0}
+            summary = import_project(
+                project_id, project_data, tracker=tracker, wipe_existing=creates_project
+            )
+
+        tracker.set_result(summary)
+
+        # calendar_applied alone also needs a recalc (#1769): an into-existing
+        # import of a calendar-bearing file can change the project calendar even
+        # when the file contributed no tasks, and the existing tasks' dates must
+        # be recomputed on the new working mask.
+        if summary["tasks_created"] > 0 or summary.get("calendar_applied"):
+            # Use the outbox service rather than a direct .delay() call so that
+            # a broker outage at import-completion time does not silently drop
+            # the recalculation.  The Celery task context has no ambient
+            # transaction, so enqueue_recalculate opens its own atomic() block.
+            from trueppm_api.apps.scheduling.services import enqueue_recalculate
+
+            enqueue_recalculate(project_id)
+
+        if summary["tasks_created"] > 0:
+            # #1359: a bulk import restructures the WBS, but clients had no signal
+            # until the async CPM pass eventually landed — a multi-second window of
+            # a stale, empty-looking task list. Emit tasks_restructured (the event
+            # the web client already invalidates the tasks cache on) so the imported
+            # tree appears immediately, ahead of the recalc's cpm_complete. Deferred
+            # via on_commit for the same reason as the project_updated broadcast
+            # below. It now runs just after the import's atomic() has committed
+            # (no ambient transaction remains → the callback fires immediately),
+            # so peers never see the restructure event for a rolled-back import.
+            from trueppm_api.apps.sync.broadcast import broadcast_board_event
+
+            transaction.on_commit(
+                lambda: broadcast_board_event(project_id, "tasks_restructured", {})
+            )
+
+        # #873/#867: an imported task that predated the project start pulled the
+        # start back (committed inside import_project). Broadcast project_updated
+        # so collaborators viewing an existing project re-fetch the new boundary
+        # — the recalc's cpm_complete event does not invalidate the project query.
+        # Deferred with on_commit (#1323): the start-pull now commits inside the
+        # import's atomic() above, and this runs just after it commits (no ambient
+        # transaction remains → the callback fires immediately), so peers re-fetch
+        # the moved boundary only once the import is durable, never on a rollback.
+        # calendar_applied rides the same broadcast (#1769): Project.calendar is
+        # project-record state (settings UI, sync clients), which cpm_complete
+        # does not invalidate.
+        broadcast_import_project_record_change(project_id, summary)
+
+    return summary
+
+
+def _claim_import(import_request_id: str) -> bool:
+    """Atomically claim a DISPATCHED ImportRequest, flipping it to DONE.
+
+    The single conditional ``UPDATE ... WHERE status=DISPATCHED`` is the
+    exactly-once idempotency token for the import (#1673): the caller runs the
+    claim inside the same transaction as the bulk_create, so the row transitions
+    to DONE atomically with the imported network. Returns ``True`` when this
+    delivery won the claim (the caller should import), ``False`` when the row was
+    already terminal — a duplicate delivery whose import must be skipped so the
+    additive path does not bulk-create the network twice.
+
+    Clears ``file_content_b64`` in the same update: the ~67 MB base64 payload
+    exists only so a PENDING/DISPATCHED row survives a broker outage and can be
+    re-dispatched by the drain (which re-reads it). Once the import reaches the
+    terminal DONE state it can never be retried, so the blob is dead weight —
+    null it now instead of carrying it until the nightly retention purge (#789).
+    """
+    from trueppm_api.apps.msproject.models import ImportRequest, ImportRequestStatus
+
+    claimed = ImportRequest.objects.filter(
+        id=import_request_id, status=ImportRequestStatus.DISPATCHED
+    ).update(status=ImportRequestStatus.DONE, file_content_b64="")
+    return bool(claimed)
+
+
+def _mark_import_dead(import_request_id: str) -> None:
+    """Flip the ImportRequest row to DEAD after a terminal (parse) failure.
+
+    DEAD is excluded from the orphan-drain recovery, so a deterministically bad
+    file is not re-dispatched forever (ADR-0092). Because it is terminal and can
+    never be retried, the base64 payload is cleared here too for the same reason
+    as DONE — it is only needed for pre-terminal retry (#789).
+    """
+    from trueppm_api.apps.msproject.models import ImportRequest, ImportRequestStatus
+
+    ImportRequest.objects.filter(id=import_request_id).exclude(
+        status=ImportRequestStatus.DONE
+    ).update(status=ImportRequestStatus.DEAD, file_content_b64="")
+
+
+def _apply_header_to_project(project_id: str, data: ProjectData) -> None:
+    """Overwrite a create-from-import shell's name/start_date from the file header.
+
+    The shell is created synchronously with a filename-derived name and today's
+    date (ADR-0092); the parsed ``<Name>``/``<StartDate>`` are authoritative once
+    the file reads cleanly. Uses ``.update()`` to bypass django-simple-history on
+    this one-shot rename (ADR-0011).
+    """
+    from datetime import date
+
+    from trueppm_api.apps.projects.models import Project
+
+    fields: dict[str, Any] = {}
+    if data.name:
+        fields["name"] = data.name[:255]
+    if data.start_date:
+        try:
+            fields["start_date"] = date.fromisoformat(data.start_date)
+        except ValueError:
+            logger.warning("import.msproject: unparseable header start_date %r", data.start_date)
+    if fields:
+        Project.objects.filter(pk=project_id).update(**fields)
+
+
+@idempotent_task(
+    lock_key_template="drain_import_queue",
+    lock_ttl=60,
+    on_contention="skip",
+    soft_time_limit=25,
+    time_limit=30,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="msproject.drain_import_queue",
+)
+def drain_import_queue(self: object) -> None:
+    """Dispatch any pending ImportRequest outbox rows.
+
+    Runs every 30 seconds via Celery Beat.  Also recovers orphaned dispatched
+    rows older than _IMPORT_ORPHAN_MINUTES (import soft_time_limit is 9 min,
+    so 15 min ensures the prior task has either completed or timed out).
+    """
+    _do_import_drain()
+
+
+@idempotent_task(
+    lock_key_template="purge_old_import_requests",
+    lock_ttl=120,
+    on_contention="skip",
+    soft_time_limit=55,
+    time_limit=90,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="msproject.purge_old_import_requests",
+)
+def purge_old_import_requests(self: object) -> None:
+    """Delete done/dead ImportRequest rows older than 7 days.
+
+    Runs nightly via Celery Beat.  Keeps file_content_b64 blobs from
+    accumulating in the database indefinitely.
+    """
+    _do_import_purge()
+
+
+def _do_import_drain() -> None:
+    """Business logic for drain_import_queue — extracted for testability."""
+    from django.utils import timezone
+
+    from trueppm_api.apps.msproject.models import ImportRequest, ImportRequestStatus
+
+    now = timezone.now()
+    orphan_cutoff = now - timedelta(minutes=_IMPORT_ORPHAN_MINUTES)
+
+    recovered = ImportRequest.objects.filter(
+        status=ImportRequestStatus.DISPATCHED,
+        dispatched_at__lt=orphan_cutoff,
+    ).update(status=ImportRequestStatus.PENDING, celery_task_id="")
+    if recovered:
+        logger.warning("drain_import_queue: recovered %d orphaned row(s)", recovered)
+
+    pending = list(ImportRequest.objects.filter(status=ImportRequestStatus.PENDING))
+    dispatched = 0
+    for req in pending:
+        try:
+            result = import_msproject.delay(
+                project_id=str(req.project_id),
+                file_content_b64=req.file_content_b64,
+                filename=req.filename,
+                initiated_by_id=req.initiated_by_id,
+                import_request_id=str(req.id),
+                creates_project=req.creates_project,
+            )
+        except SoftTimeLimitExceeded:
+            raise
+        except Exception:
+            logger.warning(
+                "drain_import_queue: broker unavailable — ImportRequest %s stays pending",
+                req.id,
+            )
+            continue
+        ImportRequest.objects.filter(id=req.id, status=ImportRequestStatus.PENDING).update(
+            status=ImportRequestStatus.DISPATCHED,
+            celery_task_id=result.id,
+            dispatched_at=now,
+        )
+        dispatched += 1
+
+    if dispatched or recovered:
+        logger.info("drain_import_queue: dispatched=%d recovered=%d", dispatched, recovered)
+
+
+def _do_import_purge(*, dry_run: bool = False, override_value: int | None = None) -> int:
+    """Business logic for purge_old_import_requests — extracted for testability.
+
+    Retention comes from ``resolve_retention`` (operator override → the
+    TRUEPPM_IMPORT_RETENTION_DAYS default, ADR-0173); ``None`` disables the purge,
+    keeping ImportRequest blobs indefinitely. Returns rows deleted, or the eligible
+    count when ``dry_run``; ``override_value`` forces a hypothetical window.
+    """
+    from django.utils import timezone
+
+    from trueppm_api.apps.msproject.models import ImportRequest, ImportRequestStatus
+    from trueppm_api.apps.observability.retention import resolve_retention
+
+    retention_days = (
+        override_value
+        if override_value is not None
+        else resolve_retention("TRUEPPM_IMPORT_RETENTION_DAYS")
+    )
+    if retention_days is None:
+        return 0
+
+    cutoff = timezone.now() - timedelta(days=retention_days)
+    qs = ImportRequest.objects.filter(
+        status__in=[ImportRequestStatus.DONE, ImportRequestStatus.DEAD],
+        requested_at__lt=cutoff,
+    )
+    if dry_run:
+        return qs.count()
+    deleted, _ = qs.delete()
+    logger.info("purge_old_import_requests: deleted %d row(s)", deleted)
+    return deleted

trueppm_api/apps/msproject/urls.py

@@ -0,0 +1,39 @@
+"""URL routing for MS Project import/export."""
+
+from __future__ import annotations
+
+from django.urls import path
+
+from trueppm_api.apps.msproject.views import (
+    CreateProjectFromMsProjectView,
+    ImportRequestProvenanceListView,
+    MsProjectExportView,
+    MsProjectImportView,
+)
+
+urlpatterns = [
+    # Create-from-import (ADR-0092). Declared before the <project_pk> route and
+    # mounted ahead of the projects router so the literal "import" segment is not
+    # captured as a project primary key.
+    path(
+        "projects/import/msproject/",
+        CreateProjectFromMsProjectView.as_view(),
+        name="project-create-from-msproject",
+    ),
+    path(
+        "projects/<project_pk>/import/msproject/",
+        MsProjectImportView.as_view(),
+        name="project-import-msproject",
+    ),
+    # Import provenance list — read-only audit / "Imported from ..." source (#799).
+    path(
+        "projects/<project_pk>/imports/",
+        ImportRequestProvenanceListView.as_view(),
+        name="project-imports-list",
+    ),
+    path(
+        "projects/<project_pk>/export/msproject.xml",
+        MsProjectExportView.as_view(),
+        name="project-export-msproject",
+    ),
+]