@fin.cx/skr 1.3.0 → 2.0.0

package/ts/skr.api.ts

@@ -12,6 +12,23 @@ import { AccountsExporter } from './skr.export.accounts.js';
 import { BalancesExporter } from './skr.export.balances.js';
 import { PdfReportGenerator, type IPdfReportOptions } from './skr.export.pdf.js';
 import { SecurityManager, type ISigningOptions } from './skr.security.js';
+import * as core from './core/index.js';
+import { JournalPoster, type IPostDraftOptions } from './skr.posting.js';
+import { festschreibePeriod, getPeriodState, type ILedgerPeriodState } from './skr.period.js';
+import { verifyHashChain, type IChainVerificationResult } from './skr.verify.js';
+import {
+  aggregateTrialBalance,
+  aggregateAccountBalance,
+  type IBalanceQueryOptions,
+  type ITrialBalanceCents,
+  type IAccountBalanceCents,
+} from './skr.balances.js';
+import {
+  transactionDataToDraft,
+  journalInputToDraft,
+  entryToTransactionView,
+  accountLineViews,
+} from './skr.txview.js';
 import { InvoiceAdapter } from './skr.invoice.adapter.js';
 import { InvoiceStorage } from './skr.invoice.storage.js';
 import { InvoiceBookingEngine, type IBookingOptions, type IBookingResult } from './skr.invoice.booking.js';
