lambda-erp 1.0.2__tar.gz → 1.1.0__tar.gz

{lambda_erp-1.0.2 → lambda_erp-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lambda-erp
-Version: 1.0.2
+Version: 1.1.0
 Summary: Core ERP logic - accounting, sales, purchasing, inventory
 Author: TORUS INVESTMENTS AG
 License-Expression: Apache-2.0

{lambda_erp-1.0.2 → lambda_erp-1.1.0}/api/pdf_profiles.py

@@ -88,6 +88,12 @@ PROFILES.update({
         tables=(PDFTable('monthly_distribution', ('month', 'percentage'), ('month', 'percentage')),)),
     'Pricing Rule': PDFProfile('record', 'Pricing rule overview',
         fields=('title', 'company', 'item_code', 'selling', 'buying', 'rate_or_discount', 'rate', 'discount_percentage', 'discount_amount', 'min_qty', 'valid_from', 'valid_upto', 'priority', 'enabled'), required=('title', 'rate_or_discount')),
+    'Price List': PDFProfile('record', 'Price list overview',
+        fields=('price_list_name', 'currency', 'selling', 'buying', 'enabled'),
+        required=('price_list_name', 'currency')),
+    'Item Price': PDFProfile('record', 'Item price overview',
+        fields=('item_code', 'price_list', 'customer', 'supplier', 'uom', 'min_qty', 'rate', 'valid_from', 'valid_upto', 'enabled'),
+        required=('item_code', 'price_list', 'rate')),
     'Bank Account': PDFProfile('record', 'Bank account overview',
         fields=('account_name', 'company', 'account', 'iban', 'currency', 'bank_name', 'bic', 'disabled'), required=('account_name', 'company', 'account', 'iban', 'currency')),
     'Bank Transaction': PDFProfile('record', 'Bank transaction overview',

{lambda_erp-1.0.2 → lambda_erp-1.1.0}/api/routers/masters.py

@@ -67,6 +67,8 @@ DELETE_REFERENCE_CHECKS = {
         ('SELECT 1 FROM "POS Invoice" WHERE customer = ? LIMIT 1', "POS invoice"),
         ('SELECT 1 FROM "Payment Entry" WHERE party_type = \'Customer\' AND party = ? LIMIT 1', "payment entry"),
         ('SELECT 1 FROM "Subscription" WHERE party_type = \'Customer\' AND party = ? LIMIT 1', "subscription"),
+        ('SELECT 1 FROM "Item Price" WHERE customer = ? LIMIT 1', "item price"),
+        ('SELECT 1 FROM "Pricing Rule" WHERE customer = ? LIMIT 1', "pricing rule"),
     ],
     "supplier": [
         ('SELECT 1 FROM "Purchase Order" WHERE supplier = ? LIMIT 1', "purchase order"),
@@ -88,6 +90,7 @@ DELETE_REFERENCE_CHECKS = {
         ('SELECT 1 FROM "Stock Ledger Entry" WHERE item_code = ? LIMIT 1', "stock ledger entry"),
         ('SELECT 1 FROM "Bin" WHERE item_code = ? LIMIT 1', "bin"),
         ('SELECT 1 FROM "Pricing Rule" WHERE item_code = ? LIMIT 1', "pricing rule"),
+        ('SELECT 1 FROM "Item Price" WHERE item_code = ? LIMIT 1', "item price"),
         ('SELECT 1 FROM "Subscription Plan" WHERE item_code = ? LIMIT 1', "subscription plan"),
         ('SELECT 1 FROM "Asset" WHERE item_code = ? LIMIT 1', "asset"),
         ('SELECT 1 FROM "Reservation" WHERE item_code = ? LIMIT 1', "reservation"),
@@ -213,6 +216,8 @@ def _normalize_master_data(data: dict) -> dict:
 
 
 MASTER_LINK_FIELDS = {
+    'customer': {'default_price_list': 'Price List'},
+    'company': {'default_price_list': 'Price List'},
     'item': {'default_warehouse': 'Warehouse'},
     'warehouse': {'company': 'Company', 'account': 'Account', 'parent_warehouse': 'Warehouse'},
     'account': {'company': 'Company', 'parent_account': 'Account'},

{lambda_erp-1.0.2 → lambda_erp-1.1.0}/api/services.py

@@ -23,6 +23,7 @@ from lambda_erp.stock.delivery_note import DeliveryNote, make_delivery_note, mak
 from lambda_erp.stock.purchase_receipt import PurchaseReceipt, make_purchase_receipt, make_purchase_receipt_return
 from lambda_erp.accounting.pos_invoice import POSInvoice
 from lambda_erp.controllers.pricing_rule import PricingRule
+from lambda_erp.controllers.item_price import PriceList, ItemPrice
 from lambda_erp.accounting.budget import Budget
 from lambda_erp.accounting.subscription import Subscription
 from lambda_erp.accounting.bank_transaction import BankTransaction
@@ -47,6 +48,8 @@ DOCUMENT_CLASSES = {
     "Purchase Receipt": PurchaseReceipt,
     "POS Invoice": POSInvoice,
     "Pricing Rule": PricingRule,
+    "Price List": PriceList,
+    "Item Price": ItemPrice,
     "Budget": Budget,
     "Subscription": Subscription,
     "Bank Transaction": BankTransaction,

{lambda_erp-1.0.2 → lambda_erp-1.1.0}/lambda_erp/accounting/pos_invoice.py

@@ -13,7 +13,11 @@ from lambda_erp.model import Document
 from lambda_erp.utils import _dict, flt, nowdate
 from lambda_erp.database import get_db
 from lambda_erp.controllers.taxes_and_totals import calculate_taxes_and_totals
-from lambda_erp.controllers.defaults import set_default_currency
+from lambda_erp.controllers.defaults import (
+    set_default_currency, apply_external_source_defaults,
+    derived_pricing_fields, derived_line_pricing_fields,
+)
+from lambda_erp.controllers.item_price import set_item_defaults
 from lambda_erp.exceptions import ValidationError
 from lambda_erp.stock.stock_ledger import (
     make_sl_entries,
@@ -65,16 +69,44 @@ class POSInvoice(Document):
         if not self.posting_date:
             self.posting_date = nowdate()
 
+        apply_external_source_defaults(self)
         self._set_customer_name()
         self._set_missing_accounts()
+        set_default_currency(self, "Customer", "customer")
         self._set_item_defaults()
+        self._validate_external_source_stock()
         if self.is_return:
             self._validate_return()
-        set_default_currency(self, "Customer", "customer")
+        # POS was the only selling document that never applied pricing rules.
+        # Nothing about a till sale makes a discount inapplicable, so the same
+        # item rang up at a different price depending on which document the
+        # sale happened to be written to.
+        from lambda_erp.controllers.pricing_rule import apply_pricing_rules
+        apply_pricing_rules(self)
+
         calculate_taxes_and_totals(self)
         self._calculate_payments()
         self._set_status()
 
+    def _validate_external_source_stock(self):
+        """An upstream system's stock movement already accounts for the goods.
+
+        `_validate_no_double_shipment` catches the same mistake on the Sales
+        Order -> Delivery Note path by looking up `sales_order_item`. A document
+        created from an external system has no such link, so that lookup finds
+        nothing and passes. Without this guard the upstream issue and this
+        document's own update_stock each decrement the same quantity.
+        """
+        if not self._data.get("external_source"):
+            return
+        if flt(self.get("update_stock")):
+            raise ValidationError(
+                f"Cannot submit with update_stock=1: this document is sourced "
+                f"from {self._data['external_source']}, which already recorded "
+                f"the stock movement. Use this invoice as a bill only and "
+                f"record any required stock movement in a separate stock document."
+            )
+
     def _validate_return(self):
         from lambda_erp.workflow import validate_return
         validate_return(self)
@@ -100,18 +132,8 @@ class POSInvoice(Document):
                     item["cost_center"] = default_cc
 
     def _set_item_defaults(self):
-        db = get_db()
-        for item in self.get("items"):
-            if item.get("item_code") and not item.get("item_name"):
-                item_data = db.get_value(
-                    "Item", item["item_code"],
-                    ["item_name", "description", "stock_uom", "standard_rate"]
-                )
-                if item_data:
-                    item["item_name"] = item_data.item_name
-                    item["uom"] = item.get("uom") or item_data.stock_uom
-                    if item.get("rate") is None and item.get("price_list_rate") is None:
-                        item["rate"] = flt(item_data.standard_rate)
+        """Names, units and unsupplied rates. See controllers/item_price.py."""
+        set_item_defaults(self, "Customer", "customer", set_description=False)
 
     def _calculate_payments(self):
         paid = sum(flt(p.get("amount", 0)) for p in self.get("payments") or [])
@@ -197,16 +219,17 @@ class POSInvoice(Document):
             account = item.get("income_account")
             if not account:
                 continue
-            income_accounts[account] = income_accounts.get(account, 0) + flt(item.get("net_amount", 0))
+            key = (account, item.get("cost_center"))
+            income_accounts[key] = income_accounts.get(key, 0) + flt(item.get("net_amount", 0))
 
-        for account, amount in income_accounts.items():
+        for (account, cost_center), amount in income_accounts.items():
             gl_entries.append(_dict(
                 account=account,
                 credit=flt(amount, 2),
                 credit_in_account_currency=flt(amount, 2),
                 debit=0,
                 debit_in_account_currency=0,
-                cost_center=db.get_value("Company", self.company, "default_cost_center"),
+                cost_center=cost_center,
                 voucher_type=self.DOCTYPE,
                 voucher_no=self.name,
                 posting_date=self.posting_date,
@@ -288,6 +311,7 @@ def make_pos_return(posi_name):
         raise ValidationError("Cannot create a return against a return")
 
     return_pos = POSInvoice(
+        **derived_pricing_fields(original, is_return=True),
         customer=original.customer,
         company=original.company,
         currency=original.get("currency") or "USD",
@@ -302,6 +326,7 @@ def make_pos_return(posi_name):
     from lambda_erp.workflow import returnable_rows
     for item in returnable_rows(original):
         return_pos.append("items", _dict(
+            **derived_line_pricing_fields(item),
             item_code=item.get("item_code"),
             item_name=item.get("item_name"),
             description=item.get("description"),

{lambda_erp-1.0.2 → lambda_erp-1.1.0}/lambda_erp/accounting/purchase_invoice.py

@@ -14,7 +14,11 @@ from lambda_erp.model import Document
 from lambda_erp.utils import _dict, flt, nowdate, add_days
 from lambda_erp.database import get_db
 from lambda_erp.controllers.taxes_and_totals import calculate_taxes_and_totals
-from lambda_erp.controllers.defaults import set_default_currency
+from lambda_erp.controllers.defaults import (
+    set_default_currency, apply_external_source_defaults,
+    derived_pricing_fields, derived_line_pricing_fields,
+)
+from lambda_erp.controllers.item_price import set_item_defaults
 from lambda_erp.accounting.general_ledger import make_gl_entries, make_reverse_gl_entries, to_base_currency
 from lambda_erp.stock.stock_ledger import (
     make_sl_entries,
@@ -65,11 +69,14 @@ class PurchaseInvoice(Document):
         if not self.posting_date:
             self.posting_date = nowdate()
 
+        apply_external_source_defaults(self)
         self._set_supplier_name()
         self._set_missing_accounts()
+        set_default_currency(self, "Supplier", "supplier")
         self._set_item_defaults()
         self._validate_stock_warehouses()
         self._validate_no_double_receipt()
+        self._validate_external_source_stock()
 
         if self.is_return:
             self._validate_return()
@@ -77,7 +84,6 @@ class PurchaseInvoice(Document):
         from lambda_erp.controllers.pricing_rule import apply_pricing_rules
         apply_pricing_rules(self)
 
-        set_default_currency(self, "Supplier", "supplier")
 
         calculate_taxes_and_totals(self)
 
@@ -172,6 +178,25 @@ class PurchaseInvoice(Document):
                 f"is already allocated against it. Cancel the Payment Entry first."
             )
 
+    def _validate_external_source_stock(self):
+        """An upstream system's stock movement already accounts for the goods.
+
+        `_validate_no_double_shipment` catches the same mistake on the Sales
+        Order -> Delivery Note path by looking up `sales_order_item`. A document
+        created from an external system has no such link, so that lookup finds
+        nothing and passes. Without this guard the upstream issue and this
+        document's own update_stock each decrement the same quantity.
+        """
+        if not self._data.get("external_source"):
+            return
+        if flt(self.get("update_stock")):
+            raise ValidationError(
+                f"Cannot submit with update_stock=1: this document is sourced "
+                f"from {self._data['external_source']}, which already recorded "
+                f"the stock movement. Use this invoice as a bill only and "
+                f"record any required stock movement in a separate stock document."
+            )
+
     def _validate_no_double_receipt(self):
         """Block update_stock=1 when the referenced Purchase Order already has
         a Purchase Receipt for the line. Otherwise stock arrives twice: once
@@ -202,19 +227,8 @@ class PurchaseInvoice(Document):
                 )
 
     def _set_item_defaults(self):
-        db = get_db()
-        for item in self.get("items"):
-            if item.get("item_code") and not item.get("item_name"):
-                item_data = db.get_value(
-                    "Item", item["item_code"],
-                    ["item_name", "description", "stock_uom", "standard_rate"]
-                )
-                if item_data:
-                    item["item_name"] = item_data.item_name
-                    item["description"] = item.get("description") or item_data.description
-                    item["uom"] = item.get("uom") or item_data.stock_uom
-                    if item.get("rate") is None and item.get("price_list_rate") is None:
-                        item["rate"] = flt(item_data.standard_rate)
+        """Names, units and unsupplied rates. See controllers/item_price.py."""
+        set_item_defaults(self, "Supplier", "supplier")
 
     def _validate_return(self):
         from lambda_erp.workflow import validate_return
@@ -408,6 +422,7 @@ def make_purchase_return(pinv_name):
         raise ValidationError("Cannot create a return against a return")
 
     return_inv = PurchaseInvoice(
+        **derived_pricing_fields(original, is_return=True),
         supplier=original.supplier,
         company=original.company,
         currency=original.get("currency") or "USD",
@@ -425,6 +440,7 @@ def make_purchase_return(pinv_name):
     from lambda_erp.workflow import returnable_rows
     for item in returnable_rows(original):
         return_inv.append("items", _dict(
+            **derived_line_pricing_fields(item),
             item_code=item.get("item_code"),
             item_name=item.get("item_name"),
             description=item.get("description"),

{lambda_erp-1.0.2 → lambda_erp-1.1.0}/lambda_erp/accounting/sales_invoice.py

@@ -18,7 +18,11 @@ from lambda_erp.model import Document
 from lambda_erp.utils import _dict, flt, getdate, nowdate, add_days
 from lambda_erp.database import get_db
 from lambda_erp.controllers.taxes_and_totals import calculate_taxes_and_totals
-from lambda_erp.controllers.defaults import set_default_currency
+from lambda_erp.controllers.defaults import (
+    set_default_currency, apply_external_source_defaults,
+    derived_pricing_fields, derived_line_pricing_fields,
+)
+from lambda_erp.controllers.item_price import set_item_defaults
 from lambda_erp.accounting.general_ledger import make_gl_entries, make_reverse_gl_entries, to_base_currency
 from lambda_erp.stock.stock_ledger import (
     make_sl_entries,
@@ -81,10 +85,13 @@ class SalesInvoice(Document):
         if not self.posting_date:
             self.posting_date = nowdate()
 
+        apply_external_source_defaults(self)
         self._set_customer_name()
         self._set_missing_accounts()
+        set_default_currency(self, "Customer", "customer")
         self._set_item_defaults()
         self._validate_no_double_shipment()
+        self._validate_external_source_stock()
 
         if self.is_return:
             self._validate_return()
@@ -92,7 +99,6 @@ class SalesInvoice(Document):
         from lambda_erp.controllers.pricing_rule import apply_pricing_rules
         apply_pricing_rules(self)
 
-        set_default_currency(self, "Customer", "customer")
 
         calculate_taxes_and_totals(self)
 
@@ -133,19 +139,27 @@ class SalesInvoice(Document):
                     item["cost_center"] = default_cc
 
     def _set_item_defaults(self):
-        db = get_db()
-        for item in self.get("items"):
-            if item.get("item_code") and not item.get("item_name"):
-                item_data = db.get_value(
-                    "Item", item["item_code"],
-                    ["item_name", "description", "stock_uom", "standard_rate"]
-                )
-                if item_data:
-                    item["item_name"] = item_data.item_name
-                    item["description"] = item.get("description") or item_data.description
-                    item["uom"] = item.get("uom") or item_data.stock_uom
-                    if item.get("rate") is None and item.get("price_list_rate") is None:
-                        item["rate"] = flt(item_data.standard_rate)
+        """Names, units and unsupplied rates. See controllers/item_price.py."""
+        set_item_defaults(self, "Customer", "customer")
+
+    def _validate_external_source_stock(self):
+        """An upstream system's stock movement already accounts for the goods.
+
+        `_validate_no_double_shipment` catches the same mistake on the Sales
+        Order -> Delivery Note path by looking up `sales_order_item`. A document
+        created from an external system has no such link, so that lookup finds
+        nothing and passes. Without this guard the upstream issue and this
+        document's own update_stock each decrement the same quantity.
+        """
+        if not self._data.get("external_source"):
+            return
+        if flt(self.get("update_stock")):
+            raise ValidationError(
+                f"Cannot submit with update_stock=1: this document is sourced "
+                f"from {self._data['external_source']}, which already recorded "
+                f"the stock movement. Use this invoice as a bill only and "
+                f"record any required stock movement in a separate stock document."
+            )
 
     def _validate_no_double_shipment(self):
         """Block update_stock=1 when the referenced Sales Order already has a
@@ -338,15 +352,14 @@ class SalesInvoice(Document):
         )
 
         # 2. Credit: Income accounts (per item)
-        #    In the reference implementation, items with the same income_account are grouped
+        # Group only lines with the same account AND cost centre.
         income_accounts = {}
         for item in self.get("items"):
             account = item.get("income_account")
-            if account not in income_accounts:
-                income_accounts[account] = 0
-            income_accounts[account] += flt(item.get("net_amount", 0))
+            key = (account, item.get("cost_center"))
+            income_accounts[key] = income_accounts.get(key, 0) + flt(item.get("net_amount", 0))
 
-        for account, amount in income_accounts.items():
+        for (account, cost_center), amount in income_accounts.items():
             gl_entries.append(
                 _dict(
                     account=account,
@@ -354,7 +367,7 @@ class SalesInvoice(Document):
                     credit_in_account_currency=flt(amount, 2),
                     debit=0,
                     debit_in_account_currency=0,
-                    cost_center=self.get("items")[0].get("cost_center") if self.get("items") else None,
+                    cost_center=cost_center,
                     voucher_type=self.DOCTYPE,
                     voucher_no=self.name,
                     posting_date=self.posting_date,
@@ -373,7 +386,7 @@ class SalesInvoice(Document):
                         credit_in_account_currency=flt(tax["tax_amount"], 2),
                         debit=0,
                         debit_in_account_currency=0,
-                        cost_center=self.get("items")[0].get("cost_center") if self.get("items") else None,
+                        cost_center=get_db().get_value("Company", self.company, "default_cost_center"),
                         voucher_type=self.DOCTYPE,
                         voucher_no=self.name,
                         posting_date=self.posting_date,
@@ -404,6 +417,7 @@ def make_sales_return(sinv_name):
         raise ValidationError("Cannot create a return against a return")
 
     return_inv = SalesInvoice(
+        **derived_pricing_fields(original, is_return=True),
         customer=original.customer,
         company=original.company,
         currency=original.get("currency") or "USD",
@@ -421,6 +435,7 @@ def make_sales_return(sinv_name):
     from lambda_erp.workflow import returnable_rows
     for item in returnable_rows(original):
         return_inv.append("items", _dict(
+            **derived_line_pricing_fields(item),
             item_code=item.get("item_code"),
             item_name=item.get("item_name"),
             description=item.get("description"),

{lambda_erp-1.0.2 → lambda_erp-1.1.0}/lambda_erp/buying/purchase_order.py

@@ -14,7 +14,11 @@ from lambda_erp.model import Document
 from lambda_erp.utils import _dict, flt, getdate, nowdate
 from lambda_erp.database import get_db
 from lambda_erp.controllers.taxes_and_totals import calculate_taxes_and_totals
-from lambda_erp.controllers.defaults import set_default_currency
+from lambda_erp.controllers.defaults import (
+    set_default_currency, apply_external_source_defaults,
+    derived_pricing_fields, derived_line_pricing_fields,
+)
+from lambda_erp.controllers.item_price import set_item_defaults
 from lambda_erp.exceptions import ValidationError
 
 class PurchaseOrder(Document):
@@ -49,13 +53,14 @@ class PurchaseOrder(Document):
         if not self.transaction_date:
             self.transaction_date = nowdate()
 
+        apply_external_source_defaults(self)
         self._set_supplier_name()
+        set_default_currency(self, "Supplier", "supplier")
         self._set_item_defaults()
 
         from lambda_erp.controllers.pricing_rule import apply_pricing_rules
         apply_pricing_rules(self)
 
-        set_default_currency(self, "Supplier", "supplier")
 
         calculate_taxes_and_totals(self)
 
@@ -65,19 +70,8 @@ class PurchaseOrder(Document):
             self.supplier_name = db.get_value("Supplier", self.supplier, "supplier_name")
 
     def _set_item_defaults(self):
-        db = get_db()
-        for item in self.get("items"):
-            if item.get("item_code") and not item.get("item_name"):
-                item_data = db.get_value(
-                    "Item", item["item_code"],
-                    ["item_name", "description", "stock_uom", "standard_rate"]
-                )
-                if item_data:
-                    item["item_name"] = item_data.item_name
-                    item["description"] = item.get("description") or item_data.description
-                    item["uom"] = item.get("uom") or item_data.stock_uom
-                    if item.get("rate") is None and item.get("price_list_rate") is None:
-                        item["rate"] = flt(item_data.standard_rate)
+        """Names, units and unsupplied rates. See controllers/item_price.py."""
+        set_item_defaults(self, "Supplier", "supplier")
 
     def _update_ordered_qty(self, direction=1):
         from lambda_erp.workflow import refresh_order_progress
@@ -101,6 +95,7 @@ def make_purchase_invoice(purchase_order_name):
         raise ValidationError("Purchase Order must be submitted before creating Purchase Invoice")
 
     pi = PurchaseInvoice(
+        **derived_pricing_fields(po, is_return=False),
         supplier=po.supplier,
         supplier_name=po.supplier_name,
         company=po.company,
@@ -116,6 +111,7 @@ def make_purchase_invoice(purchase_order_name):
             continue
 
         pi.append("items", _dict(
+            **derived_line_pricing_fields(item),
             item_code=item.get("item_code"),
             item_name=item.get("item_name"),
             description=item.get("description"),

lambda_erp-1.1.0/lambda_erp/controllers/defaults.py

@@ -0,0 +1,114 @@
+"""Shared default-setting helpers for transactional documents."""
+
+from lambda_erp.database import get_db
+from lambda_erp.utils import flt
+from lambda_erp.exceptions import ValidationError
+from lambda_erp.controllers.currency import get_exchange_rate
+
+
+def set_default_company(doc):
+    """Set company to the first available company if not specified."""
+    if doc._data.get("company"):
+        return
+    db = get_db()
+    companies = db.get_all("Company", fields=["name"], limit=1)
+    if companies:
+        doc._data["company"] = companies[0]["name"]
+
+
+def set_default_currency(doc, party_type=None, party_field=None):
+    """Default a transaction's currency and conversion_rate for new entries.
+
+    Currency precedence: a value already on the doc -> the party's
+    default_currency -> the company's (base/functional) default_currency ->
+    "USD".
+
+    conversion_rate is forced to 1.0 whenever the document currency equals the
+    company's base currency. For a foreign currency the caller-supplied rate is
+    kept; if none was supplied it is looked up from the Currency Exchange table
+    for the document's date. A foreign currency with no rate on file raises
+    (via get_exchange_rate) rather than silently booking at 1.0.
+    """
+    db = get_db()
+    company = doc._data.get("company")
+    base_currency = db.get_value("Company", company, "default_currency") if company else None
+
+    currency = doc._data.get("currency")
+    if not currency:
+        if party_type and party_field:
+            party = doc._data.get(party_field)
+            if party:
+                currency = db.get_value(party_type, party, "default_currency")
+        currency = currency or base_currency or "USD"
+        doc._data["currency"] = currency
+
+    rate = flt(doc._data.get("conversion_rate"))
+    if base_currency and currency == base_currency:
+        rate = 1.0
+    elif rate <= 0:
+        # No rate supplied — look one up (carry-forward) for the doc's date.
+        doc_date = doc._data.get("posting_date") or doc._data.get("transaction_date")
+        rate = get_exchange_rate(currency, base_currency or "USD", doc_date)
+    doc._data["conversion_rate"] = rate
+
+
+def apply_external_source_defaults(doc):
+    """Safe defaults for a document owned by an upstream system.
+
+    `external_source` means another system already decided this document's
+    content: it computed the rates under its own contract, and if goods moved
+    it recorded that movement in its own ledger. So pricing rules are off by
+    default here — re-deriving a rate that was already agreed is how an
+    integration silently bills a different number than the source system shows.
+
+    An explicit `ignore_pricing_rule: 0` still wins, for the caller that wants
+    upstream identity but local pricing.
+    """
+    for field in ("external_source", "external_reference"):
+        value = doc.get(field)
+        if value is not None and (not isinstance(value, str) or not value.strip() or value != value.strip()):
+            raise ValidationError(f"{field} must be a nonblank string without surrounding whitespace")
+    if doc.get("external_reference") and not doc.get("external_source"):
+        raise ValidationError("external_reference requires external_source")
+    if doc._persisted:
+        stored = get_db().get_value(doc.DOCTYPE, doc.name, ["external_source", "external_reference"])
+        for field in ("external_source", "external_reference"):
+            if stored and stored.get(field) and stored[field] != doc.get(field):
+                raise ValidationError(f"Cannot change {field} after it has been assigned")
+    seen = set()
+    for item in doc.get("items") or []:
+        ref = item.get("external_line_reference")
+        if ref is None:
+            continue
+        if not isinstance(ref, str) or not ref.strip() or ref != ref.strip():
+            raise ValidationError("external_line_reference must be a nonblank string without surrounding whitespace")
+        if ref in seen:
+            raise ValidationError("Duplicate external_line_reference in this document")
+        seen.add(ref)
+    if not doc._data.get("external_source"):
+        return
+    if doc._data.get("ignore_pricing_rule") is None:
+        doc._data["ignore_pricing_rule"] = 1
+    if doc.DOCTYPE in {"Sales Invoice", "Purchase Invoice", "POS Invoice"} and doc.get("update_stock") is None:
+        # POS's database default is 1. Persist the bill-only policy explicitly
+        # so loading or returning this document cannot enable stock movement.
+        doc._data["update_stock"] = 0
+
+
+def derived_pricing_fields(source, *, is_return=False):
+    """Carry price/stock policy, but never reuse an imported document identity.
+
+    Partial invoices and credits are new documents. Their connector must assign
+    a new external_reference; external_source alone retains the stock guard.
+    Returns reverse historical prices, regardless of today's pricing rules.
+    """
+    return {
+        "ignore_pricing_rule": 1 if is_return else source.get("ignore_pricing_rule"),
+        "external_source": source.get("external_source"),
+    }
+
+
+def derived_line_pricing_fields(item):
+    return {field: item.get(field) for field in (
+        "ignore_pricing_rule", "external_line_reference", "pricing_rule",
+    )}