From ad2498a35e168d4d031b8d8a7501e26cc9be7020 Mon Sep 17 00:00:00 2001 From: Ashwin Date: Wed, 12 Aug 2026 17:52:00 +0530 Subject: [PATCH 1/2] feat: implement move functionality for opportunities, tasks, and leads - Added tests for moving leads, allowing non-admin creators to move their own leads. - Updated the LeadMoveView to support moving leads with explicit order and improved permission checks. - Introduced OpportunityMoveSerializer for moving opportunities, including permission checks for creators and assignees. - Created tests for moving opportunities, ensuring proper RBAC and handling of closed stages. - Enhanced TaskMoveView to allow non-admin creators to move tasks, with similar permission checks. - Updated frontend to support moving deals with drag-and-drop functionality, including optimistic UI updates and error handling. - Added API endpoints for moving opportunities and updated mobile app to utilize the new move functionality. --- backend/cases/kanban_views.py | 94 +++------- backend/cases/tests/test_cases_kanban.py | 28 +++ backend/common/kanban.py | 110 +++++++++++ backend/common/tests/test_kanban_ordering.py | 149 +++++++++++++++ backend/leads/tests/test_leads_kanban.py | 32 ++++ backend/leads/views/kanban_views.py | 98 +++------- backend/manage.py | 3 + backend/opportunity/serializer.py | 13 +- .../tests/test_opportunity_move.py | 177 ++++++++++++++++++ backend/opportunity/views/kanban_views.py | 141 +++++++------- backend/tasks/tests/test_tasks_kanban.py | 29 +++ backend/tasks/views/kanban_views.py | 97 +++------- frontend/src/lib/server/v2/deals.js | 28 +++ .../src/routes/(app)/pipeline/+page.server.js | 30 +++ .../src/routes/(app)/pipeline/+page.svelte | 143 +++++++++++--- mobile/lib/config/api_config.dart | 11 ++ mobile/lib/providers/deals_provider.dart | 25 ++- 17 files changed, 881 insertions(+), 327 deletions(-) create mode 100644 backend/common/kanban.py create mode 100644 backend/common/tests/test_kanban_ordering.py create mode 100644 backend/opportunity/tests/test_opportunity_move.py diff --git a/backend/cases/kanban_views.py b/backend/cases/kanban_views.py index 16187e57..ae96a420 100644 --- a/backend/cases/kanban_views.py +++ b/backend/cases/kanban_views.py @@ -3,8 +3,6 @@ Kanban views for case management. Supports both status-based (default) and custom pipeline-based kanban boards. """ -from decimal import Decimal - from django.db import transaction from django.db.models import Q from django.shortcuts import get_object_or_404 @@ -22,6 +20,7 @@ from cases.serializer import ( CasePipelineSerializer, CaseStageSerializer, ) +from common.kanban import place_in_column from common.permissions import HasOrgContext, is_org_admin from common.utils import STATUS_CHOICE from common.validators import date_param, uuid_param @@ -236,7 +235,9 @@ class CaseMoveView(APIView): def patch(self, request, pk): """Move case to different column and/or position.""" org = request.profile.org - case = get_object_or_404(Case, pk=pk, org=org) + # Locked for the transaction: the move saves the whole row, so an + # edit committing between this read and that save would be lost. + case = get_object_or_404(Case.objects.select_for_update(), pk=pk, org=org) # Permission check if not is_org_admin(request.profile) and not request.user.is_superuser: @@ -286,8 +287,15 @@ class CaseMoveView(APIView): case.status = data["status"] # Calculate new order - new_order = self._calculate_order(data, case, org) - case.kanban_order = new_order + # `case.stage`/`case.status` are already the destination by this + # point, so the column queryset describes where the card is landing. + case.kanban_order = place_in_column( + self._column_qs(case, org), + above_id=data.get("above_case_id"), + below_id=data.get("below_case_id"), + explicit=data.get("kanban_order"), + exclude_pk=case.pk, + ) case.save() @@ -299,76 +307,20 @@ class CaseMoveView(APIView): } ) - def _calculate_order(self, data, case, org): - """Calculate the new kanban_order based on position hints.""" - if "kanban_order" in data: - return data["kanban_order"] + def _column_qs(self, case, org): + """The destination column, as a queryset. - above_id = data.get("above_case_id") - below_id = data.get("below_case_id") - - if above_id and below_id: - above_case = Case.objects.filter(pk=above_id, org=org).first() - below_case = Case.objects.filter(pk=below_id, org=org).first() - if above_case and below_case: - return (above_case.kanban_order + below_case.kanban_order) / 2 - - if above_id: - above_case = Case.objects.filter(pk=above_id, org=org).first() - if above_case: - if case.stage: - next_case = ( - Case.objects.filter( - org=org, - stage=case.stage, - kanban_order__gt=above_case.kanban_order, - ) - .order_by("kanban_order") - .first() - ) - else: - next_case = ( - Case.objects.filter( - org=org, - status=case.status, - stage__isnull=True, - kanban_order__gt=above_case.kanban_order, - ) - .order_by("kanban_order") - .first() - ) - - if next_case: - return (above_case.kanban_order + next_case.kanban_order) / 2 - return above_case.kanban_order + Decimal("1000") - - if below_id: - below_case = Case.objects.filter(pk=below_id, org=org).first() - if below_case: - return below_case.kanban_order - Decimal("1000") - - # Default: append to end + A board runs in one of two modes. With a pipeline, a column is a stage; + without one, it is a status bucket among the rows that have no stage. + Narrowing to the destination here is what lets + ``common.kanban.place_in_column`` resolve the neighbour hints inside + the column and ignore an id naming a card somewhere else. + """ if case.stage: - last_case = ( - Case.objects.filter(stage=case.stage, org=org) - .exclude(pk=case.pk) - .order_by("-kanban_order") - .first() - ) - else: - last_case = ( - Case.objects.filter(status=case.status, stage__isnull=True, org=org) - .exclude(pk=case.pk) - .order_by("-kanban_order") - .first() - ) - - if last_case: - return last_case.kanban_order + Decimal("1000") - return Decimal("1000") + return Case.objects.filter(org=org, stage=case.stage) + return Case.objects.filter(org=org, status=case.status, stage__isnull=True) -# Pipeline CRUD Views (following Lead/Task pattern) class CasePipelineListCreateView(APIView): """List and create case pipelines.""" diff --git a/backend/cases/tests/test_cases_kanban.py b/backend/cases/tests/test_cases_kanban.py index 539f7420..70fb68b7 100644 --- a/backend/cases/tests/test_cases_kanban.py +++ b/backend/cases/tests/test_cases_kanban.py @@ -601,6 +601,34 @@ class TestCaseMove: ) assert response.status_code == status.HTTP_200_OK + def test_move_case_non_admin_as_creator_allowed( + self, user_client, regular_user, user_profile, org_a + ): + """Creator, not assigned to themselves. The untested half everywhere. + + The assignee case above was covered; this one was not, in any module. + It is the branch that shipped dead on the opportunities board, where a + Profile was compared to a User FK and so never matched. + """ + case = Case.objects.create( + name="Creator Move Case", + status="New", + priority="Normal", + org=org_a, + created_by=regular_user, + ) + assert user_profile not in case.assigned_to.all() + + response = user_client.patch( + f"/api/cases/{case.id}/move/", + {"status": "Assigned"}, + format="json", + ) + + assert response.status_code == status.HTTP_200_OK + case.refresh_from_db() + assert case.status == "Assigned" + def test_move_case_between_with_above_and_below( self, admin_client, admin_user, org_a ): diff --git a/backend/common/kanban.py b/backend/common/kanban.py new file mode 100644 index 00000000..3c8ada83 --- /dev/null +++ b/backend/common/kanban.py @@ -0,0 +1,110 @@ +"""Fractional ordering for kanban columns. + +Leads, cases, tasks and opportunities each carry a ``kanban_order`` and each +grew its own copy of the placement maths. The copies drifted: only one excluded +the card being moved, none of them looked at the card above a ``below_id`` +neighbour (so a drop between two adjacent cards landed exactly on one of them), +none checked that a neighbour belonged to the destination column, and none had a +way back once the gaps collapsed. This module is the single copy. + +The caller passes a queryset already narrowed to the destination column, which +is what makes the neighbour handling safe: neighbours are looked up *inside* +that queryset, so an id naming a card in another column, another org, or nothing +at all is simply not found and placement falls through to append. There is no +separate validation step to forget. +""" + +from decimal import Decimal + +#: Gap left between cards when appending or offsetting past the end. +STRIDE = Decimal("1000") + +#: Rebalance rather than subdivide once neighbours are closer than this. +#: ``kanban_order`` stores 6 decimal places, so two cards nearer than 1e-6 +#: cannot both be represented; this leaves an order of magnitude of headroom. +MIN_GAP = Decimal("0.00001") + + +def _order_of(column_qs, pk): + """The order of ``pk`` if it is in this column, else ``None``.""" + if not pk: + return None + row = column_qs.filter(pk=pk).only("kanban_order").first() + return row.kanban_order if row else None + + +def _neighbour(column_qs, order, *, below): + """The order of the card immediately below or above ``order``.""" + if below: + qs = column_qs.filter(kanban_order__gt=order).order_by("kanban_order") + else: + qs = column_qs.filter(kanban_order__lt=order).order_by("-kanban_order") + return qs.values_list("kanban_order", flat=True).first() + + +def rebalance_column(column_qs): + """Renumber a column to clean ``STRIDE`` multiples, preserving its order. + + Cards are taken in ``(kanban_order, -created_at)``, the same tie-break the + board GETs read with, so a column with duplicate orders renumbers to the + sequence the user was already looking at. Written with ``bulk_update`` so + the models' own ``save()`` bookkeeping (probability, stage timestamps) does + not fire on what is purely a renumbering. + """ + changed = [] + for position, row in enumerate( + column_qs.order_by("kanban_order", "-created_at"), 1 + ): + target = STRIDE * position + if row.kanban_order != target: + row.kanban_order = target + changed.append(row) + if changed: + column_qs.model.objects.bulk_update(changed, ["kanban_order"]) + + +def place_in_column( + column_qs, *, above_id=None, below_id=None, explicit=None, exclude_pk=None +): + """Return the ``kanban_order`` for a card landing in ``column_qs``. + + ``column_qs`` must already be filtered to the destination column (org, plus + stage or status). ``above_id``/``below_id`` are the ids of the cards the + client dropped between; either, both, or neither may be given, and any that + do not name a card in this column are ignored. + + May renumber the column as a side effect: when the two neighbours have + collapsed to within ``MIN_GAP`` there is no representable value between + them, so the column is rebalanced and the placement recomputed. + """ + if explicit is not None: + return explicit + if exclude_pk is not None: + column_qs = column_qs.exclude(pk=exclude_pk) + + above = _order_of(column_qs, above_id) + below = _order_of(column_qs, below_id) + + # Fill in whichever side the client left out, so a one-sided hint still + # places *between* two real cards instead of guessing a stride past one. + if above is not None and below is None: + below = _neighbour(column_qs, above, below=True) + elif below is not None and above is None: + above = _neighbour(column_qs, below, below=False) + + if above is not None and below is not None: + if below - above < MIN_GAP: + rebalance_column(column_qs) + return place_in_column(column_qs, above_id=above_id, below_id=below_id) + return (above + below) / 2 + if above is not None: + return above + STRIDE + if below is not None: + return below - STRIDE + + last = ( + column_qs.order_by("-kanban_order") + .values_list("kanban_order", flat=True) + .first() + ) + return last + STRIDE if last is not None else STRIDE diff --git a/backend/common/tests/test_kanban_ordering.py b/backend/common/tests/test_kanban_ordering.py new file mode 100644 index 00000000..61cf8b09 --- /dev/null +++ b/backend/common/tests/test_kanban_ordering.py @@ -0,0 +1,149 @@ +"""Contract for the shared kanban ordering helper. + +Every board endpoint (leads, cases, tasks, opportunities) computes a card's +position with the same four rules, and each of the four copies got a different +subset of them wrong. These tests pin the rules once, against the helper the +four views now share. + +Opportunity is the model under test only because it is the module the board UI +lands in first. The helper takes a queryset, so nothing here is deal-specific. +""" + +from decimal import Decimal + +import pytest + +from common.kanban import MIN_GAP, STRIDE, place_in_column, rebalance_column +from opportunity.models import Opportunity + + +def _deal(org, name, stage="PROSPECTING", order=None): + return Opportunity.objects.create( + org=org, name=name, stage=stage, kanban_order=order + ) + + +def _column(org, stage="PROSPECTING"): + return Opportunity.objects.filter(org=org, stage=stage) + + +def _orders(org, stage="PROSPECTING"): + return [d.kanban_order for d in _column(org, stage).order_by("kanban_order")] + + +@pytest.mark.django_db +class TestAppend: + def test_first_card_in_an_empty_column_gets_the_stride(self, org_a): + assert place_in_column(_column(org_a)) == STRIDE + + def test_no_hints_appends_after_the_last_card(self, org_a): + _deal(org_a, "a", order=Decimal("1000")) + _deal(org_a, "b", order=Decimal("2000")) + assert place_in_column(_column(org_a)) == Decimal("3000") + + def test_the_moving_card_is_not_its_own_neighbour(self, org_a): + _deal(org_a, "a", order=Decimal("1000")) + moving = _deal(org_a, "moving", order=Decimal("9999")) + # Without the exclusion the card appends after itself and drifts up the + # column by a stride on every no-op move. + assert place_in_column(_column(org_a), exclude_pk=moving.pk) == Decimal("2000") + + +@pytest.mark.django_db +class TestBetweenTwoCards: + def test_both_hints_average_the_neighbours(self, org_a): + a = _deal(org_a, "a", order=Decimal("1000")) + b = _deal(org_a, "b", order=Decimal("2000")) + got = place_in_column(_column(org_a), above_id=a.pk, below_id=b.pk) + assert got == Decimal("1500") + + def test_above_only_averages_against_the_next_card_down(self, org_a): + a = _deal(org_a, "a", order=Decimal("1000")) + _deal(org_a, "b", order=Decimal("2000")) + assert place_in_column(_column(org_a), above_id=a.pk) == Decimal("1500") + + def test_above_the_last_card_appends(self, org_a): + a = _deal(org_a, "a", order=Decimal("1000")) + assert place_in_column(_column(org_a), above_id=a.pk) == Decimal("2000") + + +@pytest.mark.django_db +class TestBelowOnly: + """The branch every copy got wrong: a flat ``below - STRIDE``.""" + + def test_below_only_averages_against_the_card_above_it(self, org_a): + _deal(org_a, "a", order=Decimal("1000")) + _deal(org_a, "b", order=Decimal("2000")) + c = _deal(org_a, "c", order=Decimal("3000")) + # The old code returned 3000 - 1000 = 2000, colliding exactly with b. + got = place_in_column(_column(org_a), below_id=c.pk) + assert got == Decimal("2500") + assert got not in _orders(org_a) + + def test_below_the_first_card_offsets_by_a_stride(self, org_a): + a = _deal(org_a, "a", order=Decimal("1000")) + assert place_in_column(_column(org_a), below_id=a.pk) == Decimal("0") + + +@pytest.mark.django_db +class TestNeighboursOutsideTheColumn: + def test_a_neighbour_in_another_column_is_ignored(self, org_a): + _deal(org_a, "here", order=Decimal("1000")) + elsewhere = _deal( + org_a, "elsewhere", stage="NEGOTIATION", order=Decimal("500000") + ) + # Resolving neighbours from the destination queryset means a foreign id + # simply is not found, so we append instead of returning 501000. + got = place_in_column(_column(org_a), above_id=elsewhere.pk) + assert got == Decimal("2000") + + def test_a_neighbour_in_another_org_is_ignored(self, org_a, org_b): + _deal(org_a, "here", order=Decimal("1000")) + theirs = _deal(org_b, "theirs", order=Decimal("777")) + assert place_in_column(_column(org_a), above_id=theirs.pk) == Decimal("2000") + + def test_an_unknown_id_is_ignored(self, org_a): + _deal(org_a, "here", order=Decimal("1000")) + missing = "0" * 8 + "-0000-0000-0000-" + "0" * 12 + assert place_in_column(_column(org_a), above_id=missing) == Decimal("2000") + + +@pytest.mark.django_db +class TestExplicitOrder: + def test_an_explicit_order_wins_over_the_hints(self, org_a): + a = _deal(org_a, "a", order=Decimal("1000")) + b = _deal(org_a, "b", order=Decimal("2000")) + got = place_in_column( + _column(org_a), above_id=a.pk, below_id=b.pk, explicit=Decimal("42") + ) + assert got == Decimal("42") + + +@pytest.mark.django_db +class TestRebalance: + def test_a_collapsed_gap_renumbers_the_column(self, org_a): + a = _deal(org_a, "a", order=Decimal("1000")) + b = _deal(org_a, "b", order=Decimal("1000.000001")) + _deal(org_a, "c", order=Decimal("2000")) + + got = place_in_column(_column(org_a), above_id=a.pk, below_id=b.pk) + + # The column was renumbered to clean strides, so there is room again. + assert _orders(org_a) == [STRIDE, STRIDE * 2, STRIDE * 3] + assert got == Decimal("1500") + + def test_rebalance_preserves_the_visible_order(self, org_a): + for i, order in enumerate([Decimal("5"), Decimal("7"), Decimal("9")]): + _deal(org_a, f"deal-{i}", order=order) + + rebalance_column(_column(org_a)) + + names = [d.name for d in _column(org_a).order_by("kanban_order")] + assert names == ["deal-0", "deal-1", "deal-2"] + assert _orders(org_a) == [STRIDE, STRIDE * 2, STRIDE * 3] + + def test_min_gap_leaves_headroom_over_the_column_resolution(self): + # kanban_order is DecimalField(decimal_places=6), so two orders closer + # than 1e-6 cannot both be stored. Rebalancing has to trigger before + # that, not at it. + assert MIN_GAP > Decimal("0.000002") diff --git a/backend/leads/tests/test_leads_kanban.py b/backend/leads/tests/test_leads_kanban.py index 8f5b5f8e..793d175a 100644 --- a/backend/leads/tests/test_leads_kanban.py +++ b/backend/leads/tests/test_leads_kanban.py @@ -629,6 +629,38 @@ class TestLeadMoveView: ) assert response.status_code == 403 + def test_move_lead_non_admin_as_creator_allowed( + self, user_client, regular_user, org_a, user_profile + ): + """The creator half of the check, which nothing exercised. + + Every module tested the refusal, and cases and tasks tested the + assignee who is allowed, but no move test anywhere covered a creator + who is not also an assignee. That is exactly the branch that was dead + on the opportunities board (it compared a Profile to a User FK, so it + was always False) and shipped that way. This pins the answer here. + """ + _set_rls(org_a) + lead = Lead.objects.create( + first_name="Mine", + last_name="Lead", + email="minelead@example.com", + status="assigned", + created_by=regular_user, + org=org_a, + ) + assert user_profile not in lead.assigned_to.all() + + response = user_client.patch( + f"/api/leads/{lead.id}/move/", + {"status": "closed"}, + format="json", + ) + + assert response.status_code == 200 + lead.refresh_from_db() + assert lead.status == "closed" + def test_move_lead_with_explicit_order(self, admin_client, admin_user, org_a): """Move lead with explicit kanban_order.""" _set_rls(org_a) diff --git a/backend/leads/views/kanban_views.py b/backend/leads/views/kanban_views.py index 7ef80d18..d8ba3662 100644 --- a/backend/leads/views/kanban_views.py +++ b/backend/leads/views/kanban_views.py @@ -3,8 +3,6 @@ Kanban views for lead management. Supports both status-based (default) and custom pipeline-based kanban boards. """ -from decimal import Decimal - from django.db import transaction from django.db.models import Q from django.shortcuts import get_object_or_404 @@ -14,6 +12,7 @@ from rest_framework.permissions import IsAuthenticated from rest_framework.response import Response from rest_framework.views import APIView +from common.kanban import place_in_column from common.permissions import HasOrgContext, is_org_admin from common.utils import LEAD_STATUS from common.validators import date_param, uuid_param @@ -223,7 +222,9 @@ class LeadMoveView(APIView): def patch(self, request, pk): """Move lead to different column and/or position.""" org = request.profile.org - lead = get_object_or_404(Lead, pk=pk, org=org) + # Locked for the transaction: the move saves the whole row, so an + # edit committing between this read and that save would be lost. + lead = get_object_or_404(Lead.objects.select_for_update(), pk=pk, org=org) # Permission check if not is_org_admin(request.profile) and not request.user.is_superuser: @@ -276,9 +277,15 @@ class LeadMoveView(APIView): if "status" in data: lead.status = data["status"] - # Calculate new order - new_order = self._calculate_order(data, lead, org) - lead.kanban_order = new_order + # `lead.stage`/`lead.status` are already the destination by this point, + # so the column queryset below describes where the card is landing. + lead.kanban_order = place_in_column( + self._column_qs(lead, org), + above_id=data.get("above_lead_id"), + below_id=data.get("below_lead_id"), + explicit=data.get("kanban_order"), + exclude_pk=lead.pk, + ) lead.save() @@ -290,77 +297,18 @@ class LeadMoveView(APIView): } ) - def _calculate_order(self, data, lead, org): - """Calculate the new kanban_order based on position hints.""" - if "kanban_order" in data: - return data["kanban_order"] + def _column_qs(self, lead, org): + """The destination column, as a queryset. - above_id = data.get("above_lead_id") - below_id = data.get("below_lead_id") - - if above_id and below_id: - # Insert between two leads - above_lead = Lead.objects.filter(pk=above_id, org=org).first() - below_lead = Lead.objects.filter(pk=below_id, org=org).first() - if above_lead and below_lead: - return (above_lead.kanban_order + below_lead.kanban_order) / 2 - - if above_id: - # Insert after this lead - above_lead = Lead.objects.filter(pk=above_id, org=org).first() - if above_lead: - # Find the next lead after above_lead - if lead.stage: - next_lead = ( - Lead.objects.filter( - org=org, - stage=lead.stage, - kanban_order__gt=above_lead.kanban_order, - ) - .order_by("kanban_order") - .first() - ) - else: - next_lead = ( - Lead.objects.filter( - org=org, - status=lead.status, - stage__isnull=True, - kanban_order__gt=above_lead.kanban_order, - ) - .order_by("kanban_order") - .first() - ) - - if next_lead: - return (above_lead.kanban_order + next_lead.kanban_order) / 2 - return above_lead.kanban_order + Decimal("1000") - - if below_id: - # Insert before this lead - below_lead = Lead.objects.filter(pk=below_id, org=org).first() - if below_lead: - return below_lead.kanban_order - Decimal("1000") - - # Default: append to end + A board runs in one of two modes. With a pipeline, a column is a stage; + without one, it is a status bucket among the rows that have no stage. + Narrowing to the destination here is what lets + ``common.kanban.place_in_column`` resolve the neighbour hints inside + the column and ignore an id naming a card somewhere else. + """ if lead.stage: - last_lead = ( - Lead.objects.filter(stage=lead.stage, org=org) - .exclude(pk=lead.pk) - .order_by("-kanban_order") - .first() - ) - else: - last_lead = ( - Lead.objects.filter(status=lead.status, stage__isnull=True, org=org) - .exclude(pk=lead.pk) - .order_by("-kanban_order") - .first() - ) - - if last_lead: - return last_lead.kanban_order + Decimal("1000") - return Decimal("1000") + return Lead.objects.filter(org=org, stage=lead.stage) + return Lead.objects.filter(org=org, status=lead.status, stage__isnull=True) class LeadPipelineListCreateView(APIView): diff --git a/backend/manage.py b/backend/manage.py index 7e4d6bc0..02bd3412 100755 --- a/backend/manage.py +++ b/backend/manage.py @@ -21,4 +21,7 @@ if __name__ == "__main__": "forget to activate a virtual environment?" ) from exc raise + # Assigned dev port (see ~/git-prjs/PORTS.md); an explicit `runserver ` still overrides. + from django.core.management.commands.runserver import Command as runserver + runserver.default_port = "8004" execute_from_command_line(sys.argv) diff --git a/backend/opportunity/serializer.py b/backend/opportunity/serializer.py index 7e5fb212..23069033 100644 --- a/backend/opportunity/serializer.py +++ b/backend/opportunity/serializer.py @@ -390,12 +390,17 @@ class OpportunityKanbanCardSerializer(serializers.ModelSerializer): class OpportunityMoveSerializer(serializers.Serializer): """Payload for PATCH /opportunities//move/. - `stage` is required (status-based kanban only. Opportunity has no - Pipeline/Stage model yet). `above_id`/`below_id` are neighbor hints used to - compute the fractional kanban_order; explicit `kanban_order` wins if sent. + `column_id` is the id the board GET handed the client for the destination + column, which for opportunities is the `stage` value (there is no + Pipeline/Stage model here, so columns are the flat stage choices). Boards + for leads, cases and tasks take the same field name and put a stage UUID or + a status value in it, so one client component drives all four. + + `above_id`/`below_id` name the cards the drop landed between; either, both, + or neither may be sent. An explicit `kanban_order` wins over both. """ - stage = serializers.ChoiceField( + column_id = serializers.ChoiceField( choices=Opportunity._meta.get_field("stage").choices ) kanban_order = serializers.DecimalField( diff --git a/backend/opportunity/tests/test_opportunity_move.py b/backend/opportunity/tests/test_opportunity_move.py new file mode 100644 index 00000000..af3c7725 --- /dev/null +++ b/backend/opportunity/tests/test_opportunity_move.py @@ -0,0 +1,177 @@ +"""PATCH /api/opportunities//move/. + +This endpoint had no tests at all while leads, cases and tasks each had a move +test class, which is how the creator branch of its permission check stayed dead +long enough to ship. The RBAC tests below pin both answers: a non-admin creator +gets through, an unrelated non-admin does not. +""" + +from datetime import timedelta +from decimal import Decimal + +import pytest +from django.utils import timezone + +from opportunity.models import Opportunity + + +def _deal(org, name="deal", **kwargs): + kwargs.setdefault("stage", "PROSPECTING") + kwargs.setdefault("kanban_order", Decimal("1000")) + return Opportunity.objects.create(org=org, name=name, **kwargs) + + +def _move(client, deal, **payload): + payload.setdefault("column_id", "NEGOTIATION") + return client.patch( + f"/api/opportunities/{deal.id}/move/", payload, content_type="application/json" + ) + + +@pytest.mark.django_db +class TestMoveRBAC: + def test_non_admin_creator_may_move_their_own_deal( + self, user_client, regular_user, user_profile, org_a + ): + """The branch that was dead: creator, not assigned to themselves.""" + deal = _deal(org_a, created_by=regular_user) + assert deal.created_by == regular_user + assert user_profile not in deal.assigned_to.all() + + res = _move(user_client, deal) + + assert res.status_code == 200 + deal.refresh_from_db() + assert deal.stage == "NEGOTIATION" + + def test_non_admin_assignee_may_move( + self, user_client, admin_user, user_profile, org_a + ): + deal = _deal(org_a, created_by=admin_user) + deal.assigned_to.add(user_profile) + + assert _move(user_client, deal).status_code == 200 + + def test_unrelated_non_admin_is_refused(self, user_client, admin_user, org_a): + deal = _deal(org_a, created_by=admin_user) + + res = _move(user_client, deal) + + assert res.status_code == 403 + deal.refresh_from_db() + assert deal.stage == "PROSPECTING" + + def test_admin_may_move_any_deal(self, admin_client, regular_user, org_a): + deal = _deal(org_a, created_by=regular_user) + assert _move(admin_client, deal).status_code == 200 + + def test_another_orgs_deal_is_not_found(self, org_b_client, org_a): + deal = _deal(org_a) + assert _move(org_b_client, deal).status_code == 404 + + +@pytest.mark.django_db +class TestMoveContract: + def test_column_id_is_required(self, admin_client, org_a): + deal = _deal(org_a) + res = admin_client.patch( + f"/api/opportunities/{deal.id}/move/", {}, content_type="application/json" + ) + assert res.status_code == 400 + assert "column_id" in res.json()["errors"] + + def test_an_unknown_column_is_rejected(self, admin_client, org_a): + deal = _deal(org_a) + assert _move(admin_client, deal, column_id="NOT_A_STAGE").status_code == 400 + + def test_a_drop_between_two_cards_lands_between_them(self, admin_client, org_a): + above = _deal(org_a, "above", stage="NEGOTIATION", kanban_order=Decimal("1000")) + below = _deal(org_a, "below", stage="NEGOTIATION", kanban_order=Decimal("2000")) + moving = _deal(org_a, "moving") + + res = _move( + admin_client, moving, above_id=str(above.id), below_id=str(below.id) + ) + + assert res.status_code == 200 + moving.refresh_from_db() + assert above.kanban_order < moving.kanban_order < below.kanban_order + + +@pytest.mark.django_db +class TestClosingByDragging: + def test_dragging_to_won_stamps_the_close(self, admin_client, admin_profile, org_a): + deal = _deal(org_a, amount=Decimal("5000")) + + res = _move(admin_client, deal, column_id="CLOSED_WON") + + assert res.status_code == 200 + deal.refresh_from_db() + assert deal.stage == "CLOSED_WON" + assert deal.closed_on == timezone.localdate() + assert deal.closed_by == admin_profile + + def test_an_existing_expected_close_date_is_not_overwritten( + self, admin_client, org_a + ): + """`closed_on` is the owner's expected close date until the deal closes. + + Stamping today over it would silently discard a forecast the user set, + and the drag carries no date to replace it with. + """ + expected = timezone.localdate() - timedelta(days=30) + deal = _deal(org_a, amount=Decimal("5000"), closed_on=expected) + + assert _move(admin_client, deal, column_id="CLOSED_WON").status_code == 200 + + deal.refresh_from_db() + assert deal.closed_on == expected + + def test_dragging_to_won_without_an_amount_is_refused(self, admin_client, org_a): + deal = _deal(org_a, amount=None) + + res = _move(admin_client, deal, column_id="CLOSED_WON") + + assert res.status_code == 400 + assert "amount" in res.json()["errors"] + deal.refresh_from_db() + assert deal.stage == "PROSPECTING" + assert deal.closed_on is None + + def test_dragging_to_lost_needs_no_amount(self, admin_client, org_a): + deal = _deal(org_a, amount=None) + + assert _move(admin_client, deal, column_id="CLOSED_LOST").status_code == 200 + deal.refresh_from_db() + assert deal.closed_on == timezone.localdate() + + def test_reopening_clears_who_closed_it_but_keeps_the_date( + self, admin_client, admin_profile, org_a + ): + """An open deal claiming a closer is a lie; a close date is a forecast.""" + closed_on = timezone.localdate() + deal = _deal( + org_a, + stage="CLOSED_WON", + amount=Decimal("5000"), + closed_on=closed_on, + closed_by=admin_profile, + ) + + assert _move(admin_client, deal, column_id="NEGOTIATION").status_code == 200 + + deal.refresh_from_db() + assert deal.closed_by is None + assert deal.closed_on == closed_on + + +@pytest.mark.django_db +class TestProbability: + def test_a_stage_change_refreshes_the_probability(self, admin_client, org_a): + """save() only fills a 0/None probability, so the move has to set it.""" + deal = _deal(org_a, stage="NEGOTIATION", probability=75) + + assert _move(admin_client, deal, column_id="CLOSED_LOST").status_code == 200 + + deal.refresh_from_db() + assert deal.probability == 0 diff --git a/backend/opportunity/views/kanban_views.py b/backend/opportunity/views/kanban_views.py index afcddf5f..b2678493 100644 --- a/backend/opportunity/views/kanban_views.py +++ b/backend/opportunity/views/kanban_views.py @@ -5,24 +5,30 @@ flat `stage` CharField). The layout mirrors tasks/views/kanban_views.py so the frontend KanbanBoard component can consume both with the same shape. """ -from decimal import Decimal - from django.db import transaction from django.db.models import Q from django.shortcuts import get_object_or_404 +from django.utils import timezone from drf_spectacular.utils import OpenApiParameter, extend_schema from rest_framework import status from rest_framework.permissions import IsAuthenticated from rest_framework.response import Response from rest_framework.views import APIView +from common.kanban import place_in_column from common.permissions import HasOrgContext, is_org_admin from common.validators import date_param, uuid_list_param, uuid_param +from opportunity.access import assert_deal_access from opportunity.models import Opportunity, StageAgingConfig from opportunity.serializer import ( OpportunityKanbanCardSerializer, OpportunityMoveSerializer, ) +from opportunity.workflow import ( + AMOUNT_REQUIRED_STAGES, + CLOSED_STAGES, + STAGE_PROBABILITIES, +) # Column display config. Keys must match the stage choices in # common.utils.STAGES. Extra/unknown stages get the fallback. @@ -163,9 +169,10 @@ class OpportunityKanbanView(APIView): class OpportunityMoveView(APIView): """PATCH /api/opportunities//move/, change stage and/or reorder. - Mirrors TaskMoveView's fractional-order algorithm: if both neighbors are - given we average them; with only one we offset by ±1000; falling through - means append to the column. + Placement is delegated to ``common.kanban.place_in_column``, which the + leads, cases and tasks boards share. Closing a deal by dragging it into a + won/lost column is a real close: it stamps the same fields the edit form + stamps, and refuses on the same grounds. """ permission_classes = (IsAuthenticated, HasOrgContext) @@ -178,17 +185,12 @@ class OpportunityMoveView(APIView): @transaction.atomic def patch(self, request, pk): org = request.profile.org - opportunity = get_object_or_404(Opportunity, pk=pk, org=org) - - # Match Opportunity update/delete RBAC: admin OR creator OR assignee. - if not is_org_admin(request.profile) and not request.user.is_superuser: - is_owner = request.profile == opportunity.created_by - is_assignee = request.profile in opportunity.assigned_to.all() - if not (is_owner or is_assignee): - return Response( - {"error": "Permission denied"}, - status=status.HTTP_403_FORBIDDEN, - ) + # Locked for the transaction: the move rewrites the whole row, so an + # edit committing between the read and the save would be overwritten. + opportunity = get_object_or_404( + Opportunity.objects.select_for_update(), pk=pk, org=org + ) + assert_deal_access(request.profile, request.user, opportunity) serializer = OpportunityMoveSerializer(data=request.data) if not serializer.is_valid(): @@ -198,76 +200,59 @@ class OpportunityMoveView(APIView): ) data = serializer.validated_data - new_stage = data["stage"] - # If the user is moving INTO a closed stage, stamp closed_by, mirrors - # the OpportunityListView.post / OpportunityDetailView.put behavior so - # kanban-driven close events look identical to form-driven ones. - if ( - new_stage in ("CLOSED_WON", "CLOSED_LOST") - and opportunity.stage != new_stage - ): + new_stage = data["column_id"] + entering_closed = ( + new_stage in CLOSED_STAGES and opportunity.stage not in CLOSED_STAGES + ) + + # A won deal has to record what it was worth, the same rule + # OpportunityCreateSerializer.validate() applies to the edit form. The + # board cannot ask for a figure mid-drag, so it refuses and the client + # opens the deal instead of silently booking a nil win. + if new_stage in AMOUNT_REQUIRED_STAGES and not opportunity.amount: + return Response( + { + "error": True, + "errors": {"amount": "A won deal has to record what it was worth."}, + }, + status=status.HTTP_400_BAD_REQUEST, + ) + + if entering_closed: opportunity.closed_by = request.profile + # `closed_on` is the deal's *expected* close date (see the field's + # verbose name), which the close then reads as the actual one. So + # it is filled only when the deal never carried an expectation: + # stamping today unconditionally would overwrite a date the owner + # chose, and the board cannot ask for one mid-drag. + if not opportunity.closed_on: + opportunity.closed_on = timezone.localdate() + elif opportunity.stage in CLOSED_STAGES and new_stage not in CLOSED_STAGES: + # Reopened. `closed_by` is now a lie and goes; `closed_on` stays, + # because on an open deal it reads as the expected close date + # again, and clearing it would discard a forecast the close did + # not create. + opportunity.closed_by = None + + if opportunity.stage != new_stage: + # save() only fills probability when it is 0/None, so a stage change + # would otherwise keep forecasting at the old stage's odds. + opportunity.probability = STAGE_PROBABILITIES.get(new_stage, 0) opportunity.stage = new_stage - opportunity.kanban_order = self._calculate_order(data, opportunity, org) - - # Opportunity.save() auto-updates probability + stage_changed_at, no - # need to pass update_fields here, the model handles its own bookkeeping. + opportunity.kanban_order = place_in_column( + Opportunity.objects.filter(org=org, stage=new_stage), + above_id=data.get("above_id"), + below_id=data.get("below_id"), + explicit=data.get("kanban_order"), + exclude_pk=opportunity.pk, + ) opportunity.save() - aging_configs = {c.stage: c for c in StageAgingConfig.objects.filter(org=org)} return Response( { "error": False, "message": "Opportunity moved successfully", - "opportunity": OpportunityKanbanCardSerializer( - opportunity, context={"aging_configs": aging_configs} - ).data, + "opportunity": OpportunityKanbanCardSerializer(opportunity).data, } ) - - def _calculate_order(self, data, opportunity, org): - if "kanban_order" in data: - return data["kanban_order"] - - above_id = data.get("above_id") - below_id = data.get("below_id") - - if above_id and below_id: - above = Opportunity.objects.filter(pk=above_id, org=org).first() - below = Opportunity.objects.filter(pk=below_id, org=org).first() - if above and below: - return (above.kanban_order + below.kanban_order) / 2 - - if above_id: - above = Opportunity.objects.filter(pk=above_id, org=org).first() - if above: - next_opp = ( - Opportunity.objects.filter( - org=org, - stage=opportunity.stage, - kanban_order__gt=above.kanban_order, - ) - .exclude(pk=opportunity.pk) - .order_by("kanban_order") - .first() - ) - if next_opp: - return (above.kanban_order + next_opp.kanban_order) / 2 - return above.kanban_order + Decimal("1000") - - if below_id: - below = Opportunity.objects.filter(pk=below_id, org=org).first() - if below: - return below.kanban_order - Decimal("1000") - - # Append to end of the (new) column. - last = ( - Opportunity.objects.filter(stage=opportunity.stage, org=org) - .exclude(pk=opportunity.pk) - .order_by("-kanban_order") - .first() - ) - if last: - return last.kanban_order + Decimal("1000") - return Decimal("1000") diff --git a/backend/tasks/tests/test_tasks_kanban.py b/backend/tasks/tests/test_tasks_kanban.py index b16ef1c2..a82e27e4 100644 --- a/backend/tasks/tests/test_tasks_kanban.py +++ b/backend/tasks/tests/test_tasks_kanban.py @@ -665,6 +665,35 @@ class TestTaskMove: ) assert response.status_code == 200 + def test_move_task_non_admin_as_creator_allowed( + self, user_client, regular_user, user_profile, org_a + ): + """Creator, not assigned to themselves. The untested half everywhere. + + The assignee case above was covered; this one was not, in any module. + It is the branch that shipped dead on the opportunities board, where a + Profile was compared to a User FK and so never matched. + """ + _set_rls(org_a) + task = Task.objects.create( + title="Creator Move Task", + status="New", + priority="Low", + org=org_a, + created_by=regular_user, + ) + assert user_profile not in task.assigned_to.all() + + response = user_client.patch( + f"/api/tasks/{task.id}/move/", + {"status": "In Progress"}, + format="json", + ) + + assert response.status_code == 200 + task.refresh_from_db() + assert task.status == "In Progress" + def test_move_task_between_with_above_and_below( self, admin_client, admin_user, org_a ): diff --git a/backend/tasks/views/kanban_views.py b/backend/tasks/views/kanban_views.py index 139353aa..66122ebc 100644 --- a/backend/tasks/views/kanban_views.py +++ b/backend/tasks/views/kanban_views.py @@ -3,8 +3,6 @@ Kanban views for task management. Supports both status-based (default) and custom pipeline-based kanban boards. """ -from decimal import Decimal - from django.db import transaction from django.db.models import Q from django.shortcuts import get_object_or_404 @@ -14,6 +12,7 @@ from rest_framework.permissions import IsAuthenticated from rest_framework.response import Response from rest_framework.views import APIView +from common.kanban import place_in_column from common.permissions import HasOrgContext, is_org_admin from common.validators import date_param, uuid_param from tasks.models import Task, TaskPipeline, TaskStage @@ -255,7 +254,9 @@ class TaskMoveView(APIView): def patch(self, request, pk): """Move task to different column and/or position.""" org = request.profile.org - task = get_object_or_404(Task, pk=pk, org=org) + # Locked for the transaction: the move saves the whole row, so an + # edit committing between this read and that save would be lost. + task = get_object_or_404(Task.objects.select_for_update(), pk=pk, org=org) # Permission check if not is_org_admin(request.profile) and not request.user.is_superuser: @@ -305,8 +306,15 @@ class TaskMoveView(APIView): task.status = data["status"] # Calculate new order - new_order = self._calculate_order(data, task, org) - task.kanban_order = new_order + # `task.stage`/`task.status` are already the destination by this + # point, so the column queryset describes where the card is landing. + task.kanban_order = place_in_column( + self._column_qs(task, org), + above_id=data.get("above_task_id"), + below_id=data.get("below_task_id"), + explicit=data.get("kanban_order"), + exclude_pk=task.pk, + ) task.save() @@ -318,77 +326,18 @@ class TaskMoveView(APIView): } ) - def _calculate_order(self, data, task, org): - """Calculate the new kanban_order based on position hints.""" - if "kanban_order" in data: - return data["kanban_order"] + def _column_qs(self, task, org): + """The destination column, as a queryset. - above_id = data.get("above_task_id") - below_id = data.get("below_task_id") - - if above_id and below_id: - # Insert between two tasks - above_task = Task.objects.filter(pk=above_id, org=org).first() - below_task = Task.objects.filter(pk=below_id, org=org).first() - if above_task and below_task: - return (above_task.kanban_order + below_task.kanban_order) / 2 - - if above_id: - # Insert after this task - above_task = Task.objects.filter(pk=above_id, org=org).first() - if above_task: - # Find the next task after above_task - if task.stage: - next_task = ( - Task.objects.filter( - org=org, - stage=task.stage, - kanban_order__gt=above_task.kanban_order, - ) - .order_by("kanban_order") - .first() - ) - else: - next_task = ( - Task.objects.filter( - org=org, - status=task.status, - stage__isnull=True, - kanban_order__gt=above_task.kanban_order, - ) - .order_by("kanban_order") - .first() - ) - - if next_task: - return (above_task.kanban_order + next_task.kanban_order) / 2 - return above_task.kanban_order + Decimal("1000") - - if below_id: - # Insert before this task - below_task = Task.objects.filter(pk=below_id, org=org).first() - if below_task: - return below_task.kanban_order - Decimal("1000") - - # Default: append to end + A board runs in one of two modes. With a pipeline, a column is a stage; + without one, it is a status bucket among the rows that have no stage. + Narrowing to the destination here is what lets + ``common.kanban.place_in_column`` resolve the neighbour hints inside + the column and ignore an id naming a card somewhere else. + """ if task.stage: - last_task = ( - Task.objects.filter(stage=task.stage, org=org) - .exclude(pk=task.pk) - .order_by("-kanban_order") - .first() - ) - else: - last_task = ( - Task.objects.filter(status=task.status, stage__isnull=True, org=org) - .exclude(pk=task.pk) - .order_by("-kanban_order") - .first() - ) - - if last_task: - return last_task.kanban_order + Decimal("1000") - return Decimal("1000") + return Task.objects.filter(org=org, stage=task.stage) + return Task.objects.filter(org=org, status=task.status, stage__isnull=True) class TaskPipelineListCreateView(APIView): diff --git a/frontend/src/lib/server/v2/deals.js b/frontend/src/lib/server/v2/deals.js index e027b08a..8b02d6dc 100644 --- a/frontend/src/lib/server/v2/deals.js +++ b/frontend/src/lib/server/v2/deals.js @@ -499,6 +499,34 @@ export async function updateDeal({ cookies }, id, values) { ); } +/** + * Move a deal to another board column, and optionally to a position in it. + * + * `columnId` is the `id` the board GET gave for the destination lane, handed + * straight back. `aboveId`/`belowId` name the cards the drop landed between; + * the server resolves them inside the destination column, so a stale id from a + * board another user has since rearranged is ignored rather than honoured. + * Sending neither appends to the lane. + * + * @param {{ cookies: import('@sveltejs/kit').Cookies }} event + * @param {string} id + * @param {{ columnId: string, aboveId?: string, belowId?: string }} position + */ +export async function moveDeal({ cookies }, id, { columnId, aboveId, belowId }) { + return await apiRequest( + `/opportunities/${id}/move/`, + { + method: 'PATCH', + body: { + column_id: columnId, + ...(aboveId ? { above_id: aboveId } : {}), + ...(belowId ? { below_id: belowId } : {}) + } + }, + { cookies } + ); +} + /** * Create a deal. * diff --git a/frontend/src/routes/(app)/pipeline/+page.server.js b/frontend/src/routes/(app)/pipeline/+page.server.js index e8d92c0d..89580efa 100644 --- a/frontend/src/routes/(app)/pipeline/+page.server.js +++ b/frontend/src/routes/(app)/pipeline/+page.server.js @@ -1,10 +1,13 @@ +import { fail } from '@sveltejs/kit'; import { listBoard, listDeals, + moveDeal, FILTER_FIELDS, BOARD_FIELDS, BOARD_PRESETS } from '$lib/server/v2/deals.js'; +import { readableError } from '$lib/server/v2/form-errors.js'; import { readFilters, buildFilterQuery } from '$lib/server/v2/filter-params.js'; import { getOrgPeopleAndTeams, resolveMe } from '$lib/server/v2/org-people.js'; import { getTags } from '$lib/server/v2/tags.js'; @@ -106,3 +109,30 @@ export async function load(event) { ...shared }; } + +export const actions = { + /** + * Move a card to another lane, or to a position inside one. + * + * The board reorders optimistically and calls this without waiting, so the + * only job here is to persist and to report a refusal in words the card can + * show while it snaps back. A 403 stays a 403: the move endpoint refuses a + * deal the caller neither created nor is assigned to, and flattening that to + * 400 would read as bad input rather than as a permission answer. + */ + move: async ({ request, cookies }) => { + const form = await request.formData(); + const id = String(form.get('id') || ''); + const columnId = String(form.get('column_id') || ''); + const aboveId = String(form.get('above_id') || ''); + const belowId = String(form.get('below_id') || ''); + if (!id || !columnId) return fail(400, { error: 'Missing card or column.' }); + try { + await moveDeal({ cookies }, id, { columnId, aboveId, belowId }); + return { success: true }; + } catch (err) { + const status = /** @type {any} */ (err)?.status === 403 ? 403 : 400; + return fail(status, { error: readableError(err, 'Could not move the deal.') }); + } + } +}; diff --git a/frontend/src/routes/(app)/pipeline/+page.svelte b/frontend/src/routes/(app)/pipeline/+page.svelte index 2dfb9737..db80c0c4 100644 --- a/frontend/src/routes/(app)/pipeline/+page.svelte +++ b/frontend/src/routes/(app)/pipeline/+page.svelte @@ -12,11 +12,17 @@ import { money, count, shortDate } from '$lib/v2/format.js'; import { STAGE_LABEL, AGING_TONE, AGING_LABEL } from '$lib/v2/enums.js'; import { activeChips, activePresetKey, withoutParam } from '$lib/v2/filters.js'; - import { Columns3, List, Plus } from '@lucide/svelte'; + import { Columns3, List, Plus, TriangleAlert } from '@lucide/svelte'; + import { flip } from 'svelte/animate'; + import { dndzone } from 'svelte-dnd-action'; + import { invalidateAll } from '$app/navigation'; + import { deserialize } from '$app/forms'; /** @type {{ data: any }} */ let { data } = $props(); + const FLIP_MS = 160; + let deals = $derived(data.deals); let totals = $derived(data.totals); let view = $derived(data.view); @@ -28,6 +34,79 @@ render, each is just short. */ let lanes = $derived(data.lanes); + /* `dndzone` reorders the array it is handed, so the board renders from a + local copy. Rebuilt whenever the server sends new lanes, which is what + makes a rejected move snap back: the action calls `invalidateAll()` and + this effect overwrites the optimistic arrangement with the stored one. */ + let boardLanes = $state(/** @type {any[]} */ ([])); + $effect(() => { + boardLanes = lanes.map((/** @type {any} */ lane) => ({ ...lane, rows: [...lane.rows] })); + }); + + let moveError = $state(''); + + /* The header has to describe the cards under it after an optimistic move, + not the count the server sent before it. A capped lane keeps the server's + total, since its own rows are not the whole story either way. */ + function laneCount(/** @type {any} */ lane) { + return lane.truncated ? lane.count : lane.rows.length; + } + function laneSum(/** @type {any} */ lane) { + return lane.rows.reduce((/** @type {number} */ total, /** @type {any} */ r) => total + r.amount, 0); + } + + function onConsider(/** @type {any} */ lane, /** @type {any} */ e) { + lane.rows = e.detail.items; + } + + async function onFinalize(/** @type {any} */ lane, /** @type {any} */ e) { + lane.rows = e.detail.items; + const movedId = e.detail.info?.id; + const index = e.detail.items.findIndex((/** @type {any} */ r) => r.id === movedId); + // Finalize fires on both lanes of a cross-lane move. Only the lane now + // holding the card knows where it landed, so only that one persists. + if (index === -1) return; + await persistMove( + movedId, + lane.stage, + e.detail.items[index - 1]?.id, + e.detail.items[index + 1]?.id + ); + } + + /** + * Both neighbours are sent when they exist. The server resolves them inside + * the destination column and ignores any it cannot find there, so a board + * another user has rearranged since this one loaded degrades to an append + * rather than to a position computed from a card that has moved on. + */ + async function persistMove( + /** @type {string} */ id, + /** @type {string} */ columnId, + /** @type {string | undefined} */ aboveId, + /** @type {string | undefined} */ belowId + ) { + const body = new FormData(); + body.set('id', id); + body.set('column_id', columnId); + if (aboveId) body.set('above_id', aboveId); + if (belowId) body.set('below_id', belowId); + try { + const res = await fetch('?/move', { method: 'POST', body }); + const result = deserialize(await res.text()); + if (result.type === 'success') { + moveError = ''; + return; + } + moveError = + (result.type === 'failure' && /** @type {any} */ (result.data)?.error) || + 'Could not move the deal; reverted.'; + } catch { + moveError = 'Could not move the deal, reverted.'; + } + await invalidateAll(); + } + /** * Whether the current view is actually narrowed, as opposed to merely * carrying a query string. `page.url.search` alone is the wrong test: on @@ -99,10 +178,6 @@

