Account Statement Management#

Account statement management in Sure covers uploading, organizing, linking, and reviewing financial statement files (PDF, CSV, XLSX) at both the family level (Statement Vault) and per-account level. The central controller is AccountStatementsController, with supporting UI embedded in the account detail page via lazy-loaded Turbo Frames.

Related articles (separate concerns):

• Statement Deduplication — SHA-256/MD5 hashing and coverage-level duplicate detection
• Statement Period Extraction — MetadataDetector auto-fill of period_start_on / period_end_on
• Account Statement Reconciliation — three-point balance checks and monthly coverage grid
• Turbo Frame Navigation — data-turbo-frame="_top" fix for statement links inside the account tab frame

Controller Actions#

AccountStatementsController 1 provides 8 public actions. Two before_action guards apply across the surface 2:

• set_statement — scopes the lookup to the current family and enforces viewable_by?(Current.user), raising RecordNotFound for unauthorized access.
• ensure_statement_manager! — redirects non-managers away from index, create, update, destroy, link, unlink, and reject.

Both index and show render with layout: "settings" 11 12, which means they have no matching Turbo Frame for the account tab — links navigating to these pages from within the account detail frame require data-turbo-frame="_top" (see Turbo Frame Navigation).

File Upload Workflow#

create accepts a files array and iterates over each file independently 13:

1. AccountStatement.prepare_upload!(file) — reads bytes, computes SHA-256 (content_sha256) and MD5 (checksum), validates extension/content-type/size, and stores results in a prepared-upload struct.
2. AccountStatement.create_from_prepared_upload! — attaches the file, runs MetadataDetector, calls assign_account_match, and persists the record.

Per-file errors are collected without aborting the loop:

• InvalidUploadError → invalid file type flash
• DuplicateUploadError → duplicate count flash
• ActiveRecord::RecordInvalid → inline error message flash

Redirect after create is determined by redirect_after_create:

• Account specified → account_path(account, tab: "statements")
• No account but a statement was created → account_statement_path(statement) (the statement vault inbox view)
• Nothing created → account_statements_path

The accepted types and the 25 MB cap are constants on AccountStatement referenced directly in the upload form 14.

Turbo Frame Lazy-Loading (Account Detail Page)#

The Statements tab on the account detail page is lazy-loaded via a named Turbo Frame. The frame ID is dom_id(@account, :statements_tab) — e.g., statements_tab_account_42 15.

How it works:

1. When the Statements tab is activated, the browser issues a request with tab=statements and the matching Turbo-Frame header.
2. AccountsController#show detects statement_tab_active? (@tab == "statements") and calls build_statement_tab_data 16 17:
   • Builds AccountStatement::Coverage.for_year(@account, params[:statement_year])
   • Loads @account.account_statements.with_attached_original_file.ordered.to_a
   • Pre-computes AccountStatement.reconciliation_statuses_for(...) to avoid N+1
3. If the request is a Turbo Frame request targeting the statements frame, render_statement_tab_frame returns only the _statements_frame partial 18, skipping the full account-page render.
4. _statements_frame.html.erb wraps _statements.html.erb in the turbo_frame_tag.

Year filter: An auto-submit form inside _statements.html.erb submits statement_year + tab=statements on change, re-triggering the same frame request path for a different year 19.

Permission guard: @can_manage_statements requires both AccountStatement.statement_manager?(Current.user) and permission.in?([:owner, :full_control]) for the specific account 20. Read-only users see the coverage grid and statement list but not the upload form or unlink button 21 22.

Testing Infrastructure#

uploaded_file Helper#

The global test helper uploaded_file (defined in test/test_helper.rb, available to all ActiveSupport::TestCase subclasses) creates a Rack::Test::UploadedFile from a temp file:

def uploaded_file(filename:, content_type:, content: "date,amount\n2024-01-01,1\n")

It defaults to minimal valid CSV content, making it easy to create realistic upload params without managing temp files manually. Tests override content: when they need specific data (e.g., duplicate detection, oversized file validation).

Controller Test Patterns#

AccountStatementsControllerTest is an ActionDispatch::IntegrationTest covering:

• Authorization: manager vs. member vs. guest access, cross-family account ID rejection 23 24
• Upload loop behavior: continues after a validation error or invalid file type; collects all errors/successes before redirecting 25
• Deduplication: asserts no new record and a flash alert for duplicate content 26
• Redirect semantics: linked uploads go to account_path(account, tab: "statements"); unmatched uploads go to the statement show page 27
• Link / unlink / reject: verifies status transitions and redirect destinations 28
• Metadata update: covers field persistence and account linking via update 29
• Read-only view: asserts absence of edit controls for family_member on a read-only account 30

Each test uses AccountStatement.create_from_upload! to set up fixtures inline rather than relying on YAML fixtures, keeping test state explicit.

Key Files#