Models
======

The ``transactions`` app contains the portfolio ledger: buy / sell /
deposit transactions, dividend-transaction records that bridge raw
dividends into per-transaction amounts, and per-transaction
attachments.

Exchange
--------

A trading venue -- "Binance", "Kraken", "Coinbase", etc. Referenced
from :class:`Transaction` (and from
:class:`richy.staking.models.Staking`) so positions can be filtered
by exchange.

.. autoclass:: richy.transactions.models.Exchange
   :show-inheritance:

Transaction
-----------

The core portfolio record. A ``Transaction`` is a single
buy / sell / deposit move on an :class:`~richy.core.models.Item`. It
tracks price, amount, fee, date, exchange, currency, and three flags
(``is_closing``, ``is_closed``, ``is_deposit``) that classify it
inside the parent / child chain the application uses to compute
profits, market values and dividends.

The ``parents`` self-referential many-to-many is the backbone of
transaction chaining: a closing sale links back to the buys it
closes; dividend-transactions link back to the deposits that earned
them.

.. autoclass:: richy.transactions.models.Transaction
   :show-inheritance:

.. automethod:: richy.transactions.models.Transaction.get_market_value
.. automethod:: richy.transactions.models.Transaction.get_value
.. automethod:: richy.transactions.models.Transaction.get_user_item
.. automethod:: richy.transactions.models.Transaction.delete

Three cached properties expose derived values:

* ``is_positive`` -- ``True`` when ``amount > 0`` (a buy / deposit).
* ``target_as_absolute_value`` -- the user-entered ``target`` resolved
  to an absolute price (handles both ``"123"`` and ``"5%"`` inputs).
* ``target_as_percents`` -- the user-entered ``target`` resolved to a
  percentage change from the transaction price.

Dividend transactions
---------------------

``ShareDividendTransaction`` and ``EtfDividendTransaction`` bridge
raw :class:`richy.shares.models.Dividend` /
:class:`richy.etfs.models.Dividend` records into per-user,
per-deposit payouts: each row says "this user, this dividend, this
many shares, this much money, paid against these transactions".
They share an abstract base.

BaseDividendTransaction
~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: richy.transactions.models.BaseDividendTransaction
   :show-inheritance:

ShareDividendTransaction
~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: richy.transactions.models.ShareDividendTransaction
   :show-inheritance:

EtfDividendTransaction
~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: richy.transactions.models.EtfDividendTransaction
   :show-inheritance:

Attachments
-----------

Per-transaction file attachments. Files live under
``MEDIA_ROOT/transactions/<transaction_pk>/``; deleting the
``Transaction`` row -- or the ``Attachment`` row directly -- removes
the file from disk via ``AttachmentMixin.delete``.

AttachmentMixin
~~~~~~~~~~~~~~~

Shared mixin used by :class:`Attachment` here and by
:class:`richy.staking.models.Attachment` -- ensures the on-disk file
is removed when the model row is deleted.

.. autoclass:: richy.transactions.models.AttachmentMixin
   :show-inheritance:

Attachment
~~~~~~~~~~

.. autoclass:: richy.transactions.models.Attachment
   :show-inheritance:

Managers and querysets
----------------------

``TransactionManager`` and ``TransactionQuerySet`` extend
:class:`~richy.core.models.UserRelatedManager` /
:class:`~richy.core.models.UserRelatedQuerySet` (see
:doc:`/modules/core/models`) with one additional filter:

* **positive_balance** -- restricts to transactions whose item
  currently has a positive aggregate balance
  (``SUM(amount) > 0``). Used to skip already-exhausted positions on
  the portfolio overview.

.. autoclass:: richy.transactions.models.TransactionQuerySet
   :show-inheritance:

.. autoclass:: richy.transactions.models.TransactionManager
   :show-inheritance: