trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/teams/views.py

@@ -0,0 +1,201 @@
+"""Viewsets for the teams app (ADR-0078 §E).
+
+The 0.3 slice is read + facet/role assignment only:
+
+* ``TeamViewSet`` — list a project's teams (no create/delete; the default team is
+  migration-created and multi-team management is #599).
+* ``TeamMembershipViewSet`` — list the roster and PATCH a member's role/facets.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.db import transaction
+from django.db.models import Count, IntegerField, OuterRef, QuerySet, Subquery
+from django.db.models.functions import Coalesce
+from rest_framework import status, viewsets
+from rest_framework.exceptions import NotFound
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.request import Request
+from rest_framework.response import Response
+
+from trueppm_api.apps.idempotency.mixins import IdempotencyMixin
+from trueppm_api.apps.teams.models import Team, TeamMembership
+from trueppm_api.apps.teams.permissions import IsTeamFacetEditor, IsTeamMember
+from trueppm_api.apps.teams.serializers import (
+    TeamMembershipReadSerializer,
+    TeamMembershipWriteSerializer,
+    TeamSerializer,
+)
+from trueppm_api.apps.teams.services import FACET_FIELDS, live_project_membership_exists
+
+
+class TeamViewSet(viewsets.GenericViewSet[Team]):
+    """Read-only team access, nested under a project."""
+
+    permission_classes = [IsAuthenticated, IsTeamMember]
+    serializer_class = TeamSerializer
+
+    def get_queryset(self) -> QuerySet[Team]:
+        # `member_count` must not count a `TeamMembership` row whose user's
+        # `ProjectMembership` on this project has been revoked (#3511) — the
+        # ADR-0078 §F mirror only ever *creates* team rows (no `post_delete`
+        # receiver, no FK a cascade could travel), so a revoked project member's
+        # team row survives with `is_deleted=False` exactly like the facet and
+        # voter-roster seams `live_project_membership_exists()` already floors
+        # (#3386/#3387/#3334). A correlated `Subquery` (not a `Count(filter=...)`
+        # on the annotated queryset itself) because the liveness `Exists` needs
+        # `TeamMembership`'s own fields (`team__project_id`, `user_id`) in scope,
+        # which a same-level aggregate filter cannot see.
+        live_member_counts = (
+            TeamMembership.objects.filter(team=OuterRef("pk"), is_deleted=False)
+            .filter(live_project_membership_exists())
+            .order_by()
+            .values("team")
+            .annotate(cnt=Count("pk"))
+            .values("cnt")
+        )
+        qs = Team.objects.filter(is_deleted=False).annotate(
+            member_count_annotated=Coalesce(
+                Subquery(live_member_counts, output_field=IntegerField()), 0
+            )
+        )
+        project_pk = self.kwargs.get("project_pk")
+        if project_pk is not None:
+            qs = qs.filter(project_id=project_pk)
+        return qs.order_by("-is_default", "name")
+
+    def list(self, request: Request, **kwargs: object) -> Response:
+        # Paginate (#1317): a project's team list is small today, but the
+        # endpoint had no bound at all — page it through the project default so
+        # it can never serialize an unbounded set as multi-team lands (#599).
+        queryset = self.get_queryset()
+        page = self.paginate_queryset(queryset)
+        if page is not None:
+            return self.get_paginated_response(TeamSerializer(page, many=True).data)
+        return Response(TeamSerializer(queryset, many=True).data)
+
+
+class TeamMembershipViewSet(IdempotencyMixin, viewsets.GenericViewSet[TeamMembership]):
+    """Roster list + role/facet assignment.
+
+    URL: /api/v1/teams/{team_pk}/members/
+         /api/v1/teams/{team_pk}/members/{pk}/   (PATCH only)
+
+    The facets are soft-singletons: setting a facet on one member clears it from
+    whichever member currently holds it on the same team, in a single transaction
+    (reassign-moves-the-facet — ADR-0078's "transitional state during handoff" is
+    realized as an atomic move rather than a tolerated double-holder).
+    """
+
+    permission_classes = [IsAuthenticated, IsTeamFacetEditor]
+
+    def get_serializer_class(self) -> type[Any]:
+        if self.action in ("partial_update", "update"):
+            return TeamMembershipWriteSerializer
+        return TeamMembershipReadSerializer
+
+    def _get_team_or_404(self) -> Team:
+        try:
+            return Team.objects.get(pk=self.kwargs["team_pk"], is_deleted=False)
+        except Team.DoesNotExist as err:
+            raise NotFound("Team not found.") from err
+
+    def get_queryset(self) -> QuerySet[TeamMembership]:
+        # Same floor as the facet/voter seams (#3386/#3387/#3334, and the
+        # `member_count` fix above, #3511): a `TeamMembership` row can be
+        # `is_deleted=False` while the user's `ProjectMembership` on this
+        # project has been revoked, because nothing cascades the revoke onto
+        # the mirrored team row. This queryset also backs `get_object()` for
+        # `partial_update`, so a revoked member's facets/role can no longer be
+        # edited through this endpoint either — there is no legitimate reason
+        # to write to a membership row for someone who has lost project access.
+        return (
+            TeamMembership.objects.select_related("user", "team")
+            .filter(team_id=self.kwargs["team_pk"], is_deleted=False)
+            .filter(live_project_membership_exists())
+            .order_by("user__username")
+        )
+
+    def list(self, request: Request, **kwargs: object) -> Response:
+        self._get_team_or_404()
+        # Paginate (#1317) — the roster grows with the team; page it through the
+        # project default rather than serializing every membership at once.
+        queryset = self.get_queryset()
+        page = self.paginate_queryset(queryset)
+        if page is not None:
+            return self.get_paginated_response(TeamMembershipReadSerializer(page, many=True).data)
+        return Response(TeamMembershipReadSerializer(queryset, many=True).data)
+
+    def partial_update(self, request: Request, pk: object = None, **kwargs: object) -> Response:
+        team = self._get_team_or_404()
+        instance = self.get_object()
+
+        serializer = TeamMembershipWriteSerializer(instance, data=request.data, partial=True)
+        serializer.is_valid(raise_exception=True)
+        data = serializer.validated_data
+
+        # Rows the broadcast must cover: the edited member plus any prior facet
+        # holder that gets cleared (the board badge moves on both). Each entry is
+        # a plain-value snapshot taken inside the transaction so the on_commit
+        # closure never dereferences a live ORM instance after commit.
+        changed: list[dict[str, object]] = []
+
+        with transaction.atomic():
+            # Lock the target row too (not just the prior holders) so two
+            # concurrent reassignments of the same facet serialize on the same
+            # rows rather than racing to a transient zero/two-holder state.
+            locked = TeamMembership.objects.select_for_update().get(pk=instance.pk)
+
+            # Reassign each facet being turned ON: clear it from the current holder
+            # so the team ends with at most one. Locking the holders avoids a race
+            # where two concurrent assignments both believe they cleared the prior.
+            # Deliberately NOT floored on `live_project_membership_exists()` (unlike
+            # get_queryset() above, #3511): the singleton invariant must hold across
+            # every `is_deleted=False` row, including a revoked-but-still-live-row
+            # ghost holder, or a stale facet survives on a row this endpoint can no
+            # longer even see and resurfaces the moment the member is reinstated.
+            for facet in FACET_FIELDS:
+                if data.get(facet) is True:
+                    holders = (
+                        TeamMembership.objects.select_for_update()
+                        .filter(team=team, is_deleted=False, **{facet: True})
+                        .exclude(pk=locked.pk)
+                    )
+                    for holder in holders:
+                        setattr(holder, facet, False)
+                        holder.save(update_fields=[facet])
+                        changed.append(self._broadcast_snapshot(team, holder))
+
+            for field, value in data.items():
+                setattr(locked, field, value)
+            locked.save(update_fields=list(data.keys()))
+            instance = locked
+            changed.append(self._broadcast_snapshot(team, locked))
+
+        # Broadcast to the project board so other clients reflect the new facet
+        # holder(s) without a refetch. Deferred to commit so a rolled-back write
+        # broadcasts nothing.
+        project_id = str(team.project_id)
+        from trueppm_api.apps.sync.broadcast import broadcast_board_event
+
+        def _emit() -> None:
+            for payload in changed:
+                broadcast_board_event(project_id, "team_member_changed", payload)
+
+        transaction.on_commit(_emit)
+
+        return Response(TeamMembershipReadSerializer(instance).data, status=status.HTTP_200_OK)
+
+    @staticmethod
+    def _broadcast_snapshot(team: Team, membership: TeamMembership) -> dict[str, object]:
+        """Capture a membership's broadcast fields as plain values (no ORM ref)."""
+        return {
+            "membership_id": str(membership.pk),
+            "user_id": str(membership.user_id),
+            "team_id": str(team.pk),
+            "role": membership.role,
+            "is_scrum_master": membership.is_scrum_master,
+            "is_product_owner": membership.is_product_owner,
+        }

