accounted/lib/transactions/link-journal-entry.ts

/**
 * Link a bank transaction to an already-posted journal entry without creating
 * new bookkeeping. Optionally settle a customer invoice in the same call by
 * inserting an invoice_payments row pointing at the existing JE and flipping
 * the invoice status with an optimistic-lock pattern.
 *
 * Shared between two callers:
 *   - REST: app/api/transactions/[id]/link-journal-entry/route.ts
 *     (duplicate-payment UI: user confirms the suggested existing voucher)
 *   - MCP commit handler: lib/pending-operations/commit.ts
 *     (gnubok_link_transaction_to_journal_entry, agent-staged operation)
 *
 * NEVER creates a new journal entry. The match log records
 * 'linked_to_existing_voucher' for audit on success.
 */
import type { SupabaseClient } from '@supabase/supabase-js'
import { eventBus } from '@/lib/events/bus'
import { clearSettledInvoiceSuggestions } from '@/lib/invoices/clear-settled-invoice-suggestions'
import { logMatchEvent } from '@/lib/invoices/match-log'
import { createLogger } from '@/lib/logger'
import type { Invoice, Transaction } from '@/types'

const log = createLogger('transactions/link-journal-entry')

// Codes returned by linkTransactionToJournalEntry. All map to entries in
// lib/errors/structured-errors.ts so both callers (REST route, MCP commit
// handler) can surface the right HTTP status and the localized message.
// The TX-not-found case reuses the shared TX_CATEGORIZE_TX_NOT_FOUND code
// rather than a link-specific one: it predates this route and is the
// canonical "bank tx not found in this company" envelope.
export type LinkTransactionJournalEntryErrorCode =
  | 'TX_CATEGORIZE_TX_NOT_FOUND'
  | 'LINK_TX_TX_ALREADY_LINKED'
  | 'LINK_TX_JE_NOT_FOUND'
  | 'LINK_TX_JE_NOT_POSTED'
  | 'LINK_TX_INVOICE_NOT_FOUND'
  | 'LINK_TX_INVOICE_NOT_OPEN'
  | 'LINK_TX_INVOICE_CREDIT_NOTE'
  | 'LINK_TX_INVOICE_CURRENCY_MISMATCH'
  | 'LINK_TX_INVOICE_RACE'
  | 'MATCH_INVOICE_RECORD_PAYMENT_FAILED'
  | 'LINK_TX_DB_ERROR'

export interface LinkTransactionJournalEntryParams {
  transactionId: string
  journalEntryId: string
  invoiceId?: string
}

export interface LinkTransactionJournalEntryResult {
  transactionId: string
  journalEntryId: string
  voucherLabel: string
  invoiceId: string | null
  invoiceStatus: 'paid' | 'partially_paid' | null
  paidAmount: number | null
  remainingAmount: number | null
}

export type LinkTransactionJournalEntryOutcome =
  | { ok: true; result: LinkTransactionJournalEntryResult }
  | { ok: false; code: LinkTransactionJournalEntryErrorCode; details?: Record<string, unknown> }

/**
 * Canonical verifikat-label format: `${series}-${number}` (e.g. "A-12").
 * Centralised so the MCP staging preview and the committed result can't
 * diverge: divergence is a BFL 5 kap 7§ traceability hazard because the
 * verifikationsserie label that ends up in the audit trail must match the
 * label the user saw at approval time.
 *
 * Fallbacks ('A' series, empty number) are defensive only; in practice a
 * posted verifikat always has both. Callers should never construct this
 * string inline: import this helper instead.
 */
export function formatVoucherLabel(
  voucherSeries: string | null | undefined,
  voucherNumber: number | string | null | undefined,
): string {
  const series = voucherSeries ?? 'A'
  const num = voucherNumber ?? ''
  return num === '' ? series : `${series}-${num}`
}

/**
 * Is `journalEntryId` a LIVE link, i.e. does it reference a posted verifikat?
 *
 * A transaction can carry a non-null `journal_entry_id` that no longer points
 * at a live booking: reversing (storno) or correcting an entry marks the
 * original `reversed`, and while both flows try to detach or re-point the
 * transaction (engine.ts `reverseEntry`, storno-service `relinkTransactions-
 * ToEntry`), those re-links are best-effort and rows reversed before #726
 * (2026-06-15) were never touched at all. Such a transaction reads as "utan
 * koppling" in the UI: the transactions page enriches only `status='posted'`
 * links, so a reversed pointer renders as no link, yet the raw column is still
 * set.
 *
 * The "already linked" guards on the re-booking paths must mirror that same
 * posted-only predicate. If they treat any non-null pointer as linked, a
 * transaction the UI shows as free can never be re-linked or re-categorized
 * (issue #988). Returns true ONLY when the pointer references a posted entry;
 * null / missing / reversed / cancelled / draft all count as no live link, so
 * the caller may overwrite the stale pointer. Fails closed (returns true) on a
 * read error so a transient lookup blip can never detach a genuinely live link.
 */
