HEL-175: 公司端转账往来汇总接口
新增 GET /api/company/intercompany/summary：会话 company_id 强制隔离， 已确认走 eligible_intercompany_events，待确认单列，Decimal 字符串金额。 Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: multica-agent <github@multica.ai>
This commit is contained in:
总工
co-authored by
Cursor
multica-agent
Cursor
multica-agent
parent
642604f688
commit
cad12b3d28
@@ -0,0 +1,298 @@
|
||||
"""Company-portal intercompany transfer summary (HEL-175 / HEL-169).
|
||||
|
||||
Confirmed totals reuse the authoritative ``eligible_intercompany_events``
|
||||
view (intercompany + paired or locked). Pending counts/amounts are listed
|
||||
separately and never enter outflow, inflow or net. All money math uses
|
||||
``Decimal`` on stored TEXT amounts — never float or SQLite SUM.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import datetime, timedelta, timezone
|
||||
from decimal import Decimal, InvalidOperation
|
||||
import re
|
||||
import sqlite3
|
||||
|
||||
from . import settings
|
||||
|
||||
_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
|
||||
_ZERO = Decimal("0.00")
|
||||
|
||||
|
||||
class TransferSummaryInputError(ValueError):
|
||||
"""Invalid query parameters (mapped to HTTP 400)."""
|
||||
|
||||
|
||||
def today_shanghai() -> str:
|
||||
return datetime.now(timezone(timedelta(hours=8))).date().isoformat()
|
||||
|
||||
|
||||
def _validate_date(value: object, label: str) -> str:
|
||||
text = str(value or "").strip()
|
||||
if not text or not _DATE_RE.fullmatch(text):
|
||||
raise TransferSummaryInputError(f"{label}必须是 YYYY-MM-DD 格式。")
|
||||
try:
|
||||
datetime.strptime(text, "%Y-%m-%d")
|
||||
except ValueError as exc:
|
||||
raise TransferSummaryInputError(f"{label}不是有效日期。") from exc
|
||||
return text
|
||||
|
||||
|
||||
def _money(value: Decimal) -> str:
|
||||
return format(value.quantize(Decimal("0.01")), "f")
|
||||
|
||||
|
||||
def _as_decimal(raw: object) -> Decimal:
|
||||
try:
|
||||
return Decimal(str(raw))
|
||||
except (InvalidOperation, TypeError) as exc:
|
||||
raise TransferSummaryInputError("金额数据无效，无法汇总。") from exc
|
||||
|
||||
|
||||
def _company_row(connection: sqlite3.Connection, company_id: int) -> dict[str, object]:
|
||||
row = connection.execute(
|
||||
"SELECT id, name FROM companies WHERE id = ?", (company_id,)
|
||||
).fetchone()
|
||||
if row is None:
|
||||
raise TransferSummaryInputError("本公司不存在。")
|
||||
return {"id": int(row["id"]), "name": row["name"]}
|
||||
|
||||
|
||||
def _window_bounds(
|
||||
connection: sqlite3.Connection, as_of: str | None
|
||||
) -> tuple[str, str]:
|
||||
end = _validate_date(as_of, "as_of") if as_of else today_shanghai()
|
||||
start = settings.get_settings(connection).get("start_date") or "2026-01-01"
|
||||
start = _validate_date(start, "start_date")
|
||||
if start > end:
|
||||
# Opening / start-date plumbing may lag; clamp rather than 500.
|
||||
start = end
|
||||
return start, end
|
||||
|
||||
|
||||
def _load_confirmed(
|
||||
connection: sqlite3.Connection, company_id: int, start: str, end: str
|
||||
) -> list[sqlite3.Row]:
|
||||
return connection.execute(
|
||||
"""
|
||||
SELECT e.event_id, e.decision_id, e.effective_at, e.amount, e.currency,
|
||||
e.payer_company_id, e.payee_company_id, e.pairing,
|
||||
cpayer.name AS payer_company_name,
|
||||
cpayee.name AS payee_company_name
|
||||
FROM eligible_intercompany_events e
|
||||
JOIN companies cpayer ON cpayer.id = e.payer_company_id
|
||||
JOIN companies cpayee ON cpayee.id = e.payee_company_id
|
||||
WHERE (e.payer_company_id = ? OR e.payee_company_id = ?)
|
||||
AND e.effective_at >= ?
|
||||
AND e.effective_at <= ?
|
||||
ORDER BY e.event_id
|
||||
""",
|
||||
(company_id, company_id, start, end + "T23:59:59"),
|
||||
).fetchall()
|
||||
|
||||
|
||||
def _load_pending(
|
||||
connection: sqlite3.Connection, company_id: int, start: str, end: str
|
||||
) -> list[sqlite3.Row]:
|
||||
"""Pending = not eligible confirmed, still company-visible for tip only.
|
||||
|
||||
Includes unresolved / needs_review / internal_single, plus any
|
||||
intercompany decision that is neither paired nor locked.
|
||||
"""
|
||||
return connection.execute(
|
||||
"""
|
||||
SELECT c.event_id, d.id AS decision_id, d.effective_at, d.amount,
|
||||
d.currency, d.classification, d.pairing, d.locked,
|
||||
payer.company_id AS payer_company_id,
|
||||
payee.company_id AS payee_company_id,
|
||||
cpayer.name AS payer_company_name,
|
||||
cpayee.name AS payee_company_name
|
||||
FROM current_transfer_decisions c
|
||||
JOIN transfer_match_decisions d ON d.id = c.decision_id
|
||||
JOIN canonical_transfer_events e ON e.id = c.event_id
|
||||
LEFT JOIN transfer_decision_participants payer
|
||||
ON payer.decision_id = d.id AND payer.role = 'payer'
|
||||
LEFT JOIN transfer_decision_participants payee
|
||||
ON payee.decision_id = d.id AND payee.role = 'payee'
|
||||
LEFT JOIN companies cpayer ON cpayer.id = payer.company_id
|
||||
LEFT JOIN companies cpayee ON cpayee.id = payee.company_id
|
||||
WHERE e.lifecycle = 'active'
|
||||
AND (payer.company_id = ? OR payee.company_id = ?)
|
||||
AND d.effective_at >= ?
|
||||
AND d.effective_at <= ?
|
||||
AND (
|
||||
d.classification IN ('unresolved', 'needs_review', 'internal_single')
|
||||
OR (
|
||||
d.classification = 'intercompany'
|
||||
AND d.pairing != 'paired'
|
||||
AND d.locked = 0
|
||||
)
|
||||
)
|
||||
ORDER BY c.event_id
|
||||
""",
|
||||
(company_id, company_id, start, end + "T23:59:59"),
|
||||
).fetchall()
|
||||
|
||||
|
||||
def _counterparty_of(row: sqlite3.Row, company_id: int) -> tuple[int | None, str | None]:
|
||||
payer = row["payer_company_id"]
|
||||
payee = row["payee_company_id"]
|
||||
if payer is not None and int(payer) == int(company_id):
|
||||
if payee is None:
|
||||
return None, None
|
||||
return int(payee), row["payee_company_name"]
|
||||
if payee is not None and int(payee) == int(company_id):
|
||||
if payer is None:
|
||||
return None, None
|
||||
return int(payer), row["payer_company_name"]
|
||||
return None, None
|
||||
|
||||
|
||||
def _is_outflow(row: sqlite3.Row, company_id: int) -> bool:
|
||||
return row["payer_company_id"] is not None and int(row["payer_company_id"]) == int(
|
||||
company_id
|
||||
)
|
||||
|
||||
|
||||
def company_intercompany_summary(
|
||||
connection: sqlite3.Connection,
|
||||
*,
|
||||
company_id: int,
|
||||
as_of: str | None = None,
|
||||
) -> dict[str, object]:
|
||||
"""Build the HEL-169 summary payload for one company session."""
|
||||
own = _company_row(connection, company_id)
|
||||
start, end = _window_bounds(connection, as_of)
|
||||
|
||||
confirmed_rows = _load_confirmed(connection, company_id, start, end)
|
||||
pending_rows = _load_pending(connection, company_id, start, end)
|
||||
|
||||
seen_confirmed: set[int] = set()
|
||||
outflow = _ZERO
|
||||
inflow = _ZERO
|
||||
outflow_count = 0
|
||||
inflow_count = 0
|
||||
|
||||
# counterparty_id -> bucket
|
||||
buckets: dict[int, dict[str, object]] = {}
|
||||
|
||||
def bucket_for(cp_id: int, cp_name: str | None) -> dict[str, object]:
|
||||
bucket = buckets.get(cp_id)
|
||||
if bucket is None:
|
||||
bucket = {
|
||||
"company_id": cp_id,
|
||||
"company_name": cp_name or "",
|
||||
"confirmed_outflow": _ZERO,
|
||||
"confirmed_inflow": _ZERO,
|
||||
"pending_count": 0,
|
||||
"last_effective_at": None,
|
||||
}
|
||||
buckets[cp_id] = bucket
|
||||
elif cp_name and not bucket["company_name"]:
|
||||
bucket["company_name"] = cp_name
|
||||
return bucket
|
||||
|
||||
def touch_last(bucket: dict[str, object], effective_at: str | None) -> None:
|
||||
if not effective_at:
|
||||
return
|
||||
previous = bucket["last_effective_at"]
|
||||
if previous is None or str(effective_at) > str(previous):
|
||||
bucket["last_effective_at"] = effective_at
|
||||
|
||||
for row in confirmed_rows:
|
||||
event_id = int(row["event_id"])
|
||||
if event_id in seen_confirmed:
|
||||
continue
|
||||
seen_confirmed.add(event_id)
|
||||
amount = _as_decimal(row["amount"])
|
||||
cp_id, cp_name = _counterparty_of(row, company_id)
|
||||
if _is_outflow(row, company_id):
|
||||
outflow += amount
|
||||
outflow_count += 1
|
||||
if cp_id is not None:
|
||||
bucket = bucket_for(cp_id, cp_name)
|
||||
bucket["confirmed_outflow"] += amount
|
||||
touch_last(bucket, row["effective_at"])
|
||||
else:
|
||||
inflow += amount
|
||||
inflow_count += 1
|
||||
if cp_id is not None:
|
||||
bucket = bucket_for(cp_id, cp_name)
|
||||
bucket["confirmed_inflow"] += amount
|
||||
touch_last(bucket, row["effective_at"])
|
||||
|
||||
pending_total = _ZERO
|
||||
seen_pending: set[int] = set()
|
||||
for row in pending_rows:
|
||||
event_id = int(row["event_id"])
|
||||
if event_id in seen_pending or event_id in seen_confirmed:
|
||||
continue
|
||||
seen_pending.add(event_id)
|
||||
amount = _as_decimal(row["amount"])
|
||||
pending_total += amount
|
||||
cp_id, cp_name = _counterparty_of(row, company_id)
|
||||
if cp_id is not None:
|
||||
bucket = bucket_for(cp_id, cp_name)
|
||||
bucket["pending_count"] = int(bucket["pending_count"]) + 1
|
||||
touch_last(bucket, row["effective_at"])
|
||||
|
||||
net = outflow - inflow
|
||||
if net > 0:
|
||||
net_direction: str | None = "receivable"
|
||||
elif net < 0:
|
||||
net_direction = "payable"
|
||||
else:
|
||||
net_direction = None
|
||||
|
||||
counterparties = []
|
||||
for cp_id in sorted(
|
||||
buckets.keys(),
|
||||
key=lambda i: (
|
||||
-(
|
||||
buckets[i]["confirmed_outflow"] # type: ignore[operator]
|
||||
+ buckets[i]["confirmed_inflow"]
|
||||
),
|
||||
buckets[i]["company_name"] or "",
|
||||
i,
|
||||
),
|
||||
):
|
||||
bucket = buckets[cp_id]
|
||||
conf_out = bucket["confirmed_outflow"]
|
||||
conf_in = bucket["confirmed_inflow"]
|
||||
assert isinstance(conf_out, Decimal) and isinstance(conf_in, Decimal)
|
||||
counterparties.append(
|
||||
{
|
||||
"company_id": cp_id,
|
||||
"company_name": bucket["company_name"],
|
||||
"confirmed_outflow": _money(conf_out),
|
||||
"confirmed_inflow": _money(conf_in),
|
||||
"net": _money(conf_out - conf_in),
|
||||
"pending_count": int(bucket["pending_count"]),
|
||||
"last_effective_at": bucket["last_effective_at"],
|
||||
}
|
||||
)
|
||||
|
||||
return {
|
||||
"own_company": own,
|
||||
"window": {
|
||||
"start": start,
|
||||
"end": end,
|
||||
"has_opening": False,
|
||||
# Reserved for opening-balance rollout; callers must not invent balances.
|
||||
"opening": None,
|
||||
"ending": None,
|
||||
},
|
||||
"confirmed": {
|
||||
"outflow_total": _money(outflow),
|
||||
"outflow_count": outflow_count,
|
||||
"inflow_total": _money(inflow),
|
||||
"inflow_count": inflow_count,
|
||||
"net_change": _money(net),
|
||||
"net_direction": net_direction,
|
||||
},
|
||||
"pending": {
|
||||
"count": len(seen_pending),
|
||||
"amount_total": _money(pending_total),
|
||||
},
|
||||
"counterparties": counterparties,
|
||||
}
|
||||
Reference in New Issue
Block a user