lambda-erp 0.1.0__py3-none-any.whl

api/services.py

@@ -0,0 +1,372 @@
+"""Bridge between FastAPI request data and lambda_erp Document classes."""
+
+from lambda_erp.utils import _dict
+from lambda_erp.database import get_db
+
+from lambda_erp.selling.quotation import (
+    Quotation, make_sales_order,
+    make_sales_invoice_from_quotation, make_delivery_note_from_quotation,
+)
+from lambda_erp.selling.sales_order import SalesOrder, make_sales_invoice
+from lambda_erp.buying.purchase_order import PurchaseOrder, make_purchase_invoice
+from lambda_erp.accounting.sales_invoice import SalesInvoice, make_sales_return
+from lambda_erp.accounting.purchase_invoice import PurchaseInvoice, make_purchase_return
+from lambda_erp.accounting.payment_entry import PaymentEntry
+from lambda_erp.accounting.journal_entry import JournalEntry
+from lambda_erp.stock.stock_entry import StockEntry
+from lambda_erp.stock.delivery_note import DeliveryNote, make_delivery_note, make_delivery_return
+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.accounting.budget import Budget
+from lambda_erp.accounting.subscription import Subscription
+from lambda_erp.accounting.bank_transaction import BankTransaction
+
+
+# --- Doctype registries ---
+
+DOCUMENT_CLASSES = {
+    "Quotation": Quotation,
+    "Sales Order": SalesOrder,
+    "Sales Invoice": SalesInvoice,
+    "Purchase Order": PurchaseOrder,
+    "Purchase Invoice": PurchaseInvoice,
+    "Payment Entry": PaymentEntry,
+    "Journal Entry": JournalEntry,
+    "Stock Entry": StockEntry,
+    "Delivery Note": DeliveryNote,
+    "Purchase Receipt": PurchaseReceipt,
+    "POS Invoice": POSInvoice,
+    "Pricing Rule": PricingRule,
+    "Budget": Budget,
+    "Subscription": Subscription,
+    "Bank Transaction": BankTransaction,
+}
+
+CONVERTERS = {
+    ("Quotation", "Sales Order"): make_sales_order,
+    ("Quotation", "Sales Invoice"): make_sales_invoice_from_quotation,
+    ("Quotation", "Delivery Note"): make_delivery_note_from_quotation,
+    ("Sales Order", "Sales Invoice"): make_sales_invoice,
+    ("Sales Order", "Delivery Note"): make_delivery_note,
+    ("Purchase Order", "Purchase Invoice"): make_purchase_invoice,
+    ("Purchase Order", "Purchase Receipt"): make_purchase_receipt,
+    # Returns (same-to-same conversion creates a return document)
+    ("Sales Invoice", "Sales Invoice"): make_sales_return,
+    ("Purchase Invoice", "Purchase Invoice"): make_purchase_return,
+    ("Delivery Note", "Delivery Note"): make_delivery_return,
+    ("Purchase Receipt", "Purchase Receipt"): make_purchase_receipt_return,
+}
+
+MASTER_TABLES = {
+    "customer": ("Customer", "customer_name"),
+    "supplier": ("Supplier", "supplier_name"),
+    "item": ("Item", "item_name"),
+    "warehouse": ("Warehouse", "warehouse_name"),
+    "account": ("Account", "account_name"),
+    "company": ("Company", "company_name"),
+    "cost-center": ("Cost Center", "cost_center_name"),
+}
+
+# Slug <-> doctype name mapping
+SLUG_TO_DOCTYPE = {}
+DOCTYPE_TO_SLUG = {}
+for dt in DOCUMENT_CLASSES:
+    slug = dt.lower().replace(" ", "-")
+    SLUG_TO_DOCTYPE[slug] = dt
+    DOCTYPE_TO_SLUG[dt] = slug
+
+
+def register_doctype(doctype: str, cls, slug: str | None = None) -> None:
+    """Register (or override) the class used for a doctype.
+
+    Extension point for customer deployments (see
+    docs/core-extension-architecture.md): a plugin subclasses a core document
+    class and registers it here at startup, so every loader path
+    (create/load/update/submit/cancel_document) resolves the subclass.
+    `get_document_class` reads `DOCUMENT_CLASSES` live, so no other change is
+    needed.
+    """
+    DOCUMENT_CLASSES[doctype] = cls
+    slug = slug or doctype.lower().replace(" ", "-")
+    SLUG_TO_DOCTYPE[slug] = doctype
+    DOCTYPE_TO_SLUG[doctype] = slug
+
+
+def get_document_class(doctype_slug: str):
+    """Get document class from URL slug."""
+    doctype = SLUG_TO_DOCTYPE.get(doctype_slug)
+    if not doctype:
+        return None, None
+    return doctype, DOCUMENT_CLASSES[doctype]
+
+
+def create_document(doctype_slug: str, data: dict) -> dict:
+    doctype, cls = get_document_class(doctype_slug)
+    if not cls:
+        raise ValueError(f"Unknown document type: {doctype_slug}")
+    doc = cls(data)
+    doc.save()
+    return doc.as_dict()
+
+
+def load_document(doctype_slug: str, name: str) -> dict:
+    doctype, cls = get_document_class(doctype_slug)
+    if not cls:
+        raise ValueError(f"Unknown document type: {doctype_slug}")
+    doc = cls.load(name)
+    return doc.as_dict()
+
+
+def update_document(doctype_slug: str, name: str, data: dict) -> dict:
+    doctype, cls = get_document_class(doctype_slug)
+    if not cls:
+        raise ValueError(f"Unknown document type: {doctype_slug}")
+    doc = cls.load(name)
+    # Update parent fields
+    for key, value in data.items():
+        if key not in ("name", "docstatus", "creation") and key not in doc.CHILD_TABLES:
+            doc._data[key] = value
+    # Update child tables if provided
+    for table_name in doc.CHILD_TABLES:
+        if table_name in data:
+            doc._children[table_name] = []
+            for row in data[table_name]:
+                doc.append(table_name, _dict(row))
+    doc.save()
+    return doc.as_dict()
+
+
+def submit_document(doctype_slug: str, name: str) -> dict:
+    doctype, cls = get_document_class(doctype_slug)
+    if not cls:
+        raise ValueError(f"Unknown document type: {doctype_slug}")
+    doc = cls.load(name)
+    doc.submit()
+    return doc.as_dict()
+
+
+def cancel_document(doctype_slug: str, name: str) -> dict:
+    doctype, cls = get_document_class(doctype_slug)
+    if not cls:
+        raise ValueError(f"Unknown document type: {doctype_slug}")
+    doc = cls.load(name)
+    doc.cancel()
+    return doc.as_dict()
+
+
+def register_converter(source_doctype: str, target_doctype: str, fn) -> None:
+    """Register (or override) the converter for a (source, target) pair.
+
+    Extension point for customer deployments that need different conversion
+    logic (see docs/core-extension-architecture.md). To merely have the
+    converted document use an overridden class, you don't need this — register
+    the class with `register_doctype` and `convert_document` upgrades the
+    produced instance automatically.
+    """
+    CONVERTERS[(source_doctype, target_doctype)] = fn
+
+
+def convert_document(doctype_slug: str, name: str, target_doctype: str) -> dict:
+    source_doctype = SLUG_TO_DOCTYPE.get(doctype_slug)
+    if not source_doctype:
+        raise ValueError(f"Unknown document type: {doctype_slug}")
+
+    converter = CONVERTERS.get((source_doctype, target_doctype))
+    if not converter:
+        raise ValueError(f"Cannot convert {source_doctype} to {target_doctype}")
+
+    new_doc = converter(name)
+    # Honor a registered class override for the produced doctype. The core
+    # converter builds a base-class instance; if a plugin registered a subclass
+    # for the target, upgrade the instance in place so save()/on_submit() use
+    # the override. Safe because overrides are subclasses (same layout, no
+    # __slots__); guarded so a non-subclass registration is ignored.
+    override = DOCUMENT_CLASSES.get(target_doctype)
+    if override is not None and type(new_doc) is not override and issubclass(override, type(new_doc)):
+        new_doc.__class__ = override
+
+    new_doc.save()
+    return new_doc.as_dict()
+
+
+DATE_FIELDS = {
+    "Quotation": "transaction_date",
+    "Sales Order": "transaction_date",
+    "Purchase Order": "transaction_date",
+    "Sales Invoice": "posting_date",
+    "Purchase Invoice": "posting_date",
+    "Payment Entry": "posting_date",
+    "Journal Entry": "posting_date",
+    "Stock Entry": "posting_date",
+    "Delivery Note": "posting_date",
+    "Purchase Receipt": "posting_date",
+    "POS Invoice": "posting_date",
+    "Bank Transaction": "posting_date",
+}
+
+
+def list_documents(doctype_slug: str, filters: dict = None, limit: int = 50, offset: int = 0) -> list:
+    doctype = SLUG_TO_DOCTYPE.get(doctype_slug)
+    if not doctype:
+        raise ValueError(f"Unknown document type: {doctype_slug}")
+
+    db = get_db()
+    db_filters = {}
+    from_date = None
+    to_date = None
+    if filters:
+        for key, value in filters.items():
+            if value is None or value == "":
+                continue
+            if key == "from_date":
+                from_date = value
+            elif key == "to_date":
+                to_date = value
+            else:
+                db_filters[key] = value
+
+    # Date range filtering via the doctype's primary date field
+    date_field = DATE_FIELDS.get(doctype)
+    if date_field:
+        if from_date:
+            db_filters[date_field] = (">=", from_date)
+        if to_date:
+            # If we already set from_date, we need a second condition on the same field
+            if from_date:
+                # Use raw SQL fallback below
+                pass
+            else:
+                db_filters[date_field] = ("<=", to_date)
+
+    # If both from and to are set, the dict can only hold one constraint per key
+    # Fall through to a raw SQL query for that case
+    if date_field and from_date and to_date:
+        return _list_with_date_range(
+            db, doctype, doctype_slug, db_filters, date_field, from_date, to_date, limit, offset
+        )
+
+    # get_all doesn't support offset, so use raw SQL when needed
+    if offset:
+        return _list_with_offset(db, doctype, doctype_slug, db_filters, limit, offset)
+
+    rows = db.get_all(
+        doctype,
+        filters=db_filters if db_filters else None,
+        fields=["*"],
+        order_by="creation DESC",
+        limit=limit,
+    )
+
+    return _attach_children(db, doctype_slug, rows)
+
+
+def count_documents(doctype_slug: str, filters: dict = None) -> int:
+    """Count documents matching the filters (ignores limit/offset)."""
+    doctype = SLUG_TO_DOCTYPE.get(doctype_slug)
+    if not doctype:
+        raise ValueError(f"Unknown document type: {doctype_slug}")
+
+    db = get_db()
+    db_filters = {}
+    from_date = None
+    to_date = None
+    if filters:
+        for key, value in filters.items():
+            if value is None or value == "":
+                continue
+            if key == "from_date":
+                from_date = value
+            elif key == "to_date":
+                to_date = value
+            else:
+                db_filters[key] = value
+
+    date_field = DATE_FIELDS.get(doctype)
+    where_parts = []
+    params = []
+    if date_field and from_date:
+        where_parts.append(f'"{date_field}" >= ?')
+        params.append(from_date)
+    if date_field and to_date:
+        where_parts.append(f'"{date_field}" <= ?')
+        params.append(to_date)
+    for k, v in db_filters.items():
+        if isinstance(v, (list, tuple)) and len(v) == 2:
+            op, val = v
+            where_parts.append(f'"{k}" {op} ?')
+            params.append(val)
+        else:
+            where_parts.append(f'"{k}" = ?')
+            params.append(v)
+
+    query = f'SELECT COUNT(*) as c FROM "{doctype}"'
+    if where_parts:
+        query += " WHERE " + " AND ".join(where_parts)
+    rows = db.sql(query, params)
+    return int(rows[0]["c"]) if rows else 0
+
+
+def _list_with_offset(db, doctype, doctype_slug, db_filters, limit, offset):
+    where_parts = []
+    params = []
+    for k, v in db_filters.items():
+        if isinstance(v, (list, tuple)) and len(v) == 2:
+            op, val = v
+            where_parts.append(f'"{k}" {op} ?')
+            params.append(val)
+        else:
+            where_parts.append(f'"{k}" = ?')
+            params.append(v)
+    query = f'SELECT * FROM "{doctype}"'
+    if where_parts:
+        query += " WHERE " + " AND ".join(where_parts)
+    query += " ORDER BY creation DESC"
+    if limit:
+        query += f" LIMIT {int(limit)}"
+    if offset:
+        query += f" OFFSET {int(offset)}"
+    rows = db.sql(query, params)
+    return _attach_children(db, doctype_slug, rows)
+
+
+def _attach_children(db, doctype_slug: str, rows: list) -> list:
+    _, cls = get_document_class(doctype_slug)
+    result = []
+    for row in rows:
+        doc_dict = dict(row)
+        if cls and cls.CHILD_TABLES:
+            for table_name, (child_doctype, _) in cls.CHILD_TABLES.items():
+                children = db.get_all(
+                    child_doctype,
+                    filters={"parent": row["name"]},
+                    fields=["*"],
+                    order_by="idx",
+                )
+                doc_dict[table_name] = [dict(c) for c in children]
+        result.append(doc_dict)
+    return result
+
+
+def _list_with_date_range(db, doctype, doctype_slug, extra_filters, date_field, from_date, to_date, limit, offset=0):
+    """List documents when both from_date and to_date are set."""
+    where_parts = [f'"{date_field}" >= ?', f'"{date_field}" <= ?']
+    params = [from_date, to_date]
+    for k, v in extra_filters.items():
+        if isinstance(v, (list, tuple)) and len(v) == 2:
+            op, val = v
+            where_parts.append(f'"{k}" {op} ?')
+            params.append(val)
+        else:
+            where_parts.append(f'"{k}" = ?')
+            params.append(v)
+    query = (
+        f'SELECT * FROM "{doctype}" WHERE ' + " AND ".join(where_parts)
+        + " ORDER BY creation DESC"
+    )
+    if limit:
+        query += f" LIMIT {int(limit)}"
+    if offset:
+        query += f" OFFSET {int(offset)}"
+    rows = db.sql(query, params)
+    return _attach_children(db, doctype_slug, rows)