export async function hasLiveJournalEntryLink(
  supabase: SupabaseClient,
  companyId: string,
  journalEntryId: string | null | undefined,
): Promise<boolean> {
  if (!journalEntryId) return false
  const { data, error } = await supabase
    .from('journal_entries')
    .select('status')
    .eq('id', journalEntryId)
    .eq('company_id', companyId)
    .maybeSingle()
  if (error) return true
  return data?.status === 'posted'
}

export async function linkTransactionToJournalEntry(
  supabase: SupabaseClient,
  userId: string,
  companyId: string,
  params: LinkTransactionJournalEntryParams
): Promise<LinkTransactionJournalEntryOutcome> {
  const { transactionId, journalEntryId, invoiceId } = params

  // Data minimization (GDPR Art.5(1)(c)): pull only the columns needed for
  // validation, optimistic-lock invoice update, invoice_payments insert, and
  // the compensating-rollback path. No select('*').
  const { data: transaction, error: fetchTxError } = await supabase
    .from('transactions')
    .select(
      'id, date, amount, currency, exchange_rate, journal_entry_id, invoice_id, is_business, potential_invoice_id, potential_supplier_invoice_id'
    )
    .eq('id', transactionId)
    .eq('company_id', companyId)
    .single()

  if (fetchTxError || !transaction) {
    return { ok: false, code: 'TX_CATEGORIZE_TX_NOT_FOUND' }
  }

  // Only a LIVE (posted) pointer blocks re-linking. A pointer left behind by a
  // storno/correction references a 'reversed' entry: the UI already shows the
  // row as "utan koppling", so the guard must agree and let the user re-link it
  // to another verifikat (issue #988). The stale pointer is overwritten by the
  // optimistic-locked UPDATE below.
  if (
    transaction.journal_entry_id &&
    (await hasLiveJournalEntryLink(supabase, companyId, transaction.journal_entry_id as string))
  ) {
    return {
      ok: false,
      code: 'LINK_TX_TX_ALREADY_LINKED',
      details: { existingJournalEntryId: transaction.journal_entry_id as string },
    }
  }

  const { data: journalEntry, error: fetchJeError } = await supabase
    .from('journal_entries')
    .select('id, status, voucher_series, voucher_number, entry_date')
    .eq('id', journalEntryId)
    .eq('company_id', companyId)
    .single()

  if (fetchJeError || !journalEntry) {
    return { ok: false, code: 'LINK_TX_JE_NOT_FOUND' }
  }

  if (journalEntry.status !== 'posted') {
    return {
      ok: false,
      code: 'LINK_TX_JE_NOT_POSTED',
      details: { currentStatus: journalEntry.status as string },
    }
  }

  type FetchedInvoice = Pick<
    Invoice,
    | 'id'
    | 'status'
    | 'total'
    | 'paid_amount'
    | 'remaining_amount'
    | 'currency'
    | 'exchange_rate'
    | 'paid_at'
    | 'invoice_number'
    | 'credited_invoice_id'
  > & { customer?: { name?: string } | null }
  let invoice: FetchedInvoice | null = null
  let newPaidAmount = 0
  let newRemaining = 0
  let isFullyPaid = false
  let newStatus: 'paid' | 'partially_paid' = 'paid'

  if (invoiceId) {
    // Data minimization (GDPR Art.5(1)(c) / SOC 2 CC6.1): explicit column
    // list rather than select('*, customer:customers(name)'). Adding new
    // PII columns to invoices won't silently widen this fetch.
    const { data: invoiceRow, error: fetchInvError } = await supabase
      .from('invoices')
      .select(
        'id, status, total, paid_amount, remaining_amount, currency, exchange_rate, paid_at, invoice_number, credited_invoice_id, customer:customers(name)'
      )
      .eq('id', invoiceId)
      .eq('company_id', companyId)
      .single()

    if (fetchInvError || !invoiceRow) {
      return { ok: false, code: 'LINK_TX_INVOICE_NOT_FOUND' }
    }

    if (invoiceRow.credited_invoice_id) {
      return { ok: false, code: 'LINK_TX_INVOICE_CREDIT_NOTE' }
    }

    if (
      invoiceRow.status !== 'sent' &&
      invoiceRow.status !== 'overdue' &&
      invoiceRow.status !== 'partially_paid'
    ) {
      return {
        ok: false,
        code: 'LINK_TX_INVOICE_NOT_OPEN',
        details: { currentStatus: invoiceRow.status as string },
      }
    }

    invoice = invoiceRow as unknown as FetchedInvoice

    // BFL 5 kap 2§ + currency-integrity guard: invoices.paid_amount and
    // remaining_amount are stored in the INVOICE'S currency. Mixing a
    // foreign-currency tx.amount into those columns silently corrupts the
    // ledger (a 230 SEK payment would record "230 USD paid" on a USD
    // invoice). This link path is for the same-currency case only;
    // cross-currency payments must go through /api/transactions/[id]/match-
    // invoice which routes through buildInvoicePaymentClearingLines and
    // posts the FX diff on 3960/7960. Reject here to keep the contract clear.
    if (transaction.currency !== invoice.currency) {
      return {
        ok: false,
        code: 'LINK_TX_INVOICE_CURRENCY_MISMATCH',
        details: {
          transactionCurrency: transaction.currency as string,
          invoiceCurrency: invoice.currency,
        },
      }
    }

    const paidAmount = transaction.amount as number
    newPaidAmount = Math.round(((invoice.paid_amount || 0) + paidAmount) * 100) / 100
    const currentRemaining =
      invoice.remaining_amount ?? invoice.total - (invoice.paid_amount || 0)
    newRemaining = Math.max(0, Math.round((currentRemaining - paidAmount) * 100) / 100)
    isFullyPaid = newRemaining <= 0
    newStatus = isFullyPaid ? 'paid' : 'partially_paid'
  }

  // Snapshot tx state so the compensating-rollback path can restore the row
  // if a subsequent step fails: otherwise a partial state would persist
  // (tx linked, invoice unchanged, no payment row).
  const priorTxState = {
    // null, or a stale 'reversed'-entry id we're clearing (validated not-live above)
    journal_entry_id: transaction.journal_entry_id,
    invoice_id: transaction.invoice_id,
    potential_invoice_id: transaction.potential_invoice_id,
    potential_supplier_invoice_id: transaction.potential_supplier_invoice_id,
    is_business: transaction.is_business,
  }

  // Optimistic lock on the pointer we validated: null for a free row, or the
  // exact stale id for one we're detaching from a reversed entry. Locking on
  // the known value (rather than always .is(null)) lets the stale-pointer
  // overwrite through while still turning a concurrent re-link into a no-op.
  const previousJournalEntryId = (transaction.journal_entry_id as string | null) ?? null
  const txUpdate = supabase
    .from('transactions')
    .update({
      journal_entry_id: journalEntryId,
      invoice_id: invoiceId ?? null,
      potential_invoice_id: null,
      potential_supplier_invoice_id: null,
      is_business: true,
    })
    .eq('id', transactionId)
    .eq('company_id', companyId)
  const { data: updatedTxRows, error: updateTxError } = await (previousJournalEntryId === null
    ? txUpdate.is('journal_entry_id', null)
    : txUpdate.eq('journal_entry_id', previousJournalEntryId)
  ).select('id')

  if (updateTxError) {
    return { ok: false, code: 'LINK_TX_DB_ERROR', details: { reason: updateTxError.message } }
  }
  // CAS lost: a concurrent linker changed the pointer between the liveness
  // check and this write, so 0 rows matched. Fail BEFORE any invoice side
  // effects: otherwise we'd settle the invoice + insert an invoice_payments row
  // for a transaction we didn't actually link (same optimistic-lock contract as
  // manualLink in lib/reconciliation/bank-reconciliation.ts).
  if (!updatedTxRows || updatedTxRows.length === 0) {
    return {
      ok: false,
      code: 'LINK_TX_TX_ALREADY_LINKED',
      details: { existingJournalEntryId: previousJournalEntryId },
    }
  }

  async function rollbackTxLink(reason: string): Promise<void> {
    // SOC 2 PI1.3 (processing integrity): if a rollback itself fails, the
    // ledger ends up in a partial state: tx pointing at the existing
    // verifikat with no invoice_payments row, or the invoice row at an
    // intermediate paid_amount. We surface the rollback failure (IDs only,
    // no amounts or counterparty names) so a reconciliation job can
    // detect and repair the divergence. The original failure code still
    // goes back to the caller as the proximate cause.
    const { error: rollbackErr } = await supabase
      .from('transactions')
      .update(priorTxState)
      .eq('id', transactionId)
      .eq('company_id', companyId)
    if (rollbackErr) {
      log.warn('failed to roll back transaction link after subsequent step failed', {
        companyId,
        transactionId,
        journalEntryId,
        reason,
        rollbackError: rollbackErr.message,
      })
    }
  }

  const now = new Date().toISOString()

  if (invoice && invoiceId) {
    const { data: updatedRows, error: updateInvError } = await supabase
      .from('invoices')
      .update({
        status: newStatus,
        paid_at: isFullyPaid ? now : null,
        paid_amount: newPaidAmount,
        remaining_amount: newRemaining,
      })
      .eq('id', invoiceId)
      .eq('company_id', companyId)
      .in('status', ['sent', 'overdue', 'partially_paid'])
      .select('id')

    if (updateInvError) {
      await rollbackTxLink('invoice update errored')
      return { ok: false, code: 'LINK_TX_DB_ERROR', details: { reason: updateInvError.message } }
    }

    if (!updatedRows || updatedRows.length === 0) {
      await rollbackTxLink('invoice optimistic lock returned 0 rows')
      return { ok: false, code: 'LINK_TX_INVOICE_RACE' }
    }

    // BFL 5 kap 2§ + ML 8 kap 21-23§: the payment row must record the rate
    // effective on the PAYMENT date, not the invoice-creation date. If
    // transaction.exchange_rate is null (SEK tx, no rate needed), leave the
    // payment row's rate null too: a downstream Riksbanken lookup can
    // populate it lazily if reporting needs it. Falling back to
    // invoice.exchange_rate would silently record the wrong (invoice-date)
    // rate, which corrupts the FX-diff figures in any later VAT or income
    // reporting.
    const paymentExchangeRate = transaction.exchange_rate ?? null

    const { error: paymentInsertError } = await supabase
      .from('invoice_payments')
      .insert({
        user_id: userId,
        company_id: companyId,
        invoice_id: invoiceId,
        payment_date: transaction.date,
        amount: transaction.amount,
        currency: invoice.currency,
        exchange_rate: paymentExchangeRate,
        journal_entry_id: journalEntryId,
        transaction_id: transactionId,
        notes: 'Kopplad till befintlig verifikation (ingen ny bokföring skapad)',
      })

    if (paymentInsertError && paymentInsertError.code !== '23505') {
      const { error: invRevertErr } = await supabase
        .from('invoices')
        .update({
          status: invoice.status,
          paid_at: invoice.paid_at ?? null,
          paid_amount: invoice.paid_amount ?? 0,
          remaining_amount: invoice.remaining_amount ?? invoice.total,
        })
        .eq('id', invoiceId)
        .eq('company_id', companyId)
      if (invRevertErr) {
        log.warn('failed to revert invoice status after payment insert failed', {
          companyId,
          invoiceId,
          rollbackError: invRevertErr.message,
        })
      }
      await rollbackTxLink('invoice_payments insert failed')
      return { ok: false, code: 'MATCH_INVOICE_RECORD_PAYMENT_FAILED' }
    }

    // The invoice is settled, so every transaction still carrying a suggestion
    // pointer at it is dead: retire them (issue #1259). No exceptTransactionId
    // needed: this row's own hints were already nulled by the tx update above,
    // so the invoice-id filter no longer selects it.
    if (isFullyPaid) {
      await clearSettledInvoiceSuggestions(supabase, companyId, 'invoice', invoiceId)
    }
  }

  logMatchEvent(supabase, userId, transactionId, 'linked_to_existing_voucher', {
    invoiceId,
    newState: {
      journal_entry_id: journalEntryId,
      invoice_id: invoiceId ?? null,
      invoice_status: invoice ? newStatus : null,
    },
  })

  if (invoice && invoiceId) {
    try {
      eventBus.emit({
        type: 'invoice.match_confirmed',
        payload: {
          invoice: invoice as Invoice,
          transaction: transaction as Transaction,
          userId,
          companyId,
        },
      })
    } catch {
      /* non-critical */
    }
  }

  const voucherLabel = formatVoucherLabel(
    journalEntry.voucher_series as string | null,
    journalEntry.voucher_number as number | null,
  )

  return {
    ok: true,
    result: {
      transactionId,
      journalEntryId,
      voucherLabel,
      invoiceId: invoiceId ?? null,
      invoiceStatus: invoice ? newStatus : null,
      paidAmount: invoice ? newPaidAmount : null,
      remainingAmount: invoice ? newRemaining : null,
    },
  }
}