Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

25.4 KB
Raw Blame
"""The rendered invoice: one resolved document, two renderers.

The screen and the PDF must agree, forever. The way they do that here is
that neither of them decides anything: `build_document` resolves the
invoice, its snapshot and the workspace's identity into one plain
structure, and both renderers only lay it out. A field that appears on
the PDF but not on screen is a bug in one renderer, never a difference
of opinion about what the document says.

What is resolved, and in what order, is the whole subject:

  - **The snapshot wins.** It is what the document said when it was
    issued. A logo changed in September must not reach August's invoice,
    and a client renamed after the fact must not rename itself on a
    document they already hold.
  - **Live settings fill only what the snapshot never captured** — an
    invoice issued before a field existed, or a draft that has not been
    issued at all and therefore has no snapshot yet.

Nothing here is jurisdiction-specific. Whether the document reads as a
fiscal instrument or as a commercial request for payment is a matter of
what the workspace configured and what the reader's law says — the same
bytes serve a French auto-entrepreneur and a Brazilian MEI whose NFS-e
was issued at the prefeitura.
"""
from dataclasses import dataclass, field
from datetime import date as _date
from decimal import Decimal
from typing import Any, Optional

from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession

from app.fiscal.registry import TaxIdKind, format_for_display, spec_for
from app.models.invoice import Invoice, InvoiceSettings
from app.models.workspace import Workspace, WorkspaceTaxId

#: Labels a template may override. Anything not listed is not overridable,
#: which keeps a stray key in the jsonb from silently becoming UI.
#:
#: English is the fallback, not the default: `default_labels()` picks the
#: pack for the *issuer's* locale first. The document is written in the
#: sender's language, and a Brazilian shipping "Invoice / Bill to / Qty"
#: until they rename all eighteen by hand is a bad first run.
DEFAULT_LABELS: dict[str, str] = {
    "invoice": "Invoice",
    "billTo": "Bill to",
    "from": "From",
    "number": "Number",
    "issueDate": "Issue date",
    "dueDate": "Due date",
    "description": "Description",
    "quantity": "Qty",
    "unitPrice": "Unit price",
    "amount": "Amount",
    "subtotal": "Subtotal",
    "discount": "Discount",
    "tax": "Tax",
    "total": "Total",
    "paid": "Paid",
    "deducted": "Deductions",
    "balance": "Balance due",
    "statement": "Statement of account",
    "history": "Payments and deductions",
    "date": "Date",
    "payment": "Payment received",
    "withholdingTax": "Tax withheld",
    "gatewayFee": "Processing fee",
    "fxDifference": "Currency difference",
    "otherDeduction": "Other deduction",
    "paymentDetails": "Payment details",
    "notes": "Notes",
    "schedule": "Payment schedule",
}

