@fin.cx/skr 1.3.0 → 2.0.0

package/ts/skr.balances.ts

@@ -0,0 +1,127 @@
+/**
+ * Balance computation for the v2 ledger: always aggregated from the
+ * journal, never incrementally stored. Exact integer cents throughout.
+ */
+import { getDbSync } from './skr.database.js';
+import { JOURNAL_ENTRY_COLLECTION } from './skr.period.js';
+import type { TSKRType } from './skr.types.js';
+
+export interface IAccountBalanceCents {
+  accountNumber: string;
+  debitCents: number;
+  creditCents: number;
+  /** debit - credit; sign interpretation belongs to the account type */
+  balanceCents: number;
+}
+
+export interface ITrialBalanceCents {
+  accounts: IAccountBalanceCents[];
+  totalDebitCents: number;
+  totalCreditCents: number;
+  isBalanced: boolean;
+}
+
+export interface IBalanceQueryOptions {
+  dateFrom?: Date;
+  dateTo?: Date;
+  /** include festgeschriebene entries (default true) */
+  includeFinalized?: boolean;
+}
+
+function entryMatch(skrType: TSKRType, options?: IBalanceQueryOptions): Record<string, unknown> {
+  const statuses = options?.includeFinalized === false ? ['posted'] : ['posted', 'finalized'];
+  const match: Record<string, unknown> = {
+    schemaVersion: 2,
+    skrType,
+    status: { $in: statuses },
+  };
+  if (options?.dateFrom || options?.dateTo) {
+    const range: Record<string, Date> = {};
+    if (options.dateFrom) range.$gte = options.dateFrom;
+    if (options.dateTo) range.$lte = options.dateTo;
+    match.date = range;
+  }
+  return match;
+}
+
+/**
+ * Aggregated trial balance over all schemaVersion-2 entries.
+ */
+export async function aggregateTrialBalance(
+  skrType: TSKRType,
+  options?: IBalanceQueryOptions,
+): Promise<ITrialBalanceCents> {
+  const collection = getDbSync().mongoDb.collection(JOURNAL_ENTRY_COLLECTION);
+  const rows = await collection
+    .aggregate<{ _id: string; debitCents: number; creditCents: number }>([
+      { $match: entryMatch(skrType, options) },
+      { $unwind: '$lines' },
+      {
+        $group: {
+          _id: '$lines.accountNumber',
+          debitCents: {
+            $sum: { $cond: [{ $eq: ['$lines.side', 'debit'] }, '$lines.amountCents', 0] },
+          },
+          creditCents: {
+            $sum: { $cond: [{ $eq: ['$lines.side', 'credit'] }, '$lines.amountCents', 0] },
+          },
+        },
+      },
+      { $sort: { _id: 1 } },
+    ])
+    .toArray();
+
+  const accounts: IAccountBalanceCents[] = rows.map((row) => ({
+    accountNumber: row._id,
+    debitCents: row.debitCents,
+    creditCents: row.creditCents,
+    balanceCents: row.debitCents - row.creditCents,
+  }));
+  const totalDebitCents = accounts.reduce((sum, account) => sum + account.debitCents, 0);
+  const totalCreditCents = accounts.reduce((sum, account) => sum + account.creditCents, 0);
+  return {
+    accounts,
+    totalDebitCents,
+    totalCreditCents,
+    isBalanced: totalDebitCents === totalCreditCents,
+  };
+}
+
+/**
+ * Exact balance of one account.
+ */
+export async function aggregateAccountBalance(
+  accountNumber: string,
+  skrType: TSKRType,
+  options?: IBalanceQueryOptions,
+): Promise<IAccountBalanceCents> {
+  const collection = getDbSync().mongoDb.collection(JOURNAL_ENTRY_COLLECTION);
+  const rows = await collection
+    .aggregate<{ _id: string; debitCents: number; creditCents: number }>([
+      { $match: { ...entryMatch(skrType, options), 'lines.accountNumber': accountNumber } },
+      { $unwind: '$lines' },
+      { $match: { 'lines.accountNumber': accountNumber } },
+      {
+        $group: {
+          _id: '$lines.accountNumber',
+          debitCents: {
+            $sum: { $cond: [{ $eq: ['$lines.side', 'debit'] }, '$lines.amountCents', 0] },
+          },
+          creditCents: {
+            $sum: { $cond: [{ $eq: ['$lines.side', 'credit'] }, '$lines.amountCents', 0] },
+          },
+        },
+      },
+    ])
+    .toArray();
+  const row = rows[0];
+  if (!row) {
+    return { accountNumber, debitCents: 0, creditCents: 0, balanceCents: 0 };
+  }
+  return {
+    accountNumber,
+    debitCents: row.debitCents,
+    creditCents: row.creditCents,
+    balanceCents: row.debitCents - row.creditCents,
+  };
+}

