trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/projects/wbs_paths.py

@@ -0,0 +1,119 @@
+"""Placing an externally-numbered block of tasks into a project that already has rows.
+
+Every document that carries a WBS — a published template, an ``.mpp`` export, a CSV,
+a Jira pull — numbers its tasks from ``1``, because it was written against a project
+that started empty. That is correct exactly once. Writing those paths verbatim into a
+project that already holds rows puts two live tasks on the same ``wbs_path``, and
+``wbs_path`` is the only thing that records parenthood (there is no ``parent_id``
+column), so the collision is not a cosmetic numbering clash — it collapses the next
+``rewrite_level`` pass and strands the subtree underneath.
+
+The pair here is the fix for that, and it lives in its own module because it is not
+template-specific: it was written for template adoption (#3061) and the three
+importer paths need the identical rule (#3069). One definition means a repaired row,
+a seeded row and an imported row all agree about where "past the end" is.
+
+Everything here is pure reads plus arithmetic — no writes, no locking. The caller
+owns the transaction, and is responsible for holding it across the read and the
+insert if concurrent writers are possible.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+
+def min_root_ordinal(paths: Iterable[str | None]) -> int | None:
+    """The smallest numeric root label in ``paths``, or ``None`` if there is none.
+
+    Separated out because it is the half of the offset calculation that reads the
+    incoming document rather than the project, and because a caller that has already
+    computed it should not have to hand the whole path list over a second time.
+    """
+    heads = (str(path).partition(".")[0] for path in paths if path)
+    return min((int(head) for head in heads if head.isdigit()), default=None)
+
+
+def root_ordinal_offset(
+    project_id: Any,
+    *,
+    include_deleted: bool = False,
+    document_paths: Iterable[str | None] | None = None,
+) -> int:
+    """How far to shift an incoming document's root ordinals so they land past what exists.
+
+    Returns ``0`` for a project with no numeric root labels — so a first adoption is
+    shifted by nothing and keeps the document's paths exactly. Otherwise the shift
+    lands the document's *lowest* root ordinal one position past the project's
+    highest, which is what keeps the numbering contiguous across repeat adoptions.
+
+    ``document_paths`` is the incoming document's paths. It defaults to ``None``,
+    which assumes the document numbers its roots from ``1`` — the convention this
+    module's docstring describes, and what every template and export we have does.
+    That assumption is the whole reason the parameter exists: a document carrying a
+    root of ``0`` (legal in ltree, and an ``.mpp`` or CSV can hold one) maps ``0``
+    onto the project's highest existing ordinal under a from-1 shift and collides
+    with it. Passing the real paths costs one pass over a list the caller already
+    has and removes the assumption. The default reproduces the previous behavior
+    exactly, so a caller that has not been updated is no worse off than before.
+
+    ``include_deleted`` widens the scan to tombstoned rows. The uniqueness constraint
+    covers live rows only, so a tombstone cannot collide with anything being written
+    now — but it still *holds* its number, and a later restore has to have somewhere
+    to come back to. Callers allocating a number that a restore might later contend
+    with should pass ``True``; callers that only care about what is legal right now
+    can leave it ``False``.
+    """
+    from django.db.models.expressions import RawSQL
+
+    from trueppm_api.apps.projects.models import Task
+
+    rows = Task.objects.filter(project_id=project_id, wbs_path__isnull=False)
+    if not include_deleted:
+        rows = rows.filter(is_deleted=False)
+    labels = (
+        # nosec B611 — static SQL literal (no user input), empty params list; the
+        # ltree subpath() call can't be expressed in the ORM. Bandit flags any RawSQL.
+        # nosemgrep: avoid-raw-sql
+        rows.annotate(root_label=RawSQL("subpath(projects_task.wbs_path, 0, 1)::text", []))  # nosec B611
+        .values_list("root_label", flat=True)
+        # Task.Meta.ordering is ["wbs_path", "name"], and Postgres requires every
+        # ORDER BY expression to appear in a SELECT DISTINCT list — so without this
+        # Django widens the DISTINCT key to (root_label, wbs_path, name), which is
+        # unique per task. The query then streams one row per task, plus a sort, to
+        # compute a single integer. Clearing the ordering is what makes the "distinct
+        # root labels" this docstring promises actually true.
+        .order_by()
+        .distinct()
+    )
+    highest = max((int(label) for label in labels if str(label).isdigit()), default=None)
+    if highest is None:
+        return 0
+    document_floor = 1 if document_paths is None else min_root_ordinal(document_paths)
+    if document_floor is None:
+        return 0
+    # Clamped at zero: a document numbered above the project's highest root already
+    # lands past it, and a negative shift would drag it back onto occupied ground.
+    return max(highest - document_floor + 1, 0)
+
+
+def offset_wbs_path(path: str | None, offset: int) -> str | None:
+    """Shift a path's leading segment by ``offset``, preserving its subtree.
+
+    Only the leading segment moves: every path in an incoming document is relative
+    to a fresh project rooted at ``1``, so remapping just the head keeps the
+    document's whole tree shape intact ("2.1.3" under offset 4 becomes "6.1.3").
+    That is also why the ancestor/descendant relationships the caller derives from
+    these paths — summary-task detection, for one — are unaffected by the shift.
+
+    A non-numeric root label is left alone: it cannot be offset meaningfully, and
+    the ``(project, wbs_path)`` constraint now rejects it loudly if it does collide.
+    """
+    if not path or offset == 0:
+        return path or None
+    head, _, rest = str(path).partition(".")
+    if not head.isdigit():
+        return str(path)
+    shifted = str(int(head) + offset)
+    return f"{shifted}.{rest}" if rest else shifted

trueppm_api/apps/resources/apps.py

@@ -0,0 +1,8 @@
+"""App config for resources."""
+
+from django.apps import AppConfig
+
+
+class ResourcesConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "trueppm_api.apps.resources"

trueppm_api/apps/resources/capacity.py

@@ -0,0 +1,121 @@
+"""Effective per-project resource capacity — the one place the override resolves.
+
+``ProjectResource.units_override`` is a **per-project** capacity statement ("this
+person is only half on this project"). Every per-project capacity read must resolve
+it the same way, or two adjacent surfaces report different numbers for the same
+person on the same day (#3574).
+
+The fallback expression itself was duplicated across the model, the serializer and
+the utilization engine (#1582). Every Python resolution now goes through
+:func:`effective_units`. There is exactly ONE other copy, and it is unavoidable:
+``annotate_tasks_queryset`` resolves the same rule SQL-side as
+``Coalesce("units_override", "resource__max_units")`` because the comparison happens
+inside a subquery's HAVING. Keep the two in step; do not add a third.
+
+Cross-project reads (``resource-contention``, and any other span that aggregates
+several projects at once) deliberately keep ``Resource.max_units``: a slice of one
+person's time on one project is not a statement about their total capacity, and the
+slices are not additive.
+
+This module is the OSS-side read surface for that fact. A cross-project consumer that
+aggregates per-project capacity must **call** :func:`projects_effective_units` rather
+than re-derive the fallback — a second copy of it is how #3574 happened, and any
+reimplementation reaching for ``units_override or max_units`` gets the legitimate ``0``
+wrong.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+# Stand-in when a resource row carries no capacity at all. Mirrors
+# ``Resource.max_units``' own model default (full time), rendered at the field's two
+# decimal places so a fallback and a stored value serialize identically.
+DEFAULT_MAX_UNITS = Decimal("1.00")
+
+
+def effective_units(
+    units_override: Decimal | None,
+    max_units: Decimal | None,
+) -> Decimal:
+    """Resolve one resource's effective capacity on one project.
+
+    Args:
+        units_override: ``ProjectResource.units_override`` for this (project,
+            resource) pair, or ``None`` when the pair has no roster row or the
+            roster row sets no override.
+        max_units: ``Resource.max_units``, the resource's default capacity.
+
+    Returns:
+        The override when one is set, otherwise the resource default.
+
+    ``units_override`` is nullable **and** ``0`` is a legitimate stored value — a
+    person rostered on a project but holding no capacity there. The test is
+    therefore ``is not None`` and never truthiness: ``units_override or max_units``
+    would silently promote a deliberate 0 back to full time, which is the inverse of
+    what the override was set to say.
+    """
+    if units_override is not None:
+        return Decimal(units_override)
+    if max_units is not None:
+        return Decimal(max_units)
+    return DEFAULT_MAX_UNITS
+
+
+def project_effective_units(project_id: Any) -> dict[str, Decimal]:
+    """Map ``str(resource_id) -> effective capacity`` for one project's roster.
+
+    One query. Resources with assignments on the project but no roster row are
+    absent from the map by construction — callers fall back to
+    ``Resource.max_units`` for those, which is what an unrostered assignee's
+    capacity is.
+    """
+    return projects_effective_units([project_id]).get(str(project_id), {})
+
+
+def resource_effective_units(project_id: Any, resource: Any) -> Decimal:
+    """One resource's effective capacity on one project — a single-row lookup.
+
+    For callers that need exactly one pair. Hits the
+    ``uniq_project_resource_project_resource`` unique index rather than reading the
+    whole roster; use :func:`project_effective_units` when several are needed.
+    Falls back to ``resource.max_units`` when the resource is not on the roster.
+    """
+    from trueppm_api.apps.resources.models import ProjectResource
+
+    row = (
+        ProjectResource.objects.filter(
+            project_id=project_id, resource_id=resource.pk, is_deleted=False
+        )
+        .values_list("units_override")
+        .first()
+    )
+    return effective_units(row[0] if row is not None else None, resource.max_units)
+
+
+def projects_effective_units(project_ids: Iterable[Any]) -> dict[str, dict[str, Decimal]]:
+    """Batched :func:`project_effective_units` — one query for many projects.
+
+    Returns ``{str(project_id): {str(resource_id): capacity}}``. Callers that span
+    several projects (the batched sprint capacity path, #1012) use this so threading
+    the override does not reintroduce a per-project query.
+    """
+    from trueppm_api.apps.resources.models import ProjectResource
+
+    ids = [pid for pid in project_ids if pid is not None]
+    if not ids:
+        return {}
+
+    out: dict[str, dict[str, Decimal]] = {}
+    rows = ProjectResource.objects.filter(project_id__in=ids, is_deleted=False).values_list(
+        "project_id", "resource_id", "units_override", "resource__max_units"
+    )
+    for project_id, resource_id, units_override, max_units in rows:
+        out.setdefault(str(project_id), {})[str(resource_id)] = effective_units(
+            units_override, max_units
+        )
+    return out

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

@@ -0,0 +1,68 @@
+"""Initial migration for resources app."""
+
+from __future__ import annotations
+
+import uuid
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        ("projects", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Resource",
+            fields=[
+                ("id", models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True)),
+                ("server_version", models.BigIntegerField(default=0, editable=False)),
+                ("name", models.CharField(max_length=255)),
+                ("email", models.EmailField(blank=True)),
+                (
+                    "calendar",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.PROTECT,
+                        related_name="resources",
+                        to="projects.calendar",
+                    ),
+                ),
+                ("max_units", models.DecimalField(decimal_places=2, default=1.0, max_digits=4)),
+            ],
+            options={"db_table": "resources_resource", "ordering": ["name"]},
+        ),
+        migrations.CreateModel(
+            name="TaskResource",
+            fields=[
+                ("id", models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True)),
+                (
+                    "task",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="assignments",
+                        to="projects.task",
+                    ),
+                ),
+                (
+                    "resource",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="assignments",
+                        to="resources.resource",
+                    ),
+                ),
+                ("units", models.DecimalField(decimal_places=2, default=1.0, max_digits=4)),
+            ],
+            options={"db_table": "resources_task_resource"},
+        ),
+        migrations.AlterUniqueTogether(
+            name="taskresource",
+            unique_together={("task", "resource")},
+        ),
+    ]

trueppm_api/apps/resources/migrations/0001_squashed_0013_alter_projectresource_unique_together_and_more.py

@@ -0,0 +1,281 @@
+# Generated by Django 5.2.14 on 2026-06-23 21:38
+
+import uuid
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    replaces = [
+        ("resources", "0001_initial"),
+        ("resources", "0002_alter_uuid_pk_serialize_false"),
+        ("resources", "0003_resource_soft_delete"),
+        ("resources", "0004_add_taskresource_resource_index"),
+        ("resources", "0005_resource_job_role"),
+        ("resources", "0006_skill"),
+        ("resources", "0007_resource_skill"),
+        ("resources", "0008_project_resource"),
+        ("resources", "0009_task_skill_requirement"),
+        ("resources", "0010_alter_resourceskill_options_and_more"),
+        ("resources", "0011_alter_projectresource_notes"),
+        ("resources", "0012_add_resource_user_fk"),
+        ("resources", "0013_alter_projectresource_unique_together_and_more"),
+    ]
+
+    initial = True
+
+    dependencies = [
+        ("projects", "0001_initial"),
+        ("projects", "0018_estimation_governance"),
+        ("projects", "0078_alter_risktask_unique_together_and_more"),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Resource",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                ("server_version", models.BigIntegerField(default=0, editable=False)),
+                ("name", models.CharField(max_length=255)),
+                ("email", models.EmailField(blank=True, max_length=254)),
+                (
+                    "calendar",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.PROTECT,
+                        related_name="resources",
+                        to="projects.calendar",
+                    ),
+                ),
+                ("max_units", models.DecimalField(decimal_places=2, default=1.0, max_digits=4)),
+                ("is_deleted", models.BooleanField(db_index=True, default=False)),
+                ("deleted_version", models.BigIntegerField(blank=True, editable=False, null=True)),
+                ("job_role", models.CharField(blank=True, max_length=120)),
+                (
+                    "user",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        related_name="resources",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "db_table": "resources_resource",
+                "ordering": ["name"],
+            },
+        ),
+        migrations.CreateModel(
+            name="Skill",
+            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)),
+                ("name", models.CharField(max_length=120)),
+                ("normalized_name", models.CharField(max_length=120, unique=True)),
+                ("category", models.CharField(blank=True, max_length=60)),
+            ],
+            options={
+                "db_table": "resources_skill",
+                "ordering": ["name"],
+            },
+        ),
+        migrations.CreateModel(
+            name="ProjectResource",
+            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)),
+                (
+                    "project",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="resource_pool",
+                        to="projects.project",
+                    ),
+                ),
+                (
+                    "resource",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="project_memberships",
+                        to="resources.resource",
+                    ),
+                ),
+                ("role_title", models.CharField(blank=True, max_length=120)),
+                (
+                    "units_override",
+                    models.DecimalField(blank=True, decimal_places=2, max_digits=4, null=True),
+                ),
+                ("notes", models.TextField(blank=True, default="")),
+            ],
+            options={
+                "db_table": "resources_project_resource",
+                "unique_together": set(),
+                "indexes": [
+                    models.Index(fields=["project", "is_deleted"], name="proj_res_proj_del_idx")
+                ],
+                "constraints": [
+                    models.UniqueConstraint(
+                        fields=("project", "resource"),
+                        name="uniq_project_resource_project_resource",
+                    )
+                ],
+            },
+        ),
+        migrations.CreateModel(
+            name="ResourceSkill",
+            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)),
+                (
+                    "resource",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="skills",
+                        to="resources.resource",
+                    ),
+                ),
+                (
+                    "skill",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.PROTECT,
+                        related_name="resources",
+                        to="resources.skill",
+                    ),
+                ),
+                (
+                    "proficiency",
+                    models.IntegerField(
+                        choices=[(1, "Beginner"), (2, "Intermediate"), (3, "Expert")], default=2
+                    ),
+                ),
+            ],
+            options={
+                "db_table": "resources_resource_skill",
+                "unique_together": set(),
+                "indexes": [
+                    models.Index(fields=["skill", "proficiency"], name="res_skill_prof_idx")
+                ],
+                "ordering": ["skill__name"],
+                "constraints": [
+                    models.UniqueConstraint(
+                        fields=("resource", "skill"), name="uniq_resource_skill_resource_skill"
+                    )
+                ],
+            },
+        ),
+        migrations.CreateModel(
+            name="TaskResource",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                (
+                    "task",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="assignments",
+                        to="projects.task",
+                    ),
+                ),
+                (
+                    "resource",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="assignments",
+                        to="resources.resource",
+                    ),
+                ),
+                ("units", models.DecimalField(decimal_places=2, default=1.0, max_digits=4)),
+            ],
+            options={
+                "db_table": "resources_task_resource",
+                "unique_together": set(),
+                "constraints": [
+                    models.UniqueConstraint(
+                        fields=("task", "resource"), name="uniq_task_resource_task_resource"
+                    )
+                ],
+            },
+        ),
+        migrations.CreateModel(
+            name="TaskSkillRequirement",
+            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)),
+                (
+                    "task",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="skill_requirements",
+                        to="projects.task",
+                    ),
+                ),
+                (
+                    "skill",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.PROTECT,
+                        related_name="task_requirements",
+                        to="resources.skill",
+                    ),
+                ),
+                (
+                    "min_proficiency",
+                    models.IntegerField(
+                        choices=[(1, "Beginner"), (2, "Intermediate"), (3, "Expert")], default=1
+                    ),
+                ),
+            ],
+            options={
+                "db_table": "resources_task_skill_requirement",
+                "unique_together": set(),
+                "ordering": ["skill__name"],
+                "constraints": [
+                    models.UniqueConstraint(
+                        fields=("task", "skill"), name="uniq_task_skill_req_task_skill"
+                    )
+                ],
+            },
+        ),
+    ]

