"""SQLAlchemy ORM models for month-end closing sessions and their results.""" from __future__ import annotations import datetime as dt from sqlalchemy import ( Boolean, Column, Date, DateTime, Float, ForeignKey, Integer, String, Text, Index ) from sqlalchemy.orm import relationship from .database import Base def _now() -> dt.datetime: return dt.datetime.utcnow() class Session(Base): __tablename__ = "sessions" id = Column(Integer, primary_key=True) name = Column(String(255), nullable=False) reporting_month = Column(String(32)) # "2026-01" month_end_date = Column(Date) reporting_currency = Column(String(16), default="USD") clearing_lag_days = Column(Integer, default=2) rounding_tolerance = Column(Float, default=0.01) allowance_for_returns = Column(Float, default=0.0) manual_adjustment = Column(Float, default=0.0) manual_adjustment_note = Column(String(512), default="") # How the opening AR balance is established: zero (default) | carry_forward | manual opening_mode = Column(String(32), default="zero") opening_source_session_id = Column(Integer) status = Column(String(32), default="draft") # draft|processing|processed|error progress_stage = Column(String(255), default="") progress_pct = Column(Float, default=0.0) progress_rows_done = Column(Integer, default=0) progress_rows_total = Column(Integer, default=0) eta_seconds = Column(Integer, default=0) error = Column(Text, default="") created_at = Column(DateTime, default=_now) updated_at = Column(DateTime, default=_now, onupdate=_now) files = relationship("SessionFile", back_populates="session", cascade="all, delete-orphan") settlements = relationship("Settlement", back_populates="session", cascade="all, delete-orphan") exceptions = relationship("Exception_", back_populates="session", cascade="all, delete-orphan") fx_rates = relationship("FxRate", back_populates="session", cascade="all, delete-orphan") reserves = relationship("Reserve", back_populates="session", cascade="all, delete-orphan") class SessionFile(Base): __tablename__ = "session_files" id = Column(Integer, primary_key=True) session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False) filename = Column(String(512)) stored_path = Column(String(1024)) size_bytes = Column(Integer) sha256 = Column(String(64)) worksheets = Column(Text) # JSON list data_sheet = Column(String(255)) imported_rows = Column(Integer, default=0) min_date = Column(Date) max_date = Column(Date) currency = Column(String(16)) marketplace = Column(String(64)) status = Column(String(32), default="uploaded") # uploaded|parsed|invalid message = Column(Text, default="") session = relationship("Session", back_populates="files") class Settlement(Base): __tablename__ = "settlements" id = Column(Integer, primary_key=True) session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False) marketplace = Column(String(64)) account_type = Column(String(64)) settlement_id = Column(String(255)) order_total = Column(Float, default=0.0) transfer_total = Column(Float, default=0.0) transfer_amount = Column(Float) # boundary/received transfer amount if any transfer_date = Column(Date) transfer_received = Column(Boolean) row_count = Column(Integer, default=0) first_date = Column(Date) last_date = Column(Date) status = Column(String(32)) # paid|receivable session = relationship("Session", back_populates="settlements") Index("ix_settlement_session", Settlement.session_id, Settlement.marketplace, Settlement.account_type) class Transaction(Base): __tablename__ = "transactions" id = Column(Integer, primary_key=True) session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False) source_file = Column(String(512)) source_sheet = Column(String(255)) source_row = Column(Integer) marketplace = Column(String(64)) settlement_id = Column(String(255)) order_id = Column(String(255)) sku = Column(String(255)) txn_type = Column(String(255)) # original (possibly localized) type txn_type_en = Column(String(255)) # canonical English type account_type = Column(String(64)) posted_date = Column(Date) total = Column(Float, default=0.0) currency = Column(String(16), default="USD") settlement_status = Column(String(32)) # paid|receivable receivable_flag = Column(Boolean, default=False) storage_flag = Column(Boolean, default=False) # storage-fee detection drill-down Index("ix_txn_session", Transaction.session_id) class MappingRule(Base): """Admin-defined header alias: normalized source header -> canonical field. Lets Finance map new/renamed Amazon headers without code changes.""" __tablename__ = "mapping_rules" id = Column(Integer, primary_key=True) normalized_header = Column(String(255), unique=True, nullable=False) field = Column(String(128), nullable=False) created_at = Column(DateTime, default=_now) Index("ix_txn_settlement", Transaction.session_id, Transaction.settlement_id) Index("ix_txn_type", Transaction.session_id, Transaction.txn_type) Index("ix_txn_recv", Transaction.session_id, Transaction.receivable_flag) class Exception_(Base): __tablename__ = "exceptions" id = Column(Integer, primary_key=True) session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False) category = Column(String(128)) severity = Column(String(32)) # error|warning|info detail = Column(Text) source = Column(String(512), default="") session = relationship("Session", back_populates="exceptions") class FxRate(Base): __tablename__ = "fx_rates" id = Column(Integer, primary_key=True) session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False) marketplace = Column(String(64)) currency = Column(String(16), default="USD") rate = Column(Float, default=1.0) source = Column(String(64), default="manual") rate_date = Column(Date) session = relationship("Session", back_populates="fx_rates") class Reserve(Base): __tablename__ = "reserves" id = Column(Integer, primary_key=True) session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False) marketplace = Column(String(64)) account_type = Column(String(64)) amount = Column(Float, default=0.0) session = relationship("Session", back_populates="reserves") class ReceivableResultRow(Base): __tablename__ = "receivable_results" id = Column(Integer, primary_key=True) session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False) marketplace = Column(String(64)) account_type = Column(String(64)) # or "TOTAL" additional_sales = Column(Float, default=0.0) reserve = Column(Float, default=0.0) receivable_local = Column(Float, default=0.0) fx_rate = Column(Float, default=1.0) receivable_usd = Column(Float, default=0.0) currency = Column(String(16), default="USD") class ReconciliationRow(Base): __tablename__ = "reconciliation" id = Column(Integer, primary_key=True) session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False, unique=True) uploaded_total = Column(Float) receivable_orders = Column(Float) paid_orders = Column(Float) transfers_total = Column(Float) reserve_total = Column(Float) manual_adjustments = Column(Float) final_receivable_usd = Column(Float) identity_difference = Column(Float) status = Column(String(64)) notes = Column(Text, default="") # AR roll-forward components received_payouts = Column(Float, default=0.0) # Σ transfers received (negative) all_payouts = Column(Float, default=0.0) # Σ all transfers (negative) class FxRateDaily(Base): """Optional per-date FX override. Falls back to the marketplace's month rate.""" __tablename__ = "fx_rates_daily" id = Column(Integer, primary_key=True) session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False) marketplace = Column(String(64)) rate_date = Column(Date) rate = Column(Float, default=1.0) source = Column(String(64), default="manual") Index("ix_fx_daily", FxRateDaily.session_id, FxRateDaily.marketplace, FxRateDaily.rate_date) class MarketPayout(Base): """Per-marketplace disbursement totals for the AR roll-forward. Transfers are attributed to the OWNER of their tagged settlement, not the file they appear in — Amazon repeats account-level payouts across country reports (e.g. the Belgium chain's transfers sit inside the Germany file). """ __tablename__ = "market_payouts" id = Column(Integer, primary_key=True) session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False) marketplace = Column(String(64)) received_payouts = Column(Float, default=0.0) # negative all_payouts = Column(Float, default=0.0) # negative Index("ix_market_payout_session", MarketPayout.session_id, MarketPayout.marketplace) class OpeningBalance(Base): __tablename__ = "opening_balances" id = Column(Integer, primary_key=True) session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False) marketplace = Column(String(64)) amount = Column(Float, default=0.0) reason = Column(String(512), default="") source = Column(String(64), default="manual") # manual | carried_forward updated_at = Column(DateTime, default=_now, onupdate=_now) Index("ix_opening_session", OpeningBalance.session_id, OpeningBalance.marketplace) class FinanceControl(Base): """Finance's manual control-sheet amounts + sign-off, for the reconciliation section.""" __tablename__ = "finance_control" id = Column(Integer, primary_key=True) session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False, unique=True) gross_sales = Column(Float) refunds = Column(Float) net_revenue = Column(Float) disbursements = Column(Float) closing_receivable = Column(Float) tolerance = Column(Float, default=1.0) verified_by = Column(String(255), default="") verified_at = Column(DateTime) comment = Column(Text, default="") class JournalEntry(Base): __tablename__ = "journal_entries" id = Column(Integer, primary_key=True) session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False, unique=True) entry_no = Column(String(128), default="") data = Column(Text, default="") # JSON: periods + lines + receivable class ExportRecord(Base): __tablename__ = "exports" id = Column(Integer, primary_key=True) session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False) kind = Column(String(32), default="full") # full | summary path = Column(String(1024)) sha256 = Column(String(64)) size_bytes = Column(Integer) generated_at = Column(DateTime, default=_now)