#: Shipped label packs, by language. Deliberately few: this is the set
#: the product is actually sold in, and a half-translated document reads
#: worse than an English one. A locale with no pack falls back to
#: `DEFAULT_LABELS`, and every label stays individually overridable
#: afterwards regardless.
#:
#: These are *defaults for the sender*, never a translation for the
#: reader: the document keeps the words its issuer chose, whoever opens
#: it. That is why they are resolved once, at issuance, into the snapshot.
LABEL_PACKS: dict[str, dict[str, str]] = {
    "pt": {
        "invoice": "Fatura",
        "billTo": "Cliente",
        "from": "Emitente",
        "number": "Número",
        "issueDate": "Emissão",
        "dueDate": "Vencimento",
        "description": "Descrição",
        "quantity": "Qtd",
        "unitPrice": "Valor unit.",
        "amount": "Valor",
        "subtotal": "Subtotal",
        "discount": "Desconto",
        "tax": "Impostos",
        "total": "Total",
        "paid": "Recebido",
        "deducted": "Deduções",
        "balance": "Saldo devedor",
        "statement": "Extrato da fatura",
        "history": "Pagamentos e deduções",
        "date": "Data",
        "payment": "Pagamento recebido",
        "withholdingTax": "Imposto retido",
        "gatewayFee": "Taxa de processamento",
        "fxDifference": "Diferença de câmbio",
        "otherDeduction": "Outra dedução",
        "paymentDetails": "Dados para pagamento",
        "schedule": "Cronograma de pagamento",
        "notes": "Observações",
    },
    "es": {
        "invoice": "Factura",
        "billTo": "Cliente",
        "from": "Emisor",
        "number": "Número",
        "issueDate": "Emisión",
        "dueDate": "Vencimiento",
        "description": "Descripción",
        "quantity": "Cant.",
        "unitPrice": "Precio unit.",
        "amount": "Importe",
        "subtotal": "Subtotal",
        "discount": "Descuento",
        "tax": "Impuestos",
        "total": "Total",
        "paid": "Cobrado",
        "deducted": "Deducciones",
        "balance": "Saldo pendiente",
        "statement": "Estado de cuenta",
        "history": "Pagos y deducciones",
        "date": "Fecha",
        "payment": "Pago recibido",
        "withholdingTax": "Impuesto retenido",
        "gatewayFee": "Comisión de procesamiento",
        "fxDifference": "Diferencia de cambio",
        "otherDeduction": "Otra deducción",
        "paymentDetails": "Datos de pago",
        "schedule": "Calendario de pagos",
        "notes": "Notas",
    },
    "fr": {
        "invoice": "Facture",
        "billTo": "Client",
        "from": "Émetteur",
        "number": "Numéro",
        "issueDate": "Date d'émission",
        "dueDate": "Échéance",
        "description": "Désignation",
        "quantity": "Qté",
        "unitPrice": "Prix unit.",
        "amount": "Montant",
        "subtotal": "Sous-total",
        "discount": "Remise",
        "tax": "TVA",
        "total": "Total",
        "paid": "Réglé",
        "deducted": "Déductions",
        "balance": "Reste à payer",
        "statement": "Relevé de compte",
        "history": "Paiements et déductions",
        "date": "Date",
        "payment": "Paiement reçu",
        "withholdingTax": "Impôt retenu",
        "gatewayFee": "Frais de traitement",
        "fxDifference": "Écart de change",
        "otherDeduction": "Autre déduction",
        "paymentDetails": "Coordonnées de paiement",
        "schedule": "Échéancier",
        "notes": "Notes",
    },
    "de": {
        "invoice": "Rechnung",
        "billTo": "Rechnungsempfänger",
        "from": "Rechnungssteller",
        "number": "Nummer",
        "issueDate": "Rechnungsdatum",
        "dueDate": "Fällig am",
        "description": "Bezeichnung",
        "quantity": "Menge",
        "unitPrice": "Einzelpreis",
        "amount": "Betrag",
        "subtotal": "Zwischensumme",
        "discount": "Rabatt",
        "tax": "USt.",
        "total": "Gesamt",
        "paid": "Bezahlt",
        "deducted": "Abzüge",
        "balance": "Offener Betrag",
        "statement": "Kontoauszug",
        "history": "Zahlungen und Abzüge",
        "date": "Datum",
        "payment": "Zahlung erhalten",
        "withholdingTax": "Einbehaltene Steuer",
        "gatewayFee": "Bearbeitungsgebühr",
        "fxDifference": "Währungsdifferenz",
        "otherDeduction": "Sonstiger Abzug",
        "paymentDetails": "Zahlungsinformationen",
        "schedule": "Zahlungsplan",
        "notes": "Hinweise",
    },
    "it": {
        "invoice": "Fattura",
        "billTo": "Cliente",
        "from": "Emittente",
        "number": "Numero",
        "issueDate": "Data emissione",
        "dueDate": "Scadenza",
        "description": "Descrizione",
        "quantity": "Qtà",
        "unitPrice": "Prezzo unit.",
        "amount": "Importo",
        "subtotal": "Subtotale",
        "discount": "Sconto",
        "tax": "IVA",
        "total": "Totale",
        "paid": "Incassato",
        "deducted": "Trattenute",
        "balance": "Saldo dovuto",
        "statement": "Estratto conto",
        "history": "Pagamenti e trattenute",
        "date": "Data",
        "payment": "Pagamento ricevuto",
        "withholdingTax": "Ritenuta d'acconto",
        "gatewayFee": "Commissione di elaborazione",
        "fxDifference": "Differenza di cambio",
        "otherDeduction": "Altra trattenuta",
        "paymentDetails": "Dati per il pagamento",
        "schedule": "Scadenze di pagamento",
        "notes": "Note",
    },
}


