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
@@ -167,6 +167,12 @@ import {
|
||||
import { assertNoPlaintextPersonnummer } from './staging-pii-guard'
|
||||
import { generateBalanceSheet } from '@/lib/reports/balance-sheet'
|
||||
import { generateGeneralLedger } from '@/lib/reports/general-ledger'
|
||||
// Account-keyed reconciliation (one engine, three doors): the same service
|
||||
// the dashboard routes and the v1 API call.
|
||||
import { getAccountStatus } from '@/lib/reconciliation/service'
|
||||
import { listAccountItems } from '@/lib/reconciliation/items'
|
||||
import { matchPairs } from '@/lib/reconciliation/actions'
|
||||
import { parseAccountKey, type ReconciliationItemBucket } from '@/lib/reconciliation/schemas'
|
||||
import { decryptPersonnummer, maskEmployeeForResponse, maskPersonnummer } from '@/lib/salary/personnummer'
|
||||
import {
|
||||
deriveAgiFilingState,
|
||||
@@ -1358,6 +1364,7 @@ const TOOL_PREFLIGHT_MAP: Record<string, string> = {
|
||||
gnubok_vat_declaration_submit: 'gnubok_vat_declaration_validate',
|
||||
gnubok_post_annual_depreciation: 'gnubok_propose_annual_depreciation',
|
||||
gnubok_book_salary_run: 'gnubok_get_salary_run',
|
||||
gnubok_reconcile_match: 'gnubok_get_reconciliation_status',
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -8665,6 +8672,10 @@ export const tools: McpTool[] = [
|
||||
{
|
||||
name: 'gnubok_link_transaction_to_journal_entry',
|
||||
title: 'Link Transaction to Verifikat',
|
||||
// Search-only since the account-keyed gnubok_reconcile_match covers the
|
||||
// same link (one pair) for bank AND skattekonto; kept callable for clients
|
||||
// that already use it, and reachable via gnubok_search_tools.
|
||||
catalogVisibility: 'search',
|
||||
description: 'Link 1 bank tx to an already-posted verifikat (no new bokföring). Use when the user booked the affärshändelse manually. Pass invoice_id to also settle a kundfaktura. Stages.',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
@@ -9794,17 +9805,21 @@ export const tools: McpTool[] = [
|
||||
|
||||
{
|
||||
name: 'gnubok_get_reconciliation_status',
|
||||
title: 'Bank Reconciliation Status',
|
||||
description: 'Bank reconciliation for one cash account: matched/unmatched counts and totals. Judge health on unexplained_difference, not difference (large mid-year by design). Defaults to 1930, else the primary cash account; pass account_number for 1940/1932. Optional date range.',
|
||||
title: 'Reconciliation Status',
|
||||
description: 'Reconciliation bridge for one account. Pass account_key ("skattekonto" or "bank:<cash_account_id>") for bridge lines + counts; without it, the legacy bank status for account_number (default 1930). Judge health on unexplained_difference, not difference.',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
additionalProperties: false,
|
||||
properties: {
|
||||
account_key: {
|
||||
type: 'string',
|
||||
description: '"skattekonto" or "bank:<cash_account_id>". When set, returns the account-keyed status (bridge[], counts, kind block).',
|
||||
},
|
||||
date_from: { type: 'string', description: 'Start date YYYY-MM-DD' },
|
||||
date_to: { type: 'string', description: 'End date YYYY-MM-DD' },
|
||||
account_number: {
|
||||
type: 'string',
|
||||
description: 'Cash-account BAS code to reconcile, e.g. "1940". Defaults to "1930".',
|
||||
description: 'Legacy: cash-account BAS code to reconcile, e.g. "1940". Defaults to "1930". Ignored when account_key is set.',
|
||||
},
|
||||
},
|
||||
},
|
||||
@@ -9818,6 +9833,21 @@ export const tools: McpTool[] = [
|
||||
async execute(args, companyId, userId, supabase) {
|
||||
const dateFrom = args.date_from as string | undefined
|
||||
const dateTo = args.date_to as string | undefined
|
||||
const accountKey = args.account_key as string | undefined
|
||||
|
||||
if (accountKey) {
|
||||
const status = await getAccountStatus(supabase, companyId, accountKey, {
|
||||
windowFrom: dateFrom ?? null,
|
||||
windowTo: dateTo ?? null,
|
||||
})
|
||||
if (!status) throw new Error(`Unknown account_key "${accountKey}" for this company`)
|
||||
// The skattekonto engine also returns its item lists; this tool is the
|
||||
// bridge. Items live in gnubok_list_reconciliation_items.
|
||||
const { items: _items, ...rest } = status as typeof status & { items?: unknown }
|
||||
void _items
|
||||
return rest
|
||||
}
|
||||
|
||||
// Passed through as-is, undefined included: an omitted account_number is
|
||||
// "the company's bank account", which resolves to 1930 and, for a company
|
||||
// with no 1930 row, to its primary cash account. Substituting a literal
|
||||
@@ -9835,6 +9865,204 @@ export const tools: McpTool[] = [
|
||||
},
|
||||
},
|
||||
|
||||
{
|
||||
name: 'gnubok_list_reconciliation_items',
|
||||
title: 'Reconciliation Items',
|
||||
description: 'Rows behind one account\'s reconciliation bridge, bucketed (proposed, unmatched_external, unmatched_ledger, matched, ignored, upcoming): side, qualified id, amount, proposal with confidence + reasons, allowed actions. Link via gnubok_reconcile_match (search).',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
additionalProperties: false,
|
||||
properties: {
|
||||
account_key: { type: 'string', description: '"skattekonto" or "bank:<cash_account_id>".' },
|
||||
bucket: {
|
||||
type: 'string',
|
||||
enum: ['proposed', 'unmatched_external', 'unmatched_ledger', 'matched', 'ignored', 'upcoming'],
|
||||
},
|
||||
date_from: { type: 'string', description: 'YYYY-MM-DD; scopes lists, never counts' },
|
||||
date_to: { type: 'string', description: 'YYYY-MM-DD' },
|
||||
limit: { type: 'number', description: 'Default 50, max 200' },
|
||||
offset: { type: 'number' },
|
||||
},
|
||||
required: ['account_key'],
|
||||
},
|
||||
outputSchema: paginatedSchema('items', {
|
||||
type: 'object',
|
||||
properties: {
|
||||
item_id: { type: 'string' },
|
||||
item_type: { type: 'string' },
|
||||
side: { type: 'string' },
|
||||
bucket: { type: 'string' },
|
||||
amount: { type: 'number' },
|
||||
proposal: { type: ['object', 'null'] },
|
||||
actions: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}),
|
||||
annotations: {
|
||||
readOnlyHint: true,
|
||||
destructiveHint: false,
|
||||
idempotentHint: true,
|
||||
openWorldHint: false,
|
||||
},
|
||||
async execute(args, companyId, userId, supabase) {
|
||||
const accountKey = args.account_key as string
|
||||
const result = await listAccountItems(supabase, companyId, accountKey, {
|
||||
bucket: args.bucket as ReconciliationItemBucket | undefined,
|
||||
windowFrom: (args.date_from as string | undefined) ?? null,
|
||||
windowTo: (args.date_to as string | undefined) ?? null,
|
||||
limit: args.limit as number | undefined,
|
||||
offset: args.offset as number | undefined,
|
||||
})
|
||||
if (!result) throw new Error(`Unknown account_key "${accountKey}" for this company`)
|
||||
return result
|
||||
},
|
||||
},
|
||||
|
||||
{
|
||||
name: 'gnubok_reconcile_match',
|
||||
title: 'Reconcile: Link Pairs',
|
||||
description: 'Link outside rows (bank or skattekonto) to existing verifikat on one account; no new bokföring. Pass pairs, or use_proposals to apply the persisted proposals. Stages. dry_run previews.',
|
||||
// Search-only to stay under the tools/list payload ceiling: the default
|
||||
// catalog carries the reads (status + items); this write is reached via
|
||||
// gnubok_search_tools, the close_period loadout and the items tool's hint.
|
||||
catalogVisibility: 'search',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
additionalProperties: false,
|
||||
properties: {
|
||||
account_key: { type: 'string', description: '"skattekonto" or "bank:<cash_account_id>"' },
|
||||
pairs: {
|
||||
type: 'array',
|
||||
description: 'One outside row id + one journal_entry_id per pair',
|
||||
items: {
|
||||
type: 'object',
|
||||
additionalProperties: false,
|
||||
properties: {
|
||||
external_ids: { type: 'array', items: { type: 'string' } },
|
||||
journal_entry_ids: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
required: ['external_ids', 'journal_entry_ids'],
|
||||
},
|
||||
},
|
||||
use_proposals: { type: 'boolean' },
|
||||
confidence_threshold: { type: 'number', description: 'Default 0.9' },
|
||||
dry_run: { type: 'boolean' },
|
||||
idempotency_key: { type: 'string' },
|
||||
},
|
||||
required: ['account_key'],
|
||||
},
|
||||
outputSchema: STAGED_OPERATION_SCHEMA,
|
||||
annotations: {
|
||||
readOnlyHint: false,
|
||||
destructiveHint: false,
|
||||
idempotentHint: false,
|
||||
openWorldHint: false,
|
||||
},
|
||||
async execute(args, companyId, userId, supabase, actor) {
|
||||
const accountKey = args.account_key as string
|
||||
const pairs = (args.pairs as Array<{ external_ids: string[]; journal_entry_ids: string[] }> | undefined) ?? []
|
||||
const useProposals = args.use_proposals === true
|
||||
if (pairs.length === 0 && !useProposals) {
|
||||
throw new Error('Pass pairs, or use_proposals: true')
|
||||
}
|
||||
const confidenceThreshold =
|
||||
typeof args.confidence_threshold === 'number' ? (args.confidence_threshold as number) : 0.9
|
||||
|
||||
// Resolve and validate at stage time so the reviewer sees exactly which
|
||||
// pairs will be linked; the commit executor re-validates every pair.
|
||||
const preview = await matchPairs(
|
||||
supabase,
|
||||
companyId,
|
||||
userId,
|
||||
accountKey,
|
||||
{ pairs, use_proposals: useProposals, confidence_threshold: confidenceThreshold },
|
||||
{ dryRun: true },
|
||||
)
|
||||
if (!preview) throw new Error(`Unknown account_key "${accountKey}" for this company`)
|
||||
const resolvedPairs = preview.applied.map((a) => ({
|
||||
external_ids: [a.external_id],
|
||||
journal_entry_ids: [a.journal_entry_id],
|
||||
}))
|
||||
if (resolvedPairs.length === 0) {
|
||||
throw new Error('No linkable pairs: nothing to stage')
|
||||
}
|
||||
|
||||
return stagePendingOperation(
|
||||
supabase,
|
||||
companyId,
|
||||
userId,
|
||||
'reconciliation_match',
|
||||
`Koppla ${resolvedPairs.length} rad(er) på ${accountKey}`,
|
||||
{ account_key: accountKey, pairs: resolvedPairs },
|
||||
{
|
||||
account_key: accountKey,
|
||||
pair_count: resolvedPairs.length,
|
||||
pairs: resolvedPairs,
|
||||
skipped_at_stage: preview.skipped,
|
||||
source: useProposals ? 'proposals' : 'explicit',
|
||||
},
|
||||
actor,
|
||||
{
|
||||
description: 'After approval, re-read the bridge to confirm the residual.',
|
||||
tool: 'gnubok_get_reconciliation_status',
|
||||
args: { account_key: accountKey },
|
||||
},
|
||||
{
|
||||
dryRun: args.dry_run === true,
|
||||
idempotencyKey: args.idempotency_key as string | undefined,
|
||||
},
|
||||
)
|
||||
},
|
||||
},
|
||||
|
||||
{
|
||||
name: 'gnubok_reconcile_unmatch',
|
||||
title: 'Reconcile: Unlink',
|
||||
description: 'Remove the link between one outside row (bank transaction or skattekonto row) and its verifikat on an account. The verifikat is untouched. Stages (low risk).',
|
||||
catalogVisibility: 'search',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
additionalProperties: false,
|
||||
properties: {
|
||||
account_key: { type: 'string', description: '"skattekonto" or "bank:<cash_account_id>".' },
|
||||
external_id: { type: 'string', description: 'The linked outside row id (transaction_id or skattekonto_transaction_id).' },
|
||||
dry_run: { type: 'boolean' },
|
||||
idempotency_key: { type: 'string' },
|
||||
},
|
||||
required: ['account_key', 'external_id'],
|
||||
},
|
||||
outputSchema: STAGED_OPERATION_SCHEMA,
|
||||
annotations: {
|
||||
readOnlyHint: false,
|
||||
destructiveHint: false,
|
||||
idempotentHint: true,
|
||||
openWorldHint: false,
|
||||
},
|
||||
async execute(args, companyId, userId, supabase, actor) {
|
||||
const accountKey = args.account_key as string
|
||||
const externalId = args.external_id as string
|
||||
if (!parseAccountKey(accountKey)) throw new Error(`Invalid account_key "${accountKey}"`)
|
||||
return stagePendingOperation(
|
||||
supabase,
|
||||
companyId,
|
||||
userId,
|
||||
'reconciliation_unmatch',
|
||||
`Koppla bort rad ${externalId} på ${accountKey}`,
|
||||
{ account_key: accountKey, external_id: externalId },
|
||||
{ account_key: accountKey, external_id: externalId },
|
||||
actor,
|
||||
{
|
||||
description: 'After approval, the row is back in the open buckets.',
|
||||
tool: 'gnubok_list_reconciliation_items',
|
||||
args: { account_key: accountKey, bucket: 'unmatched_external' },
|
||||
},
|
||||
{
|
||||
dryRun: args.dry_run === true,
|
||||
idempotencyKey: args.idempotency_key as string | undefined,
|
||||
},
|
||||
)
|
||||
},
|
||||
},
|
||||
|
||||
|
||||
{
|
||||
name: 'gnubok_list_cash_accounts',
|
||||
|
||||
Reference in New Issue
Block a user