trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/projects/actual_date_rules.py

@@ -0,0 +1,163 @@
+"""Shared ADR-1153 actual-date invariants (#3709).
+
+``TaskSerializer._validate_actual_dates`` was the only place these rules were
+enforced until this issue: the MS Project importer, seed replay, and inbound
+external-source sync all write ``Task.actual_start`` / ``Task.actual_finish``
+directly, bypassing the serializer entirely (REST, ``task_bulk.py``, and
+``sync/upload.py`` all reuse ``TaskSerializer``, so they were already covered).
+This module holds one implementation of the ordering, future-bound, span-cap,
+and sign-off rules so every write path enforces the same thing instead of two
+implementations that can drift.
+
+Callers own how a violation surfaces — the serializer raises a field-level DRF
+``ValidationError``; the MS Project importer drops the offending field and
+records a per-row warning instead of persisting it; seed replay does the same
+defensively (its beats are deterministic and should never trip this).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from typing import TYPE_CHECKING
+
+from django.utils import timezone
+
+from trueppm_api.apps.projects.models import MAX_PROJECT_SPAN_DAYS, TaskStatus
+
+if TYPE_CHECKING:
+    from trueppm_api.apps.projects.models import Project
+
+#: Statuses on which an ``actual_finish`` may be recorded (ADR-1153 sign-off gate).
+#: Both mean "delivered" — ``Task._coerce_signoff_percent`` forces them to 100%.
+SIGNOFF_STATUSES: frozenset[str] = frozenset({TaskStatus.REVIEW, TaskStatus.COMPLETE})
+
+
+@dataclass(frozen=True)
+class ActualDateViolation:
+    """One violated ADR-1153 actual-date rule.
+
+    ``field`` names the offending ``Task`` field (``actual_start`` or
+    ``actual_finish``) so a caller with field-level error reporting (the DRF
+    serializer) can attach the message to the right key.
+    """
+
+    field: str
+    message: str
+    code: str
+
+
+def check_actual_date_order(
+    actual_start: date | None, actual_finish: date | None
+) -> ActualDateViolation | None:
+    """Ordering rule: ``actual_start <= actual_finish`` when both are present.
+
+    Mirrors the engine's own ``_validate_task_actual_order`` so no write path can
+    persist a pair that detonates the project's next recompute.
+    """
+    if actual_start is not None and actual_finish is not None and actual_start > actual_finish:
+        return ActualDateViolation(
+            field="actual_finish",
+            message=(
+                f"Actual finish cannot be earlier than actual start ({actual_start.isoformat()})."
+            ),
+            code="actual_dates_out_of_order",
+        )
+    return None
+
+
+def check_actual_date_bound(
+    field: str, label: str, value: date | None, project: Project
+) -> ActualDateViolation | None:
+    """Future bound (``max(data date, today)``) and absolute span-cap for one field.
+
+    ``field``/``label`` name which of ``actual_start`` / ``actual_finish`` is
+    being checked, so the caller can attach either rule's message to the right
+    key without re-deriving it.
+    """
+    if value is None:
+        return None
+
+    from trueppm_api.apps.scheduling.services import resolve_cpm_status_date
+
+    upper = max(resolve_cpm_status_date(project.status_date), timezone.localdate())
+    if value > upper:
+        return ActualDateViolation(
+            field=field,
+            message=f"{label} cannot be in the future (after {upper.isoformat()}).",
+            code="actual_date_in_future",
+        )
+    # Span cap, the same class as the ordering rule and measured as an ABSOLUTE
+    # offset, so a date far in the past detonates exactly like one far in the
+    # future — the future bound above does not reach that direction, and an
+    # imported or hand-typed date carries no floor otherwise (#1068 class).
+    if abs((value - project.start_date).days) > MAX_PROJECT_SPAN_DAYS:
+        return ActualDateViolation(
+            field=field,
+            message=(
+                f"{label} is more than {MAX_PROJECT_SPAN_DAYS} days from the project "
+                "start; the schedule cannot be computed within a representable date range."
+            ),
+            code="actual_date_outside_span",
+        )
+    return None
+
+
+def check_actual_finish_signoff(
+    actual_finish: date | None, status: str | None
+) -> ActualDateViolation | None:
+    """Sign-off gate: ``actual_finish`` may only be recorded on a REVIEW/COMPLETE task.
+
+    ``engine._is_complete`` reads completion as ``actual_finish is not None or
+    percent_complete >= 100``, so a finish written onto an in-flight task pins it
+    as complete in CPM while the board still shows it in progress.
+    """
+    if actual_finish is not None and status not in SIGNOFF_STATUSES:
+        return ActualDateViolation(
+            field="actual_finish",
+            message="Actual finish can only be set on a task that is in review or complete.",
+            code="actual_finish_requires_signoff",
+        )
+    return None
+
+
+def check_actual_dates(
+    *,
+    actual_start: date | None,
+    actual_finish: date | None,
+    status: str | None,
+    project: Project | None,
+) -> ActualDateViolation | None:
+    """Validate a fully-resolved ``(actual_start, actual_finish, status)`` triple.
+
+    Convenience wrapper for a caller that writes an entire row at once — the MS
+    Project importer, seed replay — where there is no payload/instance merge to
+    do first because every value passed here is already final.
+
+    ``TaskSerializer._validate_actual_dates`` does **not** use this wrapper: a
+    partial ``PATCH`` needs different field-touch semantics per rule (ordering
+    resolves payload-else-instance so a partial write that crosses the invariant
+    against a stored value is still rejected, but the bound and sign-off checks
+    apply only to a field the write actually touches, so an unrelated PATCH on a
+    task with pre-existing invalid actuals is not blocked) — see that method's
+    own docstring. It calls :func:`check_actual_date_order`,
+    :func:`check_actual_date_bound`, and :func:`check_actual_finish_signoff`
+    directly instead.
+
+    Returns the first violated rule (ordering, then future/span bound, then
+    sign-off), or ``None``.
+    """
+    violation = check_actual_date_order(actual_start, actual_finish)
+    if violation is not None:
+        return violation
+
+    if project is not None:
+        for field, label, value in (
+            ("actual_start", "Actual start", actual_start),
+            ("actual_finish", "Actual finish", actual_finish),
+        ):
+            violation = check_actual_date_bound(field, label, value, project)
+            if violation is not None:
+                return violation
+
+    return check_actual_finish_signoff(actual_finish, status)

trueppm_api/apps/projects/amend.py

@@ -0,0 +1,133 @@
+"""Amend: a structural edit to a committed plan carries a reason (#2964).
+
+Once a plan is committed (ADR-0845), the same keystrokes that built a greenfield
+draft are now editing something other people planned around. Before this, they
+were indistinguishable: no different prompt, no record, no signal to anyone.
+
+Three properties, and the third is the one most likely to be eroded later:
+
+1. **The reason lands in plan history.** Free text, no category picker — a
+   dropdown of six blessed reasons collects the nearest wrong one, which is worse
+   than nothing because it looks like data.
+2. **It reaches the people whose work moved**, not only the person who clicked.
+3. **It is never a block.** Amend records and tells. It does not gate, refuse, or
+   require approval. A planner who cannot change a committed plan will keep the
+   real plan somewhere else, and then the tool is describing fiction.
+
+Not every edit is an amend. A draft is still a draft — authoring a plan nobody
+has agreed to yet must stay frictionless, or the commit moment becomes something
+people avoid rather than something they reach for.
+"""
+
+from __future__ import annotations
+
+import logging
+from functools import partial
+from typing import TYPE_CHECKING, Any
+
+from django.db import transaction
+
+if TYPE_CHECKING:
+    from .models import Project, Task
+
+logger = logging.getLogger(__name__)
+
+#: What a reason is attached to in `HistoricalTask.history_change_reason`.
+AMEND_PREFIX = "amend"
+
+
+def is_amendable(project: Project) -> bool:
+    """True when edits to this project are amendments rather than authoring.
+
+    Keyed on lifecycle, not on the presence of a baseline: a project can be
+    committed and its baseline capture could conceivably fail, and in that state
+    edits are still edits to something people agreed to.
+    """
+    from .models import ProjectLifecycle
+
+    return project.lifecycle == ProjectLifecycle.ACTIVE
+
+
+def record_amend_reason(task: Task, reason: str | None) -> None:
+    """Attach the reason to the row's next history entry.
+
+    ``_change_reason`` is simple_history's hook and is already how this codebase
+    annotates history (`services.py`, scope acceptance). Setting it here means the
+    reason rides the *existing* history write rather than needing a parallel audit
+    table that could disagree with it.
+
+    A blank reason is stored as the bare marker rather than being dropped: "someone
+    amended this and did not say why" is itself worth knowing, and is different
+    from "this was never amended".
+    """
+    text = (reason or "").strip()
+    task._change_reason = f"{AMEND_PREFIX}: {text}" if text else AMEND_PREFIX  # type: ignore[attr-defined]
+
+
+def notify_amend(task: Task, *, actor: Any, reason: str | None) -> None:
+    """Tell the people whose work this changed.
+
+    Recipients are everyone with a **resource assignment** on the task, minus the
+    actor. Deliberately ``TaskResource`` rather than ``Task.assignee``: capacity,
+    utilization and sprint capacity all sum ``TaskResource.units``, and a bare
+    assignee carries no load and may never reach the person — so notifying off it
+    would tell the wrong set of people that their own committed work moved.
+
+    Best-effort and deferred to ``transaction.on_commit``: a notification failure
+    must never revert an edit that has already been accepted. Amend is not a gate,
+    and a failure here must not accidentally turn it into one (the ADR-0232
+    carryover pattern, as used by ``notify_sprint_membership_change``).
+    """
+    from trueppm_api.apps.resources.models import TaskResource
+
+    actor_id = actor.pk if actor is not None and getattr(actor, "is_authenticated", False) else None
+
+    assigned = TaskResource.objects.filter(task_id=task.pk)
+    if actor_id is not None:
+        # Only exclude when there IS an actor. `.exclude(field=None)` would drop
+        # every resource with no linked user, which is the opposite of intent.
+        assigned = assigned.exclude(resource__user_id=actor_id)
+    recipient_ids = list(assigned.values_list("resource__user_id", flat=True).distinct())
+    recipient_ids = [rid for rid in recipient_ids if rid is not None]
+    if not recipient_ids:
+        return
+
+    body = _amend_body(
+        getattr(actor, "username", "") or "Someone",
+        task.name,
+        reason,
+    )
+    rows = [(rid, "A committed plan changed", body, str(task.pk)) for rid in recipient_ids]
+    transaction.on_commit(partial(_emit_amend_notifications, str(task.project_id), rows, task.pk))
+
+
+def _amend_body(actor_name: str, task_name: str, reason: str | None) -> str:
+    """The notice text.
+
+    States the reason when there is one and says so plainly when there is not —
+    "no reason given" is information, and quietly omitting the clause would make
+    an unexplained change look like an explained one.
+    """
+    text = (reason or "").strip()
+    label = task_name or "Untitled"
+    if text:
+        return f"{actor_name} changed “{label}” on a committed plan — {text}"
+    return f"{actor_name} changed “{label}” on a committed plan. No reason was given."
+
+
+def _emit_amend_notifications(
+    project_id: str,
+    rows: list[tuple[Any, str, str, str]],
+    task_pk: Any,
+) -> None:
+    from trueppm_api.apps.notifications.models import NotificationEventType
+    from trueppm_api.apps.notifications.services import create_event_notifications_batch
+
+    try:
+        create_event_notifications_batch(
+            event_type=NotificationEventType.PLAN_AMENDED,
+            project_id=project_id,
+            rows=rows,
+        )
+    except Exception:
+        logger.exception("notify_amend: emit failed for task %s", task_pk)

trueppm_api/apps/projects/apps.py

@@ -0,0 +1,38 @@
+"""App config for projects."""
+
+from django.apps import AppConfig
+
+
+class ProjectsConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "trueppm_api.apps.projects"
+
+    def ready(self) -> None:
+        """Wire signal receivers when the app starts."""
+        from django.db.backends.signals import connection_created
+
+        from trueppm_api.core.db_session import disable_jit
+
+        # PostgreSQL JIT compiles the task list's page query for seconds on large
+        # projects (#3829). Registered here because this app owns that query; the
+        # receiver applies to every connection, including Celery workers'.
+        connection_created.connect(disable_jit, dispatch_uid="trueppm_disable_pg_jit")
+
+        # Import for side-effects: registers receivers on task_status_changed.
+        from trueppm_api.apps.projects import receivers
+
+        # Register the post_save handler that resets RetroActionItem.promoted_task_id
+        # when a Task is soft-deleted (ADR-0071 §2 rollback).
+        receivers._register_task_soft_delete_receiver()
+
+        # Register the post_save handler that recomputes the linked milestone
+        # rollup live when a sprint-tracked task changes (ADR-0074).
+        receivers._register_milestone_rollup_receiver()
+
+        # Register the post_save handler that seeds methodology-aware rollup
+        # config when a Program is created (ADR-0169, #527).
+        receivers._register_program_rollup_seed_receiver()
+
+        # Register the post_save handler that resets a pulled BacklogItem to
+        # PROPOSED when its Task is soft-deleted (ADR-0069 rollback, #737).
+        receivers._register_backlog_pull_rollback_receiver()