feat(reconciliation): three doors over one engine: dashboard routes, v1 API and MCP tools (#1833)
* feat(reconciliation): skattekonto bridge engine, sync-time twin proposals, account-keyed facade The engine half of the reconciliation page (design: Avstämningsmotorn). - lib/reconciliation/skattekonto-reconciliation.ts: getSkattekontoReconciliationStatus anchors at the saldo snapshot and returns the bridge (saldo hos Skatteverket, händelser som saknas, 1630-rader utan händelse, ignorerade, ingående skillnad, bokfört), the item buckets the page shows (proposed, unmatched external, unmatched ledger, matched, ignored, upcoming), opening_difference, unexplained_difference (0,00 by construction when data is consistent), dead-link handling (a link to a reversed/draft entry counts as unlinked and is flagged), awaiting_external for ledger lines within 5 days of the snapshot, staleness, and a window that scopes item lists without hiding older rows. Core reads skattekonto_transactions and the extension's snapshot row directly; no @/extensions import. - lib/reconciliation/gl-balance.ts: one ledger-balance helper with the trial-balance predicate status IN (posted, reversed). The drift check summed posted only, which misstated 1630 for any company with a storno on the account; skattekonto-drift.ts now delegates to the helper. - Proposals at sync: migration 20260823120000 adds suggested_journal_entry_id / suggested_at (ON DELETE SET NULL, partial index on open rows); the sync calls refreshSkattekontoProposals after the upsert. findMatchSuggestionsBulk now assigns one-to-one across rows (AGI period first, then nearest date) and falls back to an entry whose 1630 lines net to the amount (split lines); a proposal is never a link. - lib/reconciliation/service.ts + schemas.ts: the account-keyed facade (bank:<cash_account_id> | skattekonto | manual:NNNN) with listReconciliationAccounts (enabled cash accounts folded per IBAN, skattekonto when configured) and getAccountStatus dispatching to the bank engine or the new one; shared Zod shapes for the v1 registry, MCP schemas and the UI (PR 2). Tests: identity on a mixed fixture, storno pair, stale snapshot, awaiting window, window scoping, failed ledger read, live-linked entries never proposed; matcher one-to-one and split-line cases; proposal refresh writes/clears; service dedupe and dispatch. No UI in this PR. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(reconciliation): roundOre instead of inline öre rounding (guard ratchet) The antipattern ratchet counts Math.round(x*100)/100; the new engine used it in five places. Switch to roundOre from @/lib/money and ratchet the baseline down by the three occurrences this removes net of the matcher rewrite. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(reconciliation): three doors over one engine: dashboard routes, v1 API and MCP tools for account-keyed reconciliation PR 2 of the Avstämning build (design: Avstämning via API och MCP). Every door calls lib/reconciliation/{service,items,actions}.ts; none re-implements a link. - lib/reconciliation/items.ts: listAccountItems per account_key, the page's buckets (proposed, unmatched_external, unmatched_ledger, matched, ignored, upcoming), limit/offset; skattekonto from the engine, bank from the scoped transactions + unlinked GL lines (netted per entry). - lib/reconciliation/actions.ts: matchPairs (pairs or use_proposals, dry run, partial success with codes), unmatchLink, setItemIgnored; emits reconciliation.matched / reconciliation.unmatched. - lib/skatteverket/skattekonto-link.ts: canonical core link semantics for a skattekonto row (single line or entry net on 1630, live-link guard, race-safe update, unlink, ignore); the extension keeps its own matchSkattekontoToEntry until its tests are ported. - Dashboard routes /api/reconciliation/accounts[...]: list, status, items, links (POST), links/{linkId} (DELETE), items/{itemId}/ignore (POST); apply directly (a human clicked). - v1 routes /api/v1/companies/{id}/reconciliation/accounts[...]: same six, withApiV1, new scopes reconciliation:read / reconciliation:write (write is a staging scope for SoD), Idempotency-Key + dry_run on writes, registered for OpenAPI, load-routes, skills/accounted-api regenerated. Legacy bank routes and their transactions:* scopes unchanged. - MCP: gnubok_get_reconciliation_status takes account_key (legacy bank path untouched), new gnubok_list_reconciliation_items (default catalog), gnubok_reconcile_match (stages reconciliation_match, preflight = status) and gnubok_reconcile_unmatch (stages reconciliation_unmatch), both search-only to stay under the tools/list payload ceiling; gnubok_link_transaction_to_journal_entry moved to search. Executors in commit.ts; risk tiers medium/low; migration pair 20260823130000/130001 adds the two op types to the CHECK constraint (value list = live prod as of 2026-08-23 + the two); close_period loadout updated. Tests: service/actions/items/link unit tests, v1 route tests (401/403/400/404/ happy, idempotency, dry run), dashboard route tests, MCP tool tests + the guard suite (payload ceiling, descriptions, staging meta, qualified ids). Guards and apiskill:check green; no type errors in changed files. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(reconciliation): refresh the v1 spec snapshot and keep the ignore update readable by the phantom-column guard The six new v1 reconciliation endpoints and the two new scopes were not recorded in the spec snapshot, and setSkattekontoRowIgnored updated through one conditional payload, which the phantom-column scanner cannot read (ceiling 380 -> 381). Two literal payloads instead; snapshot updated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Jakob Wennberg
co-authored by
Claude Fable 5
Jakob Wennberg
Claude Fable 5
Jakob Wennberg
parent
0a8544e0cb
commit
3a62c5419e
@@ -0,0 +1,235 @@
|
||||
import type { SupabaseClient } from '@supabase/supabase-js'
|
||||
import { roundOre } from '@/lib/money'
|
||||
import { fetchUnlinkedGLLines, scopeTransactionsToAccount } from './bank-reconciliation'
|
||||
import { getSkattekontoReconciliationStatus } from './skattekonto-reconciliation'
|
||||
import {
|
||||
parseAccountKey,
|
||||
type ReconciliationItem,
|
||||
type ReconciliationItemBucket,
|
||||
} from './schemas'
|
||||
|
||||
/**
|
||||
* Item listing for one account, in the page's buckets, paginated with
|
||||
* limit/offset (the MCP convention; the v1 door wraps this in its cursor).
|
||||
*
|
||||
* Skattekonto items come straight from the engine (which already buckets
|
||||
* and windows them). Bank items are built from the same sources the bank
|
||||
* page uses: the account-scoped transactions for the external side and the
|
||||
* unlinked-GL-lines RPC for the ledger side; the bank matcher's proposals are
|
||||
* the rows carrying potential_journal_entry_id.
|
||||
*/
|
||||
|
||||
export const DEFAULT_ITEMS_LIMIT = 50
|
||||
export const MAX_ITEMS_LIMIT = 200
|
||||
|
||||
/** Bucket order when no bucket is requested: what to do first, first. */
|
||||
export const BUCKET_ORDER: readonly ReconciliationItemBucket[] = [
|
||||
'proposed',
|
||||
'unmatched_external',
|
||||
'unmatched_ledger',
|
||||
'ignored',
|
||||
'upcoming',
|
||||
'matched',
|
||||
]
|
||||
|
||||
export interface ListItemsOptions {
|
||||
bucket?: ReconciliationItemBucket
|
||||
windowFrom?: string | null
|
||||
windowTo?: string | null
|
||||
limit?: number
|
||||
offset?: number
|
||||
today?: string
|
||||
}
|
||||
|
||||
export interface ListItemsResult {
|
||||
items: ReconciliationItem[]
|
||||
count: number
|
||||
total_count: number
|
||||
has_more: boolean
|
||||
next_offset?: number
|
||||
/** Unmatched rows dated before windowFrom (never hidden, only counted). */
|
||||
older_unmatched_count: number
|
||||
}
|
||||
|
||||
interface CashAccountRow {
|
||||
id: string
|
||||
ledger_account: string
|
||||
currency: string | null
|
||||
is_primary: boolean | null
|
||||
}
|
||||
|
||||
interface BankTxRow {
|
||||
id: string
|
||||
date: string
|
||||
description: string | null
|
||||
merchant_name: string | null
|
||||
amount: number | string
|
||||
currency: string
|
||||
journal_entry_id: string | null
|
||||
potential_journal_entry_id: string | null
|
||||
potential_match_method: string | null
|
||||
potential_match_confidence: number | string | null
|
||||
is_ignored: boolean | null
|
||||
reconciliation_method: string | null
|
||||
}
|
||||
|
||||
function clampLimit(limit?: number): number {
|
||||
if (!limit || !Number.isFinite(limit) || limit < 1) return DEFAULT_ITEMS_LIMIT
|
||||
return Math.min(Math.floor(limit), MAX_ITEMS_LIMIT)
|
||||
}
|
||||
|
||||
function page<T>(all: T[], limit: number, offset: number): ListItemsResult & { items: T[] } {
|
||||
const items = all.slice(offset, offset + limit)
|
||||
const hasMore = offset + limit < all.length
|
||||
return {
|
||||
items,
|
||||
count: items.length,
|
||||
total_count: all.length,
|
||||
has_more: hasMore,
|
||||
...(hasMore ? { next_offset: offset + limit } : {}),
|
||||
older_unmatched_count: 0,
|
||||
} as ListItemsResult & { items: T[] }
|
||||
}
|
||||
|
||||
export async function listAccountItems(
|
||||
supabase: SupabaseClient,
|
||||
companyId: string,
|
||||
accountKey: string,
|
||||
options: ListItemsOptions = {},
|
||||
): Promise<ListItemsResult | null> {
|
||||
const parsed = parseAccountKey(accountKey)
|
||||
if (!parsed) return null
|
||||
const limit = clampLimit(options.limit)
|
||||
const offset = Math.max(0, Math.floor(options.offset ?? 0))
|
||||
|
||||
if (parsed.kind === 'skattekonto') {
|
||||
const status = await getSkattekontoReconciliationStatus(supabase, companyId, {
|
||||
today: options.today,
|
||||
windowFrom: options.windowFrom ?? null,
|
||||
windowTo: options.windowTo ?? null,
|
||||
})
|
||||
if (!status) return null
|
||||
const all = options.bucket
|
||||
? status.items[options.bucket]
|
||||
: BUCKET_ORDER.flatMap((b) => status.items[b])
|
||||
return { ...page(all, limit, offset), older_unmatched_count: status.older_unmatched_count }
|
||||
}
|
||||
|
||||
if (parsed.kind === 'bank') {
|
||||
const { data: account, error } = await supabase
|
||||
.from('cash_accounts')
|
||||
.select('id, ledger_account, currency, is_primary')
|
||||
.eq('company_id', companyId)
|
||||
.eq('id', parsed.cashAccountId)
|
||||
.maybeSingle<CashAccountRow>()
|
||||
if (error) throw new Error(`Kunde inte hämta kassakonto: ${error.message}`)
|
||||
if (!account) return null
|
||||
const currency = account.currency ?? 'SEK'
|
||||
const buckets = options.bucket ? [options.bucket] : [...BUCKET_ORDER]
|
||||
const byBucket = new Map<ReconciliationItemBucket, ReconciliationItem[]>()
|
||||
const push = (item: ReconciliationItem) => {
|
||||
byBucket.set(item.bucket, [...(byBucket.get(item.bucket) ?? []), item])
|
||||
}
|
||||
|
||||
const wantsExternal = buckets.some((b) =>
|
||||
['proposed', 'unmatched_external', 'matched', 'ignored'].includes(b),
|
||||
)
|
||||
if (wantsExternal) {
|
||||
let query = supabase
|
||||
.from('transactions')
|
||||
.select(
|
||||
'id, date, description, merchant_name, amount, currency, journal_entry_id, potential_journal_entry_id, potential_match_method, potential_match_confidence, is_ignored, reconciliation_method',
|
||||
)
|
||||
.eq('company_id', companyId)
|
||||
query = scopeTransactionsToAccount(query, account.id, currency, Boolean(account.is_primary))
|
||||
if (options.windowFrom) query = query.gte('date', options.windowFrom)
|
||||
if (options.windowTo) query = query.lte('date', options.windowTo)
|
||||
const { data, error: txError } = await query.order('date', { ascending: false }).order('id', { ascending: true })
|
||||
if (txError) throw new Error(`Kunde inte hämta transaktioner: ${txError.message}`)
|
||||
const rows = (data ?? []) as BankTxRow[]
|
||||
{
|
||||
for (const tx of rows) {
|
||||
const bucket: ReconciliationItemBucket = tx.is_ignored
|
||||
? 'ignored'
|
||||
: tx.journal_entry_id
|
||||
? 'matched'
|
||||
: tx.potential_journal_entry_id
|
||||
? 'proposed'
|
||||
: 'unmatched_external'
|
||||
if (!buckets.includes(bucket)) continue
|
||||
push({
|
||||
item_id: tx.id,
|
||||
item_type: 'transaction',
|
||||
side: 'external',
|
||||
bucket,
|
||||
date: tx.date,
|
||||
description: tx.merchant_name || tx.description || '',
|
||||
amount: roundOre(Number(tx.amount)),
|
||||
currency: tx.currency,
|
||||
linked_journal_entry_id: tx.journal_entry_id,
|
||||
proposal: tx.potential_journal_entry_id
|
||||
? {
|
||||
journal_entry_id: tx.potential_journal_entry_id,
|
||||
voucher_number: null,
|
||||
voucher_series: null,
|
||||
entry_date: tx.date,
|
||||
description: '',
|
||||
entry_status: 'posted',
|
||||
confidence: Number(tx.potential_match_confidence ?? 0.75),
|
||||
reasons: [tx.potential_match_method ?? 'föreslagen av matcharen'],
|
||||
}
|
||||
: null,
|
||||
actions:
|
||||
bucket === 'matched'
|
||||
? ['unmatch']
|
||||
: bucket === 'ignored'
|
||||
? ['unignore']
|
||||
: bucket === 'proposed'
|
||||
? ['match', 'book', 'ignore']
|
||||
: ['book', 'match', 'ignore'],
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (buckets.includes('unmatched_ledger')) {
|
||||
const lines = await fetchUnlinkedGLLines(
|
||||
supabase,
|
||||
companyId,
|
||||
account.ledger_account,
|
||||
options.windowFrom ?? undefined,
|
||||
options.windowTo ?? undefined,
|
||||
)
|
||||
// One item per entry: several 1930 lines of one voucher net, as a link settles the voucher.
|
||||
const byEntry = new Map<string, ReconciliationItem>()
|
||||
for (const l of lines) {
|
||||
const amount = roundOre(Number(l.debit_amount || 0) - Number(l.credit_amount || 0))
|
||||
const existing = byEntry.get(l.journal_entry_id)
|
||||
if (existing) {
|
||||
existing.amount = roundOre(existing.amount + amount)
|
||||
continue
|
||||
}
|
||||
byEntry.set(l.journal_entry_id, {
|
||||
item_id: l.journal_entry_id,
|
||||
item_type: 'journal_entry',
|
||||
side: 'ledger',
|
||||
bucket: 'unmatched_ledger',
|
||||
date: l.entry_date,
|
||||
description: l.entry_description || l.line_description || '',
|
||||
amount,
|
||||
currency,
|
||||
voucher_number: l.voucher_number,
|
||||
voucher_series: l.voucher_series,
|
||||
entry_status: 'posted',
|
||||
actions: ['match', 'review'],
|
||||
})
|
||||
}
|
||||
for (const it of byEntry.values()) push(it)
|
||||
}
|
||||
|
||||
const all = buckets.flatMap((b) => byBucket.get(b) ?? [])
|
||||
return page(all, limit, offset)
|
||||
}
|
||||
|
||||
return null
|
||||
}
|
||||
Reference in New Issue
Block a user