@fin.cx/skr 3.0.0 → 3.2.0

package/ts/skr.opos.ts

@@ -0,0 +1,258 @@
+/**
+ * OPOS (Offene-Posten-Buchhaltung): open-item accounting over the v2 ledger.
+ *
+ * Open items are DERIVED from the hashed journal — no separate bookkeeping
+ * state that could drift. A line on a personal account (debtors 10000-69999,
+ * creditors 70000-99999) belongs to the open item keyed by
+ * (account, belegfeld1); the item is open while its signed sum is non-zero.
+ * Settling an item is ordinary posting (core.bookBankPayment + JournalPoster),
+ * so Festschreibung and the audit chain apply unchanged.
+ *
+ * Only dunning metadata lives outside the ledger (OposMeta collection) —
+ * process state, not bookkeeping.
+ */
+import * as core from './core/index.js';
+import { getDbSync } from './skr.database.js';
+import { JOURNAL_ENTRY_COLLECTION } from './skr.period.js';
+import type { TSKRType } from './skr.types.js';
+
+export const OPOS_META_COLLECTION = 'OposMeta';
+
+export type TOposKind = 'debtor' | 'creditor';
+
+export interface IOpenItem {
+  accountNumber: string;
+  kind: TOposKind;
+  /** belegfeld1 of the originating lines (usually the invoice number) */
+  reference: string;
+  /** original claim (sum of the claim-side lines) */
+  invoiceCents: number;
+  /** settled so far (sum of the settlement-side lines) */
+  clearedCents: number;
+  /** invoiceCents - clearedCents; > 0 means open */
+  openCents: number;
+  firstDate: string;
+  lastDate: string;
+  entryIds: string[];
+  dunningLevel: number;
+  dueDate?: string;
+}
+
+export interface IAgingBucket {
+  label: string;
+  maxAgeDays: number | null;
+  items: IOpenItem[];
+  totalCents: number;
+}
+
+export interface IControlTotals {
+  debtorsCents: number;
+  creditorsCents: number;
+  debtorAccounts: number;
+  creditorAccounts: number;
+}
+
+function kindOf(accountNumber: string, policy: core.IAccountPolicy): TOposKind | null {
+  if (core.isDebtorAccount(policy, accountNumber)) return 'debtor';
+  if (core.isCreditorAccount(policy, accountNumber)) return 'creditor';
+  return null;
+}
+
+interface ILineRow {
+  entryId: string;
+  accountNumber: string;
+  belegfeld1?: string;
+  side: 'debit' | 'credit';
+  amountCents: number;
+  date: Date;
+}
+
+async function loadPersonalLines(
+  skrType: TSKRType,
+  policy: core.IAccountPolicy,
+  accountNumber?: string,
+  asOf?: Date,
+): Promise<ILineRow[]> {
+  const match: Record<string, unknown> = {
+    skrType,
+    schemaVersion: 2,
+    status: { $in: ['posted', 'finalized'] },
+  };
+  if (asOf) match.date = { $lte: asOf };
+  if (accountNumber) match['lines.accountNumber'] = accountNumber;
+
+  const docs = await getDbSync()
+    .mongoDb.collection(JOURNAL_ENTRY_COLLECTION)
+    .find(match)
+    .sort({ date: 1, sequenceNumber: 1 })
+    .toArray();
+
+  const rows: ILineRow[] = [];
+  for (const doc of docs) {
+    for (const line of (doc.lines ?? []) as Array<Record<string, unknown>>) {
+      const account = line.accountNumber as string;
+      if (!kindOf(account, policy)) continue;
+      if (accountNumber && account !== accountNumber) continue;
+      rows.push({
+        entryId: doc.id as string,
+        accountNumber: account,
+        belegfeld1: (line.belegfeld1 as string) || (doc.reference as string) || '',
+        side: line.side as 'debit' | 'credit',
+        amountCents: (line.amountCents as number) ?? 0,
+        date: doc.date as Date,
+      });
+    }
+  }
+  return rows;
+}
+
+/**
+ * Derive open items. Debtors: claims are debits, settlements credits;
+ * creditors inverse. Items with openCents === 0 are settled and omitted
+ * unless includeSettled is set.
+ */
+export async function listOpenItems(
+  skrType: TSKRType,
+  policy: core.IAccountPolicy,
+  options?: {
+    kind?: TOposKind;
+    accountNumber?: string;
+    asOf?: Date;
+    includeSettled?: boolean;
+  },
+): Promise<IOpenItem[]> {
+  const rows = await loadPersonalLines(skrType, policy, options?.accountNumber, options?.asOf);
+  const groups = new Map<string, IOpenItem>();
+
+  for (const row of rows) {
+    const kind = kindOf(row.accountNumber, policy)!;
+    if (options?.kind && kind !== options.kind) continue;
+    const key = `${row.accountNumber}:${row.belegfeld1}`;
+    let item = groups.get(key);
+    if (!item) {
+      item = {
+        accountNumber: row.accountNumber,
+        kind,
+        reference: row.belegfeld1 ?? '',
+        invoiceCents: 0,
+        clearedCents: 0,
+        openCents: 0,
+        firstDate: row.date.toISOString().slice(0, 10),
+        lastDate: row.date.toISOString().slice(0, 10),
+        entryIds: [],
+        dunningLevel: 0,
+      };
+      groups.set(key, item);
+    }
+    const isClaim = (kind === 'debtor') === (row.side === 'debit');
+    if (isClaim) item.invoiceCents += row.amountCents;
+    else item.clearedCents += row.amountCents;
+    item.lastDate = row.date.toISOString().slice(0, 10);
+    if (!item.entryIds.includes(row.entryId)) item.entryIds.push(row.entryId);
+  }
+
+  const meta = await getDbSync().mongoDb.collection(OPOS_META_COLLECTION).find({ skrType }).toArray();
+  const metaByKey = new Map(meta.map((m) => [`${m.accountNumber}:${m.reference}`, m]));
+
+  const items: IOpenItem[] = [];
+  for (const item of groups.values()) {
+    item.openCents = item.invoiceCents - item.clearedCents;
+    const extra = metaByKey.get(`${item.accountNumber}:${item.reference}`);
+    if (extra) {
+      item.dunningLevel = (extra.dunningLevel as number) ?? 0;
+      item.dueDate = extra.dueDate as string | undefined;
+    }
+    if (item.openCents !== 0 || options?.includeSettled) items.push(item);
+  }
+  return items.sort((a, b) => a.accountNumber.localeCompare(b.accountNumber) || a.firstDate.localeCompare(b.firstDate));
+}
+
+/**
+ * Aging list relative to asOf, bucketed by days since dueDate (falling back
+ * to the item's first posting date).
+ */
+export async function getAging(
+  skrType: TSKRType,
+  policy: core.IAccountPolicy,
+  kind: TOposKind,
+  asOf: Date,
+  bucketDays: number[] = [30, 60, 90],
+): Promise<IAgingBucket[]> {
+  const items = await listOpenItems(skrType, policy, { kind, asOf });
+  const buckets: IAgingBucket[] = [
+    ...bucketDays.map((days, index) => ({
+      label: index === 0 ? `0-${days}` : `${bucketDays[index - 1] + 1}-${days}`,
+      maxAgeDays: days,
+      items: [] as IOpenItem[],
+      totalCents: 0,
+    })),
+    { label: `> ${bucketDays[bucketDays.length - 1]}`, maxAgeDays: null, items: [], totalCents: 0 },
+  ];
+  for (const item of items) {
+    const anchor = item.dueDate ?? item.firstDate;
+    const ageDays = Math.max(0, Math.floor((asOf.getTime() - new Date(anchor).getTime()) / 86_400_000));
+    const bucket =
+      buckets.find((candidate) => candidate.maxAgeDays !== null && ageDays <= candidate.maxAgeDays) ??
+      buckets[buckets.length - 1];
+    bucket.items.push(item);
+    bucket.totalCents += item.openCents;
+  }
+  return buckets;
+}
+
+/**
+ * Subledger control totals: the aggregated personal-account balances that a
+ * balance sheet reports as Forderungen (B.II.1) / Verbindlichkeiten (C.4)
+ * aus Lieferungen und Leistungen. Control accounts themselves are blocked for
+ * posting, so these aggregates ARE the control balances.
+ */
+export async function getControlTotals(
+  skrType: TSKRType,
+  policy: core.IAccountPolicy,
+  asOf?: Date,
+): Promise<IControlTotals> {
+  const rows = await loadPersonalLines(skrType, policy, undefined, asOf);
+  let debtorsCents = 0;
+  let creditorsCents = 0;
+  const debtorAccounts = new Set<string>();
+  const creditorAccounts = new Set<string>();
+  for (const row of rows) {
+    const signed = row.side === 'debit' ? row.amountCents : -row.amountCents;
+    if (kindOf(row.accountNumber, policy) === 'debtor') {
+      debtorsCents += signed;
+      debtorAccounts.add(row.accountNumber);
+    } else {
+      creditorsCents -= signed; // creditors carry credit balances positive
+      creditorAccounts.add(row.accountNumber);
+    }
+  }
+  return {
+    debtorsCents,
+    creditorsCents,
+    debtorAccounts: debtorAccounts.size,
+    creditorAccounts: creditorAccounts.size,
+  };
+}
+
+/**
+ * Dunning metadata (process state, not bookkeeping — letters are out of
+ * scope; the level/due-date state machine is in).
+ */
+export async function setOposMeta(params: {
+  skrType: TSKRType;
+  accountNumber: string;
+  reference: string;
+  dunningLevel?: number;
+  dueDate?: string;
+}): Promise<void> {
+  const update: Record<string, unknown> = { updatedAt: new Date() };
+  if (params.dunningLevel !== undefined) update.dunningLevel = params.dunningLevel;
+  if (params.dueDate !== undefined) update.dueDate = params.dueDate;
+  await getDbSync()
+    .mongoDb.collection(OPOS_META_COLLECTION)
+    .updateOne(
+      { skrType: params.skrType, accountNumber: params.accountNumber, reference: params.reference },
+      { $set: update },
+      { upsert: true },
+    );
+}