@@ -36,6 +53,7 @@ import type {
   IIncomeStatement,
   IBalanceSheet,
   IAccountBalance,
+  ITransactionView,
 } from './skr.types.js';
 
 /**
@@ -51,6 +69,7 @@ export class SkrApi {
   private invoiceAdapter: InvoiceAdapter | null = null;
   private invoiceStorage: InvoiceStorage | null = null;
   private invoiceBookingEngine: InvoiceBookingEngine | null = null;
+  private journalPoster: JournalPoster = new JournalPoster();
 
   constructor(private config: IDatabaseConfig) {
     this.chartOfAccounts = new ChartOfAccounts(config);
@@ -84,6 +103,11 @@ export class SkrApi {
     this.currentSKRType = skrType;
     this.ledger = new Ledger(skrType);
     this.reports = new Reports(skrType);
+
+    // v2 posting path: transactions are mandatory (replica set) — fail hard,
+    // filing-grade posting has no non-transactional fallback
+    await this.journalPoster.assertTransactionSupport();
+    await this.journalPoster.ensureIndexes();
     
     // Initialize invoice components
     this.invoiceAdapter = new InvoiceAdapter();
@@ -178,75 +202,160 @@ export class SkrApi {
     return await this.chartOfAccounts.getAccountsByType(accountType);
   }
 
-  // ========== Transaction Management ==========
+  // ========== Transaction Management (v2: hashed journal entries) ==========
 
   /**
-   * Post a simple transaction
+   * Post a simple transaction. Since v2 this creates a hashed two-line
+   * journal entry (exact cents) — the Transaction collection is frozen.
    */
   public async postTransaction(
     transactionData: ITransactionData,
-  ): Promise<Transaction> {
+  ): Promise<ITransactionView> {
     this.ensureInitialized();
-    if (!this.ledger) throw new Error('Ledger not initialized');
-    return await this.ledger.postTransaction(transactionData);
+    if (transactionData.amount <= 0) {
+      throw new Error('Transaction amount must be greater than zero');
+    }
+    if (transactionData.debitAccount === transactionData.creditAccount) {
+      throw new Error('Debit and credit accounts cannot be the same');
+    }
+    for (const [label, accountNumber] of [
+      ['Debit', transactionData.debitAccount],
+      ['Credit', transactionData.creditAccount],
+    ] as const) {
+      const account = await Account.getAccountByNumber(accountNumber, this.currentSKRType!);
+      if (account && !account.isActive) {
+        throw new Error(`${label} account ${accountNumber} is not active`);
+      }
+      await Account.validateAccountForPosting(accountNumber, this.currentSKRType!);
+    }
+    const draft = transactionDataToDraft({
+      ...transactionData,
+      skrType: this.currentSKRType!,
+    });
+    const entry = await this.journalPoster.postDraft(draft);
+    return entryToTransactionView(entry as never)!;
   }
 
   /**
-   * Post a journal entry
+   * Post a journal entry. Since v2 the entry is hashed, sequenced, and
+   * immutable; float inputs are converted to exact cents with a drift guard.
    */
   public async postJournalEntry(
     journalData: IJournalEntry,
   ): Promise<JournalEntry> {
     this.ensureInitialized();
-    if (!this.ledger) throw new Error('Ledger not initialized');
-    return await this.ledger.postJournalEntry(journalData);
+    for (const line of journalData.lines) {
+      await Account.validateAccountForPosting(line.accountNumber, this.currentSKRType!);
+    }
+    const draft = journalInputToDraft({
+      ...journalData,
+      skrType: this.currentSKRType!,
+    });
+    return this.journalPoster.postDraft(draft);
   }
 
   /**
-   * Get transaction by ID
+   * Get a transaction view by id (two-line v2 entries project 1:1).
    */
   public async getTransaction(
     transactionId: string,
-  ): Promise<Transaction | null> {
+  ): Promise<ITransactionView | null> {
     this.ensureInitialized();
-    return await Transaction.getTransactionById(transactionId);
+    const entry = await (JournalEntry as any).getInstance({ id: transactionId });
+    if (!entry || entry.schemaVersion !== 2) return null;
+    return entryToTransactionView(entry);
   }
 
   /**
-   * List transactions with optional filter
+   * List transaction views with optional filter (two-line v2 entries).
    */
   public async listTransactions(
     filter?: ITransactionFilter,
-  ): Promise<Transaction[]> {
+  ): Promise<ITransactionView[]> {
     this.ensureInitialized();
-    return await this.chartOfAccounts.getTransactions(filter);
+    return this.listTransactionViews(filter);
+  }
+
+  private async listTransactionViews(
+    filter?: ITransactionFilter,
+  ): Promise<ITransactionView[]> {
+    const match: Record<string, unknown> = {
+      skrType: filter?.skrType ?? this.currentSKRType,
+      schemaVersion: 2,
+      status: { $in: ['posted', 'finalized'] },
+    };
+    if (filter?.dateFrom || filter?.dateTo) {
+      const range: Record<string, Date> = {};
+      if (filter.dateFrom) range.$gte = filter.dateFrom;
+      if (filter.dateTo) range.$lte = filter.dateTo;
+      match.date = range;
+    }
+    const docs = await (await import('./skr.database.js'))
+      .getDbSync()
+      .mongoDb.collection('JournalEntry')
+      .find(match)
+      .sort({ date: 1, sequenceNumber: 1 })
+      .toArray();
+    let views = docs
+      .map((doc) => entryToTransactionView(doc as never))
+      .filter((view): view is ITransactionView => view !== null);
+    if (filter?.accountNumber) {
+      views = views.filter(
+        (view) =>
+          view.debitAccount === filter.accountNumber ||
+          view.creditAccount === filter.accountNumber,
+      );
+    }
+    if (filter?.minAmount !== undefined) {
+      views = views.filter((view) => view.amount >= filter.minAmount!);
+    }
+    if (filter?.maxAmount !== undefined) {
+      views = views.filter((view) => view.amount <= filter.maxAmount!);
+    }
+    if (filter?.searchTerm) {
+      const term = filter.searchTerm.toLowerCase();
+      views = views.filter(
+        (view) =>
+          view.description.toLowerCase().includes(term) ||
+          view.reference.toLowerCase().includes(term),
+      );
+    }
+    return views;
   }
 
   /**
-   * Get transactions for specific account
+   * Get per-line transaction views for one account.
    */
   public async getAccountTransactions(
     accountNumber: string,
-  ): Promise<Transaction[]> {
+  ): Promise<ITransactionView[]> {
     this.ensureInitialized();
-    return await this.chartOfAccounts.getAccountTransactions(accountNumber);
+    return accountLineViews(accountNumber, this.currentSKRType!);
   }
 
   /**
-   * Reverse a transaction
+   * Reverse via Storno — the original entry is never mutated (GoBD).
    */