def default_labels(locale: Optional[str]) -> dict[str, str]:
    """The label pack for the issuer's language, English if none ships.

    Keyed on the language subtag, so `pt-BR` and `pt-PT` share a pack —
    the two differ in vocabulary a translator would care about and not in
    the eighteen words on an invoice.
    """
    if not locale:
        return dict(DEFAULT_LABELS)
    language = locale.replace("_", "-").split("-")[0].lower()
    return dict(LABEL_PACKS.get(language, DEFAULT_LABELS))


#: The default when a workspace has picked no colour. Deliberately a
#: neutral ink rather than the product's own brand: the document belongs
#: to the sender, not to the tool that printed it.
DEFAULT_ACCENT = "#111827"


@dataclass
class DocumentParty:
    """One side of the document. Every field optional, because a workspace
    that has filled nothing in still gets a usable page."""

    name: Optional[str] = None
    legal_name: Optional[str] = None
    address: Optional[str] = None
    email: Optional[str] = None
    #: Rendered `(label, value)` pairs — already resolved through the
    #: fiscal pack, so no renderer needs to know what a CNPJ is.
    tax_ids: list[tuple[str, str]] = field(default_factory=list)


@dataclass
class DocumentLine:
    description: str
    quantity: Decimal
    unit_price: Decimal
    total: Decimal
    tax_rate: Optional[Decimal] = None
    #: Printed beside the quantity: "12 hours", not "12". Last and
    #: defaulted so the positional constructions already in the tests
    #: keep meaning what they meant.
    unit: Optional[str] = None


@dataclass(frozen=True)
class DocumentMovement:
    """One settlement on a statement: money that arrived, or an amount
    closed without it. The description is already in the document's
    language and says what kind it was, never the bank's own text."""

    day: _date
    description: str
    amount: Decimal


@dataclass(frozen=True)
class DocumentInstallment:
    label: Optional[str]
    due_date: _date
    amount: Decimal


@dataclass
class InvoiceDocument:
    """Everything a renderer needs, and nothing it has to look up."""

    number: Optional[str]
    status: str
    state: str
    issue_date: _date
    due_date: _date
    currency: str
    subtotal: Decimal
    discount: Decimal
    tax_total: Decimal
    total: Decimal
    amount_paid: Decimal
    #: Settled without money arriving: tax withheld, a fee kept. Shown
    #: so that total, paid and balance add up on the page.
    amount_deducted: Decimal
    balance: Decimal
    issuer: DocumentParty
    client: DocumentParty
    lines: list[DocumentLine]
    labels: dict[str, str]
    accent_color: str
    logo_id: Optional[str]
    payment_details: Optional[str]
    notes: Optional[str]
    footer_note: Optional[str]
    custom_fields: list[tuple[str, str]]
    #: True when the invoice carries enough to be worth rendering as a
    #: document at all. An amount with no lines is a perfectly good
    #: receivable and a poor-looking fatura, so the UI asks first.
    has_line_items: bool
    #: Which side of the ledger. On a payable the parties are already
    #: swapped below, so a renderer never has to know — but it is carried
    #: so a screen can say "received" instead of "issued", which is the
    #: difference between showing a document and claiming to have written
    #: one.
    direction: str = "receivable"
    #: The dates the money is expected on, when there is more than one.
    #: Rendered as a small table under the header so the client sees
    #: the same split they agreed to.
    installments: list[DocumentInstallment] = field(default_factory=list)
    #: Set on a statement of account: what settled the invoice, in date
    #: order. Empty on the invoice itself, which is the document as issued.
    movements: list[DocumentMovement] = field(default_factory=list)
    #: A statement of account rather than the invoice: titled as one, and
    #: always showing what is paid, deducted and left.
    statement: bool = False


