feat: Add CD001-MCP FinMail Repository and Routing (CD001, #27)

[steadhac]

PR #312 — FinMail Repository and Routing
Add full unit test coverage for the FinMail repository layer and address routing module.
Tests exercise all repository query methods — vendor email filters, admin email filters,
external emails, stats, unread counts, bulk mark-as-read, pagination, cross-vendor
isolation, and Email model methods — plus the routing function that resolves addresses
to inboxes.
 
No bugs expected in the repository/routing layer — all tests currently pass.
 
Tests follow the established pattern with:
 

• Title / Basically question / Steps / Expected Results
   
  📁 Test Files
  tests/unit/mcp/test_finmail_repositories.py
  tests/unit/mcp/test_finmail_routing.py
   

TestListVendorEmailsFilters

Test ID	Title
test_fm_repo_001	list_vendor_emails filters by message_type
test_fm_repo_002	list_vendor_emails filters by is_read=False
test_fm_repo_003	list_vendor_emails filters by is_read=True

TestGetVendorEmailStats

Test ID	Title
test_fm_repo_004	get_vendor_email_stats returns zeros when empty
test_fm_repo_005	get_vendor_email_stats returns correct counts with emails

TestGetVendorUnreadCount

Test ID	Title
test_fm_repo_006	get_vendor_unread_count returns correct count
test_fm_repo_007	get_vendor_unread_count returns zero when all read

TestMarkAllVendorAsRead

Test ID	Title
test_fm_repo_008	mark_all_vendor_as_read marks all unread emails
test_fm_repo_009	mark_all_vendor_as_read skips already-read emails

TestListAdminEmailsFilters

Test ID	Title
test_fm_repo_010	list_admin_emails filters by message_type
test_fm_repo_011	list_admin_emails filters by is_read

TestGetAdminEmailStats

Test ID	Title
test_fm_repo_012	get_admin_email_stats returns zeros when empty
test_fm_repo_013	get_admin_email_stats returns correct counts

TestMarkAllAdminAsRead

Test ID	Title
test_fm_repo_014	mark_all_admin_as_read marks all unread
test_fm_repo_015	mark_all_admin_as_read returns zero when none unread

TestExternalEmails

Test ID	Title
test_fm_repo_016	list_external_emails returns external inbox messages
test_fm_repo_017	get_external_email_stats returns correct counts
test_fm_repo_018	get_external_email_stats returns zeros when empty

TestMarkAsRead

Test ID	Title
test_fm_repo_019	mark_as_read on already-read email returns email
test_fm_repo_020	mark_as_read on nonexistent email returns None

TestListAdminEmailsIsReadTrue

Test ID	Title
test_fm_repo_021	list_admin_emails filters by is_read=True

TestPagination

Test ID	Title
test_fm_repo_022	list_vendor_emails respects limit
test_fm_repo_023	list_vendor_emails respects offset

TestCrossVendorIsolation

Test ID	Title
test_fm_repo_024	list_vendor_emails scoped to vendor_id
test_fm_repo_025	mark_all_vendor_as_read does not affect other vendor
test_fm_repo_026	get_email cross-namespace returns None

TestEmailModel

Test ID	Title
test_fm_repo_027	Email repr includes id and subject
test_fm_repo_028	parse_addresses returns None for invalid JSON
test_fm_repo_029	to_summary_dict truncates long body

TestGetDepartmentAddresses

Test ID	Title
test_fm_rte_001	get_department_addresses returns all 8 departments
test_fm_rte_002	get_department_addresses scoped to namespace

TestRouteAndDeliverUserBranch

Test ID	Title
test_fm_rte_003	Delivery to user address routes to admin inbox
test_fm_rte_004	Delivery to unknown address routes to external inbox