feat(categories): add confidence-scored transaction categorization (#…

[ExcelDsigN-tech]

feat(categories): confidence-scored transaction categorization (Closes #961, Closes #962, Closes #963, Closes #964)

Overview

Recon before implementing found #961, #962 and #964 already fully built in the codebase, verified but not touched. #963 had a partial rule-based implementation with a genuine gap (no confidence/scoring), which this PR fills by replacing the first-match category rule list with weighted, confidence-scored signals.

Feature Summary

• Category matching now scores every matching category instead of stopping at the first rule hit
• New scoreCategories() returns ranked {category, confidence} results; inferCategory() takes the top score, preserving existing behavior for existing callers
• New non-persisting POST /categories/payments/:paymentId/suggest endpoint lets a caller preview or override a category before calling the existing auto-assign endpoint
• Build notification preferences center #961, Implement onboarding checklist wizard #962 and Build merchant dashboard with real-time metrics #964 verified as already fully implemented in main, closed here with no code changes to reflect that the work already exists

Technical Implementation

• Scoring: the category rule list is now weighted signals rather than first-match, so a payment scores against every matching category. scoreCategories() returns ranked {category, confidence} results, and inferCategory() now just takes the top score, preserving existing behavior and callers.
• Suggestion endpoint: POST /categories/payments/:paymentId/suggest is non-persisting, letting a caller preview or override a category before calling the existing auto-assign endpoint.
• Heuristic, not ML: this is a heuristic weighted-rule scorer, not a trained model, since no labeled categorization corrections exist yet to train one. Marked with a ponytail: comment noting the upgrade path.
• Verification that Build notification preferences center #961, Implement onboarding checklist wizard #962, Build merchant dashboard with real-time metrics #964 are already done: Build notification preferences center #961 (notification preferences center) is implemented in backend/src/services/notifications/preferenceService.ts, frontend/components/NotificationPreferences.tsx, frontend/app/dashboard/notifications/preferences/page.tsx. Implement onboarding checklist wizard #962 (onboarding checklist wizard) is implemented in backend/src/services/onboarding/onboarding-checklist.ts plus the role-onboarding.ts route (role-based checklist), and a separate merchant KYC onboarding wizard (frontend/components/onboarding/OnboardingChecklist.tsx). Build merchant dashboard with real-time metrics #964 (merchant dashboard, real-time metrics) is implemented via backend/src/index.ts, which already broadcasts an analytics snapshot every 30s over the analytics.updates WebSocket channel, consumed by frontend/lib/analytics/realtime.ts on both dashboard pages. No code changes were made for these three; they are closed here to reflect that the work is already in main.

Test Coverage

• vitest run src/services/__tests__/categories.test.ts: 4/4 passing (ranking, confidence stacking/cap, fallback-to-other, inferCategory back-compat)
• eslint: clean on all touched files
• tsc --noEmit: reports 10 pre-existing errors in the categories module (a broken PaymentCategoryType export, since no PaymentCategory model exists in schema.prisma, plus a repo-wide req.params: string | string[] typing gap). Confirmed via git stash diff against main that none of these are introduced by this change; out of scope to fix here.

Files Changed

• backend/src/services/categories.ts
• backend/src/controllers/CategoriesController.ts
• backend/src/routes/categories.ts
• backend/src/services/__tests__/categories.test.ts

Checklists

• First-match rule list replaced with weighted, confidence-scored signals
• scoreCategories() returns ranked results, inferCategory() preserves existing behavior
• Non-persisting suggest endpoint added ahead of the existing auto-assign endpoint
• Build notification preferences center #961, Implement onboarding checklist wizard #962 and Build merchant dashboard with real-time metrics #964 verified as already implemented, no duplicate code added
• New unit tests passing, eslint clean
• Pre-existing tsc errors confirmed not introduced by this change

Notes for reviewers

• Build notification preferences center #961, Implement onboarding checklist wizard #962 and Build merchant dashboard with real-time metrics #964 are closed here with zero code changes, purely to reflect that the underlying work already exists in main; the verification details for each are listed above so reviewers can confirm independently.
• This is a heuristic weighted-rule scorer, not a trained model, since there's no labeled correction data yet; the upgrade path is flagged with a ponytail: comment in the code.
• The 10 pre-existing tsc --noEmit errors in the categories module (broken PaymentCategoryType export, missing PaymentCategory model, repo-wide req.params typing gap) are confirmed present on main via git stash and are out of scope for this PR.

[vercel]

@ExcelDsigN-tech is attempting to deploy a commit to the smartdevs17's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@ExcelDsigN-tech Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits