From 81e572c8ab9a2e9e5f48ca7a81e433b7887ae436 Mon Sep 17 00:00:00 2001 From: Herculino Trotta Date: Sat, 10 Oct 2026 15:26:59 -0300 Subject: [PATCH 1/4] feat(simulator): add projected baseline calculation Per-currency monthly net changes from active, tracked accounts, plus the exchange rate for currencies with an exchange currency. --- app/apps/mini_tools/utils/simulator.py | 90 ++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 app/apps/mini_tools/utils/simulator.py diff --git a/app/apps/mini_tools/utils/simulator.py b/app/apps/mini_tools/utils/simulator.py new file mode 100644 index 00000000..ac569550 --- /dev/null +++ b/app/apps/mini_tools/utils/simulator.py @@ -0,0 +1,90 @@ +from decimal import Decimal + +from django.db.models import Case, DecimalField, F, Sum, Value, When +from django.db.models.functions import TruncMonth +from django.utils import timezone + +from apps.accounts.models import Account +from apps.currencies.models import Currency +from apps.currencies.utils.convert import convert +from apps.transactions.models import Transaction + + +def get_simulator_baseline(user): + """ + Build the projected baseline the simulator applies hypothetical entries on. + + For each currency, returns the projected net change (every transaction, + paid or not) of each month that has transactions, keyed by "YYYY-MM", so + the balance at the start of any month can be derived by summing every + month before it. Archived and untracked accounts are ignored. + + Currencies with an exchange currency also carry the rate used to show + their converted amounts. + """ + accounts = Account.objects.filter(is_archived=False).exclude( + id__in=user.untracked_accounts.values_list("id", flat=True) + ) + currencies = ( + Currency.objects.filter( + id__in=accounts.values_list("currency", flat=True), is_archived=False + ) + .select_related("exchange_currency") + .order_by("name") + ) + + monthly = {} + for row in ( + Transaction.objects.filter(account__in=accounts) + .annotate(month=TruncMonth("reference_date")) + .values("account__currency", "month") + .annotate( + total=Sum( + Case( + When(type=Transaction.Type.INCOME, then=F("amount")), + When(type=Transaction.Type.EXPENSE, then=-F("amount")), + default=Value(0), + output_field=DecimalField(), + ) + ) + ) + .order_by() + ): + monthly.setdefault(row["account__currency"], {})[ + row["month"].strftime("%Y-%m") + ] = float(row["total"] or 0) + + return { + "current_month": timezone.localdate(timezone.now()).strftime("%Y-%m"), + "currencies": [ + { + "id": currency.id, + "name": currency.name, + "code": currency.code, + "prefix": currency.prefix, + "suffix": currency.suffix, + "decimal_places": currency.decimal_places, + "monthly": monthly.get(currency.id, {}), + "exchange": _get_exchange(currency), + } + for currency in currencies + ], + } + + +def _get_exchange(currency): + if not currency.exchange_currency: + return None + + rate, prefix, suffix, decimal_places = convert( + Decimal("1"), currency, currency.exchange_currency + ) + if rate is None: + return None + + return { + "rate": float(rate), + "prefix": prefix, + "suffix": suffix, + "decimal_places": decimal_places, + } From bdf0cf8d4ce7be8302a5924f22d2c10bd84e912f Mon Sep 17 00:00:00 2001 From: Herculino Trotta Date: Sat, 10 Oct 2026 15:26:59 -0300 Subject: [PATCH 2/4] feat(simulator): add simulator tool page Hyperscript-driven page to simulate one-time, recurring and installment expenses or incomes over the projected balance. --- app/apps/mini_tools/urls.py | 5 + app/apps/mini_tools/views.py | 19 + app/templates/mini_tools/simulator.html | 479 ++++++++++++++++++++++++ 3 files changed, 503 insertions(+) create mode 100644 app/templates/mini_tools/simulator.html diff --git a/app/apps/mini_tools/urls.py b/app/apps/mini_tools/urls.py index e4740424..0166de22 100644 --- a/app/apps/mini_tools/urls.py +++ b/app/apps/mini_tools/urls.py @@ -8,6 +8,11 @@ urlpatterns = [ views.unit_price_calculator, name="unit_price_calculator", ), + path( + "tools/simulator/", + views.simulator, + name="simulator", + ), path( "tools/currency-converter/", views.currency_converter, diff --git a/app/apps/mini_tools/views.py b/app/apps/mini_tools/views.py index 2acd039d..359b1470 100644 --- a/app/apps/mini_tools/views.py +++ b/app/apps/mini_tools/views.py @@ -1,11 +1,14 @@ from django.contrib.auth.decorators import login_required from django.shortcuts import render +from django.utils import timezone +from apps.common.widgets.datepicker import AirMonthYearPickerInput from apps.common.widgets.decimal import convert_to_decimal from apps.currencies.models import Currency from apps.currencies.utils.convert import convert from apps.mini_tools.forms import CurrencyConverterForm from apps.mini_tools.utils.exchange_rate_map import get_currency_exchange_map +from apps.mini_tools.utils.simulator import get_simulator_baseline @login_required @@ -13,6 +16,22 @@ def unit_price_calculator(request): return render(request, "mini_tools/unit_price_calculator.html") +@login_required +def simulator(request): + start_month_input = AirMonthYearPickerInput( + clear_button=False, attrs={"class": "w-full sim-start"} + ).render("start_month", timezone.localdate(timezone.now()).replace(day=1)) + + return render( + request, + "mini_tools/simulator.html", + context={ + "baseline": get_simulator_baseline(request.user), + "start_month_input": start_month_input, + }, + ) + + @login_required def currency_converter(request): rate_map = get_currency_exchange_map() diff --git a/app/templates/mini_tools/simulator.html b/app/templates/mini_tools/simulator.html new file mode 100644 index 00000000..4912bb32 --- /dev/null +++ b/app/templates/mini_tools/simulator.html @@ -0,0 +1,479 @@ +{% extends "layouts/base.html" %} +{% load formats %} +{% load i18n %} + +{% block title %}{% translate 'Simulator' %}{% endblock %} + +{% block content %} + {% get_current_language as LANGUAGE_CODE %} + {{ baseline|json_script:"simulator-baseline" }} +
+
+
{% translate 'Simulator' %}
+
+

+ {% translate 'See how a one-time, recurring or installment expense or income would affect your projected balance in the coming months.' %} +

+ + {% if not baseline.currencies %} + + {% else %} +
+
+
+
+ {% translate 'Currency' %} + +
+
+ {% translate 'Months to simulate' %} + +
+
+
+
+ + + +
+ +
+ + +
+ +
+
+
+
{% translate 'Final balance without simulation' %}
+
+
+
+
+
+
{% translate 'Final balance with simulation' %}
+
+
+
+
+
+
{% translate 'Total impact' %}
+
+
+
+
+
+
{% translate 'Lowest balance with simulation' %}
+
+
+
+
+
+ +
+
+
+ +
+
+
+ +
+
+ + + + + + + + + + + +
{% translate 'Month' %}{% translate 'Projected change' %}{% translate 'Simulated change' %}{% translate 'Balance without simulation' %}{% translate 'Balance with simulation' %}
+
+
+

+ {% translate 'The simulation starts at the earliest starting month among your entries, or the current month if there are none. Balances include paid and unpaid transactions, and archived and untracked accounts are ignored. Converted amounts use the latest exchange rate.' %} +

+ {% endif %} + + +
+{% endblock %} From 916c401ce3735a6674c133926f8f822ef8c4a44a Mon Sep 17 00:00:00 2001 From: Herculino Trotta Date: Sat, 10 Oct 2026 15:26:59 -0300 Subject: [PATCH 3/4] feat(sidebar): add simulator to tools menu --- app/templates/includes/sidebar.html | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/app/templates/includes/sidebar.html b/app/templates/includes/sidebar.html index 5162a873..1edaf52b 100644 --- a/app/templates/includes/sidebar.html +++ b/app/templates/includes/sidebar.html @@ -132,6 +132,12 @@ active="currency_converter" icon="fa-solid fa-money-bill-transfer"> + + From 6e72594ec7455d18310b0bdb2d699ed5184d5da0 Mon Sep 17 00:00:00 2001 From: Herculino Trotta Date: Sat, 10 Oct 2026 15:26:59 -0300 Subject: [PATCH 4/4] test(simulator): cover baseline calculation and page --- app/apps/mini_tools/tests.py | 130 ++++++++++++++++++++++++++++++++++- 1 file changed, 128 insertions(+), 2 deletions(-) diff --git a/app/apps/mini_tools/tests.py b/app/apps/mini_tools/tests.py index 7ce503c2..e2227048 100644 --- a/app/apps/mini_tools/tests.py +++ b/app/apps/mini_tools/tests.py @@ -1,3 +1,129 @@ -from django.test import TestCase +from datetime import date +from decimal import Decimal +from unittest.mock import patch -# Create your tests here. +from django.contrib.auth import get_user_model +from django.test import TestCase, override_settings +from django.urls import reverse +from django.utils import timezone + +from apps.accounts.models import Account, AccountGroup +from apps.common.middleware.thread_local import delete_current_user, write_current_user +from apps.currencies.models import Currency, ExchangeRate +from apps.mini_tools.utils.simulator import get_simulator_baseline +from apps.transactions.models import Transaction + + +@override_settings( + STORAGES={ + "default": {"BACKEND": "django.core.files.storage.FileSystemStorage"}, + "staticfiles": { + "BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage" + }, + }, + WHITENOISE_AUTOREFRESH=True, +) +@patch( + "apps.mini_tools.utils.simulator.timezone.localdate", + return_value=date(2026, 3, 15), +) +class SimulatorTests(TestCase): + def setUp(self): + User = get_user_model() + self.user = User.objects.create_user( + email="testuser@test.com", password="testpass123" + ) + self.client.login(username="testuser@test.com", password="testpass123") + write_current_user(self.user) + + self.currency = Currency.objects.create( + code="USD", name="US Dollar", decimal_places=2, prefix="$ " + ) + group = AccountGroup.objects.create(name="Group") + self.account = Account.objects.create( + name="Checking", group=group, currency=self.currency + ) + + def tearDown(self): + delete_current_user() + + def _transaction(self, type, amount, reference_date, is_paid=True, account=None): + return Transaction.objects.create( + account=account or self.account, + type=type, + is_paid=is_paid, + date=reference_date, + reference_date=reference_date, + amount=Decimal(amount), + description="Test", + owner=self.user, + ) + + def _currency(self, baseline): + return next(c for c in baseline["currencies"] if c["id"] == self.currency.id) + + def test_baseline_monthly_projection(self, _): + self._transaction(Transaction.Type.INCOME, "1000", date(2026, 1, 1)) + self._transaction(Transaction.Type.EXPENSE, "200", date(2026, 2, 1), False) + self._transaction(Transaction.Type.INCOME, "500", date(2026, 3, 1), False) + self._transaction(Transaction.Type.EXPENSE, "50", date(2026, 3, 1)) + self._transaction(Transaction.Type.EXPENSE, "100", date(2031, 5, 1), False) + + baseline = get_simulator_baseline(self.user) + currency = self._currency(baseline) + + self.assertEqual(baseline["current_month"], "2026-03") + self.assertEqual( + currency["monthly"], + {"2026-01": 1000.0, "2026-02": -200.0, "2026-03": 450.0, "2031-05": -100.0}, + ) + self.assertIsNone(currency["exchange"]) + + def test_baseline_ignores_archived_and_untracked_accounts(self, _): + group = AccountGroup.objects.create(name="Other") + archived = Account.objects.create( + name="Old", group=group, currency=self.currency, is_archived=True + ) + untracked = Account.objects.create( + name="Hidden", group=group, currency=self.currency + ) + untracked.untracked_by.add(self.user) + + self._transaction(Transaction.Type.INCOME, "100", date(2026, 3, 1)) + self._transaction( + Transaction.Type.INCOME, "1000", date(2026, 3, 1), account=archived + ) + self._transaction( + Transaction.Type.INCOME, "1000", date(2026, 3, 1), account=untracked + ) + + currency = self._currency(get_simulator_baseline(self.user)) + + self.assertEqual(currency["monthly"], {"2026-03": 100.0}) + + def test_baseline_exchange_rate(self, _): + euro = Currency.objects.create( + code="EUR", name="Euro", decimal_places=2, suffix=" EUR" + ) + self.currency.exchange_currency = euro + self.currency.save() + ExchangeRate.objects.create( + from_currency=self.currency, + to_currency=euro, + rate=Decimal("0.5"), + date=timezone.now(), + ) + + currency = self._currency(get_simulator_baseline(self.user)) + + self.assertEqual( + currency["exchange"], + {"rate": 0.5, "prefix": "", "suffix": " EUR", "decimal_places": 2}, + ) + + def test_simulator_view_renders(self, _): + response = self.client.get(reverse("simulator")) + + self.assertEqual(response.status_code, 200) + self.assertContains(response, 'id="simulator-baseline"') + self.assertContains(response, "sim-start")