trueppm_api/apps/timetracking/apps.py

@@ -0,0 +1,9 @@
+"""App config for the time-tracking app (ADR-0185)."""
+
+from django.apps import AppConfig
+
+
+class TimetrackingConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "trueppm_api.apps.timetracking"
+    verbose_name = "Time tracking"

trueppm_api/apps/timetracking/migrations/0001_initial.py

@@ -0,0 +1,117 @@
+# Generated by Django 5.2.14 on 2026-06-30 12:51
+
+import uuid
+
+import django.core.validators
+import django.db.models.deletion
+import django.utils.timezone
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        ("projects", "0097_backlogitem_backlogitem_tags_gin_and_more"),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="ActiveTimer",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                ("started_at", models.DateTimeField()),
+                ("note", models.CharField(blank=True, max_length=500)),
+                (
+                    "task",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="+",
+                        to="projects.task",
+                    ),
+                ),
+                (
+                    "user",
+                    models.OneToOneField(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="active_timer",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "db_table": "timetracking_active_timer",
+            },
+        ),
+        migrations.CreateModel(
+            name="TimeEntry",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                ("server_version", models.BigIntegerField(default=0, editable=False)),
+                ("is_deleted", models.BooleanField(db_index=True, default=False)),
+                ("deleted_version", models.BigIntegerField(blank=True, editable=False, null=True)),
+                (
+                    "minutes",
+                    models.PositiveIntegerField(
+                        validators=[
+                            django.core.validators.MinValueValidator(1),
+                            django.core.validators.MaxValueValidator(1440),
+                        ]
+                    ),
+                ),
+                ("entry_date", models.DateField(default=django.utils.timezone.localdate)),
+                ("note", models.CharField(blank=True, max_length=500)),
+                (
+                    "source",
+                    models.CharField(
+                        choices=[("manual", "Manual"), ("timer", "Timer")],
+                        default="manual",
+                        max_length=10,
+                    ),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                (
+                    "task",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="time_entries",
+                        to="projects.task",
+                    ),
+                ),
+                (
+                    "user",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="time_entries",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "db_table": "timetracking_time_entry",
+                "indexes": [
+                    models.Index(
+                        fields=["user", "entry_date"], name="timetrackin_user_id_8b4245_idx"
+                    ),
+                    models.Index(
+                        fields=["user", "task", "entry_date"], name="timetrackin_user_id_8c4ce4_idx"
+                    ),
+                    models.Index(
+                        fields=["task", "server_version"], name="timetrackin_task_id_efb2b5_idx"
+                    ),
+                ],
+            },
+        ),
+    ]

trueppm_api/apps/timetracking/migrations/0002_timesheetsubmission.py

@@ -0,0 +1,46 @@
+# Generated by Django 5.2.15 on 2026-07-05 16:02
+
+import uuid
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("timetracking", "0001_initial"),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="TimesheetSubmission",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                ("week_start", models.DateField()),
+                ("submitted_at", models.DateTimeField()),
+                (
+                    "user",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="timesheet_submissions",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "db_table": "timetracking_timesheet_submission",
+                "constraints": [
+                    models.UniqueConstraint(
+                        fields=("user", "week_start"), name="uniq_timesheet_submission_user_week"
+                    )
+                ],
+            },
+        ),
+    ]

trueppm_api/apps/timetracking/migrations/0003_timeentry_deleted_at_timeentry_deleted_by.py

@@ -0,0 +1,31 @@
+# Generated by Django 5.2.16 on 2026-07-13 21:27
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("timetracking", "0002_timesheetsubmission"),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="timeentry",
+            name="deleted_at",
+            field=models.DateTimeField(blank=True, null=True),
+        ),
+        migrations.AddField(
+            model_name="timeentry",
+            name="deleted_by",
+            field=models.ForeignKey(
+                blank=True,
+                null=True,
+                on_delete=django.db.models.deletion.SET_NULL,
+                related_name="deleted_time_entries",
+                to=settings.AUTH_USER_MODEL,
+            ),
+        ),
+    ]

trueppm_api/apps/timetracking/migrations/0004_timeentry_sync_seq_and_more.py

@@ -0,0 +1,24 @@
+# Generated by Django 5.2.16 on 2026-07-28 12:47
+
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("projects", "0128_acceptancecriterion_sync_seq_apitoken_sync_seq_and_more"),
+        ("timetracking", "0003_timeentry_deleted_at_timeentry_deleted_by"),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="timeentry",
+            name="sync_seq",
+            field=models.BigIntegerField(default=0, editable=False),
+        ),
+        migrations.AddIndex(
+            model_name="timeentry",
+            index=models.Index(fields=["task", "sync_seq"], name="timetrackin_task_id_a6ce52_idx"),
+        ),
+    ]

trueppm_api/apps/timetracking/models.py

@@ -0,0 +1,178 @@
+"""Time-tracking domain models — logged effort and the running timer (ADR-0185 §2).
+
+``TimeEntry`` is the durable, sync-eligible fact; ``ActiveTimer`` is transient live
+state. The split is deliberate (ADR-0185 §2): a ticking timer is derived state, not a
+logged fact, so it is *not* a ``VersionedModel`` and a stopped timer is hard-deleted,
+not soft-deleted. Nothing here broadcasts — a time entry mutates no shared board state
+(ADR-0185 §5).
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from django.conf import settings
+from django.core.validators import MaxValueValidator, MinValueValidator
+from django.db import models
+from django.utils import timezone
+
+from trueppm_api.apps.projects.models import VersionedModel
+
+
+class TimeEntrySource(models.TextChoices):
+    """Provenance of a logged entry — drives the UI/undo affordance."""
+
+    MANUAL = "manual", "Manual"
+    TIMER = "timer", "Timer"
+
+
+class TimeEntry(VersionedModel):
+    """A contributor's logged effort against a task (ADR-0185 §2).
+
+    The durable, sync-eligible record of *where a user's hours went*. The row is owned
+    by the logger: ``user`` is server-set to ``request.user`` and is never client-
+    supplied, so the entry is IDOR-safe by construction. Duration is canonical integer
+    ``minutes`` (1..1440) to avoid the decimal-hours rounding drift the constraint
+    exists to prevent — the client formats ``h:mm``.
+
+    There is **no** uniqueness constraint on ``(user, task, entry_date)``: a contributor
+    may legitimately log multiple entries against the same task on the same day (two
+    sessions). The weekly grid aggregates them.
+    """
+
+    task = models.ForeignKey(
+        "projects.Task",
+        on_delete=models.CASCADE,
+        related_name="time_entries",
+    )
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="time_entries",
+    )
+    minutes = models.PositiveIntegerField(
+        validators=[MinValueValidator(1), MaxValueValidator(1440)],
+    )
+    entry_date = models.DateField(default=timezone.localdate)
+    note = models.CharField(max_length=500, blank=True)
+    source = models.CharField(
+        max_length=10,
+        choices=TimeEntrySource.choices,
+        default=TimeEntrySource.MANUAL,
+    )
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    # Soft-delete accountability (issue #1888). The base ``VersionedModel.soft_delete()``
+    # only flips ``is_deleted``, so a removed entry left no trace of *when* or *by whom*
+    # — and the task activity stream, which filtered ``is_deleted=False``, silently
+    # dropped its ``time_logged`` event too. That is an EVM/billing integrity gap: logged
+    # hours could be revised or removed with no record. These fields let the stream
+    # synthesize a ``time_deleted`` event, mirroring the ``TaskComment``/``TaskAttachment``
+    # soft-delete precedent. ``deleted_by`` is the acting user (always the owner — entries
+    # are self-scoped) and SET_NULLs on account deletion, so the event actor goes null.
+    deleted_at = models.DateTimeField(null=True, blank=True)
+    deleted_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="deleted_time_entries",
+    )
+
+    class Meta:
+        db_table = "timetracking_time_entry"
+        indexes = [
+            # Header today/week rollup + weekly grid read.
+            models.Index(fields=["user", "entry_date"]),
+            # Grid cell (task, date) upsert/aggregate.
+            models.Index(fields=["user", "task", "entry_date"]),
+            # Per-project sync delta pull (task → server_version).
+            models.Index(fields=["task", "server_version"]),
+            models.Index(fields=["task", "sync_seq"]),
+        ]
+
+    def __str__(self) -> str:
+        return f"TimeEntry({self.user_id}, {self.minutes}m, {self.entry_date})"
+
+    def soft_delete(self, *, actor: Any | None = None) -> None:
+        """Stamp ``deleted_at``/``deleted_by`` before delegating to the base soft-delete.
+
+        Mirrors ``Dependency.soft_delete()``'s stamping (issue #1888): the base
+        ``VersionedModel.soft_delete()`` persists the whole row, so setting these two
+        fields first writes them in the same UPDATE that flips ``is_deleted``. Without
+        the timestamp the activity stream could not order or surface the ``time_deleted``
+        event, so a removed entry vanished from the ``time_logged`` feed with no trace.
+        """
+        self.deleted_at = timezone.now()
+        self.deleted_by = actor
+        super().soft_delete()
+
+
+class ActiveTimer(models.Model):
+    """The running stopwatch — transient live state, deliberately NOT versioned (ADR-0185 §2).
+
+    Elapsed time is derived (``now - started_at``); the row carries no logged fact, so
+    syncing it as versioned WatermelonDB rows would churn for a value the client
+    recomputes locally. The ``OneToOneField(user)`` is the singleton guarantee — a user
+    has at most one running timer at the DB level (cleaner than a partial unique on a
+    status flag). ``stop`` finalizes it into a ``TimeEntry`` and *deletes* this row
+    (no tombstone to sync); it is recovered after a reload via ``GET /me/timer/``.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    user = models.OneToOneField(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="active_timer",
+    )
+    task = models.ForeignKey(
+        "projects.Task",
+        on_delete=models.CASCADE,
+        related_name="+",
+    )
+    started_at = models.DateTimeField()
+    note = models.CharField(max_length=500, blank=True)
+
+    class Meta:
+        db_table = "timetracking_active_timer"
+
+    def __str__(self) -> str:
+        return f"ActiveTimer({self.user_id} -> {self.task_id})"
+
+
+class TimesheetSubmission(models.Model):
+    """A contributor's "I marked this week done" signal — a per-user-per-week marker (ADR-0224).
+
+    Deliberately **not** a :class:`VersionedModel` (mirrors :class:`ActiveTimer`): submitting a
+    week is an inherently *online* action on a web-first surface, and the row carries no field a
+    client edits offline, so WatermelonDB version/tombstone machinery would churn sync for a
+    boolean-shaped signal. It is the whole submission state machine 0.4 ships — no approver, no
+    lock, no return; the 0.5 approval epic (#100) reads or extends this row's existence +
+    ``submitted_at`` as its "Submitted" signal without migrating :class:`TimeEntry`.
+
+    ``week_start`` is canonicalized to the ISO Monday by the view before write, so the
+    ``(user, week_start)`` uniqueness cannot fragment into off-by-a-day rows. Un-submit hard-
+    deletes the row (no tombstone — not sync-eligible).
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="timesheet_submissions",
+    )
+    week_start = models.DateField()
+    submitted_at = models.DateTimeField()
+
+    class Meta:
+        db_table = "timetracking_timesheet_submission"
+        constraints = [
+            models.UniqueConstraint(
+                fields=["user", "week_start"],
+                name="uniq_timesheet_submission_user_week",
+            ),
+        ]
+
+    def __str__(self) -> str:
+        return f"TimesheetSubmission({self.user_id}, week of {self.week_start})"