{/if} - +{#if moveError} + +
+
+ + {moveError} +
+
+{/if} + {#if view === 'board'}
- {#each lanes as lane (lane.stage)} + {#each boardLanes as lane (lane.stage)}
{STAGE_LABEL[lane.stage]} - {count(lane.count)} · {money(lane.sum, data.org.currency)} + {count(laneCount(lane))} · {money(laneSum(lane), data.org.currency)}
-
- {#if lane.truncated} - -

- Showing the first {lane.rows.length}. Filter to see the - rest. -

- {/if} + {#if lane.truncated} + +

+ Showing the first {lane.rows.length}. Filter to see the + rest. +

+ {/if} +
onConsider(lane, e)} + onfinalize={(e) => onFinalize(lane, e)} + > {#each lane.rows as d (d.id)} - -
{d.name}
+ +
+ {d.name}
{d.account.name}
@@ -149,7 +250,7 @@ >{shortDate(d.closed_on)}
- +
{:else}

Nothing in this stage.

{/each} diff --git a/mobile/lib/config/api_config.dart b/mobile/lib/config/api_config.dart index 9489de4c..9f5a1d38 100644 --- a/mobile/lib/config/api_config.dart +++ b/mobile/lib/config/api_config.dart @@ -206,6 +206,17 @@ class ApiConfig { static String opportunityComment(String commentId) => '$apiBaseUrl/opportunities/comment/$commentId/'; + /// The deals board: stage columns with their cards, capped at 100 a column. + /// Status-based, so a column's `id` is the stage value itself. + static String get opportunitiesKanban => '$apiBaseUrl/opportunities/kanban/'; + + /// Move a deal to another column and, optionally, to a position in it. Takes + /// `column_id` plus `above_id`/`below_id`, the same contract the web board + /// uses. Distinct from `PATCH /opportunities//`, which edits the deal: + /// this one also stamps the close when the destination is a closed stage. + static String opportunityMove(String id) => + '$apiBaseUrl/opportunities/$id/move/'; + /// Sales goals. Reading is open to any member and narrowed server-side to /// their own goals and their teams'; creating, editing and deleting are /// admin-only and answer 403 to everyone else. diff --git a/mobile/lib/providers/deals_provider.dart b/mobile/lib/providers/deals_provider.dart index 2177bee1..0763245b 100644 --- a/mobile/lib/providers/deals_provider.dart +++ b/mobile/lib/providers/deals_provider.dart @@ -553,15 +553,32 @@ class DealsNotifier extends AsyncNotifier { } /// Quick stage change, optimistic local update for snappy UX. + /// + /// Goes through the board's move endpoint rather than the deal's own + /// `PATCH`, which is what dragging a card means and what the web board + /// sends. Three things follow from that, none of which the deal edit path + /// could do: + /// + /// * Dropping into Closed Won or Closed Lost stamps `closed_by`, and fills + /// `closed_on` when the deal never carried an expected close date. On the + /// edit path a deal with no close date was refused outright, so a drag to + /// Won on a fresh deal could not succeed at all. + /// * A won deal still has to record an amount. The server answers 400 naming + /// the field, which the caller shows; there is no amount to collect + /// mid-drag, so the deal has to be opened. + /// * `probability` is set server-side from the destination stage, so it is + /// no longer sent from here. `Opportunity.save()` only fills a 0/None one, + /// which is why the move endpoint sets it explicitly. + /// + /// Sending no neighbours appends to the destination column, which is where a + /// stage change with no position in mind belongs. Future<({bool success, String? error})> updateDealStage( String id, DealStage stage, ) async { try { - final url = '${ApiConfig.opportunities}$id/'; - final response = await _apiService.patch(url, { - 'stage': stage.value, - 'probability': stage.defaultProbability, + final response = await _apiService.patch(ApiConfig.opportunityMove(id), { + 'column_id': stage.value, }); if (response.success && response.data != null) { From f8f7dc0c119277d9934a78c5cd338dda2f3361f1 Mon Sep 17 00:00:00 2001 From: Ashwin Date: Wed, 12 Aug 2026 20:19:53 +0530 Subject: [PATCH 2/2] feat: add email templates for assigned contacts, leads, and opportunities - Created new email templates for notifying users when a contact, lead, or opportunity is assigned to them. - Added a health check HTML template for server status. - Introduced magic link email templates for sign-in codes and links. - Implemented a new root email template for consistent styling across emails. - Updated packaging tests to ensure all templates are included in the wheel. - Modified settings to remove project-level template directories, ensuring templates are sourced from app directories. - Added new templates for goal milestones and stale deals alerts in the opportunity module. - Bumped version to 1.3.0 and updated dependencies in the project configuration. - Enhanced Dockerfile for better build management and added .dockerignore for cleaner builds. - Introduced CSAT rating functionality in the frontend with corresponding tests. --- .github/workflows/publish.yml | 198 ++++++++++++++++++ .github/workflows/tests.yml | 70 +++++++ backend/README.md | 147 ++++++++----- backend/cases/csat_views.py | 11 +- backend/cases/tasks.py | 32 ++- .../cases/templates/csat/survey_email.html | 64 ++++++ backend/cases/tests/test_csat.py | 54 +++++ .../assigned_to/account_assigned.html | 0 .../templates/assigned_to/cases_assigned.html | 0 .../assigned_to/contact_assigned.html | 0 .../templates/assigned_to/leads_assigned.html | 0 .../assigned_to/opportunity_assigned.html | 0 backend/{ => common}/templates/healthz.html | 0 .../templates/magic_link_code_email.html | 0 .../templates/magic_link_email.html | 0 .../templates/root_email_template_new.html | 0 backend/common/tests/test_packaging.py | 117 +++++++++++ backend/crm/settings.py | 17 +- .../templates/opportunity/goal_milestone.html | 0 .../opportunity/stale_deals_alert.html | 0 backend/pyproject.toml | 12 +- backend/uv.lock | 2 +- docker-compose.yml | 4 + frontend/.dockerignore | 30 +++ frontend/Dockerfile | 72 ++++++- frontend/src/lib/server/v2/csat.js | 43 ++++ frontend/src/lib/server/v2/csat.test.js | 42 ++++ .../(no-layout)/csat/[token]/+page.server.js | 8 +- .../(no-layout)/csat/[token]/+page.svelte | 9 +- 29 files changed, 856 insertions(+), 76 deletions(-) create mode 100644 .github/workflows/publish.yml create mode 100644 backend/cases/templates/csat/survey_email.html rename backend/{ => common}/templates/assigned_to/account_assigned.html (100%) rename backend/{ => common}/templates/assigned_to/cases_assigned.html (100%) rename backend/{ => common}/templates/assigned_to/contact_assigned.html (100%) rename backend/{ => common}/templates/assigned_to/leads_assigned.html (100%) rename backend/{ => common}/templates/assigned_to/opportunity_assigned.html (100%) rename backend/{ => common}/templates/healthz.html (100%) rename backend/{ => common}/templates/magic_link_code_email.html (100%) rename backend/{ => common}/templates/magic_link_email.html (100%) rename backend/{ => common}/templates/root_email_template_new.html (100%) create mode 100644 backend/common/tests/test_packaging.py rename backend/{ => opportunity}/templates/opportunity/goal_milestone.html (100%) rename backend/{ => opportunity}/templates/opportunity/stale_deals_alert.html (100%) create mode 100644 frontend/.dockerignore create mode 100644 frontend/src/lib/server/v2/csat.js create mode 100644 frontend/src/lib/server/v2/csat.test.js diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 00000000..665ba011 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,198 @@ +name: Publish to PyPI + +# Publishing is the one irreversible thing this repo does. PyPI refuses a second +# upload of a version that already exists, so a wrong or broken artifact cannot +# be replaced, only yanked and superseded. Every gate below exists because of +# that: verify the built distribution before it leaves, not after. +# +# `django-crm` on PyPI is an existing project (0.2.0 in 2019 through 0.9.0 in +# 2021, then dormant). This resumes it rather than claiming a new name. Note +# that PyPI stopped at 0.9.0 while git carried on to 1.0, 1.1 and 1.2, so those +# three tags have no release behind them. +on: + push: + tags: + # Both spellings on purpose. Every tag in this repo's history is + # unprefixed (1.2, 1.1, 0.9.0), so matching only 'v*' would mean someone + # tagging 1.4.0 out of habit gets silence instead of a release, and + # silence is the worst possible failure for a publish trigger. The + # version check below strips a leading v when there is one. + - 'v[0-9]*' + - '[0-9]*' + # Lets a release be rehearsed end to end without uploading: everything runs + # except the publish job, which is gated on the trigger below. + workflow_dispatch: + +concurrency: + group: publish-${{ github.ref }} + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Install uv + uses: astral-sh/setup-uv@v6 + with: + enable-cache: true + cache-dependency-glob: 'backend/uv.lock' + + # The tag is what people will `pip install ==`, and the version inside the + # wheel is what they actually get. Nothing else compares them, and a + # mismatch is only discoverable after the upload it cannot be undone from. + - name: Tag matches the packaged version + if: startsWith(github.ref, 'refs/tags/') + working-directory: backend + run: | + tag="${GITHUB_REF_NAME#v}" + packaged="$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")" + if [ "$tag" != "$packaged" ]; then + echo "::error::tag v$tag does not match pyproject.toml version $packaged" + exit 1 + fi + echo "publishing version $packaged" + + - name: Build the wheel and sdist + working-directory: backend + run: uv build --out-dir "$RUNNER_TEMP/dist" + + # README.md is the long description, so a construct PyPI will not render + # fails here rather than landing as a broken project page on a version + # that cannot be replaced. The publish action verifies metadata too, but + # only on the tag path: this is what makes a workflow_dispatch dry run + # tell you anything about the description. + - name: Check the distribution metadata + run: uvx twine check "$RUNNER_TEMP"/dist/* + + # `check` walks the URLconf into the invoices views, which import + # WeasyPrint at module scope. + - name: Install system dependencies (WeasyPrint) + run: | + sudo apt-get update + sudo apt-get install -y \ + libpango-1.0-0 \ + libpangocairo-1.0-0 \ + libgdk-pixbuf-2.0-0 \ + libffi-dev \ + shared-mime-info + + # The same gate as the package-build job in tests.yml, repeated here + # because that job runs on the branch and this runs on the tag. Run from + # $RUNNER_TEMP: inside the source tree every app imports from the working + # directory, which is what let two installed apps ship missing from the + # wheel with a green suite. + - name: Install the built wheel into a clean environment and start it + env: + DJANGO_SETTINGS_MODULE: crm.settings + SECRET_KEY: startup-check-only-not-a-deployment-secret + run: | + cd "$RUNNER_TEMP" + uv venv --python 3.12 pkgenv + uv pip install --python pkgenv/bin/python dist/*.whl + mkdir -p neutral && cd neutral + "$RUNNER_TEMP/pkgenv/bin/django-admin" check + "$RUNNER_TEMP/pkgenv/bin/python" -c "import django; django.setup(); from django.template.loader import get_template; [get_template(n) for n in ('magic_link_email.html', 'magic_link_code_email.html', 'root_email_template_new.html', 'healthz.html', 'assigned_to/leads_assigned.html', 'opportunity/goal_milestone.html', 'csat/survey_email.html')]; print('templates resolve from the installed package')" + + - name: Upload the distributions + uses: actions/upload-artifact@v4 + with: + name: dist + path: ${{ runner.temp }}/dist/ + if-no-files-found: error + + publish: + needs: build + if: startsWith(github.ref, 'refs/tags/') + runs-on: ubuntu-latest + + # Trusted Publishing (OIDC). No API token is stored in this repo, so there + # is no long-lived PyPI credential to leak or rotate, and publish rights are + # bound to this repository, this workflow file and this environment. + # + # Configured once on pypi.org under the project's Publishing settings, with + # GitHub's own casing for the first two, which is what lands in the OIDC + # token claims: + # owner: Django-CRM <- the org the repo was TRANSFERRED to. The + # PyPI project page still shows + # MicroPyramid from the 2021 release, and + # MicroPyramid/Django-CRM now redirects + # here. The publisher must name where the + # code lives, not where it used to. + # repository: Django-CRM + # workflow: publish.yml <- this file, matched by filename + # environment: pypi <- must equal `environment.name` below + environment: + name: pypi + url: https://pypi.org/project/django-crm/ + + permissions: + # The only permission the OIDC exchange needs. Deliberately no + # `contents: write`: publishing does not modify the repository. + id-token: write + + steps: + - name: Download the distributions + uses: actions/download-artifact@v4 + with: + name: dist + path: dist/ + + # Pinned to a commit SHA rather than the `v1` tag used elsewhere in this + # repo. A moving tag means whatever the upstream owner repoints it to runs + # inside the job holding the OIDC token that can publish as us. tests.yml + # can afford tags; this job cannot. + # dc37677b2e1c63e2034f94d8a5b11f265b73ba33 is pypa/gh-action-pypi-publish + # v1.14.2. Bump both together, never the comment alone. + - name: Publish + uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 + + # The other half of the release. PyPI carries the API; this carries the UI, + # which is a Node server (adapter-node, 81 server load functions and 64 form + # actions) and cannot be a Python package. Built from the SAME tag as the + # wheel above so "enterprise runs community 1.4.2" names one commit rather + # than an API version and whatever the UI happened to be. + frontend-image: + # Gated on `build` even though the image does not use the wheel. The two + # artifacts are one release under one tag, so a wheel that fails + # verification must not leave a matching image published with nothing to + # match. Without this they race, and a failed build still ships the image. + needs: build + if: startsWith(github.ref, 'refs/tags/') + runs-on: ubuntu-latest + + permissions: + contents: read + packages: write + + steps: + - uses: actions/checkout@v4 + + # Plain docker CLI rather than docker/login-action + build-push-action. + # This job can push an image under the org's namespace, so the fewer + # third-party actions holding that token the better. The CLI is already + # on the runner and the whole recipe is four lines. + - name: Build and push + env: + REGISTRY: ghcr.io + GHCR_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + version="${GITHUB_REF_NAME#v}" + owner="$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')" + image="${REGISTRY}/${owner}/bottlecrm-frontend" + + echo "${GHCR_TOKEN}" | docker login "${REGISTRY}" -u "${GITHUB_ACTOR}" --password-stdin + + # The default (last) stage is the production server. Naming it is not + # optional: `target: dev` in docker-compose.yml means the stage order + # is load-bearing, and a silent change to it would ship a Vite dev + # server to everyone who pulls this tag. + docker build --target runtime \ + -t "${image}:${version}" \ + -t "${image}:latest" \ + frontend/ + + docker push "${image}:${version}" + docker push "${image}:latest" diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 1e886f6d..1c792c2e 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -232,6 +232,76 @@ jobs: working-directory: backend run: uv run ruff format --check . + # Nothing above this job exercises the built distribution. Development uses an + # editable install, which hatchling implements as a single .pth file adding all + # of backend/ to sys.path, so every app and template is reachable whether or not + # `[tool.hatch.build.targets.wheel]` in pyproject.toml ever lists it. That is how + # `business_hours` and `macros` came to be installed apps that no wheel shipped: + # a green suite, and `pip install django-crm` dead on ModuleNotFoundError. + package-build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Install uv + uses: astral-sh/setup-uv@v6 + with: + enable-cache: true + cache-dependency-glob: 'backend/uv.lock' + + # `check` walks the URLconf, which reaches the invoices views, which import + # WeasyPrint at module scope. Without these it fails on a missing .so and + # says nothing about packaging. + - name: Install system dependencies (WeasyPrint) + run: | + sudo apt-get update + sudo apt-get install -y \ + libpango-1.0-0 \ + libpangocairo-1.0-0 \ + libgdk-pixbuf-2.0-0 \ + libffi-dev \ + shared-mime-info + + - name: Build the wheel + working-directory: backend + run: uv build --wheel --out-dir "$RUNNER_TEMP/dist" + + # Deliberately run from $RUNNER_TEMP rather than backend/. From inside the + # source tree `crm` and every app resolve from the working directory, which + # reproduces the exact blindness this job exists to remove. The venv gets + # the wheel and its declared dependencies, nothing else. + - name: Install the wheel into a clean environment + run: | + cd "$RUNNER_TEMP" + uv venv --python 3.12 pkgenv + uv pip install --python pkgenv/bin/python dist/*.whl + + # Loads every app in INSTALLED_APPS and every view behind the URLconf, so a + # package missing from the wheel fails here. Warnings do not fail `check`, + # so keep this output empty: a standing warning is where the next real one + # hides. + - name: Start the installed package + env: + DJANGO_SETTINGS_MODULE: crm.settings + SECRET_KEY: startup-check-only-not-a-deployment-secret + run: | + mkdir -p "$RUNNER_TEMP/neutral" + cd "$RUNNER_TEMP/neutral" + "$RUNNER_TEMP/pkgenv/bin/django-admin" check + + # `check` does not open a template, so it is blind to the second half of + # the same defect: these render the magic-link login emails, and they only + # ship because they sit in an app's templates/ directory. A project-level + # templates/ dir resolves to site-packages once installed. + - name: Resolve packaged templates + env: + DJANGO_SETTINGS_MODULE: crm.settings + SECRET_KEY: startup-check-only-not-a-deployment-secret + run: | + cd "$RUNNER_TEMP/neutral" + "$RUNNER_TEMP/pkgenv/bin/python" -c "import django; django.setup(); from django.template.loader import get_template; [get_template(n) for n in ('magic_link_email.html', 'magic_link_code_email.html', 'root_email_template_new.html', 'healthz.html', 'assigned_to/leads_assigned.html', 'opportunity/goal_milestone.html', 'csat/survey_email.html')]; print('templates resolve from the installed package')" + frontend-checks: runs-on: ubuntu-latest diff --git a/backend/README.md b/backend/README.md index 018d79e4..686890cc 100644 --- a/backend/README.md +++ b/backend/README.md @@ -4,38 +4,48 @@ The backend for BottleCRM, a multi-tenant CRM platform built with Django REST Fr ## Tech Stack -- **Django 4.2.1** - Web framework -- **Django REST Framework 3.14.0** - API toolkit -- **PostgreSQL** - Database (psycopg2-binary 2.9.11) -- **Celery 5.5.3** - Async task queue -- **Redis 4.6.0** - Message broker for Celery -- **djangorestframework-simplejwt 5.2.2** - JWT authentication -- **drf-spectacular 0.26.2** - OpenAPI/Swagger documentation -- **django-ses 3.5.0** - AWS SES email backend -- **Sentry SDK 1.24.0** - Error tracking +Minimum versions, as declared in `pyproject.toml`. That file is the source of +truth; the list here is a summary and `uv.lock` pins what actually gets +installed. + +- **Django 6.0.7+** - Web framework +- **Django REST Framework 3.17+** - API toolkit +- **PostgreSQL** - Database, via **psycopg 3.2.10+** with the `pool` extra +- **Celery 5.6+** - Async task queue +- **Redis 8.0+** - Message broker for Celery +- **djangorestframework-simplejwt 5.5+** - JWT authentication +- **drf-spectacular 0.30+** - OpenAPI/Swagger documentation +- **django-ses 4.7+** - AWS SES email backend +- **WeasyPrint 69+** - Invoice and estimate PDF generation +- **Sentry SDK 2.66+** - Error tracking + +> psycopg 3, not psycopg2. The `pool` extra is required rather than optional: +> Django raises `ImproperlyConfigured` for pool options under psycopg2, and +> `DATABASES["default"]["OPTIONS"]["pool"]` depends on it. ## Django Apps | App | Description | |-----|-------------| -| `common` | User, Organization, Profile, Comments, Attachments, Document models | +| `common` | User, Organization, Profile, Teams, Comments, Attachments, Document models | | `accounts` | Customer account management | | `leads` | Lead tracking and conversion | | `contacts` | Contact management | | `opportunity` | Sales pipeline and deal tracking | -| `cases` | Customer support tickets | +| `cases` | Customer support tickets, solutions, approvals, escalation | | `tasks` | Task management | -| `invoices` | Invoicing system | -| `events` | Calendar events | -| `teams` | Team management | -| `emails` | Email handling | -| `planner` | Planner events | -| `boards` | Kanban board system | -| `marketing` | Newsletter and contact forms | +| `invoices` | Invoices, estimates, recurring invoices, products | +| `orders` | Orders and order line items | +| `business_hours` | Business hours and holiday calendars for SLA timing | +| `macros` | Saved reply and action macros for cases | + +`teams` was merged into `common`. The `emails`, `events`, `planner` and +`boards` apps were removed after 0.9.0; see the release notes if you are +upgrading from that version. ## Prerequisites -- **Python 3.10+** (uv installs a matching Python automatically if needed) +- **Python 3.12+** (uv installs a matching Python automatically if needed) - **PostgreSQL** - **Redis** (for Celery) - **[uv](https://docs.astral.sh/uv/)**: Python package & venv manager (replaces pip + virtualenv) @@ -107,6 +117,8 @@ Create a `.env` file in the `backend/` directory: # python -c "import secrets; print(secrets.token_urlsafe(48))" SECRET_KEY=your-secret-key-here ENV_TYPE=dev +DEBUG=True +ALLOWED_HOSTS=localhost,127.0.0.1 # Database DBNAME=bottlecrm @@ -123,7 +135,20 @@ ADMIN_EMAIL=admin@bottlecrm.com CELERY_BROKER_URL=redis://localhost:6379/0 CELERY_RESULT_BACKEND=redis://localhost:6379/0 -# Domain +# The web app, NOT this API. Every link the backend emails is built from it: +# the magic-link sign-in URL, the customer invoice and estimate portals, the +# CSAT survey. Point it at the API host and every one of those links 404s. +FRONTEND_URL=http://localhost:5173 + +# Google sign-in. Without these the OAuth login flow cannot complete, which is +# the only interactive way into the app. +GOOGLE_CLIENT_ID=your-google-client-id +GOOGLE_CLIENT_SECRET=your-google-client-secret + +# Where the browser calls this API from. The SvelteKit dev server by default. +CORS_ALLOWED_ORIGINS=http://localhost:5173 + +# This API's own public origin DOMAIN_NAME=http://localhost:8000 ``` @@ -170,7 +195,7 @@ uv run celery -A crm worker --loglevel=INFO To generate the OpenAPI schema file: ```bash -python manage.py spectacular --file openapi.yml +uv run python manage.py spectacular --file openapi.yml ``` ## Architecture @@ -220,14 +245,16 @@ PostgreSQL RLS provides database-level tenant isolation as defense-in-depth. 2. **RLS policies filter queries**: Only rows matching `org_id` are visible 3. **Fail-safe design**: Empty context returns zero rows (NULLIF pattern) -#### Protected Tables (24 total) +#### Protected Tables -| Category | Tables | -|----------|--------| -| Core Business | `lead`, `accounts`, `contacts`, `opportunity`, `case`, `task`, `invoice` | -| Supporting | `comment`, `attachments`, `document`, `teams`, `activity`, `tags`, `address`, `solution` | -| Boards | `board`, `board_column`, `board_task`, `board_member` | -| Other | `apiSettings`, `account_email`, `emailLogs`, `invoice_history`, `security_audit_log` | +`ORG_SCOPED_TABLES` in `common/rls/__init__.py` is the list, and the only one +worth trusting. It is deliberately not reproduced here: this section used to +carry a copy and a count, and both went stale, naming tables that no longer +exist and a total that was wrong by more than double. + +```bash +uv run python manage.py manage_rls --status # what is actually protected +``` #### Configuration @@ -247,21 +274,19 @@ cursor.execute(get_enable_policy_sql("my_table")) ```bash # Check RLS status on all tables -python manage.py manage_rls --status +uv run python manage.py manage_rls --status # Verify database user is non-superuser (required for RLS) -python manage.py manage_rls --verify-user +uv run python manage.py manage_rls --verify-user # Test RLS isolation between organizations -python manage.py manage_rls --test - -# Enable RLS on all configured tables -python manage.py manage_rls --enable - -# Disable RLS (for debugging only) -python manage.py manage_rls --disable +uv run python manage.py manage_rls --test ``` +Policies are enabled by migration, using `get_enable_policy_sql()`, so there is +no `--enable` flag to run by hand and no `--disable` to reach for when +something is in the way. A table becomes protected when its migration says so. + #### Critical: Database User Setup **PostgreSQL superusers bypass ALL RLS policies.** You must use a non-superuser: @@ -344,6 +369,7 @@ backend/ │ ├── base.py # BaseModel │ ├── middleware/ │ └── tasks.py # Celery tasks +│ └── templates/ # Email templates, shipped as package data ├── accounts/ ├── leads/ ├── contacts/ @@ -351,16 +377,17 @@ backend/ ├── cases/ ├── tasks/ ├── invoices/ -├── events/ -├── teams/ -├── emails/ -├── planner/ -├── boards/ -├── marketing/ -├── templates/ +├── orders/ +├── business_hours/ +├── macros/ └── static/ ``` +> Templates live in their owning app's `templates/` directory rather than a +> project-level one. `TEMPLATES[0]["DIRS"]` is empty on purpose: a `BASE_DIR` +> entry resolves to `site-packages` once the package is installed, where +> nothing is written, and the login emails would not render. + ## Development ### Code Quality @@ -432,16 +459,38 @@ uv lock --upgrade |----------|-------------| | `SECRET_KEY` | Django secret key, and the JWT signing key. At least 32 bytes | | `ENV_TYPE` | Environment type (`dev` or `prod`) | +| `DEBUG` | `True` or `False`. Never `True` in production | +| `ALLOWED_HOSTS` | Comma-separated hostnames. Defaults to `localhost,127.0.0.1` | | `DBNAME` | PostgreSQL database name | -| `DBUSER` | PostgreSQL username | +| `DBUSER` | PostgreSQL username. Must NOT be a superuser, see the RLS section | | `DBPASSWORD` | PostgreSQL password | | `DBHOST` | PostgreSQL host | | `DBPORT` | PostgreSQL port | +| `DB_POOL_ENABLED` | Connection pooling, off by default. See the note below | +| `DB_POOL_MIN_SIZE` | Pool minimum, default `2`. Per process, not per host | +| `DB_POOL_MAX_SIZE` | Pool maximum, default `10`. Per process, not per host | +| `FRONTEND_URL` | The **web app** origin. Every emailed link is built from it | +| `DOMAIN_NAME` | This API's own public origin | +| `GOOGLE_CLIENT_ID` | Google OAuth client id. Required for sign-in | +| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret. Required for sign-in | +| `CORS_ALLOWED_ORIGINS` | Comma-separated browser origins allowed to call the API | +| `CORS_ALLOW_ALL` | Development escape hatch. Leave off in production | +| `CSRF_TRUSTED_ORIGINS` | Comma-separated origins trusted for CSRF | +| `TRUST_PROXY_SSL_HEADER` | Set when running behind a TLS-terminating proxy | | `DEFAULT_FROM_EMAIL` | Default sender email | | `ADMIN_EMAIL` | Admin notification email | +| `EMAIL_BACKEND` | Django email backend. Defaults to AWS SES | +| `AWS_SES_REGION_NAME` | AWS SES region | +| `AWS_SES_REGION_ENDPOINT` | AWS SES endpoint | | `CELERY_BROKER_URL` | Redis URL for Celery broker | | `CELERY_RESULT_BACKEND` | Redis URL for Celery results | -| `DOMAIN_NAME` | Application domain | +| `DJANGO_ORG_API_KEY_AUTH` | Enables org API key authentication | + +> **`DB_POOL_ENABLED` is not just a performance knob.** RLS context lives in a +> session-scoped variable, so a pooled connection carries the previous tenant's +> org id unless something clears it. The `reset` callback in +> `common/rls/pool.py` is what clears it, and pooling must never be enabled +> without it. ## Troubleshooting @@ -477,4 +526,8 @@ uv run celery -A crm worker --loglevel=DEBUG ## License -MIT License - see [LICENSE](../LICENSE) for details. +MIT License. See +[LICENSE](https://github.com/django-crm/Django-CRM/blob/master/LICENSE). + +The link is absolute on purpose. This file is the package's long description on +PyPI, where a relative `../LICENSE` points outside the distribution and 404s. diff --git a/backend/cases/csat_views.py b/backend/cases/csat_views.py index d4f2181a..861ee797 100644 --- a/backend/cases/csat_views.py +++ b/backend/cases/csat_views.py @@ -23,6 +23,8 @@ from rest_framework.views import APIView from cases.models import CsatSurvey from cases.tasks import ( + CSAT_RATING_MAX, + CSAT_RATING_MIN, CSAT_TOKEN_TTL_DAYS, csat_signer, hash_csat_token, @@ -120,12 +122,15 @@ class PublicCsatView(APIView): rating_int = int(rating) except (TypeError, ValueError): return Response( - {"error": "rating must be an integer 1-5"}, + { + "error": f"rating must be an integer " + f"{CSAT_RATING_MIN}-{CSAT_RATING_MAX}" + }, status=drf_status.HTTP_400_BAD_REQUEST, ) - if rating_int < 1 or rating_int > 5: + if rating_int < CSAT_RATING_MIN or rating_int > CSAT_RATING_MAX: return Response( - {"error": "rating must be 1..5"}, + {"error": f"rating must be {CSAT_RATING_MIN}..{CSAT_RATING_MAX}"}, status=drf_status.HTTP_400_BAD_REQUEST, ) diff --git a/backend/cases/tasks.py b/backend/cases/tasks.py index 053b0efe..1a74db53 100644 --- a/backend/cases/tasks.py +++ b/backend/cases/tasks.py @@ -27,6 +27,16 @@ CSAT_SEND_DELAY_MINUTES = 30 # Salt scoping the TimestampSigner so a leak doesn't help forge tokens # elsewhere in the codebase. CSAT_SIGNER_SALT = "cases.csat_survey" +# The rating scale, in one place because two things read it: the survey email +# renders a star per value, and csat_views.CsatPublicView validates the POST +# against the same bounds. A scale that disagreed with the validator would put +# a star in the email that the API rejects on arrival. +CSAT_RATING_MIN = 1 +CSAT_RATING_MAX = 5 +# The ends of the scale, labelled. Mirrors SCALE_ENDS in the survey page so the +# email and the page it links to describe the same 1 and the same 5. +CSAT_SCALE_LOW_LABEL = "Not good" +CSAT_SCALE_HIGH_LABEL = "Great" # Cap a single case at 3 escalations total. Past that, a human needs to step in. ESCALATION_COUNT_CAP = 3 @@ -309,17 +319,19 @@ def send_csat_survey(case_id, org_id): "contact": contact, "org": case.org, "link": link, + # Each value becomes a star linking to `{link}?rating=`, which + # only pre-selects on the page. Nothing is recorded until that page + # POSTs, because a link is a GET and mail scanners follow GETs. + "rating_scale": range(CSAT_RATING_MIN, CSAT_RATING_MAX + 1), + "scale_low_label": CSAT_SCALE_LOW_LABEL, + "scale_high_label": CSAT_SCALE_HIGH_LABEL, } - try: - html = render_to_string("csat/survey_email.html", context=context) - except Exception: - # Template missing in dev: fall back to a plain link so the task - # still records the survey row + token. Production has the template. - html = ( - f"

Hi {contact.first_name or 'there'},

" - f'

How did we do on case "{case.name}"?

' - f'

Rate your experience

' - ) + # Deliberately unguarded. This render used to sit under a bare + # `except Exception` that fell back to a plain link, with a comment saying + # the template existed in production. It never existed anywhere, so every + # survey ever sent took the fallback and nobody found out. A template that + # fails to render is now a task failure that Celery logs. + html = render_to_string("csat/survey_email.html", context=context) msg = EmailMessage( subject=f"How did we do?, {case.name}", diff --git a/backend/cases/templates/csat/survey_email.html b/backend/cases/templates/csat/survey_email.html new file mode 100644 index 00000000..1d19d1e0 --- /dev/null +++ b/backend/cases/templates/csat/survey_email.html @@ -0,0 +1,64 @@ +{% extends 'root_email_template_new.html' %} + +{% comment %} +The rating is answered here, in the mail client, not on the page. Each star is +an ordinary link carrying its own value, so the customer's first click is the +answer and /csat/ becomes a confirmation. + +A link is a GET, and mail scanners and link-preview bots follow GETs. So the +value travels as a query parameter that only PRE-SELECTS the rating; nothing is +recorded until the page POSTs. Making a star link record the rating directly +would let any scanner in the delivery path answer the survey. +{% endcomment %} + +{% block preheader %}How did we do on "{{ case.name }}"?{% endblock preheader %} + +{% block heading %}How did we do?{% endblock heading %} + +{% block content_body %} +

Hi {{ contact.first_name|default:"there" }},

+

Your case with {{ org.name }} is closed. Tap a star to rate it, and we will only ask you this once.

+{% endblock content_body %} + +{% block metadata %} + + + + + + + + +{% endblock metadata %} + +{% block button_link %} + + + {% for value in rating_scale %} + + {% endfor %} + + + + +
+ + ★{{ value }} + +
+ + + + + +
{{ scale_low_label }}{{ scale_high_label }}
+
+{% endblock button_link %} + +{% block extra_content %} +

+ Or open the survey to leave a comment as well. +

+{% endblock extra_content %} diff --git a/backend/cases/tests/test_csat.py b/backend/cases/tests/test_csat.py index c988a93f..a84677e4 100644 --- a/backend/cases/tests/test_csat.py +++ b/backend/cases/tests/test_csat.py @@ -7,6 +7,7 @@ so `send_csat_survey.apply_async(countdown=...)` runs inline. from __future__ import annotations +import re from datetime import timedelta import pytest @@ -15,6 +16,8 @@ from django.utils import timezone from cases import analytics from cases.models import Case, CsatSurvey from cases.tasks import ( + CSAT_RATING_MAX, + CSAT_RATING_MIN, CSAT_TOKEN_TTL_DAYS, csat_signer, hash_csat_token, @@ -115,6 +118,57 @@ class TestSendCsatSurvey: assert CsatSurvey.objects.filter(case=closed_case).count() == 1 +# -------------------------------------------------------------------------- +# The survey email +# +# `csat/survey_email.html` did not exist for the whole life of this feature. +# The render sat under a bare `except Exception` that fell back to a plain +# link, with a comment claiming production had the template, so every survey +# ever sent went out through the fallback and the suite stayed green because +# nothing here looked at the body. These assert the body. + + +class TestCsatSurveyEmail: + def test_sends_one_html_email(self, closed_case, mailoutbox): + send_csat_survey(str(closed_case.id), str(closed_case.org_id)) + assert len(mailoutbox) == 1 + assert mailoutbox[0].content_subtype == "html" + assert mailoutbox[0].to == ["pat@example.com"] + + def test_body_renders_the_real_template(self, closed_case, mailoutbox): + """The fallback had none of this markup, so it pins template, not text.""" + send_csat_survey(str(closed_case.id), str(closed_case.org_id)) + body = mailoutbox[0].body + # From root_email_template_new.html, which only an extending template + # can produce. + assert "Sent by BottleCRM" in body + assert closed_case.name in body + + def test_one_star_link_per_point_on_the_scale(self, closed_case, mailoutbox): + send_csat_survey(str(closed_case.id), str(closed_case.org_id)) + survey = CsatSurvey.objects.get(case=closed_case) + body = mailoutbox[0].body + + expected = list(range(CSAT_RATING_MIN, CSAT_RATING_MAX + 1)) + for value in expected: + assert f"?rating={value}" in body, f"no star link for rating {value}" + # And nothing off the ends, which the API would reject on arrival. + for value in (CSAT_RATING_MIN - 1, CSAT_RATING_MAX + 1): + assert f"?rating={value}" not in body + assert body.count("?rating=") == len(expected) + assert survey.rating is None # arriving is not answering + + def test_links_point_at_the_survey_for_this_token(self, closed_case, mailoutbox): + """Every star carries the same token, so one click identifies one survey.""" + send_csat_survey(str(closed_case.id), str(closed_case.org_id)) + survey = CsatSurvey.objects.get(case=closed_case) + body = mailoutbox[0].body + + tokens = set(re.findall(r"/csat/([^?\"]+)", body)) + assert len(tokens) == 1, f"expected one token in the email, got {tokens}" + assert hash_csat_token(tokens.pop()) == survey.token_hash + + # -------------------------------------------------------------------------- # Public GET diff --git a/backend/templates/assigned_to/account_assigned.html b/backend/common/templates/assigned_to/account_assigned.html similarity index 100% rename from backend/templates/assigned_to/account_assigned.html rename to backend/common/templates/assigned_to/account_assigned.html diff --git a/backend/templates/assigned_to/cases_assigned.html b/backend/common/templates/assigned_to/cases_assigned.html similarity index 100% rename from backend/templates/assigned_to/cases_assigned.html rename to backend/common/templates/assigned_to/cases_assigned.html diff --git a/backend/templates/assigned_to/contact_assigned.html b/backend/common/templates/assigned_to/contact_assigned.html similarity index 100% rename from backend/templates/assigned_to/contact_assigned.html rename to backend/common/templates/assigned_to/contact_assigned.html diff --git a/backend/templates/assigned_to/leads_assigned.html b/backend/common/templates/assigned_to/leads_assigned.html similarity index 100% rename from backend/templates/assigned_to/leads_assigned.html rename to backend/common/templates/assigned_to/leads_assigned.html diff --git a/backend/templates/assigned_to/opportunity_assigned.html b/backend/common/templates/assigned_to/opportunity_assigned.html similarity index 100% rename from backend/templates/assigned_to/opportunity_assigned.html rename to backend/common/templates/assigned_to/opportunity_assigned.html diff --git a/backend/templates/healthz.html b/backend/common/templates/healthz.html similarity index 100% rename from backend/templates/healthz.html rename to backend/common/templates/healthz.html diff --git a/backend/templates/magic_link_code_email.html b/backend/common/templates/magic_link_code_email.html similarity index 100% rename from backend/templates/magic_link_code_email.html rename to backend/common/templates/magic_link_code_email.html diff --git a/backend/templates/magic_link_email.html b/backend/common/templates/magic_link_email.html similarity index 100% rename from backend/templates/magic_link_email.html rename to backend/common/templates/magic_link_email.html diff --git a/backend/templates/root_email_template_new.html b/backend/common/templates/root_email_template_new.html similarity index 100% rename from backend/templates/root_email_template_new.html rename to backend/common/templates/root_email_template_new.html diff --git a/backend/common/tests/test_packaging.py b/backend/common/tests/test_packaging.py new file mode 100644 index 00000000..be6e63a1 --- /dev/null +++ b/backend/common/tests/test_packaging.py @@ -0,0 +1,117 @@ +"""The built wheel ships every app the settings install, and every template. + +``pip install django-crm`` gets whatever ``[tool.hatch.build.targets.wheel]`` +lists in ``pyproject.toml`` and nothing else. That list is hand-maintained, and +a source checkout never exercises it: the editable install used in development +is a single ``.pth`` file adding all of ``backend/`` to ``sys.path``, so every +app imports whether or not it was ever packaged. + +Both halves of that gap were live. ``business_hours`` and ``macros`` were in +``INSTALLED_APPS`` and absent from the wheel, so an installed copy died at +startup with ``ModuleNotFoundError``. The magic-link login emails lived in a +project-level ``templates/`` directory reached through ``TEMPLATES[0]["DIRS"]`` +via ``BASE_DIR``, which resolves to ``site-packages`` once installed, so they +would not have rendered either. + +Derived from the app registry rather than a second hand-written list here, +because a list of "apps to check" fails exactly the way the list it checks +does. See ``test_org_index_coverage.py`` for the same reasoning. +""" + +from __future__ import annotations + +import tomllib +from pathlib import Path + +import pytest +from django.apps import apps +from django.conf import settings +from django.template import TemplateDoesNotExist +from django.template.loader import get_template + +# The project package. Holds settings/urls/celery/wsgi, so it is required at +# runtime, but it is not an app and never appears in INSTALLED_APPS. +PROJECT_PACKAGE = "crm" + +# Templates that used to sit in the project-level templates/ directory. Each is +# rendered by name from application code, so the name is the contract: moving a +# file between app template directories is fine, dropping it out of a packaged +# app is not. +MOVED_TEMPLATES = [ + "assigned_to/account_assigned.html", + "assigned_to/cases_assigned.html", + "assigned_to/contact_assigned.html", + "assigned_to/leads_assigned.html", + "assigned_to/opportunity_assigned.html", + "healthz.html", + "magic_link_code_email.html", + "magic_link_email.html", + "opportunity/goal_milestone.html", + "opportunity/stale_deals_alert.html", + "root_email_template_new.html", +] + + +def _backend_root() -> Path: + return Path(settings.BASE_DIR) + + +def _first_party_apps() -> set[str]: + """Installed apps whose source lives in this repo, not in site-packages.""" + root = _backend_root() + return { + config.label + for config in apps.get_app_configs() + if Path(config.path).resolve().parent == root.resolve() + } + + +def _build_config() -> dict: + with open(_backend_root() / "pyproject.toml", "rb") as handle: + return tomllib.load(handle)["tool"]["hatch"]["build"]["targets"] + + +def test_wheel_packages_match_installed_apps(): + """Every first-party app is packaged, and nothing packaged has been deleted.""" + packaged = set(_build_config()["wheel"]["packages"]) + expected = _first_party_apps() | {PROJECT_PACKAGE} + + assert packaged == expected, ( + "pyproject.toml [tool.hatch.build.targets.wheel].packages has drifted " + f"from INSTALLED_APPS. Missing from the wheel: " + f"{sorted(expected - packaged)}. Packaged but not installed: " + f"{sorted(packaged - expected)}." + ) + + +def test_sdist_includes_every_wheel_package(): + """The sdist carries at least what the wheel does, as a trailing-slash path.""" + targets = _build_config() + included = set(targets["sdist"]["include"]) + missing = [ + f"{name}/" + for name in targets["wheel"]["packages"] + if f"{name}/" not in included + ] + + assert not missing, ( + f"pyproject.toml [tool.hatch.build.targets.sdist].include is missing {missing}. " + "An sdist that omits an installed app builds a wheel that cannot start." + ) + + +@pytest.mark.parametrize("name", MOVED_TEMPLATES) +def test_template_resolves_through_an_app_directory(name): + """Resolvable with TEMPLATES[0]["DIRS"] empty, so it ships as package data.""" + assert settings.TEMPLATES[0]["DIRS"] == [], ( + "A project-level template directory resolves to site-packages/templates " + "on an installed copy, where nothing is written. Keep templates in the " + "owning app's templates/ directory so APP_DIRS finds them." + ) + try: + get_template(name) + except TemplateDoesNotExist: # pragma: no cover - the assertion is the report + pytest.fail( + f"{name} is not reachable through any installed app's templates/ " + "directory, so it will be absent from the wheel." + ) diff --git a/backend/crm/settings.py b/backend/crm/settings.py index 035c9a74..27c55acc 100644 --- a/backend/crm/settings.py +++ b/backend/crm/settings.py @@ -100,9 +100,12 @@ ROOT_URLCONF = "crm.urls" TEMPLATES = [ { "BACKEND": "django.template.backends.django.DjangoTemplates", - "DIRS": [ - os.path.join(BASE_DIR, "templates"), - ], + # No project-level template directory. Every template lives in its + # owning app's templates/ dir and is found by APP_DIRS, so it ships + # inside the wheel as package data. A BASE_DIR entry here would resolve + # to site-packages/templates on a pip install, where nothing is + # installed, and the magic-link login emails would fail to render. + "DIRS": [], "APP_DIRS": True, "OPTIONS": { "context_processors": [ @@ -221,7 +224,13 @@ AUTH_USER_MODEL = "common.User" STATIC_ROOT = os.path.join(BASE_DIR, "staticfiles") STATIC_URL = "/static/" -STATICFILES_DIRS = [os.path.join(BASE_DIR, "static")] +# Only when it exists. A source checkout keeps backend/static/ as a place to +# drop files; an installed copy resolves BASE_DIR to site-packages, where there +# is no such directory, and an unconditional entry raises staticfiles.W004 on +# every startup check. A permanent warning is where the next real one hides. +STATICFILES_DIRS = [ + path for path in [os.path.join(BASE_DIR, "static")] if os.path.isdir(path) +] ENV_TYPE = os.environ.get("ENV_TYPE", "dev") if ENV_TYPE == "dev": diff --git a/backend/templates/opportunity/goal_milestone.html b/backend/opportunity/templates/opportunity/goal_milestone.html similarity index 100% rename from backend/templates/opportunity/goal_milestone.html rename to backend/opportunity/templates/opportunity/goal_milestone.html diff --git a/backend/templates/opportunity/stale_deals_alert.html b/backend/opportunity/templates/opportunity/stale_deals_alert.html similarity index 100% rename from backend/templates/opportunity/stale_deals_alert.html rename to backend/opportunity/templates/opportunity/stale_deals_alert.html diff --git a/backend/pyproject.toml b/backend/pyproject.toml index f50b11f4..280efdaf 100644 --- a/backend/pyproject.toml +++ b/backend/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "django-crm" -version = "1.0.0" +version = "1.3.0" description = "Open-source multi-tenant CRM platform built on Django REST Framework with row-level security." readme = "README.md" requires-python = ">=3.12" @@ -96,14 +96,21 @@ docs = [ ] [tool.hatch.build.targets.wheel] +# Must stay in sync with the first-party entries of INSTALLED_APPS in +# crm/settings.py, plus the crm project package itself. An app installed but +# not packaged here imports fine from a source checkout and raises +# ModuleNotFoundError on a pip install, which is how business_hours and macros +# went missing. common/tests/test_packaging.py fails if the two drift apart. packages = [ "accounts", + "business_hours", "cases", "common", "contacts", "crm", "invoices", "leads", + "macros", "opportunity", "orders", "tasks", @@ -112,17 +119,18 @@ packages = [ [tool.hatch.build.targets.sdist] include = [ "accounts/", + "business_hours/", "cases/", "common/", "contacts/", "crm/", "invoices/", "leads/", + "macros/", "opportunity/", "orders/", "tasks/", "static/", - "templates/", "manage.py", ".env.example", "pytest.ini", diff --git a/backend/uv.lock b/backend/uv.lock index 01453feb..a2d3c7ec 100644 --- a/backend/uv.lock +++ b/backend/uv.lock @@ -583,7 +583,7 @@ wheels = [ [[package]] name = "django-crm" -version = "1.0.0" +version = "1.3.0" source = { editable = "." } dependencies = [ { name = "cairocffi" }, diff --git a/docker-compose.yml b/docker-compose.yml index 1ccc12e6..3203c960 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -88,6 +88,10 @@ services: build: context: ./frontend dockerfile: Dockerfile + # frontend/Dockerfile is multi-stage and its LAST stage is the production + # server. Without this, compose would build that instead and run a + # prebuilt bundle against the source mount below, which never reloads. + target: dev env_file: - .env.docker # Optional local overrides (gitignored); values here win over .env.docker. diff --git a/frontend/.dockerignore b/frontend/.dockerignore new file mode 100644 index 00000000..42f89fe6 --- /dev/null +++ b/frontend/.dockerignore @@ -0,0 +1,30 @@ +# The compose frontend service builds with `context: ./frontend`, and Docker +# reads .dockerignore from the context root, so the repo-root .dockerignore has +# never applied to this build. Without this file the whole of node_modules and +# .svelte-kit ships to the daemon on every build. + +# Secrets. Load-bearing, not tidiness: the builder stage copies the source in, +# and vite.config.js calls loadEnv(), so a real .env in the context would be +# read at build time. PUBLIC_SENTRY_DSN in particular flips autoUploadSourceMaps +# on, and the build then fails looking for a SENTRY_AUTH_TOKEN that is not there. +# Every PUBLIC_ value this app reads comes from $env/dynamic/public, which is +# resolved at RUNTIME, so nothing here needs an .env to build correctly. +.env +.env.* + +# Install and build outputs. Regenerated inside the image; copying the host's +# would also drop a linux-x64 image on top of whatever the host built. +node_modules +.svelte-kit +build + +# Never needed by a build +.git +.gitignore +.vscode +.idea +.playwright-mcp +coverage +*.log +.DS_Store +Thumbs.db diff --git a/frontend/Dockerfile b/frontend/Dockerfile index 7c5f57aa..0d81eb35 100644 --- a/frontend/Dockerfile +++ b/frontend/Dockerfile @@ -1,17 +1,79 @@ -FROM node:24-slim +# syntax=docker/dockerfile:1 +# +# One file, two outputs: the `dev` stage docker-compose runs, and the default +# `runtime` stage a release publishes. They were going to be two files, which is +# how the pnpm pin in here already drifted from the one in .github/workflows +# (11.17.0 against 10). A single base stage means there is one version to bump. +# +# RUNTIME CONFIGURATION +# +# Every value this app reads from the environment comes through +# `$env/dynamic/public`, which adapter-node resolves per process at startup, not +# at build time. So one image serves any deployment and nothing below bakes a +# hostname in: +# +# PUBLIC_DJANGO_API_URL required. The Django API origin, no trailing /api. +# ORIGIN required in production. See below. +# PUBLIC_SENTRY_DSN optional. Unset disables Sentry (`enabled: !!dsn`). +# PORT defaults to 3000. HOST already defaults to 0.0.0.0. +# +# ORIGIN is the one that fails quietly. adapter-node compares the Origin header +# of every form POST against it, and with no ORIGIN set a proxied request is +# answered `403 Cross-site POST form submissions are forbidden`. GETs still +# work, so the app looks healthy while all 64 form actions reject. Set it to the +# public URL users type, e.g. ORIGIN=https://crm.example.com. -# Enable pnpm via corepack. Pin the version so image builds are reproducible. +FROM node:24-slim AS base +# Pinned so image builds are reproducible. RUN corepack enable && corepack prepare pnpm@11.17.0 --activate - WORKDIR /app -# Install dependencies (layer cached). +# Manifests only, so this layer caches on the lockfile rather than on source. # pnpm-workspace.yaml carries the install settings (onlyBuiltDependencies, # allowBuilds) that pnpm 10+ no longer reads from package.json. Without it # @sentry/cli's postinstall is silently skipped and its binary never lands. +FROM base AS deps COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./ RUN pnpm install --frozen-lockfile -EXPOSE 5173 +# The compose target. Source and node_modules arrive as mounts, so this stage +# deliberately copies no source of its own. +FROM deps AS dev +EXPOSE 5173 CMD ["pnpm", "dev", "--host", "0.0.0.0"] + + +FROM deps AS builder +COPY . . +RUN pnpm build + + +# Runtime dependencies only. `build/` is NOT self-contained: SvelteKit keeps +# instrumentation.server.js external so OpenTelemetry can hook the process +# before anything else loads, and it imports @sentry/sveltekit by name. Without +# this stage the server dies at boot on ERR_MODULE_NOT_FOUND. +# +# --ignore-scripts because the `prepare` script shells out to svelte-kit, which +# is a devDependency and therefore absent here. package.json already tolerates +# that with `|| echo ''`; skipping it outright keeps the failure out of the log. +FROM base AS prod-deps +COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./ +RUN pnpm install --prod --frozen-lockfile --ignore-scripts + + +FROM node:24-slim AS runtime +WORKDIR /app +ENV NODE_ENV=production + +COPY --from=prod-deps --chown=node:node /app/node_modules ./node_modules +COPY --from=builder --chown=node:node /app/build ./build +# The server reads its own name and version from here on startup. +COPY --chown=node:node package.json ./ + +# Present in the node images already. The server binds 3000, so it needs no +# privileged port and no reason to be root. +USER node + +EXPOSE 3000 +CMD ["node", "build/index.js"] diff --git a/frontend/src/lib/server/v2/csat.js b/frontend/src/lib/server/v2/csat.js new file mode 100644 index 00000000..31a2be13 --- /dev/null +++ b/frontend/src/lib/server/v2/csat.js @@ -0,0 +1,43 @@ +/** + * The rating a customer clicked in the survey email. + * + * The email renders one star per point on the scale, each an ordinary link to + * `/csat/?rating=N`. This reads that N so the page can open with the + * star already lit and ask only whether they want to add a comment. + * + * It PRE-SELECTS and nothing more. A link is a GET, and mail scanners, + * corporate link-rewriters and preview bots all follow GETs before a human + * sees the message, so treating the parameter as an answer would let anything + * in the delivery path fill in the survey. The rating is recorded by the form + * POST on the page, never by arriving at it. + * + * Lives here rather than in `+page.server.js` so vitest can reach it: that + * harness resolves `$lib` and `$env/dynamic/public` and nothing else, so a + * route module importing `$app/forms` for its actions cannot be loaded at all. + * See the docstring in `vitest.config.js`, and `support.js` for the same move. + */ + +// Mirrors CSAT_RATING_MIN / CSAT_RATING_MAX in backend/cases/tasks.py. The +// backend is the boundary that matters: it re-validates the POST against these +// same bounds, so a mismatch here degrades the pre-selection and cannot widen +// what is accepted. +export const RATING_MIN = 1; +export const RATING_MAX = 5; + +/** + * @param {URL} url + * @returns {number | null} the clicked rating, or null when there wasn't one + */ +export function preselectedRating(url) { + const raw = url.searchParams.get('rating'); + if (raw === null) return null; + + // Number('') is 0 and Number(' 3 ') is 3, so neither an empty parameter nor + // a padded one can be trusted to the range check alone. Require the digits + // and nothing else. + if (!/^\d+$/.test(raw)) return null; + + const value = Number(raw); + if (value < RATING_MIN || value > RATING_MAX) return null; + return value; +} diff --git a/frontend/src/lib/server/v2/csat.test.js b/frontend/src/lib/server/v2/csat.test.js new file mode 100644 index 00000000..04738866 --- /dev/null +++ b/frontend/src/lib/server/v2/csat.test.js @@ -0,0 +1,42 @@ +import { describe, expect, it } from 'vitest'; + +import { preselectedRating, RATING_MAX, RATING_MIN } from './csat.js'; + +/** @param {string} query */ +function url(query) { + return new URL(`https://app.example.com/csat/tok${query}`); +} + +describe('preselectedRating', () => { + it('reads the star clicked in the email', () => { + for (let value = RATING_MIN; value <= RATING_MAX; value += 1) { + expect(preselectedRating(url(`?rating=${value}`))).toBe(value); + } + }); + + it('returns null when the link carries no rating', () => { + expect(preselectedRating(url(''))).toBeNull(); + expect(preselectedRating(url('?other=3'))).toBeNull(); + }); + + // Number('') is 0 and Number(' 3 ') is 3, so a range check on its own would + // let an empty or padded parameter through as a rating. + it('rejects anything that is not bare digits', () => { + for (const raw of ['', ' ', ' 3 ', '3.0', '+3', '-1', '1e1', 'four', 'null']) { + expect(preselectedRating(url(`?rating=${encodeURIComponent(raw)}`))).toBeNull(); + } + }); + + it('rejects values outside the scale', () => { + for (const raw of ['0', '6', '10', '99999']) { + expect(preselectedRating(url(`?rating=${raw}`))).toBeNull(); + } + }); + + // Repeated parameters are legal in a URL and searchParams.get returns the + // first. Worth pinning: a link-rewriter appending its own rating must not be + // able to change what the customer clicked into something else. + it('takes the first value when the parameter repeats', () => { + expect(preselectedRating(url('?rating=2&rating=5'))).toBe(2); + }); +}); diff --git a/frontend/src/routes/(no-layout)/csat/[token]/+page.server.js b/frontend/src/routes/(no-layout)/csat/[token]/+page.server.js index f3482011..e016eb02 100644 --- a/frontend/src/routes/(no-layout)/csat/[token]/+page.server.js +++ b/frontend/src/routes/(no-layout)/csat/[token]/+page.server.js @@ -9,10 +9,12 @@ import { fail } from '@sveltejs/kit'; import { env } from '$env/dynamic/public'; +import { preselectedRating } from '$lib/server/v2/csat.js'; + const API_BASE_URL = `${env.PUBLIC_DJANGO_API_URL}/api`; /** @type {import('./$types').PageServerLoad} */ -export async function load({ params, fetch }) { +export async function load({ params, fetch, url }) { const res = await fetch(`${API_BASE_URL}/public/csat/${params.token}/`); if (res.status === 410) { return { gone: true, token: params.token }; @@ -26,6 +28,10 @@ export async function load({ params, fetch }) { const data = await res.json(); return { token: params.token, + // The star clicked in the email, if any. Only meaningful on this branch: + // the gone/invalid/error states report themselves instead of offering the + // scale, so a rating would have nothing to pre-select. + clickedRating: preselectedRating(url), survey: { ticketSubject: data.case_subject, closedAt: data.case_closed_on, diff --git a/frontend/src/routes/(no-layout)/csat/[token]/+page.svelte b/frontend/src/routes/(no-layout)/csat/[token]/+page.svelte index 44d2fdd4..7d20034e 100644 --- a/frontend/src/routes/(no-layout)/csat/[token]/+page.svelte +++ b/frontend/src/routes/(no-layout)/csat/[token]/+page.svelte @@ -30,9 +30,12 @@ let survey = $derived(data.survey); - // Seeded once from the loader if the customer already answered within the - // edit window; after that it is theirs to change. - let rating = $state(untrack(() => data.survey?.rating ?? 0)); + // Seeded once from the loader; after that it is theirs to change. A rating + // already stored wins over the star clicked in the email: inside the edit + // window this page is reached by someone revisiting their own answer, and + // showing them the old email's star instead of what they submitted would + // read as the answer having been lost. + let rating = $state(untrack(() => data.survey?.rating ?? data.clickedRating ?? 0)); let comment = $state(untrack(() => data.survey?.comment ?? '')); let hover = $state(0); let submitting = $state(false);