trueppm_api/apps/resources/migrations/0002_alter_uuid_pk_serialize_false.py

@@ -0,0 +1,36 @@
+"""Add serialize=False to UUID primary key fields.
+
+Django 5's migration autodetector expects primary_key=True UUIDs to also
+carry serialize=False in the migration state. Without it, makemigrations
+--check reports spurious "Alter field id" operations on every run.
+No database schema change is made by these operations.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("resources", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="resource",
+            name="id",
+            field=models.UUIDField(
+                default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+            ),
+        ),
+        migrations.AlterField(
+            model_name="taskresource",
+            name="id",
+            field=models.UUIDField(
+                default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+            ),
+        ),
+    ]

trueppm_api/apps/resources/migrations/0003_resource_soft_delete.py

@@ -0,0 +1,30 @@
+"""Add soft-delete fields to Resource.
+
+VersionedModel gained is_deleted and deleted_version in the projects 0004
+migration. Resource extends VersionedModel and needs the same columns so
+the schema matches the model definition. TaskResource extends models.Model
+directly and does not need these fields.
+"""
+
+from __future__ import annotations
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("resources", "0002_alter_uuid_pk_serialize_false"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="resource",
+            name="is_deleted",
+            field=models.BooleanField(db_index=True, default=False),
+        ),
+        migrations.AddField(
+            model_name="resource",
+            name="deleted_version",
+            field=models.BigIntegerField(blank=True, editable=False, null=True),
+        ),
+    ]