Tafsil

Tafsil (تفصیل) is a common concept in Iranian accounting systems. In the standard Iranian accounting tree structure of accounts, first three layers of accounts are named گروه and کل and معین, respectively. Transactions and journal entry lines usually reference the third layer (معین) and the first two layers are only for grouping purposes. But when more detailed recording of events is needed, a forth layer may be used for some accounts. Each of these fourth layer accounts correspond to a Tafsil Target, which is usually a Party.

So when we want to have more granular recording of events in an account, we further "describe" or "detail" (literal meaning of tafsil) the account into sub-accounts, each representing the transactions of that parent account with a specific party or other entity. Then all transactions only happen on the child accounts and not the parent account, which then acts as a grouping layer. Note that having tafsil is defined for each level 3 account separately, so the overall tree of account may have mixed leaf nodes of depth 3 and 4.

Data Model

In data model, there are three fields to store tafsil related data: has_tafsil, tafsil_type, and tafsil_target_id. These are main examples for different types of accounts based on tafsil status:

has_tafsil	tafsil_type	tafsil_target_id	Description
None	None	None	Tafsil is unapplicable, for example for accounts of type کل and گروه in an standard accounting tree.
False	None	None	حساب تفصیل‌پذیر: This account does not have tafsil, a normal third layer account.
True	Party, etc.	None	حساب تفصیل‌پذیر: This account has tafsil of type Party and is a parent tafsil node. For each transacting party a child for this account must be created and used in the JournalEntryLine object.
None	Party, etc.	PartyID: int	حساب تفصیلی: This is a sub-account created for transaction of Party with id=PartyID related to the parent account.

Tafsil Types

Usually tafsil refers to a party, but sometimes it may be useful to detail an account by other types of object, like Product. Note that tafsil type is specific to each account with tafsil, so although each account may only has one specific tafsil type, different accounts can have different tafsil types. The enum used for representing tafsil types is TafsilType. For each tafsil type like TafsilType.PARTY, there is a target model that stores the objects referenced by that type, like Party. These referenced models are all an instance of TafsilTarget abstract model. The pair of tafsil_type and tafsil_target_id fields can be imagined as a GenericForeignKey to a TafsilTarget object.

Tafsil Object Reference

Tafsil is a common concept in creating entries, so in the API and UI, instead of referring to the target objects by the low level tafsil_target_id field, the tafsil object reference can be any of the following values.

• Number: The accounting number for Party/Product/… as an integer or string.

When referencing a Party object:

• Mobile: The value of the party's main mobile number can also be used as a reference to it. To distinguish this usage from normal numbers, the mobile must be passed as a dict like {"mobile": "09120000000"}.
• National Code: The value of the party's national code/ID can also be used as a reference to it. To distinguish this usage from normal numbers, the value must be passed as a dict like {"national_code": "0030000001"}.

Note that externally (in API, UI, etc.) we do not use the primary key of TafsilTarget models, and just use their number or other unique fields. The type of target object is determined by the context, usually the parent account.

This is an example of using different tafsil object reference types for creating a entry:

{
    "description": "Example entry",
    "lines": [
        {"account": "1001", "tafsil": 1, "debit_amount": 1, "description": "object with number=1"},
        {"account": "1002", "tafsil": "2", "debit_amount": 1, "description": "object with number=2"},
        {"account": "1003", "tafsil": {"mobile": "09120000000"}, "debit_amount": 1, "description": "object with mobile=09120000000"},
        {"account": "1004", "tafsil": {"national_code": "0030000001"}, "debit_amount": 1, "description": "object with national_code=0030000001"},
        …
    ]
}