[IMP] l10n_br_fiscal: operation/line docstring

Author: rvalyi

l10n_br_fiscal/models/operation.py

@@ -17,6 +17,54 @@
 
 
 class Operation(models.Model):
+    """
+    Defines a Fiscal Operation, representing the nature and fiscal intent of
+    a transaction (e.g., Sale, Return, Import, Industrialization).
+
+    A Fiscal Operation is a core configuration entity in the Brazilian
+    fiscal localization. It serves as a central point to orchestrate how
+    fiscal documents and their lines are processed by determining:
+
+    1.  **Transaction Type**: Specifies if the operation is an Inbound
+        (e.g., purchase, return from customer), Outbound (e.g., sale,
+        return to supplier), or Other type of fiscal movement.
+
+    2.  **Operation Lines (`line_ids`)**: Each Fiscal Operation contains
+        one or more `l10n_br_fiscal.operation.line` records. These lines
+        define specific rules or conditions (based on partner profiles,
+        product types, company tax regime, etc.) under which a
+        particular set of fiscal treatments apply. The system selects
+        the "best match" operation line based on the context of a
+        transaction.
+
+    3.  **CFOP (Código Fiscal de Operações e Prestações)**: The selected
+        `operation.line` determines the appropriate CFOP codes
+        (internal, external, export) for the transaction line. The CFOP
+        itself carries significant fiscal meaning and influences tax
+        calculations and reporting.
+
+    4.  **Tax Definitions (`tax_definition_ids` on `operation.line` and `cfop`)**:
+        The selected `operation.line` and the determined `cfop` can both
+        hold `l10n_br_fiscal.tax.definition` records. These tax
+        definitions specify which taxes (ICMS, IPI, PIS, COFINS, etc.)
+        apply, along with their respective CST/CSOSN codes and other
+        parameters. This linkage allows the Fiscal Operation to drive
+        the tax calculation engine.
+
+    5.  **Document Characteristics**: It can also define default behaviors
+        or properties for documents generated under this operation, such
+        as the electronic document purpose (`edoc_purpose`), default
+        price type (sale vs. cost), and links to inverse or return
+        operations.
+
+    Essentially, when a fiscal document is created, the user selects a
+    Fiscal Operation. The system then uses this operation and the
+    transactional context (partner, product, company) to find the most
+    suitable `operation.line`. This line, in turn, provides the CFOP
+    and a set of tax definitions, which are then used by the tax engine
+    to calculate all applicable taxes.
+    """
+
     _name = "l10n_br_fiscal.operation"
     _description = "Fiscal Operation"
     _inherit = ["mail.thread", "mail.activity.mixin"]

l10n_br_fiscal/models/operation_line.py

@@ -201,6 +201,52 @@ def map_fiscal_taxes(
         service_type=None,
         ind_final=None,
     ):
+        """
+        Map and determine the applicable fiscal taxes, CFOP, IPI guideline,
+        and ICMS tax benefit for a given context.
+
+        The method aggregates tax definitions from various sources, applying a
+        precedence order:
+        1. Company-level tax definitions.
+        2. NCM-defined taxes (IPI, II).
+        3. ICMS Regulation specific taxes.
+        4. Taxes defined directly on this fiscal operation line.
+        5. Taxes defined on the determined CFOP.
+        6. Taxes from the partner's fiscal profile.
+
+        It also filters taxes based on whether the product is subject to
+        ICMS or ISSQN.
+
+        :param company: The company record (res.company).
+        :param partner: The partner record (res.partner).
+        :param product: Optional product record (product.product).
+        :param fiscal_price: (Unused in direct logic; kept for signature
+            consistency for overrides/extensions)
+        :param fiscal_quantity: (Unused in direct logic; kept for signature
+            consistency for overrides/extensions)
+        :param ncm: Optional NCM record (l10n_br_fiscal.ncm);
+            defaults to product's NCM.
+        :param nbm: Optional NBM record (l10n_br_fiscal.nbm);
+            defaults to product's NBM.
+        :param nbs: Optional NBS record (l10n_br_fiscal.nbs);
+            defaults to product's NBS.
+        :param cest: Optional CEST record (l10n_br_fiscal.cest);
+            defaults to product's CEST.
+        :param city_taxation_code: Optional City Taxation Code record
+            (l10n_br_fiscal.city.taxation.code).
+        :param service_type: Optional Service Type record
+            (l10n_br_fiscal.service.type).
+        :param ind_final: (Passed to icms_regulation_id.map_tax; not directly
+            used for tax calculation here)
+        :return: A dictionary containing:
+            - 'taxes': A dictionary of applicable tax records
+              (l10n_br_fiscal.tax) keyed by their tax_domain.
+            - 'cfop': The determined CFOP record (l10n_br_fiscal.cfop).
+            - 'ipi_guideline': The determined IPI guideline record
+              (l10n_br_fiscal.tax.ipi.guideline).
+            - 'icms_tax_benefit_id': The determined ICMS tax benefit record
+              ID (l10n_br_fiscal.tax.definition) or False.
+        """
         mapping_result = {
             "taxes": {},
             "cfop": False,