package/ts/skr.classes.journalentry.ts

@@ -12,10 +12,12 @@ import type {
   IJournalEntry,
   IJournalEntryLine,
 } from './skr.types.js';
+import { ImmutableEntryError } from './skr.errors.js';
 
 declare abstract class SmartDataDbDocBase {
-  public save(): Promise<void>;
-  public delete(): Promise<void>;
+  public creationStatus: 'db' | 'new' | 'mixed';
+  public save(opts?: { session?: any }): Promise<void>;
+  public delete(opts?: { session?: any }): Promise<void>;
   public static getInstance<T>(
     this: new (...args: any[]) => T,
     query: Record<string, any>,
@@ -72,7 +74,34 @@ export class JournalEntry extends SmartDataDbDoc {
 
   @svDb()
   @index()
-  public status!: 'draft' | 'posted' | 'reversed';
+  public status!: 'draft' | 'posted' | 'reversed' | 'finalized';
+
+  // --- schemaVersion 2: GoBD hash chain + Festschreibung ------------------
+  @svDb()
+  public schemaVersion?: number;
+
+  @svDb()
+  @index()
+  public sequenceNumber?: number;
+
+  @svDb()
+  public prevHash?: string;
+
+  @svDb()
+  public entryHash?: string;
+
+  @svDb()
+  public finalizedAt?: Date | null;
+
+  @svDb()
+  @index()
+  public reversalOf?: string;
+
+  @svDb()
+  public taxScenario?: string;
+
+  @svDb()
+  public currency?: string;
 
   @svDb()
   public transactionIds!: string[];
@@ -299,8 +328,14 @@ export class JournalEntry extends SmartDataDbDoc {
       }
     }
 
-    // Validate posting key consistency across all lines
-    const consistencyValidation = validatePostingKeyConsistency(this.lines);
+    // Validate posting key consistency across all lines (v1 numeric keys only;
+    // schemaVersion-2 lines carry string buKeys validated by the core)
+    const consistencyValidation = validatePostingKeyConsistency(
+      this.lines.filter(
+        (line): line is IJournalEntryLine & { postingKey: NonNullable<IJournalEntryLine['postingKey']> } =>
+          line.postingKey !== undefined,
+      ),
+    );
     if (!consistencyValidation.isValid) {
       validationErrors.push(...consistencyValidation.errors);
     }
@@ -439,6 +474,13 @@ export class JournalEntry extends SmartDataDbDoc {
   }
 
   public async beforeSave(): Promise<void> {
+    // GoBD immutability: once a hashed (schemaVersion 2) entry is persisted it
+    // must never change — corrections happen via Storno entries only.
+    // Festschreibung stamps bypass doc saves (raw updates outside the hash).
+    if (this.creationStatus === 'db' && this.entryHash) {
+      throw new ImmutableEntryError(this.id);
+    }
+
     // Normalize any negative amounts to the correct side
     this.sanitizeLines();
     // Recalculate totals before saving
@@ -457,4 +499,11 @@ export class JournalEntry extends SmartDataDbDoc {
       throw new Error('Journal entry must have at least one line');
     }
   }
+
+  public async delete(opts?: { session?: any }): Promise<void> {
+    if (this.entryHash) {
+      throw new ImmutableEntryError(this.id);
+    }
+    await super.delete(opts);
+  }
 }

package/ts/skr.classes.reports.ts

@@ -1,7 +1,8 @@
 import * as plugins from './plugins.js';
 import { Account } from './skr.classes.account.js';
-import { Transaction } from './skr.classes.transaction.js';
 import { Ledger } from './skr.classes.ledger.js';
+import * as core from './core/index.js';
+import { accountLineViews, loadDraftsForExport } from './skr.txview.js';
 import type {
   TSKRType,
   ITrialBalanceReport,
@@ -11,6 +12,7 @@ import type {
   IBalanceSheet,
   IBalanceSheetEntry,
   IReportParams,
+  ITransactionView,
 } from './skr.types.js';
 
 export class Reports {
@@ -49,26 +51,37 @@ export class Reports {
     let totalCredits = 0;
 
     for (const account of accounts) {
-      // Get balance for the period if specified
-      const balance = params?.dateTo
-        ? await this.ledger.getAccountBalance(
-            account.accountNumber,
-            params.dateTo,
-          )
-        : await this.ledger.getAccountBalance(account.accountNumber);
-
-      if (balance.debitTotal !== 0 || balance.creditTotal !== 0) {
+      // Per-account activity from the v2 (hashed) journal entries
+      const views = await accountLineViews(
+        account.accountNumber,
+        this.skrType,
+        params?.dateTo
+          ? { skrType: this.skrType, dateTo: params.dateTo }
+          : undefined,
+      );
+      let debitTotal = 0;
+      let creditTotal = 0;
+      for (const view of views) {
+        if (view.debitAccount === account.accountNumber) debitTotal += view.amount;
+        if (view.creditAccount === account.accountNumber) creditTotal += view.amount;
+      }
+      const signedBalance =
+        account.accountType === 'asset' || account.accountType === 'expense'
+          ? debitTotal - creditTotal
+          : creditTotal - debitTotal;
+
+      if (debitTotal !== 0 || creditTotal !== 0) {
         const entry: ITrialBalanceEntry = {
           accountNumber: account.accountNumber,
           accountName: account.accountName,
-          debitBalance: balance.debitTotal,
-          creditBalance: balance.creditTotal,
-          netBalance: balance.balance,
+          debitBalance: debitTotal,
+          creditBalance: creditTotal,
+          netBalance: signedBalance,
         };
 
         entries.push(entry);
-        totalDebits += balance.debitTotal;
-        totalCredits += balance.creditTotal;
+        totalDebits += debitTotal;
+        totalCredits += creditTotal;
       }
     }
 
@@ -342,48 +355,17 @@ export class Reports {
     account: Account,
     params?: IReportParams,
   ): Promise<number> {
-    let transactions = await Transaction.getTransactionsByAccount(
-      account.accountNumber,
-      this.skrType,
-    );
-
-    // Apply date filter if provided
-    if (params?.dateFrom || params?.dateTo) {
-      // Normalize dates for inclusive comparison
-      const dateFrom = params.dateFrom ? new Date(params.dateFrom) : null;
-      const dateTo = params.dateTo ? new Date(params.dateTo) : null;
-      
-      // Set dateFrom to start of day (00:00:00.000)
-      if (dateFrom) {
-        dateFrom.setHours(0, 0, 0, 0);
-      }
-      
-      // Set dateTo to end of day (23:59:59.999) for inclusive comparison
-      if (dateTo) {
-        dateTo.setHours(23, 59, 59, 999);
-      }
-      
-      transactions = transactions.filter((transaction) => {
-        const txDate = transaction.date instanceof Date 
-          ? transaction.date 
-          : new Date(transaction.date);
-        const txTime = txDate.getTime();
-        
-        if (dateFrom && txTime < dateFrom.getTime()) return false;
-        if (dateTo && txTime > dateTo.getTime()) return false;
-        return true;
-      });
-    }
+    // v2: per-account activity is projected from hashed journal entries
+    const views = await accountLineViews(account.accountNumber, this.skrType, params);
 
     let debitTotal = 0;
     let creditTotal = 0;
-
-    for (const transaction of transactions) {
-      if (transaction.debitAccount === account.accountNumber) {
-        debitTotal += transaction.amount;
+    for (const view of views) {
+      if (view.debitAccount === account.accountNumber) {
+        debitTotal += view.amount;
       }
-      if (transaction.creditAccount === account.accountNumber) {
-        creditTotal += transaction.amount;
+      if (view.creditAccount === account.accountNumber) {
+        creditTotal += view.amount;
       }
     }
 
@@ -489,44 +471,10 @@ export class Reports {
   private async getAccountTransactions(
     accountNumber: string,
     params?: IReportParams,
-  ): Promise<Transaction[]> {
-    let transactions = await Transaction.getTransactionsByAccount(
-      accountNumber,
-      this.skrType,
-    );
-
-    // Apply date filter
-    if (params?.dateFrom || params?.dateTo) {
-      // Normalize dates for inclusive comparison
-      const dateFrom = params.dateFrom ? new Date(params.dateFrom) : null;
-      const dateTo = params.dateTo ? new Date(params.dateTo) : null;
-      
-      // Set dateFrom to start of day (00:00:00.000)
-      if (dateFrom) {
-        dateFrom.setHours(0, 0, 0, 0);
-      }
-      
-      // Set dateTo to end of day (23:59:59.999) for inclusive comparison
-      if (dateTo) {
-        dateTo.setHours(23, 59, 59, 999);
-      }
-      
-      transactions = transactions.filter((transaction) => {
-        const txDate = transaction.date instanceof Date 
-          ? transaction.date 
-          : new Date(transaction.date);
-        const txTime = txDate.getTime();
-        
-        if (dateFrom && txTime < dateFrom.getTime()) return false;
-        if (dateTo && txTime > dateTo.getTime()) return false;
-        return true;
-      });
-    }
-
-    // Sort by date
-    transactions.sort((a, b) => a.date.getTime() - b.date.getTime());
-
-    return transactions;
+  ): Promise<ITransactionView[]> {
+    // v2: transaction-shaped line views from hashed journal entries,
+    // already date-filtered (inclusive day range) and sorted
+    return accountLineViews(accountNumber, this.skrType, params);
   }
 
   /**
@@ -744,41 +692,21 @@ export class Reports {
    * Export to DATEV format
    */
   public async exportToDATEV(params?: IReportParams): Promise<string> {
-    // DATEV format is specific to German accounting software
-    // This is a simplified implementation
-    const transactions = await Transaction.getInstances({
-      skrType: this.skrType,
-      status: 'posted',
+    // EXTF 700 / Formatversion 13 over the v2 (hashed) journal entries
+    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 drafts = await loadDraftsForExport(this.skrType, dateFrom, dateTo);
+    const rows = core.journalDraftsToDatevRows(drafts);
+    const { csv } = core.writeExtfBuchungsstapel(rows, {
+      createdAt: new Date(),
+      consultantNumber: 0,
+      clientNumber: 0,
+      fiscalYearStart: new Date(Date.UTC(dateFrom.getUTCFullYear(), 0, 1)),
+      dateFrom,
+      dateTo,
+      label: 'Buchungsstapel',
+      festschreibung: false,
     });
-
-    const lines: string[] = [];
-
-    // DATEV header
-    lines.push('EXTF;510;21;"Buchungsstapel";1;;;;;;;;;;;;;;');
-
-    for (const transaction of transactions) {
-      const date = transaction.date
-        .toISOString()
-        .split('T')[0]
-        .replace(/-/g, '');
-      const line = [
-        transaction.amount.toFixed(2).replace('.', ','),
-        'S',
-        'EUR',
-        '',
-        '',
-        transaction.debitAccount,
-        transaction.creditAccount,
-        '',
-        date,
-        '',
-        transaction.description.substring(0, 60),
-        '',
-      ].join(';');
-
-      lines.push(line);
-    }
-
-    return lines.join('\n');
+    return csv;
   }
 }

package/ts/skr.database.ts

@@ -3,6 +3,9 @@ import type { IDatabaseConfig } from './skr.types.js';
 
 let dbInstance: plugins.smartdata.SmartdataDb | null = null;
 
+/** MongoDB ClientSession type, derived from smartdata to avoid a direct mongodb dependency. */
+export type TDbSession = ReturnType<plugins.smartdata.SmartdataDb['startSession']>;
+
 export const getDb = async (
   config?: IDatabaseConfig,
 ): Promise<plugins.smartdata.SmartdataDb> => {

package/ts/skr.errors.ts

@@ -0,0 +1,44 @@
+/**
+ * Typed errors for the v2 posting path so callers can react precisely.
+ */
+
+export class ImmutableEntryError extends Error {
+  constructor(entryId: string) {
+    super(
+      `Journal entry ${entryId} is festgeschrieben (hashed) and immutable — corrections only via Storno entries`,
+    );
+    this.name = 'ImmutableEntryError';
+  }
+}
+
+export class PeriodLockedError extends Error {
+  constructor(skrType: string, period: string) {
+    super(`Period ${period} (${skrType}) is festgeschrieben — no further postings allowed`);
+    this.name = 'PeriodLockedError';
+  }
+}
+
+export class SequenceConflictError extends Error {
+  constructor(skrType: string, fiscalYear: number) {
+    super(
+      `Hash-chain head moved concurrently for ${skrType}/${fiscalYear} — transaction aborted`,
+    );
+    this.name = 'SequenceConflictError';
+  }
+}
+
+export class NotImplementedError extends Error {
+  constructor(feature: string) {
+    super(feature);
+    this.name = 'NotImplementedError';
+  }
+}
+
+export class TransactionsUnsupportedError extends Error {
+  constructor(detail: string) {
+    super(
+      `MongoDB deployment does not support transactions (replica set required) — filing-grade posting has no non-transactional fallback. ${detail}`,
+    );
+    this.name = 'TransactionsUnsupportedError';
+  }
+}

package/ts/skr.export.ts

@@ -1,5 +1,6 @@
 import * as plugins from './plugins.js';
 import * as path from 'path';
+import { createHash } from 'crypto';
 import type { IAccountData, ITransactionData, IJournalEntry, TSKRType } from './skr.types.js';
 
 export interface IExportOptions {
@@ -370,12 +371,8 @@ COMPLIANCE
       Buffer.from(hash, 'hex')
     );
     
-    // Create a sync hash function wrapper for MerkleTree
-    const hashFn = (data: Buffer) => {
-      // Convert async to sync by using crypto directly
-      const crypto = require('crypto');
-      return crypto.createHash('sha256').update(data).digest();
-    };
+    // Sync SHA-256 for MerkleTree (ESM import — require() is unavailable here)
+    const hashFn = (data: Buffer) => createHash('sha256').update(data).digest();
     
     const tree = new plugins.MerkleTree(leaves, hashFn, {
       sortPairs: true