fix(mcp): link_document_to_voucher marks the inbox item handled; document lists stop misleading agents (#2170)

Three MCP feedback reports (seq 265062, 288474, 288577; three companies) hit the same hole: link_document_to_voucher attaches the document to the verifikat but never stamps the inbox item it came from, and both inbox read surfaces derive "handled" from the inbox row's own link columns, never from document_attachments.journal_entry_id. So an attached document stayed "unprocessed" forever: agents re-saw it as missing underlag (one reporter paged 750 rows to find the ~15 real ones), and one user read the five leftover rows as duplicates and was about to delete the only copies of underlag sitting on posted verifikat. - commitLinkDocumentToVoucher and the bulk twin now stamp invoice_inbox_items.created_journal_entry_id, keyed on document_id, CAS on both link columns, 23505 tolerated (samlingsverifikat). Same shape as the create_voucher + inbox_item_id stamp; best-effort so inbox bookkeeping never rolls back a committed link. - gnubok_list_unmatched_documents returns file_name (same embed list_inbox_items uses) and the extraction's page coverage, so an agent can tell "no total on this document" from "we read 3 of 38 pages" and does not have to fetch each document to learn what it is (seq 265062, 288574). - gnubok_list_transactions_without_documents no longer echoes the column default "uncategorized" on rows that are booked by construction: list_uncategorized_transactions uses the same word for "no journal entry yet", and an agent read the label and tried to re-book an already-booked share-capital deposit (seq 288574). No tools/list payload change: the unmatched-documents item schema is untyped and the category field already allowed null. Claude-Session: https://claude.ai/code/session_013yw62FMXGSzo6icFDiBwP3 Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-04 08:57:53 +02:00
parent bac9e01e2d
commit 01d903d3a3
5 changed files with 181 additions and 4 deletions
@@ -1461,6 +1461,7 @@ describe('commitPendingOperation: link_document_to_voucher', () => {
      data: { id: 'doc-1', file_name: 'kvitto.pdf', journal_entry_id: 'je-1', journal_entry_line_id: null },
      error: null,
    })                                                                           // linkToJournalEntry: doc update
+    enqueue({ data: null, error: null })                                         // inbox stamp (best-effort)
    enqueue({ data: null, error: null })                                         // dispatcher commit update

    const result = await commitPendingOperation(
@@ -1470,7 +1471,7 @@ describe('commitPendingOperation: link_document_to_voucher', () => {
  })

  it('happy path: links doc to verifikation with no prior journal_entry_id', async () => {
-    const { supabase, enqueue } = createQueuedMockSupabase()
+    const { supabase, enqueue, calls, findCall } = createQueuedMockSupabase()
    enqueue({ data: { id: 'op-1' }, error: null })                              // CAS claim
    enqueue({ data: { id: 'doc-1', journal_entry_id: null }, error: null })     // doc fetch
    enqueue({ data: { id: 'je-1' }, error: null })                              // linkToJournalEntry: JE ownership
@@ -1478,6 +1479,7 @@ describe('commitPendingOperation: link_document_to_voucher', () => {
      data: { id: 'doc-1', file_name: 'faktura.pdf', journal_entry_id: 'je-1', journal_entry_line_id: null },
      error: null,
    })                                                                           // linkToJournalEntry: doc update
+    enqueue({ data: null, error: null })                                         // inbox stamp (best-effort)
    enqueue({ data: null, error: null })                                         // dispatcher commit update

    const result = await commitPendingOperation(
@@ -1488,6 +1490,39 @@ describe('commitPendingOperation: link_document_to_voucher', () => {
      document_id: 'doc-1',
      journal_entry_id: 'je-1',
    })
+    // The inbox item the document came from is stamped as handled, keyed on
+    // document_id and CAS-guarded on both link columns: otherwise
+    // list_inbox_items / list_unmatched_documents keep listing an attached
+    // document as unprocessed forever.
+    expect(findCall('invoice_inbox_items', 'update')).toEqual([{ created_journal_entry_id: 'je-1' }])
+    const inboxFilters = calls
+      .filter((c) => c.table === 'invoice_inbox_items' && (c.method === 'eq' || c.method === 'is'))
+      .map((c) => c.args)
+    expect(inboxFilters).toEqual([
+      ['document_id', 'doc-1'],
+      ['company_id', 'company-1'],
+      ['created_journal_entry_id', null],
+      ['created_supplier_invoice_id', null],
+    ])
+  })
+
+  it('inbox stamp is best-effort: a failed stamp never fails the committed link', async () => {
+    const { supabase, enqueue } = createQueuedMockSupabase()
+    enqueue({ data: { id: 'op-1' }, error: null })                              // CAS claim
+    enqueue({ data: { id: 'doc-1', journal_entry_id: null }, error: null })     // doc fetch
+    enqueue({ data: { id: 'je-1' }, error: null })                              // linkToJournalEntry: JE ownership
+    enqueue({
+      data: { id: 'doc-1', file_name: 'faktura.pdf', journal_entry_id: 'je-1', journal_entry_line_id: null },
+      error: null,
+    })                                                                           // linkToJournalEntry: doc update
+    enqueue({ data: null, error: { code: '23505', message: 'duplicate key value' } }) // inbox stamp: samlingsverifikat already claimed
+    enqueue({ data: null, error: null })                                         // dispatcher commit update
+
+    const result = await commitPendingOperation(
+      supabase as never, 'user-1', 'company-1', makePendingOp(baseOp),
+    )
+    expect(result.status).toBe('committed')
+    expect(result.data).toMatchObject({ document_id: 'doc-1', journal_entry_id: 'je-1' })
  })

  it('auto-rejects 409 when linkToJournalEntry throws a period-lock error', async () => {
@@ -1532,6 +1567,7 @@ describe('commitPendingOperation: link_documents_to_vouchers', () => {
      data: { id: 'doc-1', file_name: 'kvitto1.pdf', journal_entry_id: 'je-1', journal_entry_line_id: null },
      error: null,
    })                                                                       // linkToJournalEntry: doc update
+    enqueue({ data: null, error: null })                                   // inbox stamp (best-effort)
    // row 2: doc-2 -> je-2
    enqueue({ data: { id: 'doc-2', journal_entry_id: null }, error: null })  // doc fetch
    enqueue({ data: { id: 'je-2' }, error: null })                          // linkToJournalEntry: JE ownership
@@ -1539,6 +1575,7 @@ describe('commitPendingOperation: link_documents_to_vouchers', () => {
      data: { id: 'doc-2', file_name: 'kvitto2.pdf', journal_entry_id: 'je-2', journal_entry_line_id: null },
      error: null,
    })                                                                       // linkToJournalEntry: doc update
+    enqueue({ data: null, error: null })                                   // inbox stamp (best-effort)
    enqueue({ data: null, error: null })                                    // dispatcher commit update

    const result = await commitPendingOperation(
@@ -1563,6 +1600,7 @@ describe('commitPendingOperation: link_documents_to_vouchers', () => {
      data: { id: 'doc-2', file_name: 'kvitto2.pdf', journal_entry_id: 'je-2', journal_entry_line_id: null },
      error: null,
    })                                                                      // linkToJournalEntry: doc update
+    enqueue({ data: null, error: null })                                  // inbox stamp (best-effort)
    enqueue({ data: null, error: null })                                   // dispatcher commit update

    const result = await commitPendingOperation(
@@ -1592,6 +1630,7 @@ describe('commitPendingOperation: link_documents_to_vouchers', () => {
      data: { id: 'doc-2', file_name: 'kvitto2.pdf', journal_entry_id: 'je-2', journal_entry_line_id: null },
      error: null,
    })                                                                              // linkToJournalEntry: doc update
+    enqueue({ data: null, error: null })                                          // inbox stamp (best-effort)
    enqueue({ data: null, error: null })                                           // dispatcher commit update

    const result = await commitPendingOperation(
@@ -3999,6 +3999,47 @@ async function precheckDocumentLink(
  return { ok: true }
 }

+/**
+ * After a document is linked to a verifikat, stamp the inbox item it came
+ * from (if any) so the inbox reads "handled". Both inbox read surfaces derive
+ * "done" from the inbox row's own link columns, never from
+ * document_attachments.journal_entry_id: gnubok_list_inbox_items computes
+ * processed from matched_transaction_id / created_supplier_invoice_id /
+ * created_journal_entry_id, and gnubok_list_unmatched_documents filters on the
+ * same two nulls. Without this stamp a document attached through
+ * link_document_to_voucher stays "unprocessed" forever: agents re-see it as
+ * missing underlag, and one user read the five leftover rows as duplicates
+ * and nearly deleted the only copies of underlag sitting on posted verifikat
+ * (feedback 2026-08-24..26, three companies).
+ *
+ * Same shape as the create_voucher + inbox_item_id stamp: CAS on the null
+ * link columns so a concurrent claim stays a no-op, and unique_violation
+ * tolerated because the UNIQUE on created_journal_entry_id lets only one
+ * inbox item point at a samlingsverifikat. Best-effort by design: the link is
+ * already committed and inbox bookkeeping must not roll it back.
+ */
+async function stampInboxItemForLinkedDocument(
+  supabase: SupabaseClient,
+  companyId: string,
+  documentId: string,
+  journalEntryId: string,
+): Promise<void> {
+  const { error } = await supabase
+    .from('invoice_inbox_items')
+    .update({ created_journal_entry_id: journalEntryId })
+    .eq('document_id', documentId)
+    .eq('company_id', companyId)
+    .is('created_journal_entry_id', null)
+    .is('created_supplier_invoice_id', null)
+  if (error && error.code !== '23505') {
+    log.warn('Failed to mark inbox item handled after document link (link still committed)', {
+      documentId,
+      journalEntryId,
+      error: error.message,
+    })
+  }
+}
+
 /**
 * Shared failure mapping for both link executors. A locked period is the one
 * case worth its own sentence: it is recoverable by unlocking, unlike the rest,
@@ -4040,6 +4081,7 @@ async function commitLinkDocumentToVoucher(
      journalEntryId,
      journalEntryLineId,
    )
+    await stampInboxItemForLinkedDocument(supabase, companyId, documentId, journalEntryId)
    return {
      data: {
        document_id: updated.id,
@@ -4095,6 +4137,7 @@ async function commitLinkDocumentsToVouchers(
      const updated = await linkToJournalEntry(
        supabase, companyId, documentId, journalEntryId, link.journal_entry_line_id ?? undefined,
      )
+      await stampInboxItemForLinkedDocument(supabase, companyId, documentId, journalEntryId)
      linked.push({ document_id: updated.id, journal_entry_id: updated.journal_entry_id as string })
    } catch (err) {
      // Same mapping as the single executor, including its locked-period