from __future__ import annotations from datetime import date import math import re from typing import Any import sqlite3 from .shared import db, fail, new_id, normalize_date, now_iso, ok, row_to_dict _VALID_STATUSES = {"verified", "unverified", "rejected"} _VALID_LOAN_DEFINITIONS = {"principal_only", "principal_interest_fees"} _VALID_CURRENCIES = {"KRW", "USD", "EUR", "JPY", "CNY", "GBP"} _VALID_KINDS = {"balance", "cash_balance", "total_value", "loan", "loan_balance"} _VALID_SOURCE_TYPES = {"manual", "import", "account_write", "reconciliation", "snapshot"} _COLUMNS = ( "amount", "currency", "valuation_kind", "source_type", "source_ref", "verification_status", "memo", "as_of_at", "timezone", "cost_basis", "net_contributed", "reported_principal_kind", "reported_principal_label", "profit", "return_rate", "return_basis", "principal", "interest", "fee", "representative_liability_definition", ) def _valuation(row: Any) -> dict[str, Any]: return row_to_dict(row) def _public_candidate(row: Any) -> dict[str, Any]: return {k: row[k] for k in ("id", "basis_date", "currency", "valuation_kind", "verification_status")} def _strict_int(value: Any, field: str, allow_none: bool = True) -> int | None: if value is None and allow_none: return None if isinstance(value, bool): raise ValueError(f"{field} must be an integer") if isinstance(value, int): return value if isinstance(value, str) and re.fullmatch(r"[+-]?\d+", value.strip()): return int(value.strip()) raise ValueError(f"{field} must be an integer") def _strict_float(value: Any, field: str) -> float | None: if value is None: return None if isinstance(value, bool): raise ValueError(f"{field} must be a finite number") try: result = float(value) except (TypeError, ValueError) as exc: raise ValueError(f"{field} must be a finite number") from exc if not math.isfinite(result): raise ValueError(f"{field} must be a finite number") return result def _validate_common(account_id: str, basis_date: str, amount: int, currency: str, verification_status: str, valuation_kind: str, source_type: str, representative_liability_definition: str | None) -> tuple[str, int, str, str, str, str | None] | dict[str, Any]: if not isinstance(account_id, str) or not account_id.strip(): return fail("validation_error", "account_id must be non-empty") try: basis = normalize_date(basis_date) amount_int = _strict_int(amount, "amount", allow_none=False) except Exception as exc: return fail("validation_error", str(exc)) currency_norm = (currency or "KRW").strip().upper() if currency_norm not in _VALID_CURRENCIES: return fail("validation_error", f"currency must be one of {sorted(_VALID_CURRENCIES)}") status = (verification_status or "unverified").strip().lower() if status not in _VALID_STATUSES: return fail("validation_error", "verification_status must be verified, unverified, or rejected") if not isinstance(valuation_kind, str): return fail("validation_error", "valuation_kind must be a string") kind = valuation_kind.strip().lower() or "balance" if kind not in _VALID_KINDS: return fail("validation_error", f"valuation_kind must be one of {sorted(_VALID_KINDS)}") source = (source_type or "manual").strip().lower() or "manual" if source not in _VALID_SOURCE_TYPES: return fail("validation_error", f"source_type must be one of {sorted(_VALID_SOURCE_TYPES)}") definition = representative_liability_definition.strip() if representative_liability_definition else None if kind in {"loan", "loan_balance"} and definition not in _VALID_LOAN_DEFINITIONS: return fail("validation_error", "loan valuation requires representative_liability_definition") if kind not in {"loan", "loan_balance"} and definition is not None: return fail("validation_error", "non-loan valuation cannot define representative liability") if amount_int is None: return fail("validation_error", "amount must be an integer") return basis, amount_int, currency_norm, status, source, definition def record_account_valuation_candidate(conn: sqlite3.Connection, account_id: str, basis_date: str, amount: int, currency: str, source_type: str, source_ref: str, idempotency_key: str, memo: str = "") -> dict[str, Any]: """Append an unverified candidate on a caller-owned transaction.""" account = conn.execute("SELECT currency FROM accounts WHERE id=?", (account_id,)).fetchone() if account is None: return fail("not_found", "account not found") if (currency or "KRW").upper() != (account["currency"] or "KRW").upper(): return fail("validation_error", "valuation currency must match account currency") basis = normalize_date(basis_date) existing = conn.execute("SELECT * FROM account_valuations WHERE account_id=? AND idempotency_key=?", (account_id, idempotency_key)).fetchone() if existing: return ok(valuation=_valuation(existing), reused=True) valuation_id = new_id("valuation") conn.execute("""INSERT INTO account_valuations (id,account_id,basis_date,amount,currency,valuation_kind,source_type,source_ref,verification_status,recorded_at,memo,idempotency_key) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)""", (valuation_id, account_id, basis, int(amount), (currency or "KRW").upper(), "balance", source_type, source_ref or "", "unverified", now_iso(), memo, idempotency_key)) return ok(valuation=_valuation(conn.execute("SELECT * FROM account_valuations WHERE id=?", (valuation_id,)).fetchone()), reused=False) def register_account_valuation( account_id: str, basis_date: str, amount: int, currency: str = "KRW", valuation_kind: str = "balance", source_type: str = "manual", source_ref: str = "", verification_status: str = "unverified", memo: str = "", idempotency_key: str = "", as_of_at: str | None = None, timezone: str | None = None, cost_basis: int | None = None, net_contributed: int | None = None, reported_principal_kind: str | None = None, reported_principal_label: str | None = None, profit: int | None = None, return_rate: float | None = None, return_basis: str | None = None, principal: int | None = None, interest: int | None = None, fee: int | None = None, representative_liability_definition: str | None = None, db_path: str | None = None, supersedes_id: str | None = None, correction_reason: str = "", ) -> dict[str, Any]: validated = _validate_common(account_id, basis_date, amount, currency, verification_status, valuation_kind, source_type, representative_liability_definition) if isinstance(validated, dict): return validated basis, amount_int, currency_norm, status, source_norm, definition = validated try: optional_ints = {name: _strict_int(value, name) for name, value in { "cost_basis": cost_basis, "net_contributed": net_contributed, "profit": profit, "principal": principal, "interest": interest, "fee": fee}.items()} return_rate = _strict_float(return_rate, "return_rate") except (TypeError, ValueError) as exc: return fail("validation_error", str(exc)) if (as_of_at is None) != (timezone is None): return fail("validation_error", "as_of_at and timezone must be supplied together") if as_of_at is not None: try: from datetime import datetime parsed = datetime.fromisoformat(as_of_at) if parsed.tzinfo is None: return fail("validation_error", "as_of_at must include timezone offset") except (TypeError, ValueError) as exc: return fail("validation_error", f"invalid as_of_at: {exc}") ts = now_iso() values = (amount_int, currency_norm, (valuation_kind or "balance").strip().lower(), source_norm, source_ref or "", status, memo or "", as_of_at, timezone, optional_ints["cost_basis"], optional_ints["net_contributed"], reported_principal_kind, reported_principal_label, optional_ints["profit"], return_rate, return_basis, optional_ints["principal"], optional_ints["interest"], optional_ints["fee"], definition) with db(db_path) as conn: account = conn.execute("SELECT * FROM accounts WHERE id=?", (account_id,)).fetchone() if account is None: return fail("not_found", "account not found") if currency_norm != (account["currency"] or "KRW").upper(): return fail("validation_error", "valuation currency must match account currency") if (valuation_kind or "balance").strip().lower() in {"loan", "loan_balance"} and str(account["type"]).lower() != "loan": return fail("validation_error", "loan valuation kind requires a loan account") if idempotency_key: existing = conn.execute("SELECT * FROM account_valuations WHERE account_id=? AND idempotency_key=?", (account_id, idempotency_key)).fetchone() if existing: current = _valuation(existing) incoming = dict(zip(_COLUMNS, values)) incoming.update({"account_id": account_id, "basis_date": basis, "supersedes_id": supersedes_id, "correction_reason": correction_reason or ""}) comparable = set(incoming) - {"id", "recorded_at"} if all(current.get(k) == v for k, v in incoming.items() if k in comparable): return ok(valuation=current, reused=True) return fail("idempotency_conflict", "idempotency_key already has a different payload", valuation=current) valuation_id = new_id("valuation") try: conn.execute("""INSERT INTO account_valuations (id,account_id,basis_date,amount,currency,valuation_kind,source_type,source_ref,verification_status,recorded_at,memo,idempotency_key,supersedes_id,correction_reason,as_of_at,timezone,cost_basis,net_contributed,reported_principal_kind,reported_principal_label,profit,return_rate,return_basis,principal,interest,fee,representative_liability_definition) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""", (valuation_id, account_id, basis, *values[:6], ts, values[6], idempotency_key or "", supersedes_id, correction_reason, *values[7:])) except sqlite3.IntegrityError as exc: if supersedes_id: return fail("correction_conflict", "valuation already has a correction") return fail("idempotency_conflict", str(exc)) except Exception as exc: return fail("validation_error", str(exc)) row = conn.execute("SELECT * FROM account_valuations WHERE id=?", (valuation_id,)).fetchone() return ok(valuation=_valuation(row), reused=False) def list_account_valuations(account_id: str, include_rejected: bool = True, db_path: str | None = None) -> dict[str, Any]: where = "" if include_rejected else " AND verification_status <> 'rejected'" with db(db_path) as conn: rows = conn.execute(f"SELECT * FROM account_valuations WHERE account_id=?{where} ORDER BY basis_date, recorded_at, id", (account_id,)).fetchall() values = [_valuation(row) for row in rows] return ok(account_id=account_id, valuations=values, count=len(values)) def select_account_valuation(account_id: str, basis_date: str, as_of: bool = False, currency: str | None = None, valuation_kind: str | None = None, db_path: str | None = None) -> dict[str, Any]: try: basis = normalize_date(basis_date) except Exception as exc: return fail("validation_error", str(exc)) with db(db_path) as conn: clauses = ["account_id=?"] params: list[Any] = [account_id] if currency: clauses.append("currency=?"); params.append(currency.strip().upper()) if valuation_kind: clauses.append("valuation_kind=?"); params.append(valuation_kind.strip().lower()) rows = conn.execute(f"SELECT * FROM account_valuations WHERE {' AND '.join(clauses)} ORDER BY basis_date DESC, recorded_at DESC, id DESC", params).fetchall() leaves = [r for r in rows if conn.execute("SELECT 1 FROM account_valuations WHERE supersedes_id=?", (r["id"],)).fetchone() is None] verified = [r for r in leaves if r["verification_status"] == "verified" and r["basis_date"] <= basis] exact = [r for r in verified if r["basis_date"] == basis] # Candidates are evidence at or before the requested basis. Exact # selection only surfaces same-date unverified evidence; as-of # selection surfaces unverified evidence newer than the selected # verified value, while never looking into the future. latest_verified_date = max((x["basis_date"] for x in verified), default="") candidate = [ r for r in leaves if r["verification_status"] != "verified" and r["basis_date"] <= basis and (r["basis_date"] == basis if not as_of else (not latest_verified_date or r["basis_date"] > latest_verified_date)) ] matching = exact if not as_of else [r for r in verified if r["basis_date"] == latest_verified_date] if len(matching) > 1: return fail("ambiguous_valuation", "multiple verified valuation leaves match the scope") row = matching[0] if matching else None if row is None: result = ok(account_id=account_id, basis_date=basis, valuation=None, carried_forward=False) if candidate: result["warning"] = "unverified_candidate" result["unverified_candidates"] = [_public_candidate(item) for item in candidate] return result age = (date.fromisoformat(basis) - date.fromisoformat(row["basis_date"])).days warning = "unverified_candidate" if candidate else ("carry_forward" if age else None) result = ok(account_id=account_id, basis_date=basis, valuation=_valuation(row), carried_forward=bool(age), valuation_age_days=age, warning=warning) if candidate: result["unverified_candidates"] = [_public_candidate(item) for item in candidate] return result def correct_account_valuation(valuation_id: str, amount: int, correction_reason: str, idempotency_key: str = "", db_path: str | None = None, **fields: Any) -> dict[str, Any]: if not correction_reason or not correction_reason.strip(): return fail("validation_error", "correction_reason is required") with db(db_path) as conn: source = conn.execute("SELECT * FROM account_valuations WHERE id=?", (valuation_id,)).fetchone() if source is None: return fail("not_found", "valuation not found") if idempotency_key: prior = conn.execute("SELECT * FROM account_valuations WHERE account_id=? AND idempotency_key=?", (source["account_id"], idempotency_key)).fetchone() if prior: expected = {"amount": amount, "supersedes_id": valuation_id, "correction_reason": correction_reason.strip()} expected.update({k: fields[k] for k in fields}) if all(prior[k] == v for k, v in expected.items() if k in prior.keys()): return ok(valuation=_valuation(prior), reused=True) return fail("idempotency_conflict", "idempotency_key already has a different payload", valuation=_valuation(prior)) if conn.execute("SELECT 1 FROM account_valuations WHERE supersedes_id=?", (valuation_id,)).fetchone(): return fail("correction_conflict", "valuation already has a correction") preserved = {name: fields[name] if name in fields else source[name] for name in ( "currency", "valuation_kind", "source_type", "source_ref", "verification_status", "memo", "as_of_at", "timezone", "cost_basis", "net_contributed", "reported_principal_kind", "reported_principal_label", "profit", "return_rate", "return_basis", "principal", "interest", "fee", "representative_liability_definition")} return register_account_valuation( source["account_id"], source["basis_date"], amount, **preserved, idempotency_key=idempotency_key, supersedes_id=valuation_id, correction_reason=correction_reason.strip(), db_path=db_path, )