feat(rot-rut): overview page, beslutsfil import, avslag reclaim, MCP list + settle (#2397)

* feat(rot-rut): overview page, beslutsfil import, avslag reclaim, MCP list + settle

Follow-up to #2239/#2360 for firms whose every invoice carries ROT/RUT.

- /invoices/rot-rut: tiles (at Skatteverket on 1513, awaiting beslut,
  refused to book, ready to request) and one row per begaran with mark
  uploaded, cancel, download and "Bokfor nekat belopp"; the Fakturor
  button links here, ?rot-rut=1 still opens the file dialog.
- Beslutsfil import from the UI through the existing import route.
- Reclaim of the share Skatteverket refused: one voucher debit 1510 /
  credit 1513 per invoice (source_type rot_rut_reclaim), CAS-attached to
  the begaran and guarded by a partial unique index; the invoice reopens
  for the refused share via invoices.deduction_reclaimed_total, with the
  customer-share formula and its SQL twin gaining the same term. The
  payment dialog and bank match then settle the reopened remaining as a
  plain 1510 clearing; a booked kontantmetod invoice is proposed accrual-
  shaped so revenue is never recognised twice. Unknown per-invoice split
  of a partial beslut is refused, never allocated.
- MCP: gnubok_list_rot_rut_payout_requests (search-only read) and
  gnubok_settle_rot_rut_payout (staged write, op settle_rot_rut_payout)
  sharing one pre-flight + settle with the dashboard match route.
- Migrations 20260907140000 (reclaim state, source_type, INSERT guard),
  20260907140100/140101 (pending_operations op type).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D9wvsGnvu5tHGqYnJnjnaB

* chore(rot-rut): renumber migrations after merging main

Main already carries 20260907143000 and 20260907150000, so the three
rot-rut migrations move to 20260907160000/160100/160101 to keep the
applied order monotonic (see memory: migration-version-collisions).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D9wvsGnvu5tHGqYnJnjnaB

* fix(rot-rut): close the reclaim gaps found by skeptics, CI and review

Skeptic refutations (#2397):
- payment-sync recomputes remaining with deduction_reclaimed_total, so a
  storno of a payment on a reopened invoice no longer strands the refused
  share (R1).
- Reclaim refused while an invoice sits in a later live begäran
  (ROT_RUT_RECLAIM_INVOICE_REREQUESTED); the overview and the MCP list hide
  the action for the same case (C2).
- A reclaimed invoice is blocked from a new begäran (DEDUCTION_RECLAIMED)
  until the reclaim voucher is reversed (R2/C3).
- Storno of the reclaim voucher syncs the invoices and the begäran back
  (rot-rut-reclaim-reversal.ts, hooked into reverseEntry) (R3).
- A paid invoice with NULL paid_amount counts its customer share as paid
  (C4). Crediting an invoice with a reclaimed share is refused on the
  dashboard, v1 and MCP paths (R4).

CI and review:
- Build: custom-coded MCP errors via Object.assign, not codedError.
- pg-real: column default for default_voucher_series_per_source_type
  re-stated with rot_rut_reclaim (20260907160200); the default test now
  re-applies the latest default migration.
- Checks: accounted-api skill regenerated (journal-entries source types).
- CodeRabbit/Superagent: per-item refused shares must reconcile with the
  request-level beslut; per-invoice reopen through the idempotent RPC
  apply_rot_rut_reclaim_invoice (20260907160300) with a resume path;
  update-stage settle failures keep the voucher id (failed_partial);
  Stockholm calendar date for the booking; existing-voucher tab uses the
  same proposal method; MCP stage checks bank_line junction rows.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D9wvsGnvu5tHGqYnJnjnaB

* fix(rot-rut): carry the voucher id through the match outcome type; date the reclaim on the beslut

- The shared match outcome now declares journalEntryId on update-stage
  errors, matching the settle service (Core Build TS2339 on 2d6cece1a).
- The reclaim voucher is dated on the Swedish calendar day of Skatteverkets
  beslut (decided_at), today only when no decision date is recorded, and
  the confirm dialog states the date (Swedish accounting review: BFL 5 kap
  6-7 §, datum for affarshandelsen).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D9wvsGnvu5tHGqYnJnjnaB

* fix(rot-rut): reclaim RPCs validate the share and derive the invoice state; idempotent revert; v1 credit guard reads the column

- apply_rot_rut_reclaim_invoice (20260907160400 replaces the 160300
  signature) takes only the refused share, validates it against the locked
  item, request and invoice, and derives remaining_amount and status from
  the INSERT-guard formula (review: caller-supplied accounting values,
  CWE-862). revert_rot_rut_reclaim_invoice mirrors it for a reversed
  reclaim voucher; the request link is cleared only after every leg.
- v1 credit route projection includes deduction_reclaimed_total so the
  reclaim guard actually fires there.
- Overview keeps "Bokfor nekat belopp" available while legs are pending
  (resume after a partial failure).
- Match and settle routes attach journal_entry_id on update-stage errors.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D9wvsGnvu5tHGqYnJnjnaB

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Mattsson
2026-09-08 00:13:05 +02:00
committed by GitHub
co-authored by Claude Fable 5.1
parent 5d735097a1
commit fdcb7d937e
52 changed files with 4016 additions and 122 deletions
+12
View File
@@ -351,6 +351,18 @@ async function createCreditNote(
})
}
// A refused ROT/RUT share booked onto the customer (rot_rut_reclaim) moved
// kronor from 1513 to 1510 after issue; the credit note reverses the
// issue-time split (1510 total minus deduction, 1513 deduction) and would
// leave a phantom fordran on 1510 and a phantom liability on 1513. Reverse
// the reclaim voucher first; the storno sync closes the invoice again.
if (Number((originalInvoice as { deduction_reclaimed_total?: number | null }).deduction_reclaimed_total ?? 0) > 0) {
return errorResponseFromCode('INVOICE_CREDIT_ROT_RUT_RECLAIMED', log, {
requestId,
details: { deduction_reclaimed_total: originalInvoice.deduction_reclaimed_total },
})
}
// Self-billed originals have invoice_number null by design (the DB
// constraint invoices_self_billed_numbering enforces it); their number
// lives in external_invoice_number. Without this fallback the credit note
@@ -0,0 +1,130 @@
import { describe, it, expect, vi, beforeEach } from 'vitest'
import { NextResponse } from 'next/server'
import {
createMockRequest,
createMockRouteParams,
parseJsonResponse,
createQueuedMockSupabase,
} from '@/tests/helpers'
const { supabase: mockSupabase, reset } = createQueuedMockSupabase()
const requireAuthMock = vi.fn()
vi.mock('@/lib/auth/require-auth', () => ({
requireAuth: (...args: unknown[]) => requireAuthMock(...args),
}))
vi.mock('@/lib/company/context', () => ({
requireCompanyId: vi.fn().mockResolvedValue('company-1'),
getActiveCompanyId: vi.fn().mockResolvedValue('company-1'),
}))
vi.mock('@/lib/auth/require-write', () => ({
requireWritePermission: vi.fn().mockResolvedValue({ ok: true }),
}))
const mockReclaim = vi.fn()
vi.mock('@/lib/invoices/rot-rut-reclaim', () => ({
reclaimRotRutRefusal: (...args: unknown[]) => mockReclaim(...args),
}))
import { POST } from '../route'
const REQUEST_ID = '22222222-2222-4222-8222-222222222222'
const mockUser = { id: 'user-1', email: 'test@test.se' }
const routeParams = createMockRouteParams({ id: REQUEST_ID })
function makeReq(body: unknown = { booking_date: '2026-08-21' }) {
return createMockRequest(`/api/rot-rut/payout-requests/${REQUEST_ID}/reclaim`, {
method: 'POST',
body,
})
}
beforeEach(() => {
vi.clearAllMocks()
reset()
requireAuthMock.mockResolvedValue({ user: mockUser, supabase: mockSupabase })
mockReclaim.mockResolvedValue({
ok: true,
journalEntryId: 'je-reclaim',
reclaimedTotal: 2000,
invoices: [
{ invoice_id: 'inv-1', invoice_number: '2026-002', reclaimed_amount: 2000, remaining_amount: 2000, status: 'partially_paid' },
],
})
})
describe('POST /api/rot-rut/payout-requests/[id]/reclaim', () => {
it('returns 401 when not authenticated', async () => {
requireAuthMock.mockResolvedValue({
user: null,
supabase: mockSupabase,
error: NextResponse.json({ error: 'Unauthorized' }, { status: 401 }),
})
const response = await POST(makeReq(), routeParams)
expect(response.status).toBe(401)
expect(mockReclaim).not.toHaveBeenCalled()
})
it('returns 400 on an invalid body', async () => {
const response = await POST(makeReq({ booking_date: 'yesterday' }), routeParams)
expect(response.status).toBe(400)
expect(mockReclaim).not.toHaveBeenCalled()
})
it('returns 404 when the request is not in the company', async () => {
mockReclaim.mockResolvedValue({ ok: false, kind: 'code', code: 'ROT_RUT_REQUEST_NOT_FOUND' })
const response = await POST(makeReq(), routeParams)
const { status, body } = await parseJsonResponse<{ error: { code: string } }>(response)
expect(status).toBe(404)
expect(body.error.code).toBe('ROT_RUT_REQUEST_NOT_FOUND')
})
it('maps service refusals to their structured codes', async () => {
mockReclaim.mockResolvedValue({
ok: false,
kind: 'code',
code: 'ROT_RUT_RECLAIM_SPLIT_UNKNOWN',
details: { request_id: REQUEST_ID },
})
const response = await POST(makeReq(), routeParams)
const { status, body } = await parseJsonResponse<{ error: { code: string } }>(response)
expect(status).toBe(400)
expect(body.error.code).toBe('ROT_RUT_RECLAIM_SPLIT_UNKNOWN')
mockReclaim.mockResolvedValue({ ok: false, kind: 'code', code: 'ROT_RUT_RECLAIM_ALREADY_DONE' })
const conflict = await POST(makeReq(), routeParams)
expect(conflict.status).toBe(409)
})
it('books the reclaim with the caller as acting user and the body date', async () => {
const response = await POST(makeReq(), routeParams)
const { status, body } = await parseJsonResponse<{
data: { journal_entry_id: string; reclaimed_total: number; invoices: unknown[] }
}>(response)
expect(status).toBe(200)
expect(body.data).toEqual({
journal_entry_id: 'je-reclaim',
reclaimed_total: 2000,
invoices: [
{ invoice_id: 'inv-1', invoice_number: '2026-002', reclaimed_amount: 2000, remaining_amount: 2000, status: 'partially_paid' },
],
})
expect(mockReclaim).toHaveBeenCalledWith(mockSupabase, 'user-1', 'company-1', {
requestId: REQUEST_ID,
bookingDate: '2026-08-21',
})
})
it('returns 500 when the engine refuses to book', async () => {
mockReclaim.mockResolvedValue({
ok: false,
kind: 'error',
error: new Error('No open fiscal period'),
stage: 'book',
})
const response = await POST(makeReq(), routeParams)
expect(response.status).toBeGreaterThanOrEqual(400)
})
})
@@ -0,0 +1,63 @@
import { NextResponse } from 'next/server'
import { withRouteContext } from '@/lib/api/with-route-context'
import { validateBody } from '@/lib/api/validate'
import { RotRutReclaimSchema } from '@/lib/api/schemas'
import { errorResponse, errorResponseFromCode } from '@/lib/errors/get-structured-error'
import { reclaimRotRutRefusal } from '@/lib/invoices/rot-rut-reclaim'
/**
* POST /api/rot-rut/payout-requests/[id]/reclaim
*
* Books the share of a begäran that Skatteverket refused back onto the
* customer(s) and reopens their invoices for it:
*
* Debit 1510 Kundfordringar [refused share, per invoice]
* Credit 1513 Skattereduktion rot/rut [refused share, per invoice]
*
* The amounts come from the recorded beslut (PATCH or beslutsfil import);
* the body carries only the booking date. See lib/invoices/rot-rut-reclaim.ts
* for every refusal.
*/
export const POST = withRouteContext<{ params: Promise<{ id: string }> }>(
'rot_rut.requests.reclaim',
async (request, ctx, { params }) => {
const { user, supabase, companyId, log, requestId } = ctx
const { id } = await params
const validation = await validateBody(request, RotRutReclaimSchema)
if (!validation.success) return validation.response
const outcome = await reclaimRotRutRefusal(supabase, user.id, companyId!, {
requestId: id,
bookingDate: validation.data.booking_date,
})
if (!outcome.ok) {
if (outcome.kind === 'code') {
return errorResponseFromCode(outcome.code, log, { requestId, details: outcome.details })
}
if (outcome.stage === 'book') {
log.error('failed to book rot/rut reclaim entry', outcome.error as Error)
} else {
log.error('rot/rut reclaim failed', outcome.error as Error, { stage: outcome.stage })
}
return errorResponse(outcome.error, log, { requestId })
}
log.info('rot/rut refused share reclaimed', {
userId: user.id,
payoutRequestId: id,
journalEntryId: outcome.journalEntryId,
reclaimedTotal: outcome.reclaimedTotal,
})
return NextResponse.json({
data: {
journal_entry_id: outcome.journalEntryId,
reclaimed_total: outcome.reclaimedTotal,
invoices: outcome.invoices,
},
})
},
{ requireWrite: true },
)
@@ -50,7 +50,12 @@ export const POST = withRouteContext<{ params: Promise<{ id: string }> }>(
} else if (outcome.stage === 'book') {
log.error('failed to book rot/rut payout entry', outcome.error as Error)
}
return errorResponse(outcome.error, log, { requestId })
// At stage 'update' the voucher is posted: name it so nobody books the
// payout twice while repairing the request row.
return errorResponse(outcome.error, log, {
requestId,
...(outcome.journalEntryId ? { details: { journal_entry_id: outcome.journalEntryId } } : {}),
})
}
log.info('rot/rut payout settled', {
+3 -2
View File
@@ -20,8 +20,9 @@ export const GET = withRouteContext('rot_rut.requests.list', async (request, ctx
.select(
'id, name, deduction_type, status, requested_total, decided_total, file_name, file_document_id, ' +
'created_at, submitted_at, decided_at, settlement_journal_entry_id, ' +
'items:rot_rut_payout_request_items(id, invoice_id, requested_amount, decided_amount, ' +
'invoice:invoices(id, invoice_number))',
'reclaim_journal_entry_id, reclaimed_at, skv_referensnummer, ' +
'items:rot_rut_payout_request_items(id, invoice_id, requested_amount, decided_amount, reclaimed_amount, ' +
'invoice:invoices(id, invoice_number, status, remaining_amount))',
)
.eq('company_id', companyId!)
.order('created_at', { ascending: false })
@@ -3,13 +3,7 @@ import { withRouteContext } from '@/lib/api/with-route-context'
import { validateBody } from '@/lib/api/validate'
import { MatchRotRutPayoutSchema } from '@/lib/api/schemas'
import { errorResponse, errorResponseFromCode } from '@/lib/errors/get-structured-error'
import { resolveSettlementAccount } from '@/lib/bookkeeping/settlement-account'
import {
settleRotRutPayoutRequest,
settleRotRutPayoutRequestSet,
} from '@/lib/invoices/rot-rut-settle'
import { hasLiveJournalEntryLink } from '@/lib/transactions/link-journal-entry'
import { hasBankLineJunctionRow } from '@/lib/transactions/is-booked'
import { matchTransactionToRotRutPayout } from '@/lib/invoices/rot-rut-match-transaction'
import { ensureInitialized } from '@/lib/init'
ensureInitialized()
@@ -31,6 +25,10 @@ ensureInitialized()
* body may name several begäran (`request_ids`, #2239): then ONE voucher
* carries one 1513 credit per begäran and the row is linked to it, provided
* the expected payouts sum to the row exactly.
*
* The pre-flight and the settle live in lib/invoices/rot-rut-match-transaction
* (shared with the MCP settle_rot_rut_payout executor); this route only maps
* the outcome to HTTP.
*/
export const POST = withRouteContext<{ params: Promise<{ id: string }> }>(
'transaction.match_rot_rut_payout',
@@ -49,88 +47,14 @@ export const POST = withRouteContext<{ params: Promise<{ id: string }> }>(
const txLog = log.child({ transactionId, payoutRequestIds })
// transaction_voucher_links rides along: a row bulk-booked into a
// samlingsverifikat carries journal_entry_id = NULL and must still refuse.
const { data: transactionRow, error: fetchTxError } = await supabase
.from('transactions')
.select(
'id, date, amount, currency, journal_entry_id, cash_account_id, transaction_voucher_links(journal_entry_id, role)',
)
.eq('id', transactionId)
.eq('company_id', companyId!)
.single()
if (fetchTxError || !transactionRow) {
return errorResponseFromCode('TX_CATEGORIZE_TX_NOT_FOUND', txLog, { requestId })
}
const { transaction_voucher_links: junctionLinks, ...transaction } = transactionRow as {
id: string
date: string
amount: number
currency: string | null
journal_entry_id: string | null
cash_account_id: string | null
transaction_voucher_links?: Array<{ journal_entry_id: string; role?: string | null }> | null
}
if (!(transaction.amount > 0)) {
return errorResponseFromCode('ROT_RUT_MATCH_NOT_INCOME', txLog, {
requestId,
details: { amount: transaction.amount },
})
}
if ((transaction.currency || 'SEK').toUpperCase() !== 'SEK') {
return errorResponseFromCode('ROT_RUT_MATCH_CURRENCY', txLog, {
requestId,
details: { currency: transaction.currency },
})
}
// Only a LIVE (posted) pointer or a bank_line junction row blocks: a
// pointer left behind by a storno reads as "utan koppling" in the UI and
// must stay matchable (same predicate as link-journal-entry, issue #988).
if (
hasBankLineJunctionRow(junctionLinks) ||
(await hasLiveJournalEntryLink(supabase, companyId!, transaction.journal_entry_id))
) {
return errorResponseFromCode('ROT_RUT_MATCH_TX_ALREADY_LINKED', txLog, {
requestId,
details: { existingJournalEntryId: transaction.journal_entry_id },
})
}
// Debit the cash account THIS transaction belongs to, never a company-wide
// default (mirrors match-supplier-invoice).
const bankAccount = await resolveSettlementAccount(
const outcome = await matchTransactionToRotRutPayout(
supabase,
user.id,
companyId!,
transaction.cash_account_id,
{ transactionId, requestIds: payoutRequestIds },
txLog,
)
// Shared by both shapes: amount, date and account come from the bank row;
// the link CAS locks on the pointer read above (null for a free row, or
// the stale pointer of a reversed entry the guard let through).
const settleParams = {
paymentDate: transaction.date,
amount: transaction.amount,
bankAccount,
transactionId,
previousJournalEntryId: transaction.journal_entry_id,
}
const outcome =
payoutRequestIds.length === 1
? await settleRotRutPayoutRequest(supabase, user.id, companyId!, {
requestId: payoutRequestIds[0],
...settleParams,
})
: await settleRotRutPayoutRequestSet(supabase, user.id, companyId!, {
requestIds: payoutRequestIds,
...settleParams,
})
if (!outcome.ok) {
if (outcome.kind === 'code') {
return errorResponseFromCode(outcome.code, txLog, { requestId, details: outcome.details })
@@ -138,20 +62,25 @@ export const POST = withRouteContext<{ params: Promise<{ id: string }> }>(
if (outcome.stage === 'book') {
txLog.error('failed to book rot/rut payout entry', outcome.error as Error)
}
return errorResponse(outcome.error, txLog, { requestId })
// At stage 'update' the voucher is posted: name it so nobody books the
// payout twice while repairing the request row.
return errorResponse(outcome.error, txLog, {
requestId,
...(outcome.journalEntryId ? { details: { journal_entry_id: outcome.journalEntryId } } : {}),
})
}
txLog.info('rot/rut payout matched from bank transaction', {
userId: user.id,
journalEntryId: outcome.journalEntryId,
amount: outcome.amount,
fullyPaid: 'fullyPaid' in outcome ? outcome.fullyPaid : true,
fullyPaid: outcome.fullyPaid,
})
return NextResponse.json({
success: true,
journal_entry_id: outcome.journalEntryId,
...('request' in outcome ? { request: outcome.request } : { requests: outcome.requests }),
...(outcome.request ? { request: outcome.request } : { requests: outcome.requests }),
category: 'income_other',
})
},
@@ -39,7 +39,7 @@ const CreditNoteRequest = z.object({
})
const ORIGINAL_INVOICE_COLUMNS =
'id, invoice_number, customer_id, invoice_date, due_date, delivery_date, status, currency, exchange_rate, exchange_rate_date, subtotal, subtotal_sek, vat_amount, vat_amount_sek, total, total_sek, vat_treatment, vat_rate, moms_ruta, your_reference, our_reference, invoice_marking, notes, reverse_charge_text, credited_invoice_id, document_type, default_dimensions'
'id, invoice_number, customer_id, invoice_date, due_date, delivery_date, status, currency, exchange_rate, exchange_rate_date, subtotal, subtotal_sek, vat_amount, vat_amount_sek, total, total_sek, vat_treatment, vat_rate, moms_ruta, your_reference, our_reference, invoice_marking, notes, reverse_charge_text, credited_invoice_id, document_type, default_dimensions, deduction_reclaimed_total'
// default_dimensions stays in this projection: the inserted credit-note row is
// handed to createCreditNoteJournalEntry, which reads the bag off the row so
@@ -199,6 +199,14 @@ export const POST = withApiV1<{ params: Promise<{ companyId: string; id: string
requestId: ctx.requestId,
})
}
// Same guard as the dashboard credit route: a reclaimed ROT/RUT share
// (rot_rut_reclaim) must be reversed before the issue-time split is credited.
if (Number((original as { deduction_reclaimed_total?: number | null }).deduction_reclaimed_total ?? 0) > 0) {
return v1ErrorResponseFromCode('INVOICE_CREDIT_ROT_RUT_RECLAIMED', ctx.log, {
requestId: ctx.requestId,
details: { deduction_reclaimed_total: original.deduction_reclaimed_total },
})
}
if (!['sent', 'paid', 'overdue'].includes(original.status)) {
return v1ErrorResponseFromCode('INVOICE_CREDIT_NOT_SENT', ctx.log, {
requestId: ctx.requestId,