feat: bill auto-detect patterns now mark bills paid on import (#274)

The matcher (BillService::matchTransactionToBill) existed since the
initial commit but had zero callers — the form's promise of auto-linking
never ran. Imports (CSV/OFX/QIF, both pipelines) and bank sync now call
autoMatchPaidFromImport after persisting rows: a debit matching a bill's
pattern (description or vendor), within 10% of the amount, on the bill's
account, and dated within the due window marks the bill paid with the
transaction LINKED (never duplicated). Marking paid advances the due
date, which inherently prevents same-period duplicates and historical
re-imports from double-advancing. Import summary reports the count.
8 new unit tests + live verification; help text and docs updated.

Author: otherworld-dev

budget/CHANGELOG.md

@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Deep links into the app (`#/transactions`, `#/bills`, …) are now honored on page load, including a pre-filled transaction search (`#/transactions?search=…`)
 
 ### Fixed
+- **Bill auto-detect patterns now actually work** ([#274](https://github.com/otherworld-dev/Budget/issues/274)): the bill form has always offered a "pattern to match in transaction descriptions", but no import path ever ran the matcher. Imports and bank syncs now mark a bill as paid when a transaction matches its pattern (amount within 10%, account agreement, dated within the bill's due window) — the transaction is linked, never duplicated, the due date advances, and the Bills Calendar ticks the month off. Same-period duplicates and historical re-imports cannot double-advance a bill; the import summary reports how many bills were marked paid
 - Transaction search is now case-insensitive on PostgreSQL and SQLite (plain `LIKE` is case-sensitive there — searching "rent" missed "Rent"; MySQL/MariaDB installs were unaffected)
 - Bank sync connections no longer get permanently stuck after a failed sync: one transient provider failure (bridge outage, lapsed SimpleFIN subscription, network error) set the connection to an error state that every later sync — manual and the daily background job — refused to touch ("Connection is not active"), with no path back. Failed connections are now retried, so they self-heal once the provider recovers, and the real provider error is surfaced instead of the status gate ([#277](https://github.com/otherworld-dev/Budget/issues/277))
 

budget/js/budget-app.js

@@ -31,6 +31,7 @@ public function __construct(
         private \OCA\Budget\Db\DismissedImportMapper $dismissedImportMapper,
         private \OCA\Budget\Service\Import\ImportRuleApplicator $ruleApplicator,
         private \OCA\Budget\Service\TransactionTagService $transactionTagService,
+        private \OCA\Budget\Service\BillService $billService,
         private IL10N $l,
         private LoggerInterface $logger
     ) {
@@ -198,6 +199,7 @@ public function sync(string $userId, int $connectionId, bool $force = false): ar
         }
 
         $mappingsByExternalId = [];
+        $createdForBillMatch = [];
         foreach ($enabledMappings as $m) {
             $mappingsByExternalId[$m->getExternalAccountId()] = $m;
         }
@@ -319,6 +321,7 @@ public function sync(string $userId, int $connectionId, bool $force = false): ar
                     // application) is swallowed by the catch below, and the
                     // persisted row must still get its balance recompute.
                     $createdAny = true;
+                    $createdForBillMatch[] = $createdTx;
 
                     // Apply deferred tag actions from import rules
                     if (!empty($txData['_deferred_tags'])) {
@@ -407,6 +410,16 @@ public function sync(string $userId, int $connectionId, bool $force = false): ar
             ];
         }
 
+        // Auto-mark bills paid from matching synced transactions (#274).
+        // Best-effort: a matching failure must never fail the sync.
+        if (!empty($createdForBillMatch)) {
+            try {
+                $this->billService->autoMatchPaidFromImport($userId, $createdForBillMatch);
+            } catch (\Exception $e) {
+                $this->logger->warning('Bill auto-match after sync failed: ' . $e->getMessage(), ['app' => 'budget']);
+            }
+        }
+
         // Update connection sync status
         $connection->setLastSyncAt(date('Y-m-d H:i:s'));
         $connection->setLastError($totalErrors > 0 ? $this->l->t('Sync completed with %1$s error(s)', [$totalErrors]) : null);

budget/js/budget-app.js.map

@@ -847,6 +847,113 @@ public function matchTransactionToBill(string $userId, string $description, floa
         return null;
     }
 
+    /**
+     * Auto-mark bills paid from freshly imported transactions (#274).
+     *
+     * For each imported debit that matches an active bill's auto-detect
+     * pattern (amount within 10%, account matching when the bill has one,
+     * transaction date within the bill's current due window), the bill is
+     * marked paid with the transaction LINKED — no duplicate money movement
+     * is ever recorded. Marking paid advances the due date, so a second
+     * same-period transaction in the batch falls outside the new window and
+     * cannot double-advance the bill.
+     *
+     * @param \OCA\Budget\Db\Transaction[] $transactions freshly created rows
+     * @return int number of bills marked paid
+     */
+    public function autoMatchPaidFromImport(string $userId, array $transactions): int {
+        if (empty($transactions)) {
+            return 0;
+        }
+
+        $bills = array_filter(
+            $this->findActive($userId),
+            fn(Bill $bill) => !($bill->getIsTransfer() ?? false)
+                && !empty($bill->getAutoDetectPattern())
+                && $bill->getNextDueDate() !== null
+        );
+        if (empty($bills)) {
+            return 0;
+        }
+
+        $marked = 0;
+        foreach ($transactions as $transaction) {
+            if ($transaction->getType() !== 'debit') {
+                continue;
+            }
+            if (($transaction->getStatus() ?? 'cleared') === 'scheduled') {
+                continue;
+            }
+
+            foreach ($bills as $key => $bill) {
+                if (!$this->importedTransactionMatchesBill($bill, $transaction)) {
+                    continue;
+                }
+
+                try {
+                    $this->markPaid($bill->getId(), $userId, $transaction->getDate(), false, $transaction->getId());
+                    $marked++;
+                    // Reload: the due date advanced (or the bill deactivated),
+                    // which is what keeps this loop from double-advancing
+                    $bills[$key] = $this->find($bill->getId(), $userId);
+                    if (!$bills[$key]->getIsActive() || $bills[$key]->getNextDueDate() === null) {
+                        unset($bills[$key]);
+                    }
+                } catch (\Exception $e) {
+                    $this->logger->warning(
+                        "Auto-match failed marking bill {$bill->getId()} paid from imported transaction {$transaction->getId()}: {$e->getMessage()}"
+                    );
+                }
+                break; // one bill per transaction
+            }
+        }
+
+        return $marked;
+    }
+
+    /**
+     * Match an imported transaction against a bill: pattern in description
+     * or vendor, amount within 10%, account agreement, and the transaction
+     * date inside the bill's current due window (so historical re-imports
+     * can't advance bills through future periods).
+     */
+    private function importedTransactionMatchesBill(Bill $bill, \OCA\Budget\Db\Transaction $transaction): bool {
+        $pattern = (string) $bill->getAutoDetectPattern();
+        $haystack = $transaction->getDescription() . ' ' . ($transaction->getVendor() ?? '');
+        if (stripos($haystack, $pattern) === false) {
+            return false;
+        }
+
+        $billAmount = (float) $bill->getAmount();
+        if ($billAmount <= 0 || abs((float) $transaction->getAmount() - $billAmount) > $billAmount * 0.1) {
+            return false;
+        }
+
+        if ($bill->getAccountId() !== null && $bill->getAccountId() !== $transaction->getAccountId()) {
+            return false;
+        }
+
+        $dueDate = $bill->getNextDueDate();
+        $daysOff = abs((strtotime($transaction->getDate()) - strtotime($dueDate)) / 86400);
+
+        return $daysOff <= $this->dueDateToleranceDays($bill->getFrequency());
+    }
+
+    /**
+     * How far an imported payment may sit from the due date and still count
+     * as paying THIS occurrence — roughly half the recurrence interval,
+     * capped so monthly+ bills accept payments up to two weeks early/late.
+     */
+    private function dueDateToleranceDays(?string $frequency): int {
+        return match ($frequency) {
+            'daily' => 1,
+            'weekly' => 3,
+            'biweekly' => 6,
+            'semi-monthly' => 7,
+            default => 15, // monthly, quarterly, semi-annually, yearly, custom, one-time
+        };
+    }
+
     /**
      * Attempt to auto-pay a bill and handle success/failure.
      *

budget/lib/Service/BankSync/BankSyncService.php

@@ -54,6 +54,7 @@ public function __construct(
         TagSetService $tagSetService,
         TransactionTagService $transactionTagService,
         ImportAccountLinkService $accountLinkService,
+        private \OCA\Budget\Service\BillService $billService,
         IL10N $l
     ) {
         $this->appData = $appData;
@@ -721,6 +722,7 @@ private function executeMultiAccountImport(string $userId, string $fileId, strin
         $accountResults = [];
         $hashCounts = [];
         $touchedAccounts = [];
+        $createdForBillMatch = [];
 
         try {
         foreach ($parsedData['accounts'] as $sourceAccount) {
@@ -785,6 +787,7 @@ private function executeMultiAccountImport(string $userId, string $fileId, strin
                         deferBalanceUpdate: true
                     );
                     $touchedAccounts[(int)$destAccountId] = true;
+                    $createdForBillMatch[] = $createdTx;
 
                     // Apply deferred tag actions from import rules
                     if (!empty($transaction['_deferred_tags'])) {
@@ -845,6 +848,15 @@ private function executeMultiAccountImport(string $userId, string $fileId, strin
 
         $totalProcessed = array_sum(array_map(fn($a) => count($a['transactions']), $parsedData['accounts']));
 
+        // Auto-mark bills paid from matching imported transactions (#274).
+        // Best-effort: a matching failure must never fail the import.
+        $billsMarkedPaid = 0;
+        try {
+            $billsMarkedPaid = $this->billService->autoMatchPaidFromImport($userId, $createdForBillMatch);
+        } catch (\Exception $e) {
+            // ignore
+        }
+
         // Remember the routing so the next same-format import can pre-fill it.
         // Best-effort: never let this break a completed import.
         try {
@@ -860,6 +872,7 @@ private function executeMultiAccountImport(string $userId, string $fileId, strin
             'totalProcessed' => $totalProcessed,
             'accountResults' => array_values($accountResults),
             'transfersLinked' => $transfersLinked,
+            'billsMarkedPaid' => $billsMarkedPaid,
         ];
     }
 
@@ -904,6 +917,7 @@ private function executeSingleAccountImport(string $userId, string $fileId, stri
         $transferLinkIds = [];
         $hashCounts = [];
         $touchedAccounts = [];
+        $createdForBillMatch = [];
 
         // Detect date format from all rows before processing individually (unless preset set it)
         if (!$preset) {
@@ -996,6 +1010,7 @@ private function executeSingleAccountImport(string $userId, string $fileId, stri
                     deferBalanceUpdate: true
                 );
                 $touchedAccounts[$txAccountId] = true;
+                $createdForBillMatch[] = $createdTx;
 
                 // Apply tags from preset (e.g., Toshl Tags)
                 if ($preset && !empty($transaction['_tagNames']) && !empty($transaction['categoryId'])) {
@@ -1079,6 +1094,15 @@ private function executeSingleAccountImport(string $userId, string $fileId, stri
             }
         }
 
+        // Auto-mark bills paid from matching imported transactions (#274).
+        // Best-effort: a matching failure must never fail the import.
+        $billsMarkedPaid = 0;
+        try {
+            $billsMarkedPaid = $this->billService->autoMatchPaidFromImport($userId, $createdForBillMatch);
+        } catch (\Exception $e) {
+            // ignore
+        }
+
         if ($hasAccountColumn) {
             $result = [
                 'imported' => $imported,
@@ -1087,13 +1111,15 @@ private function executeSingleAccountImport(string $userId, string $fileId, stri
                 'totalProcessed' => count($data),
                 'accountResults' => array_values($perAccountResults),
                 'accountsCreated' => $accountsCreated,
+                'billsMarkedPaid' => $billsMarkedPaid,
             ];
         } else {
             $result = [
                 'imported' => $imported,
                 'skipped' => $skipped,
                 'errors' => $errors,
                 'totalProcessed' => count($data),
+                'billsMarkedPaid' => $billsMarkedPaid,
                 'accountResults' => [[
                     'destinationAccountId' => $accountId,
                     'destinationAccountName' => $account->getName(),

budget/lib/Service/BillService.php

@@ -1463,6 +1463,14 @@ export default class ImportModule {
 
             if (response.ok) {
                 showSuccess(t('budget', 'Successfully imported {imported} transactions ({skipped} skipped)', { imported: result.imported, skipped: result.skipped }));
+                if (result.billsMarkedPaid > 0) {
+                    showSuccess(n(
+                        'budget',
+                        '%n bill was automatically marked as paid from matching transactions',
+                        '%n bills were automatically marked as paid from matching transactions',
+                        result.billsMarkedPaid
+                    ));
+                }
                 if (result.errors && result.errors.length > 0) {
                     // Partial failure (e.g. a mapped destination account was
                     // deleted) — must not masquerade as a full success

budget/lib/Service/ImportService.php

@@ -5401,7 +5401,7 @@ class="app-navigation-search-clear icon-close"
             <div class="form-group">
                 <label for="bill-auto-pattern"><?php p($l->t('Auto-detect Pattern')); ?></label>
                 <input type="text" id="bill-auto-pattern" aria-describedby="bill-auto-pattern-help" maxlength="255" placeholder="<?php p($l->t('e.g., NETFLIX, SPOTIFY')); ?>">
-                <small id="bill-auto-pattern-help" class="form-text"><?php p($l->t('Pattern to match in transaction descriptions for auto-linking')); ?></small>
+                <small id="bill-auto-pattern-help" class="form-text"><?php p($l->t('Imported transactions matching this pattern (similar amount, near the due date) automatically mark the bill as paid')); ?></small>
             </div>
 
             <div class="form-group">

budget/src/modules/import/ImportModule.js

@@ -67,6 +67,7 @@ protected function setUp(): void {
 			$dismissedImportMapper,
 			$ruleApplicator,
 			$transactionTagService,
+			$this->createMock(\OCA\Budget\Service\BillService::class),
 			$this->l,
 			$this->logger
 		);