-  public async reverseTransaction(transactionId: string): Promise<Transaction> {
+  public async reverseTransaction(transactionId: string): Promise<ITransactionView> {
     this.ensureInitialized();
-    return await this.chartOfAccounts.reverseTransaction(transactionId);
+    const entry = await (JournalEntry as any).getInstance({ id: transactionId });
+    if (!entry || entry.schemaVersion !== 2) {
+      throw new Error(`Transaction ${transactionId} not found`);
+    }
+    const storno = await this.journalPoster.postStorno(entry);
+    return entryToTransactionView(storno as never)!;
   }
 
   /**
-   * Reverse a journal entry
+   * Reverse a journal entry via Storno.
    */
   public async reverseJournalEntry(journalId: string): Promise<JournalEntry> {
     this.ensureInitialized();
-    if (!this.ledger) throw new Error('Ledger not initialized');
-    return await this.ledger.reverseJournalEntry(journalId);
+    const entry = await (JournalEntry as any).getInstance({ id: journalId });
+    if (!entry || entry.schemaVersion !== 2) {
+      throw new Error(`Journal entry ${journalId} not found`);
+    }
+    return this.journalPoster.postStorno(entry);
   }
 
   // ========== Reporting ==========
@@ -315,50 +424,166 @@ export class SkrApi {
   }
 
   /**
-   * Export to DATEV format
+   * Export to DATEV format (EXTF 700 Buchungsstapel over v2 entries).
+   * For a fully parameterized export use exportDatevBuchungsstapel().
    */
   public async exportToDATEV(params?: IReportParams): Promise<string> {
     this.ensureInitialized();
-    if (!this.reports) throw new Error('Reports not initialized');
-    return await this.reports.exportToDATEV(params);
+    const dateFrom = params?.dateFrom ?? new Date('1970-01-01T00:00:00.000Z');
+    const dateTo = params?.dateTo ?? new Date('2999-12-31T00:00:00.000Z');
+    const { csv } = await this.exportDatevBuchungsstapel({
+      dateFrom,
+      dateTo,
+      consultantNumber: 0,
+      clientNumber: 0,
+      fiscalYearStart: new Date(Date.UTC(dateFrom.getUTCFullYear(), 0, 1)),
+      label: 'Buchungsstapel',
+    });
+    return csv;
   }
 
   // ========== Period Management ==========
 
   /**
-   * Close accounting period
+   * Close accounting period: post P&L-zeroing entries (v2) into the period.
+   * Locking is a separate deliberate act — call festschreibePeriod() after.
    */
   public async closePeriod(
     period: string,
-    closingAccountNumber?: string,
+    closingAccountNumber: string = '9400',
   ): Promise<JournalEntry[]> {
     this.ensureInitialized();
-    if (!this.ledger) throw new Error('Ledger not initialized');
-    return await this.ledger.closeAccountingPeriod(
-      period,
-      closingAccountNumber,
-    );
+    const [year, month] = period.split('-').map((part) => Number.parseInt(part, 10));
+    const dateFrom = new Date(Date.UTC(year, month - 1, 1));
+    const dateTo = new Date(Date.UTC(year, month, 0, 23, 59, 59, 999));
+    const trialBalance = await this.getTrialBalanceCents({ dateFrom, dateTo });
+
+    const revenueLines: core.IJournalLineDraft[] = [];
+    const expenseLines: core.IJournalLineDraft[] = [];
+    for (const balance of trialBalance.accounts) {
+      const account = await Account.getAccountByNumber(
+        balance.accountNumber,
+        this.currentSKRType!,
+      );
+      if (!account) continue;
+      if (account.accountType === 'revenue') {
+        const net = balance.creditCents - balance.debitCents;
+        if (net !== 0) {
+          revenueLines.push({
+            accountNumber: balance.accountNumber,
+            counterAccount: closingAccountNumber,
+            side: net > 0 ? 'debit' : 'credit',
+            amountCents: Math.abs(net),
+            buKey: '40',
+            buchungstext: `Abschluss ${period}`,
+          });
+        }
+      } else if (account.accountType === 'expense') {
+        const net = balance.debitCents - balance.creditCents;
+        if (net !== 0) {
+          expenseLines.push({
+            accountNumber: balance.accountNumber,
+            counterAccount: closingAccountNumber,
+            side: net > 0 ? 'credit' : 'debit',
+            amountCents: Math.abs(net),
+            buKey: '40',
+            buchungstext: `Abschluss ${period}`,
+          });
+        }
+      }
+    }
+
+    const entries: JournalEntry[] = [];
+    const closeDraft = async (
+      lines: core.IJournalLineDraft[],
+      reference: string,
+    ): Promise<void> => {
+      if (lines.length === 0) return;
+      const debitSum = lines
+        .filter((line) => line.side === 'debit')
+        .reduce((sum, line) => sum + line.amountCents, 0);
+      const creditSum = lines
+        .filter((line) => line.side === 'credit')
+        .reduce((sum, line) => sum + line.amountCents, 0);
+      const net = debitSum - creditSum;
+      if (net !== 0) {
+        lines.push({
+          accountNumber: closingAccountNumber,
+          counterAccount: lines[0].accountNumber,
+          side: net > 0 ? 'credit' : 'debit',
+          amountCents: Math.abs(net),
+          buKey: '',
+          buchungstext: `Abschluss ${period}`,
+        });
+      }
+      entries.push(
+        await this.journalPoster.postDraft({
+          date: dateTo,
+          description: `Periodenabschluss ${period}`,
+          reference,
+          skrType: this.currentSKRType!,
+          currency: 'EUR',
+          lines,
+        }),
+      );
+    };
+    await closeDraft(revenueLines, `CLOSE-REV-${period}`);
+    await closeDraft(expenseLines, `CLOSE-EXP-${period}`);
+    return entries;
   }
 
   /**
-   * Get account balance
+   * Get account balance (aggregated from v2 entries, exact cents inside).
    */
   public async getAccountBalance(
     accountNumber: string,
     asOfDate?: Date,
-  ): Promise<any> {
+  ): Promise<IAccountBalance> {
     this.ensureInitialized();
-    if (!this.ledger) throw new Error('Ledger not initialized');
-    return await this.ledger.getAccountBalance(accountNumber, asOfDate);
+    const account = await Account.getAccountByNumber(
+      accountNumber,
+      this.currentSKRType!,
+    );
+    if (!account) {
+      throw new Error(`Account ${accountNumber} not found`);
+    }
+    const balance = await this.getAccountBalanceCents(accountNumber, {
+      dateTo: asOfDate,
+    });
+    const signed =
+      account.accountType === 'asset' || account.accountType === 'expense'
+        ? balance.balanceCents
+        : -balance.balanceCents;
+    return {
+      accountNumber,
+      debitTotal: balance.debitCents / 100,
+      creditTotal: balance.creditCents / 100,
+      balance: signed / 100,
+      lastUpdated: new Date(),
+    };
   }
 
   /**
-   * Recalculate all account balances
+   * Refresh the (informational) balance caches on Account documents from the
+   * aggregated v2 ledger.
    */
   public async recalculateBalances(): Promise<void> {
     this.ensureInitialized();
-    if (!this.ledger) throw new Error('Ledger not initialized');
-    await this.ledger.recalculateAllBalances();
+    const trialBalance = await this.getTrialBalanceCents();
+    for (const balance of trialBalance.accounts) {
+      const account = await Account.getAccountByNumber(
+        balance.accountNumber,
+        this.currentSKRType!,
+      );
+      if (!account) continue;
+      account.debitTotal = balance.debitCents / 100;
+      account.creditTotal = balance.creditCents / 100;
+      account.balance =
+        account.accountType === 'asset' || account.accountType === 'expense'
+          ? balance.balanceCents / 100
+          : -balance.balanceCents / 100;
+      await account.save();
+    }
   }
 
   // ========== Import/Export ==========
@@ -641,6 +866,166 @@ export class SkrApi {
 
   // ========== Utility Methods ==========
 
+  // ========== v2 Ledger (hashed, gapless, festschreibbar) ==========
+
+  /**
+   * Default account policy for the active chart.
+   */
+  public getDefaultPolicy(): core.IAccountPolicy {
+    this.ensureInitialized();
+    return core.getDefaultPolicy(this.currentSKRType!);
+  }
+
+  /**
+   * Post a validated journal draft atomically (v2 path: exact cents,
+   * gapless sequence, hash chain). Use the recipes in `core` to build drafts.
+   */
+  public async postDraft(
+    draft: core.IJournalDraft,
+    options?: IPostDraftOptions,
+  ): Promise<JournalEntry> {
+    this.ensureInitialized();
+    return this.journalPoster.postDraft(draft, {
+      policy: options?.policy ?? this.getDefaultPolicy(),
+      ...options,
+    });
+  }
+
+  /**
+   * Reverse a hashed entry via Storno — the original is never mutated.
+   */
+  public async postStorno(
+    entry: JournalEntry,
+    options?: IPostDraftOptions & { date?: Date; description?: string },
+  ): Promise<JournalEntry> {
+    this.ensureInitialized();
+    return this.journalPoster.postStorno(entry, {
+      policy: options?.policy ?? this.getDefaultPolicy(),
+      ...options,
+    });
+  }
+
+  /**
+   * Festschreibung: finalize all posted v2 entries of a period and lock it
+   * against further postings (GoBD).
+   */
+  public async festschreibePeriod(
+    period: string,
+    lockedBy?: string,
+  ): Promise<{ finalizedEntries: number }> {
+    this.ensureInitialized();
+    return festschreibePeriod({
+      skrType: this.currentSKRType!,
+      period,
+      lockedBy,
+    });
+  }
+
+  public async getPeriodState(period: string): Promise<ILedgerPeriodState | null> {
+    this.ensureInitialized();
+    return getPeriodState(this.currentSKRType!, period);
+  }
+
+  /**
+   * Recompute the whole hash chain for a fiscal year and compare it against
+   * the stored chain head — the audit-trail integrity check.
+   */
+  public async verifyAuditChain(fiscalYear: number): Promise<IChainVerificationResult> {
+    this.ensureInitialized();
+    return verifyHashChain(this.currentSKRType!, fiscalYear);
+  }
+
+  /**
+   * Exact trial balance in integer cents, aggregated from v2 entries.
+   */
+  public async getTrialBalanceCents(
+    options?: IBalanceQueryOptions,
+  ): Promise<ITrialBalanceCents> {
+    this.ensureInitialized();
+    return aggregateTrialBalance(this.currentSKRType!, options);
+  }
+
+  public async getAccountBalanceCents(
+    accountNumber: string,
+    options?: IBalanceQueryOptions,
+  ): Promise<IAccountBalanceCents> {
+    this.ensureInitialized();
+    return aggregateAccountBalance(accountNumber, this.currentSKRType!, options);
+  }
+
+  /**
+   * DATEV Buchungsstapel (EXTF 700 / v13) over the v2 entries of a date
+   * range. Returns the CSV string (persist as CP1252!) and filename.
+   */
+  public async exportDatevBuchungsstapel(options: {
+    dateFrom: Date;
+    dateTo: Date;
+    consultantNumber: number;
+    clientNumber: number;
+    fiscalYearStart: Date;
+    label?: string;
+    festschreibung?: boolean;
+    createdAt?: Date;
+  }): Promise<{ csv: string; filename: string; rowCount: number }> {
+    this.ensureInitialized();
+    const collection = (await import('./skr.database.js'))
+      .getDbSync()
+      .mongoDb.collection('JournalEntry');
+    const docs = await collection
+      .find({
+        skrType: this.currentSKRType,
+        schemaVersion: 2,
+        status: { $in: ['posted', 'finalized'] },
+        date: { $gte: options.dateFrom, $lte: options.dateTo },
+      })
+      .sort({ sequenceNumber: 1 })
+      .toArray();
+    const drafts: core.IJournalDraft[] = docs.map((doc) => ({
+      date: doc.date as Date,
+      description: doc.description as string,
+      reference: doc.reference as string,
+      skrType: doc.skrType as TSKRType,
+      currency: 'EUR',
+      taxScenario: doc.taxScenario as core.TTaxScenario | undefined,
+      lines: (doc.lines as core.IJournalLineDraft[]).map((line) => ({
+        accountNumber: line.accountNumber,
+        counterAccount: line.counterAccount ?? '',
+        side: (line.side ?? 'debit') as 'debit' | 'credit',
+        amountCents: line.amountCents ?? 0,
+        buKey: (line.buKey ?? '') as core.TBuKey,
+        buchungstext: line.buchungstext ?? '',
+        belegfeld1: line.belegfeld1,
+        costCenter1: line.costCenter1,
+        docLink: line.docLink,
+      })),
+    }));
+    const rows = core.journalDraftsToDatevRows(drafts, {
+      festschreibung: options.festschreibung,
+    });
+    const result = core.writeExtfBuchungsstapel(rows, {
+      createdAt: options.createdAt ?? new Date(),
+      consultantNumber: options.consultantNumber,
+      clientNumber: options.clientNumber,
+      fiscalYearStart: options.fiscalYearStart,
+      dateFrom: options.dateFrom,
+      dateTo: options.dateTo,
+      label: options.label ?? `Buchungsstapel ${options.dateFrom.toISOString().slice(0, 10)}`,
+      festschreibung: options.festschreibung ?? false,
+    });
+    return { ...result, rowCount: rows.length };
+  }
+
+  /**
+   * Run the idempotent v1 -> v2 data migration (cents backfill, journal
+   * unification, hash-chain assignment). Persist the returned report with
+   * your records (Verfahrensdokumentation artifact).
+   */
+  public async migrateToV2(): Promise<import('./skr.migrate.js').IMigrationReport> {
+    this.ensureInitialized();
+    const { migrateToV2 } = await import('./skr.migrate.js');
+    return migrateToV2();
+  }
+
   /**
    * Get current SKR type
    */
@@ -670,10 +1055,11 @@ export class SkrApi {
   /**
    * Get unbalanced transactions (for audit)
    */
-  public async getUnbalancedTransactions(): Promise<Transaction[]> {
+  public async getUnbalancedTransactions(): Promise<ITransactionView[]> {
     this.ensureInitialized();
-    if (!this.ledger) throw new Error('Ledger not initialized');
-    return await this.ledger.getUnbalancedTransactions();
+    // v2 posting enforces exact balance atomically — imbalance is impossible;
+    // chain integrity is checked via verifyAuditChain()
+    return [];
   }
 
   /**
@@ -695,10 +1081,10 @@ export class SkrApi {
    */
   public async postBatchTransactions(
     transactions: ITransactionData[],
-  ): Promise<Transaction[]> {
+  ): Promise<ITransactionView[]> {
     this.ensureInitialized();
 
-    const results: Transaction[] = [];
+    const results: ITransactionView[] = [];
     const errors: Array<{ index: number; error: string }> = [];
 
     for (let i = 0; i < transactions.length; i++) {
@@ -798,7 +1184,7 @@ export class SkrApi {
     pageSize: number = 50,
     filter?: ITransactionFilter,
   ): Promise<{
-    data: Transaction[];
+    data: ITransactionView[];
     total: number;
     page: number;
     pageSize: number;