mirror of
https://github.com/eitchtee/WYGIWYH.git
synced 2026-11-19 07:08:54 +01:00
Off unless MCP_ENABLED=true. Runs inside the web app (stateless Streamable HTTP, JSON responses), so no extra container or supervisord program. - Tools run the REST views in-process as the caller, so permissions, sharing, validation and transaction rules stay the API's. - 11 curated tools with compact output, plus search_api/call_api to reach every other API endpoint from the OpenAPI schema. - OAuth protected-resource metadata (RFC 9728) and a WWW-Authenticate hint on 401s, so MCP clients find the existing OAuth server and DCR. - GET /api/transactions/summary/: totals per currency and type, optionally grouped by category, tag, entity, account or month. API changes found while testing it: - Writes no longer need Django model permissions, which nothing granted; access now matches the web UI (signed-in user, scoped querysets, owner-only edits of shared objects). API tokens and OAuth apps can now write for regular users. - Account group owner is read-only; it could be set to another user. - Reject negative installment, recurring, DCA and exchange-rate amounts, a zero recurrence interval, and performance on non-investment accounts. - Accounts can be archived; group_id/exchange_currency_id are optional; category accepts null; currency prefix/suffix keep their spaces. - Transactions filter by tags and entities. - OpenAPI: separate request schemas (COMPONENT_SPLIT_REQUEST) and real descriptions for the viewsets and DCA chart actions.
278 lines
11 KiB
Python
278 lines
11 KiB
Python
from copy import deepcopy
|
|
|
|
from django.db.models import Count, Sum
|
|
from drf_spectacular.types import OpenApiTypes
|
|
from drf_spectacular.utils import OpenApiParameter, extend_schema, inline_serializer
|
|
from rest_framework import serializers, viewsets
|
|
from rest_framework.decorators import action
|
|
from rest_framework.exceptions import ValidationError
|
|
from rest_framework.response import Response
|
|
|
|
from apps.api.serializers import (
|
|
TransactionSerializer,
|
|
TransactionCategorySerializer,
|
|
TransactionTagSerializer,
|
|
InstallmentPlanSerializer,
|
|
TransactionEntitySerializer,
|
|
RecurringTransactionSerializer,
|
|
)
|
|
from apps.transactions.models import (
|
|
Transaction,
|
|
TransactionCategory,
|
|
TransactionTag,
|
|
InstallmentPlan,
|
|
TransactionEntity,
|
|
RecurringTransaction,
|
|
)
|
|
from apps.rules.signals import transaction_updated, transaction_created
|
|
from apps.api.permissions import SHARED_OBJECT_PERMISSIONS
|
|
|
|
# group_by -> (id field, name field)
|
|
SUMMARY_GROUPS = {
|
|
"category": ("category__id", "category__name"),
|
|
"tag": ("tags__id", "tags__name"),
|
|
"entity": ("entities__id", "entities__name"),
|
|
"account": ("account__id", "account__name"),
|
|
"month": (None, "reference_date"),
|
|
}
|
|
|
|
|
|
class TransactionViewSet(viewsets.ModelViewSet):
|
|
"""Income (`IN`) and expense (`EX`) entries. `amount` is never negative;
|
|
`type` gives the direction. `amount` is required unless `sub_transactions` is
|
|
sent; then it's their sum. `reference_date` is the month the transaction
|
|
counts toward, which may differ from `date`. Transfers are an expense and
|
|
an income linked through `linked_transaction`; deleting one deletes both."""
|
|
|
|
queryset = Transaction.objects.all()
|
|
serializer_class = TransactionSerializer
|
|
filterset_fields = {
|
|
"account": ["exact"],
|
|
"type": ["exact"],
|
|
"is_paid": ["exact"],
|
|
"date": ["exact", "gte", "lte", "gt", "lt"],
|
|
"reference_date": ["exact", "gte", "lte", "gt", "lt"],
|
|
"mute": ["exact"],
|
|
"amount": ["exact", "gte", "lte", "gt", "lt"],
|
|
"description": ["exact", "icontains"],
|
|
"notes": ["exact", "icontains"],
|
|
"category": ["exact", "isnull"],
|
|
"tags": ["exact"],
|
|
"entities": ["exact"],
|
|
"installment_plan": ["exact", "isnull"],
|
|
"installment_id": ["exact", "gte", "lte"],
|
|
"recurring_transaction": ["exact", "isnull"],
|
|
"internal_note": ["exact", "icontains"],
|
|
"internal_id": ["exact"],
|
|
"deleted": ["exact"],
|
|
"created_at": ["exact", "gte", "lte", "gt", "lt"],
|
|
"updated_at": ["exact", "gte", "lte", "gt", "lt"],
|
|
"deleted_at": ["exact", "gte", "lte", "gt", "lt", "isnull"],
|
|
"owner": ["exact"],
|
|
}
|
|
search_fields = ["description", "notes", "internal_note"]
|
|
ordering_fields = "__all__"
|
|
ordering = ["-id"]
|
|
|
|
def get_queryset(self):
|
|
return Transaction.objects.prefetch_related("sub_transactions")
|
|
|
|
def perform_create(self, serializer):
|
|
instance = serializer.save()
|
|
transaction_created.send(sender=instance)
|
|
|
|
def perform_update(self, serializer):
|
|
old_data = deepcopy(self.get_object())
|
|
instance = serializer.save()
|
|
transaction_updated.send(sender=instance, old_data=old_data)
|
|
|
|
def partial_update(self, request, *args, **kwargs):
|
|
kwargs["partial"] = True
|
|
return self.update(request, *args, **kwargs)
|
|
|
|
@extend_schema(
|
|
summary="Sum transactions",
|
|
description=(
|
|
"Totals and counts of the transactions matching the same filters as "
|
|
"the list, split by currency and type, optionally grouped. Muted "
|
|
"transactions and those in muted categories are left out unless "
|
|
"`include_muted` is true. Grouping by tag or entity counts a "
|
|
"transaction once per tag/entity; untagged ones have a null group."
|
|
),
|
|
parameters=[
|
|
OpenApiParameter("group_by", enum=list(SUMMARY_GROUPS)),
|
|
OpenApiParameter("include_muted", OpenApiTypes.BOOL),
|
|
],
|
|
responses=inline_serializer(
|
|
"TransactionSummaryRow",
|
|
{
|
|
"currency": serializers.CharField(),
|
|
"type": serializers.CharField(),
|
|
"group": serializers.CharField(allow_null=True, required=False),
|
|
"group_id": serializers.IntegerField(allow_null=True, required=False),
|
|
"total": serializers.DecimalField(max_digits=42, decimal_places=30),
|
|
"count": serializers.IntegerField(),
|
|
},
|
|
many=True,
|
|
),
|
|
)
|
|
@action(detail=False, methods=["get"], pagination_class=None)
|
|
def summary(self, request):
|
|
group_by = request.query_params.get("group_by")
|
|
if group_by and group_by not in SUMMARY_GROUPS:
|
|
raise ValidationError(
|
|
{"group_by": f"Must be one of: {', '.join(SUMMARY_GROUPS)}."}
|
|
)
|
|
|
|
queryset = self.filter_queryset(self.get_queryset())
|
|
if request.query_params.get("include_muted", "").lower() != "true":
|
|
queryset = queryset.exclude(mute=True).exclude(category__mute=True)
|
|
|
|
id_field, group_field = SUMMARY_GROUPS.get(group_by, (None, None))
|
|
fields = ["account__currency__code", "type"] + [
|
|
f for f in (id_field, group_field) if f
|
|
]
|
|
rows = (
|
|
queryset.order_by() # the default ordering would split the groups
|
|
.values(*fields)
|
|
.annotate(total=Sum("amount"), count=Count("id"))
|
|
# by group first, so months come out in order
|
|
.order_by(*[f for f in (group_field,) if f], "account__currency__code", "type")
|
|
)
|
|
|
|
data = []
|
|
for row in rows:
|
|
item = {
|
|
"currency": row["account__currency__code"],
|
|
"type": row["type"],
|
|
"total": row["total"],
|
|
"count": row["count"],
|
|
}
|
|
if group_field:
|
|
group = row[group_field]
|
|
item["group"] = group.strftime("%Y-%m") if group_by == "month" and group else group
|
|
if id_field:
|
|
item["group_id"] = row[id_field]
|
|
data.append(item)
|
|
return Response(data)
|
|
|
|
|
|
class TransactionCategoryViewSet(viewsets.ModelViewSet):
|
|
"""Categories, one per transaction. Transactions in a muted category are left out of totals. Sending a category name that doesn't exist on a transaction creates it."""
|
|
|
|
permission_classes = SHARED_OBJECT_PERMISSIONS
|
|
queryset = TransactionCategory.objects.all()
|
|
serializer_class = TransactionCategorySerializer
|
|
filterset_fields = {
|
|
"name": ["exact", "icontains"],
|
|
"mute": ["exact"],
|
|
"active": ["exact"],
|
|
"owner": ["exact"],
|
|
}
|
|
search_fields = ["name"]
|
|
ordering_fields = "__all__"
|
|
ordering = ["id"]
|
|
|
|
def get_queryset(self):
|
|
return TransactionCategory.objects.all()
|
|
|
|
|
|
class TransactionTagViewSet(viewsets.ModelViewSet):
|
|
"""Tags; a transaction can have many. Sending a tag name that doesn't exist on a transaction creates it."""
|
|
|
|
permission_classes = SHARED_OBJECT_PERMISSIONS
|
|
queryset = TransactionTag.objects.all()
|
|
serializer_class = TransactionTagSerializer
|
|
filterset_fields = {
|
|
"name": ["exact", "icontains"],
|
|
"active": ["exact"],
|
|
"owner": ["exact"],
|
|
}
|
|
search_fields = ["name"]
|
|
ordering_fields = "__all__"
|
|
ordering = ["id"]
|
|
|
|
def get_queryset(self):
|
|
return TransactionTag.objects.all()
|
|
|
|
|
|
class TransactionEntityViewSet(viewsets.ModelViewSet):
|
|
"""Entities are the people or businesses on the other side of a transaction. Sending an entity name that doesn't exist on a transaction creates it."""
|
|
|
|
permission_classes = SHARED_OBJECT_PERMISSIONS
|
|
queryset = TransactionEntity.objects.all()
|
|
serializer_class = TransactionEntitySerializer
|
|
filterset_fields = {
|
|
"name": ["exact", "icontains"],
|
|
"active": ["exact"],
|
|
"owner": ["exact"],
|
|
}
|
|
search_fields = ["name"]
|
|
ordering_fields = "__all__"
|
|
ordering = ["id"]
|
|
|
|
def get_queryset(self):
|
|
return TransactionEntity.objects.all()
|
|
|
|
|
|
class InstallmentPlanViewSet(viewsets.ModelViewSet):
|
|
"""A purchase split into a fixed number of installments. Saving a plan creates or updates one transaction per installment. `installment_amount` is required unless `sub_transactions` is sent; then it's their sum."""
|
|
|
|
queryset = InstallmentPlan.objects.all()
|
|
serializer_class = InstallmentPlanSerializer
|
|
filterset_fields = {
|
|
"account": ["exact"],
|
|
"type": ["exact"],
|
|
"description": ["exact", "icontains"],
|
|
"number_of_installments": ["exact", "gte", "lte", "gt", "lt"],
|
|
"installment_start": ["exact", "gte", "lte", "gt", "lt"],
|
|
"installment_total_number": ["exact", "gte", "lte", "gt", "lt"],
|
|
"start_date": ["exact", "gte", "lte", "gt", "lt"],
|
|
"reference_date": ["exact", "gte", "lte", "gt", "lt", "isnull"],
|
|
"end_date": ["exact", "gte", "lte", "gt", "lt", "isnull"],
|
|
"recurrence": ["exact"],
|
|
"installment_amount": ["exact", "gte", "lte", "gt", "lt"],
|
|
"category": ["exact", "isnull"],
|
|
"notes": ["exact", "icontains"],
|
|
"add_description_to_transaction": ["exact"],
|
|
"add_notes_to_transaction": ["exact"],
|
|
}
|
|
search_fields = ["description", "notes"]
|
|
ordering_fields = "__all__"
|
|
ordering = ["-id"]
|
|
|
|
def get_queryset(self):
|
|
return InstallmentPlan.objects.prefetch_related("sub_transactions")
|
|
|
|
|
|
class RecurringTransactionViewSet(viewsets.ModelViewSet):
|
|
"""A transaction or transfer that repeats on a schedule. Saving one generates its upcoming transactions and updates the unpaid ones. `amount` is required unless `sub_transactions` is sent; then it's their sum."""
|
|
|
|
queryset = RecurringTransaction.objects.all()
|
|
serializer_class = RecurringTransactionSerializer
|
|
filterset_fields = {
|
|
"is_paused": ["exact"],
|
|
"account": ["exact"],
|
|
"type": ["exact"],
|
|
"amount": ["exact", "gte", "lte", "gt", "lt"],
|
|
"description": ["exact", "icontains"],
|
|
"category": ["exact", "isnull"],
|
|
"notes": ["exact", "icontains"],
|
|
"reference_date": ["exact", "gte", "lte", "gt", "lt", "isnull"],
|
|
"start_date": ["exact", "gte", "lte", "gt", "lt"],
|
|
"end_date": ["exact", "gte", "lte", "gt", "lt", "isnull"],
|
|
"recurrence_type": ["exact"],
|
|
"recurrence_interval": ["exact", "gte", "lte", "gt", "lt"],
|
|
"keep_at_most": ["exact", "gte", "lte", "gt", "lt"],
|
|
"last_generated_date": ["exact", "gte", "lte", "gt", "lt", "isnull"],
|
|
"last_generated_reference_date": ["exact", "gte", "lte", "gt", "lt", "isnull"],
|
|
"add_description_to_transaction": ["exact"],
|
|
"add_notes_to_transaction": ["exact"],
|
|
}
|
|
search_fields = ["description", "notes"]
|
|
ordering_fields = "__all__"
|
|
ordering = ["-id"]
|
|
|
|
def get_queryset(self):
|
|
return RecurringTransaction.objects.prefetch_related("sub_transactions")
|