def _label_map(
    template: Optional[dict[str, Any]], locale: Optional[str] = None
) -> dict[str, str]:
    """The issuer's language pack, overridden only by keys that exist.

    A template is free-form jsonb by design, so it can hold anything a
    hand edit put there; unknown keys are ignored rather than rendered.
    """
    labels = default_labels(locale)
    overrides = (template or {}).get("labels")
    if isinstance(overrides, dict):
        for key, value in overrides.items():
            if key in DEFAULT_LABELS and isinstance(value, str) and value.strip():
                labels[key] = value.strip()
    return labels


def _custom_field_pairs(
    template: Optional[dict[str, Any]], values: Optional[dict[str, Any]]
) -> list[tuple[str, str]]:
    """Only fields the workspace declared, in the order it declared them.

    Driven by the definitions rather than by the stored values, so a field
    removed from settings stops printing without anyone editing invoices.
    """
    defs = (template or {}).get("custom_fields")
    if not isinstance(defs, list) or not values:
        return []
    pairs: list[tuple[str, str]] = []
    for definition in defs:
        if not isinstance(definition, dict):
            continue
        key = definition.get("key")
        if not isinstance(key, str):
            continue
        value = values.get(key)
        if value in (None, ""):
            continue
        pairs.append((str(definition.get("label") or key), str(value)))
    return pairs


def _format_tax_id(kind_value: str, value: str) -> tuple[str, str]:
    """A document as a person reads it, resolved through the pack.

    An unrecognised kind still renders — a stored value must never become
    unprintable because a pack changed underneath it.
    """
    try:
        kind = TaxIdKind(kind_value)
    except ValueError:
        return kind_value.upper(), value
    spec = spec_for(kind)
    # `label_key` is an i18n key; its last segment is a usable fallback for
    # a server-rendered PDF, which has no translator.
    label = spec.label_key.rsplit(".", 1)[-1].upper()
    # Masked here rather than by the reader: this structure feeds a PDF as
    # well as a screen, and the PDF has nobody to ask.
    return label, format_for_display(kind, value)


