feat(api): read and write sub-transactions

Transactions, installment plans and recurring transactions take a nested
sub_transactions list; their amount becomes the parts' sum. Changing only
the amount of a split transaction, or adding parts to a transfer, is a
validation error.
This commit is contained in:
Herculino Trotta committed 2026-11-14 02:13:21 -03:00
1 parent ae245fb1d1
commit 5459865366
3 files changed
+206 -29

No files matched your search

+105 -26
View File
@@ -1,5 +1,6 @@
from decimal import Decimal
from django.db import transaction as db_transaction
from django.utils.translation import gettext_lazy as _
from drf_spectacular import openapi
from drf_spectacular.types import OpenApiTypes
@@ -22,10 +23,85 @@ from apps.transactions.models import (
InstallmentPlan,
TransactionEntity,
RecurringTransaction,
SubTransaction,
)
from apps.common.middleware.thread_local import get_current_user
class SubTransactionSerializer(serializers.ModelSerializer):
class Meta:
model = SubTransaction
fields = ["id", "name", "amount"]
read_only_fields = ["id"]
class SubTransactionsMixin:
"""`sub_transactions`, when sent, replaces the parts; a non-empty list sets
the amount to their sum. Declare the field on the serializer itself."""
sub_amount_field = "amount"
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.fields[self.sub_amount_field].required = False
def is_transfer(self, data):
return False
def validate(self, data):
field = self.sub_amount_field
subs = data.get("sub_transactions")
has_parts = self.instance is not None and self.instance.sub_transactions.exists()
if self.is_transfer(data):
if subs:
raise serializers.ValidationError(
{"sub_transactions": _("Transfers can't have sub-transactions.")}
)
if has_parts:
data["sub_transactions"] = []
elif subs:
data[field] = sum(sub["amount"] for sub in subs)
elif subs is None and field in data and has_parts:
raise serializers.ValidationError(
{
field: _(
"The amount is the sum of the sub-transactions; "
"send sub_transactions instead."
)
}
)
if not self.partial and data.get(field) is None:
raise serializers.ValidationError({field: _("This field is required.")})
return super().validate(data)
@staticmethod
def set_sub_transactions(instance, subs):
if subs is None:
return
instance.sub_transactions.all().delete()
for sub in subs:
instance.sub_transactions.create(**sub)
def create(self, validated_data):
subs = validated_data.pop("sub_transactions", None)
with db_transaction.atomic():
instance = super().create(validated_data)
self.set_sub_transactions(instance, subs)
self.after_save(instance, created=True)
return instance
def update(self, instance, validated_data):
subs = validated_data.pop("sub_transactions", None)
with db_transaction.atomic():
instance = super().update(instance, validated_data)
self.set_sub_transactions(instance, subs)
self.after_save(instance, created=False)
return instance
def after_save(self, instance, created):
"""Runs once the parts are saved, e.g. to generate transactions from them."""
class TransactionCategorySerializer(serializers.ModelSerializer):
permission_classes = [IsAuthenticated]
@@ -62,7 +138,9 @@ class TransactionEntitySerializer(serializers.ModelSerializer):
]
class InstallmentPlanSerializer(serializers.ModelSerializer):
class InstallmentPlanSerializer(SubTransactionsMixin, serializers.ModelSerializer):
sub_amount_field = "installment_amount"
sub_transactions = SubTransactionSerializer(many=True, required=False)
category: str | int = TransactionCategoryField(required=False)
tags: str | int = TransactionTagField(required=False)
entities: str | int = TransactionEntityField(required=False)
@@ -84,6 +162,7 @@ class InstallmentPlanSerializer(serializers.ModelSerializer):
"end_date",
"recurrence",
"installment_amount",
"sub_transactions",
"category",
"tags",
"entities",
@@ -91,18 +170,15 @@ class InstallmentPlanSerializer(serializers.ModelSerializer):
]
read_only_fields = ["installment_total_number", "end_date"]
def create(self, validated_data):
instance = super().create(validated_data)
instance.create_transactions()
return instance
def update(self, instance, validated_data):
instance = super().update(instance, validated_data)
instance.update_transactions()
return instance
def after_save(self, instance, created):
if created:
instance.create_transactions()
else:
instance.update_transactions()
class RecurringTransactionSerializer(serializers.ModelSerializer):
class RecurringTransactionSerializer(SubTransactionsMixin, serializers.ModelSerializer):
sub_transactions = SubTransactionSerializer(many=True, required=False)
category: str | int = TransactionCategoryField(required=False)
tags: str | int = TransactionTagField(required=False)
entities: str | int = TransactionEntityField(required=False)
@@ -115,6 +191,7 @@ class RecurringTransactionSerializer(serializers.ModelSerializer):
"account",
"type",
"amount",
"sub_transactions",
"to_account",
"to_amount",
"description",
@@ -142,19 +219,20 @@ class RecurringTransactionSerializer(serializers.ModelSerializer):
)
return super().validate(attrs)
def create(self, validated_data):
instance = super().create(validated_data)
instance.create_upcoming_transactions()
return instance
def is_transfer(self, data):
type_ = data.get("type", getattr(self.instance, "type", None))
return type_ == RecurringTransaction.Type.TRANSFER
def update(self, instance, validated_data):
instance = super().update(instance, validated_data)
instance.update_unpaid_transactions()
instance.generate_upcoming_transactions()
return instance
def after_save(self, instance, created):
if created:
instance.create_upcoming_transactions()
else:
instance.update_unpaid_transactions()
instance.generate_upcoming_transactions()
class TransactionSerializer(serializers.ModelSerializer):
class TransactionSerializer(SubTransactionsMixin, serializers.ModelSerializer):
sub_transactions = SubTransactionSerializer(many=True, required=False)
category: str | int = TransactionCategoryField(required=False)
tags: str | int = TransactionTagField(required=False)
entities: str | int = TransactionEntityField(required=False)
@@ -194,6 +272,9 @@ class TransactionSerializer(serializers.ModelSerializer):
self.fields["account_id"].queryset = Account.objects.all()
def is_transfer(self, data):
return bool(self.instance and self.instance.linked_transaction_id)
def validate(self, data):
if not self.partial:
if "date" in data and "reference_date" not in data:
@@ -204,12 +285,12 @@ class TransactionSerializer(serializers.ModelSerializer):
raise serializers.ValidationError(
_("Either 'date' or 'reference_date' must be provided.")
)
return data
return super().validate(data)
def create(self, validated_data):
tags = validated_data.pop("tags", [])
entities = validated_data.pop("entities", [])
transaction = Transaction.objects.create(**validated_data)
transaction = super().create(validated_data)
transaction.tags.set(tags)
transaction.entities.set(entities)
return transaction
@@ -217,9 +298,7 @@ class TransactionSerializer(serializers.ModelSerializer):
def update(self, instance, validated_data):
tags = validated_data.pop("tags", None)
entities = validated_data.pop("entities", None)
for attr, value in validated_data.items():
setattr(instance, attr, value)
instance.save()
instance = super().update(instance, validated_data)
if tags is not None:
instance.tags.set(tags)
+3 -3
View File
@@ -52,7 +52,7 @@ class TransactionViewSet(viewsets.ModelViewSet):
ordering = ["-id"]
def get_queryset(self):
return Transaction.objects.all()
return Transaction.objects.prefetch_related("sub_transactions")
def perform_create(self, serializer):
instance = serializer.save()
@@ -145,7 +145,7 @@ class InstallmentPlanViewSet(viewsets.ModelViewSet):
ordering = ["-id"]
def get_queryset(self):
return InstallmentPlan.objects.all()
return InstallmentPlan.objects.prefetch_related("sub_transactions")
class RecurringTransactionViewSet(viewsets.ModelViewSet):
@@ -175,4 +175,4 @@ class RecurringTransactionViewSet(viewsets.ModelViewSet):
ordering = ["-id"]
def get_queryset(self):
return RecurringTransaction.objects.all()
return RecurringTransaction.objects.prefetch_related("sub_transactions")
@@ -221,3 +221,101 @@ class SubTransactionTests(TestCase):
for transaction in plan.transactions.all():
self.assertEqual(transaction.amount, Decimal("100"))
self.assertEqual(len(self._parts(transaction)), 2)
class SubTransactionApiTests(TestCase):
def setUp(self):
user = get_user_model().objects.create_user(
email="api@test.com", password="pw", is_superuser=True
)
self.api = APIClient()
self.api.force_authenticate(user=user)
currency = Currency.objects.create(code="EUR", name="EUR", decimal_places=2)
self.account = Account.objects.create(name="A", currency=currency, owner=user)
def test_create_read_and_update_sub_transactions(self):
response = self.api.post(
"/api/transactions/",
{"account_id": self.account.id, "type": "EX", "date": "2030-01-10", "description": "Shop",
"sub_transactions": [{"name": "A", "amount": "1.50"}, {"name": "B", "amount": "2"}]},
format="json",
)
self.assertEqual(response.status_code, 201, response.data)
self.assertEqual(Decimal(response.data["amount"]), Decimal("3.50"))
self.assertEqual([s["name"] for s in response.data["sub_transactions"]], ["A", "B"])
url = f"/api/transactions/{response.data['id']}/"
# The amount can't drift from the parts
response = self.api.patch(url, {"amount": "9"}, format="json")
self.assertEqual(response.status_code, 400)
response = self.api.patch(url, {"sub_transactions": [{"name": "C", "amount": "4"}]}, format="json")
self.assertEqual(response.status_code, 200, response.data)
self.assertEqual(Decimal(response.data["amount"]), Decimal("4"))
self.assertEqual(self.api.get(url).data["sub_transactions"][0]["name"], "C")
def test_amount_required_without_sub_transactions(self):
response = self.api.post(
"/api/transactions/",
{"account_id": self.account.id, "type": "EX", "date": "2030-01-10"},
format="json",
)
self.assertEqual(response.status_code, 400)
self.assertIn("amount", response.data)
def _parts(self, owner):
return [(s.name, s.amount) for s in owner.sub_transactions.all()]
def test_installment_plan_parts_reach_every_installment(self):
response = self.api.post(
"/api/installment-plans/",
{"account": self.account.id, "type": "EX", "description": "Laptop",
"number_of_installments": 3, "start_date": "2030-01-10", "recurrence": "monthly",
"sub_transactions": [{"name": "Principal", "amount": "90"}, {"name": "Interest", "amount": "10"}]},
format="json",
)
self.assertEqual(response.status_code, 201, response.data)
self.assertEqual(Decimal(response.data["installment_amount"]), Decimal("100"))
plan = InstallmentPlan.all_objects.get()
installments = plan.transactions.all()
self.assertEqual(len(installments), 3)
for transaction in installments:
self.assertEqual(transaction.amount, Decimal("100"))
self.assertEqual(len(self._parts(transaction)), 2)
url = f"/api/installment-plans/{plan.id}/"
self.assertEqual(self.api.patch(url, {"installment_amount": "5"}, format="json").status_code, 400)
response = self.api.patch(url, {"sub_transactions": [{"name": "Principal", "amount": "80"}]}, format="json")
self.assertEqual(response.status_code, 200, response.data)
for transaction in plan.transactions.all():
self.assertEqual(self._parts(transaction), [("Principal", Decimal("80"))])
self.assertEqual(transaction.amount, Decimal("80"))
def test_recurring_parts_follow_its_transactions_and_transfers_drop_them(self):
response = self.api.post(
"/api/recurring-transactions/",
{"account": self.account.id, "type": "EX", "description": "Internet",
"start_date": timezone.localdate().isoformat(), "recurrence_type": "month", "recurrence_interval": 1,
"sub_transactions": [{"name": "Plan", "amount": "50"}, {"name": "Router", "amount": "10"}]},
format="json",
)
self.assertEqual(response.status_code, 201, response.data)
self.assertEqual(Decimal(response.data["amount"]), Decimal("60"))
self.assertEqual([s["name"] for s in response.data["sub_transactions"]], ["Plan", "Router"])
recurring = RecurringTransaction.all_objects.get()
generated = Transaction.all_objects.filter(recurring_transaction=recurring)
self.assertTrue(generated)
for transaction in generated:
self.assertEqual(transaction.amount, Decimal("60"))
self.assertEqual(len(self._parts(transaction)), 2)
other = Account.objects.create(name="B", currency=self.account.currency, owner=self.account.owner)
url = f"/api/recurring-transactions/{recurring.id}/"
self.assertEqual(
self.api.patch(url, {"type": "TR", "to_account": other.id,
"sub_transactions": [{"name": "X", "amount": "1"}]}, format="json").status_code,
400,
)
response = self.api.patch(url, {"type": "TR", "to_account": other.id}, format="json")
self.assertEqual(response.status_code, 200, response.data)
self.assertEqual(response.data["sub_transactions"], [])