package/ts/skr.ustva.ts

@@ -0,0 +1,151 @@
+/**
+ * UStVA period extraction: one period's account movements plus the EXACT
+ * scenario Bemessungsgrundlagen (igE / §13b) taken from taxScenario-tagged
+ * journal entries. The result feeds @fin.cx/tax `computeUstva()` directly —
+ * movements as `IAccountMovementInput[]`, scenarioBases as
+ * `IScenarioBaseInput`.
+ *
+ * Base extraction per tagged entry: sum of (debit - credit) over lines that
+ * sit neither on a policy VAT account nor on a personal account (>= 10000).
+ * For the recipe shapes that is exactly the net expense line; Stornos flip
+ * sides and cancel. Every extracted base is cross-checked against the
+ * entry's own input-VAT line — disagreement lands in `warnings`.
+ */
+import { vatFromNetCents } from '@fin.cx/calculation';
+import { getDbSync } from './skr.database.js';
+import { JOURNAL_ENTRY_COLLECTION } from './skr.period.js';
+import { aggregateTrialBalance } from './skr.balances.js';
+import type { IAccountPolicy } from './core/index.js';
+import type { TSKRType } from './skr.types.js';
+
+export interface IUstvaMovement {
+  accountNumber: string;
+  /** debitCents - creditCents over the period */
+  signedCents: number;
+}
+
+export interface IUstvaScenarioBases {
+  /** igE 19 % net bases (Kz 89) */
+  intraEuAcquisitionStandardCents: number;
+  /** igE 7 % net bases (Kz 93) */
+  intraEuAcquisitionReducedCents: number;
+  /**
+   * §13b bases (Kz 46). The scenario tag does not distinguish EU services
+   * from other §13b cases — everything lands here; reclassify to Kz 84
+   * manually if a non-EU-services §13b case ever occurs.
+   */
+  reverseChargeServicesEuCents: number;
+}
+
+export interface IUstvaPeriodData {
+  movements: IUstvaMovement[];
+  scenarioBases: IUstvaScenarioBases;
+  /** tagged igE/§13b entries examined */
+  taggedEntryCount: number;
+  /** extraction anomalies — review before filing */
+  warnings: string[];
+}
+
+interface IRawEntry {
+  sequenceNumber?: number;
+  journalNumber?: string;
+  taxScenario?: string;
+  lines: Array<{ accountNumber: string; side?: string; amountCents?: number }>;
+}
+
+function isPersonalAccount(accountNumber: string): boolean {
+  const numeric = Number.parseInt(accountNumber, 10);
+  return numeric >= 10000 && numeric <= 99999;
+}
+
+export async function getUstvaPeriodData(
+  skrType: TSKRType,
+  policy: IAccountPolicy,
+  options: { dateFrom: Date; dateTo: Date },
+): Promise<IUstvaPeriodData> {
+  const trialBalance = await aggregateTrialBalance(skrType, options);
+  const movements: IUstvaMovement[] = trialBalance.accounts
+    .filter((account) => account.balanceCents !== 0)
+    .map((account) => ({
+      accountNumber: account.accountNumber,
+      signedCents: account.balanceCents,
+    }));
+
+  const vatAccounts = new Set(Object.values(policy.vat));
+  const warnings: string[] = [];
+  const scenarioBases: IUstvaScenarioBases = {
+    intraEuAcquisitionStandardCents: 0,
+    intraEuAcquisitionReducedCents: 0,
+    reverseChargeServicesEuCents: 0,
+  };
+
+  const collection = getDbSync().mongoDb.collection(JOURNAL_ENTRY_COLLECTION);
+  const tagged = (await collection
+    .find(
+      {
+        schemaVersion: 2,
+        skrType,
+        status: { $in: ['posted', 'finalized'] },
+        taxScenario: { $in: ['intra_eu_acquisition', 'reverse_charge_13b'] },
+        date: { $gte: options.dateFrom, $lte: options.dateTo },
+      },
+      { projection: { sequenceNumber: 1, journalNumber: 1, taxScenario: 1, lines: 1 } },
+    )
+    .toArray()) as unknown as IRawEntry[];
+
+  for (const entry of tagged) {
+    const label = entry.journalNumber ?? `seq ${entry.sequenceNumber}`;
+    const inputVatAccount =
+      entry.taxScenario === 'intra_eu_acquisition'
+        ? policy.vat.intraEuAcqInput
+        : policy.vat.reverseChargeInput;
+
+    let baseCents = 0;
+    let inputVatCents = 0;
+    for (const line of entry.lines) {
+      const amount = line.amountCents ?? 0;
+      const signed = line.side === 'debit' ? amount : -amount;
+      if (line.accountNumber === inputVatAccount) {
+        inputVatCents += signed;
+        continue;
+      }
+      if (vatAccounts.has(line.accountNumber)) continue;
+      if (isPersonalAccount(line.accountNumber)) continue;
+      baseCents += signed;
+    }
+
+    if (baseCents === 0 && inputVatCents !== 0) {
+      warnings.push(
+        `entry ${label}: no base extractable (counterparty not a personal account?) — VAT line is ${inputVatCents} cents`,
+      );
+      continue;
+    }
+    if (baseCents === 0) continue;
+
+    // rate detection from the entry's own VAT line (19 % vs 7 %)
+    const absBase = Math.abs(baseCents);
+    const absVat = Math.abs(inputVatCents);
+    const reduced = Math.abs(absVat * 100 - 7 * absBase) < Math.abs(absVat * 100 - 19 * absBase);
+    const rate = reduced ? 7 : 19;
+    const expectedVat = vatFromNetCents(baseCents, rate);
+    if (Math.abs(inputVatCents - expectedVat) > 2) {
+      warnings.push(
+        `entry ${label}: base ${baseCents} cents at ${rate} % expects VAT ${expectedVat}, ledger line says ${inputVatCents}`,
+      );
+    }
+
+    if (entry.taxScenario === 'intra_eu_acquisition') {
+      if (reduced) scenarioBases.intraEuAcquisitionReducedCents += baseCents;
+      else scenarioBases.intraEuAcquisitionStandardCents += baseCents;
+    } else {
+      scenarioBases.reverseChargeServicesEuCents += baseCents;
+    }
+  }
+
+  return {
+    movements,
+    scenarioBases,
+    taggedEntryCount: tagged.length,
+    warnings,
+  };
+}