api/templates/document.html

@@ -0,0 +1,197 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>
+  @page { size: {{ page_size }}; margin: 20mm 15mm; }
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body { font-family: Helvetica, Arial, sans-serif; font-size: 9pt; color: #1a1a1a; line-height: 1.4; }
+
+  .header { display: flex; justify-content: space-between; margin-bottom: 20px; }
+  .company { font-size: 14pt; font-weight: bold; color: #2563eb; }
+  .doc-title { text-align: right; }
+  .doc-title h1 { font-size: 16pt; color: #1a1a1a; margin: 0; }
+  .doc-title .doc-name { font-size: 10pt; color: #666; }
+  .doc-title .doc-date { font-size: 9pt; color: #888; margin-top: 2px; }
+
+  .parties { display: flex; justify-content: space-between; margin-bottom: 20px; padding: 12px; background: #f8fafc; border-radius: 4px; }
+  .party-block h3 { font-size: 8pt; text-transform: uppercase; letter-spacing: 0.5px; color: #888; margin-bottom: 4px; }
+  .party-block .name { font-weight: bold; font-size: 10pt; }
+  .party-block .detail { font-size: 8pt; color: #555; }
+
+  .meta-row { display: flex; gap: 30px; margin-bottom: 15px; font-size: 8.5pt; }
+  .meta-item { }
+  .meta-item .label { color: #888; text-transform: uppercase; letter-spacing: 0.3px; font-size: 7pt; }
+  .meta-item .value { font-weight: 600; }
+
+  table.items { width: 100%; border-collapse: collapse; margin-bottom: 15px; }
+  table.items th { background: #f1f5f9; padding: 6px 8px; text-align: left; font-size: 8pt; font-weight: 600; color: #555; border-bottom: 2px solid #e2e8f0; }
+  table.items td { padding: 6px 8px; border-bottom: 1px solid #f1f5f9; }
+  table.items .num { text-align: right; }
+  table.items tfoot td { border-top: 2px solid #e2e8f0; font-weight: bold; }
+
+  .totals { margin-left: auto; width: 250px; margin-bottom: 20px; }
+  .totals table { width: 100%; }
+  .totals td { padding: 4px 0; font-size: 9pt; }
+  .totals td.label { color: #555; }
+  .totals td.amount { text-align: right; font-weight: 600; }
+  .totals .grand { font-size: 11pt; border-top: 2px solid #1a1a1a; padding-top: 6px; }
+
+  .taxes { margin-bottom: 10px; }
+  .taxes h3 { font-size: 8pt; color: #888; text-transform: uppercase; margin-bottom: 4px; }
+
+  .status-badge { display: inline-block; padding: 2px 10px; border-radius: 10px; font-size: 8pt; font-weight: bold; }
+  .status-submitted { background: #dbeafe; color: #1d4ed8; }
+  .status-cancelled { background: #fee2e2; color: #dc2626; }
+  .status-draft { background: #f3f4f6; color: #6b7280; }
+  .status-return { background: #fef3c7; color: #d97706; }
+
+  .footer { margin-top: 30px; padding-top: 10px; border-top: 1px solid #e5e7eb; font-size: 7.5pt; color: #999; text-align: center; }
+  .remarks { margin-top: 15px; padding: 8px; background: #fefce8; border-radius: 4px; font-size: 8pt; color: #713f12; }
+</style>
+</head>
+<body>
+
+{# ---- Header ---- #}
+<div class="header">
+  <div>
+    <div class="company">{{ company_name or doc.company or "" }}</div>
+  </div>
+  <div class="doc-title">
+    <h1>{{ title }}{% if doc.is_return %} <span class="status-badge status-return">RETURN</span>{% endif %}</h1>
+    <div class="doc-name">{{ doc.name }}</div>
+    <div class="doc-date">{{ doc.posting_date or doc.transaction_date or "" }}</div>
+  </div>
+</div>
+
+{# ---- Parties ---- #}
+<div class="parties">
+  <div class="party-block">
+    <h3>From</h3>
+    <div class="name">{{ company_name or doc.company or "" }}</div>
+    {% if company_info %}
+    {% if company_info.get("address") %}<div class="detail">{{ company_info.address }}</div>{% endif %}
+    {% if company_info.get("city") or company_info.get("zip_code") or company_info.get("country") %}<div class="detail">{{ company_info.get("city", "") }}{% if company_info.get("zip_code") %} {{ company_info.zip_code }}{% endif %}{% if company_info.get("country") %}, {{ company_info.country }}{% endif %}</div>{% endif %}
+    {% if company_info.get("email") %}<div class="detail">{{ company_info.email }}</div>{% endif %}
+    {% if company_info.get("phone") %}<div class="detail">{{ company_info.phone }}</div>{% endif %}
+    {% if company_info.get("tax_id") %}<div class="detail">Tax ID: {{ company_info.tax_id }}</div>{% endif %}
+    {% endif %}
+  </div>
+  <div class="party-block" style="text-align: right;">
+    <h3>{{ party_label }}</h3>
+    <div class="name">{{ party_name }}</div>
+    {% if party_info %}
+    {% if party_info.get("address") %}<div class="detail">{{ party_info.address }}</div>{% endif %}
+    {% if party_info.get("city") or party_info.get("zip_code") or party_info.get("country") %}<div class="detail">{{ party_info.get("city", "") }}{% if party_info.get("zip_code") %} {{ party_info.zip_code }}{% endif %}{% if party_info.get("country") %}, {{ party_info.country }}{% endif %}</div>{% endif %}
+    {% if party_info.get("email") %}<div class="detail">{{ party_info.email }}</div>{% endif %}
+    {% if party_info.get("phone") %}<div class="detail">{{ party_info.phone }}</div>{% endif %}
+    {% if party_info.get("tax_id") %}<div class="detail">Tax ID: {{ party_info.tax_id }}</div>{% endif %}
+    {% endif %}
+  </div>
+</div>
+
+{# ---- Meta fields ---- #}
+{% if meta_fields %}
+<div class="meta-row">
+  {% for m in meta_fields %}
+  <div class="meta-item">
+    <div class="label">{{ m.label }}</div>
+    <div class="value">{{ m.value }}</div>
+  </div>
+  {% endfor %}
+</div>
+{% endif %}
+
+{# ---- Items table ---- #}
+<table class="items">
+  <thead>
+    <tr>
+      <th style="width: 30px">#</th>
+      <th>Item</th>
+      <th>Description</th>
+      {% if show_warehouse %}<th>Warehouse</th>{% endif %}
+      <th class="num">Qty</th>
+      <th class="num">Rate</th>
+      <th class="num">Amount</th>
+    </tr>
+  </thead>
+  <tbody>
+    {% for item in items %}
+    <tr>
+      <td>{{ loop.index }}</td>
+      <td style="font-weight: 600">{{ item.item_code or "" }}</td>
+      <td>{{ item.item_name or item.description or "" }}</td>
+      {% if show_warehouse %}<td>{{ item.warehouse or "" }}</td>{% endif %}
+      <td class="num">{{ item.qty }}</td>
+      <td class="num">{{ "%.2f"|format(item.rate or 0) }}</td>
+      <td class="num">{{ "%.2f"|format(item.amount or item.net_amount or (item.qty or 0) * (item.rate or 0)) }}</td>
+    </tr>
+    {% endfor %}
+  </tbody>
+</table>
+
+{# ---- Taxes ---- #}
+{% if taxes %}
+<div class="taxes">
+  <h3>Taxes & Charges</h3>
+  <table class="items">
+    <thead>
+      <tr>
+        <th>Description</th>
+        <th class="num">Rate</th>
+        <th class="num">Amount</th>
+      </tr>
+    </thead>
+    <tbody>
+      {% for tax in taxes %}
+      <tr>
+        <td>{{ tax.description or tax.account_head or "" }}</td>
+        <td class="num">{{ "%.1f"|format(tax.rate or 0) }}%</td>
+        <td class="num">{{ "%.2f"|format(tax.tax_amount or 0) }}</td>
+      </tr>
+      {% endfor %}
+    </tbody>
+  </table>
+</div>
+{% endif %}
+
+{# ---- Totals ---- #}
+<div class="totals">
+  <table>
+    <tr>
+      <td class="label">Net Total</td>
+      <td class="amount">{{ currency }} {{ "%.2f"|format(doc.net_total or 0) }}</td>
+    </tr>
+    {% if doc.total_taxes_and_charges %}
+    <tr>
+      <td class="label">Tax</td>
+      <td class="amount">{{ currency }} {{ "%.2f"|format(doc.total_taxes_and_charges or 0) }}</td>
+    </tr>
+    {% endif %}
+    <tr class="grand">
+      <td class="label">Grand Total</td>
+      <td class="amount">{{ currency }} {{ "%.2f"|format(doc.grand_total or 0) }}</td>
+    </tr>
+    {% if doc.outstanding_amount is defined and doc.outstanding_amount is not none %}
+    <tr>
+      <td class="label">Outstanding</td>
+      <td class="amount">{{ currency }} {{ "%.2f"|format(doc.outstanding_amount or 0) }}</td>
+    </tr>
+    {% endif %}
+  </table>
+</div>
+
+{# ---- Remarks ---- #}
+{% if doc.remarks %}
+<div class="remarks">
+  <strong>Remarks:</strong> {{ doc.remarks }}
+</div>
+{% endif %}
+
+{# ---- Footer ---- #}
+<div class="footer">
+  {{ doc.name }} &middot; Generated from Lambda ERP
+</div>
+
+</body>
+</html>

lambda_erp/__init__.py

@@ -0,0 +1,3 @@
+"""Lambda ERP - Core ERP logic packaged as a standalone library."""
+
+__version__ = "0.1.0"

lambda_erp/accounting/bank_transaction.py

@@ -0,0 +1,76 @@
+"""
+Bank Transaction.
+
+Bank Transaction represents a single entry from a bank statement.
+It can be matched to Payment Entries or Invoices for reconciliation.
+When matched, it sets clearance_date on the referenced document.
+"""
+
+from lambda_erp.model import Document
+from lambda_erp.utils import _dict, flt, nowdate
+from lambda_erp.database import get_db
+from lambda_erp.exceptions import ValidationError
+
+class BankTransaction(Document):
+    DOCTYPE = "Bank Transaction"
+    CHILD_TABLES = {}
+    PREFIX = "BT"
+
+    def validate(self):
+        deposit = flt(self.deposit)
+        withdrawal = flt(self.withdrawal)
+        if not deposit and not withdrawal:
+            raise ValidationError("Either Deposit or Withdrawal amount is required")
+        if deposit and withdrawal:
+            raise ValidationError("Cannot have both Deposit and Withdrawal")
+
+        if not self.posting_date:
+            self._data["posting_date"] = nowdate()
+
+        self._calculate_unallocated()
+        self._set_status()
+
+    def _calculate_unallocated(self):
+        total = flt(self.deposit) or flt(self.withdrawal)
+        allocated = flt(self.allocated_amount)
+        self._data["unallocated_amount"] = flt(total - allocated, 2)
+
+    def _set_status(self):
+        unallocated = flt(self._data.get("unallocated_amount", 0))
+        total = flt(self.deposit) or flt(self.withdrawal)
+        if unallocated <= 0 and total > 0:
+            self._data["status"] = "Reconciled"
+        elif flt(self.allocated_amount) > 0:
+            self._data["status"] = "Partially Reconciled"
+        else:
+            self._data["status"] = "Unreconciled"
+
+def reconcile_bank_transaction(bank_transaction_name, reference_doctype, reference_name):
+    """Match a bank transaction to a payment entry or invoice.
+
+    Sets clearance_date on the referenced document and updates the
+    bank transaction's allocated amount and status.
+    """
+    db = get_db()
+
+    bt = BankTransaction.load(bank_transaction_name)
+    total = flt(bt.deposit) or flt(bt.withdrawal)
+    unallocated = flt(bt._data.get("unallocated_amount", total))
+
+    if unallocated <= 0:
+        raise ValidationError("Bank Transaction is already fully reconciled")
+
+    # Set reference on bank transaction
+    bt._data["reference_doctype"] = reference_doctype
+    bt._data["reference_name"] = reference_name
+    bt._data["allocated_amount"] = total
+    bt._calculate_unallocated()
+    bt._set_status()
+    bt._persist()
+
+    # Set clearance_date on the referenced document
+    if db.exists(reference_doctype, reference_name):
+        db.set_value(reference_doctype, reference_name, "clearance_date", bt.posting_date)
+        db.commit()
+
+    return bt.as_dict()