async def build_document(
    session: AsyncSession,
    invoice: Invoice,
    settings: InvoiceSettings,
    workspace: Workspace,
) -> InvoiceDocument:
    from app.services import invoice_service

    snapshot = invoice.snapshot or {}
    snap_issuer = snapshot.get("issuer") or {}
    snap_client = snapshot.get("counterparty") or {}

    # Live settings are the fallback, never the override: an issued
    # document keeps what it captured.
    def issued_or_live(key: str, live: Any) -> Any:
        if snapshot and key in snap_issuer:
            return snap_issuer.get(key)
        return live

    # The issuer's documents, frozen like the rest of the issuer's
    # identity. Reading the live rows here was the one thing the snapshot
    # did not cover, so correcting a CNPJ next month silently rewrote the
    # CNPJ on an invoice a client received last month — the exact thing
    # freezing exists to prevent.
    #
    # Live rows still answer for a draft, and for a snapshot written
    # before this field existed, where the alternative is a document with
    # no tax id at all.
    snap_tax_ids = snap_issuer.get("tax_ids") if snapshot else None
    if snap_tax_ids is not None:
        issuer_tax_ids = [
            _format_tax_id(t["kind"], t["value"])
            for t in snap_tax_ids
            if isinstance(t, dict) and t.get("kind") and t.get("value")
        ]
    else:
        tax_rows = await session.execute(
            select(WorkspaceTaxId).where(WorkspaceTaxId.workspace_id == workspace.id)
        )
        issuer_tax_ids = [
            _format_tax_id(row.kind, row.value) for row in tax_rows.scalars().all()
        ]

    workspace_party = DocumentParty(
        name=issued_or_live("display_name", settings.issuer_display_name) or workspace.name,
        legal_name=issued_or_live("legal_name", workspace.legal_name),
        address=issued_or_live("address", workspace.address),
        tax_ids=issuer_tax_ids,
    )

    payee = invoice.payee
    counterparty = DocumentParty(
        name=snap_client.get("name") if snapshot else (payee.name if payee else None),
        address=snap_client.get("address") if snapshot else (payee.address if payee else None),
        email=snap_client.get("email") if snapshot else (payee.email if payee else None),
        tax_ids=[
            _format_tax_id(t["kind"], t["value"])
            for t in (snap_client.get("tax_ids") or [])
            if isinstance(t, dict) and t.get("kind") and t.get("value")
        ]
        if snapshot
        else [_format_tax_id(t.kind, t.value) for t in (payee.tax_ids if payee else [])],
    )

    # On a payable the supplier wrote the document and we received it, so
    # the blocks swap. Doing it once here rather than in each renderer is
    # what keeps the PDF and the screen from disagreeing about who is who
    # — and stops the product printing a supplier's bill under our own
    # name, which is the wrong claim to make on paper.
    payable = invoice.direction == "payable"
    issuer = counterparty if payable else workspace_party
    client = workspace_party if payable else counterparty

    template = snapshot.get("template") if snapshot else settings.template

    # An import arrives already named, and that name is reproduced
    # verbatim. Only a document we wrote takes our prefix: putting it on
    # someone else's reference would restyle their document into our
    # numbering.
    if invoice.origin == "imported":
        number = invoice.external_number or None
    elif invoice.number is not None:
        prefix = (snapshot.get("number_prefix") if snapshot else settings.number_prefix) or ""
        number = f"{prefix}{invoice.number}"
    else:
        number = None

    return InvoiceDocument(
        number=number,
        status=invoice.status,
        state=invoice_service.derive_state(invoice),
        issue_date=invoice.issue_date,
        due_date=invoice.due_date,
        installments=[
            DocumentInstallment(label=i.label, due_date=i.due_date, amount=i.amount)
            for i in invoice.installments
        ],
        currency=invoice.currency,
        subtotal=invoice.subtotal or Decimal("0"),
        discount=invoice.discount or Decimal("0"),
        tax_total=invoice.tax_total or Decimal("0"),
        total=invoice.total or Decimal("0"),
        amount_paid=invoice_service.allocated_total(invoice),
        amount_deducted=invoice_service.deducted_total(invoice),
        balance=invoice_service.balance(invoice),
        issuer=issuer,
        client=client,
        lines=[
            DocumentLine(
                description=line.description,
                quantity=line.quantity,
                unit=line.unit,

                unit_price=line.unit_price,
                total=line.total,
                tax_rate=line.tax_rate,
            )
            for line in invoice.lines
        ],
        # The workspace's own language, because the sender writes the
        # document. Once issued, the snapshot carries the resolved labels
        # and this is never consulted again — switching the interface to
        # English must not retitle a document already in a client's hands.
        labels=_label_map(template, snapshot.get("locale") if snapshot else workspace.locale),
        # Logo, accent, payment details and footer are the *issuer's*
        # identity, and on a payable the issuer is the supplier. Ours have
        # no business on their page: the logo would brand their document
        # with our mark, and payment details are worse than cosmetic —
        # printing our bank account under "pay to" on a bill we owe states
        # the opposite of what is true. We hold none of theirs, so the
        # blocks are simply left empty rather than filled with a stand-in.
        accent_color=(
            DEFAULT_ACCENT
            if payable
            else (issued_or_live("accent_color", settings.accent_color) or DEFAULT_ACCENT)
        ),
        # The id, not a URL: the two surfaces that draw this reach the
        # file by different routes — one authenticated, one behind a
        # share token — and neither should be hard-coded here.
        logo_id=(
            None
            if payable
            else (
                str(raw_logo)
                if (raw_logo := issued_or_live("logo_id", settings.logo_id))
                else None
            )
        ),
        payment_details=(
            None if payable else issued_or_live("payment_details", settings.payment_details)
        ),
        notes=invoice.notes,
        footer_note=None if payable else issued_or_live("footer_note", settings.footer_note),
        custom_fields=_custom_field_pairs(template, invoice.custom_fields),
        has_line_items=bool(invoice.lines),
        direction=invoice.direction,
    )


#: The document label for each deduction kind, so a statement names the
#: reason in the document's language.
_DEDUCTION_LABEL = {
    "withholding_tax": "withholdingTax",
    "gateway_fee": "gatewayFee",
    "fx_difference": "fxDifference",
    "other": "otherDeduction",
}


async def build_statement(
    session: AsyncSession,
    invoice: Invoice,
    settings: InvoiceSettings,
    workspace: Workspace,
) -> InvoiceDocument:
    """The invoice's statement of account: the document with what settled
    it since, and how that arrives at the balance.

    The invoice as issued stays what it was (see `invoice_archive`); this
    is the other document, the one that is supposed to change. Payments
    are named as payments, not by the bank's text, which is the
    workspace's own record and has no business on a page sent out. Notes
    on deductions stay off it for the same reason.
    """
    from dataclasses import replace

    document = await build_document(session, invoice, settings, workspace)
    labels = document.labels
    movements: list[DocumentMovement] = []
    for allocation in invoice.allocations:
        day = (
            allocation.transaction.date
            if allocation.transaction is not None
            else allocation.allocated_at.date()
        )
        movements.append(DocumentMovement(day, labels["payment"], allocation.amount))
    for deduction in invoice.deductions:
        description = labels[_DEDUCTION_LABEL.get(deduction.kind, "otherDeduction")]
        if deduction.tax_kind:
            description = f"{description} ({deduction.tax_kind.upper()})"
        movements.append(DocumentMovement(deduction.deducted_at.date(), description, deduction.amount))
    movements.sort(key=lambda m: m.day)
    return replace(document, movements=movements, statement=True)


def document_payload(document: InvoiceDocument) -> dict[str, Any]:
    """The document as JSON, for the on-screen renderer and the share page.

    Decimals become strings rather than floats: the frontend formats them
    with the workspace's locale, and a float would have already lost the
    cents by the time it got there.
    """
    return {
        "number": document.number,
        "status": document.status,
        "state": document.state,
        "issue_date": document.issue_date.isoformat(),
        "due_date": document.due_date.isoformat(),
        "currency": document.currency,
        "subtotal": str(document.subtotal),
        "discount": str(document.discount),
        "tax_total": str(document.tax_total),
        "total": str(document.total),
        "amount_paid": str(document.amount_paid),
        "amount_deducted": str(document.amount_deducted),
        "balance": str(document.balance),
        "issuer": {
            "name": document.issuer.name,
            "legal_name": document.issuer.legal_name,
            "address": document.issuer.address,
            "tax_ids": [{"label": k, "value": v} for k, v in document.issuer.tax_ids],
        },
        "client": {
            "name": document.client.name,
            "address": document.client.address,
            "email": document.client.email,
            "tax_ids": [{"label": k, "value": v} for k, v in document.client.tax_ids],
        },
        "lines": [
            {
                "description": line.description,
                "quantity": str(line.quantity),
                "unit": line.unit,
                "unit_price": str(line.unit_price),
                "total": str(line.total),
                "tax_rate": str(line.tax_rate) if line.tax_rate is not None else None,
            }
            for line in document.lines
        ],
        "labels": document.labels,
        "accent_color": document.accent_color,
        "logo_id": document.logo_id,
        "payment_details": document.payment_details,
        "notes": document.notes,
        "footer_note": document.footer_note,
        "custom_fields": [{"label": k, "value": v} for k, v in document.custom_fields],
        "has_line_items": document.has_line_items,
        "direction": document.direction,
        "installments": [
            {"label": i.label, "due_date": i.due_date.isoformat(), "amount": str(i.amount)}
            for i in document.installments
        ],
    }