integreat/docs/superpowers/specs/2026-05-21-bulk-code-transactions-requirements.md

Bulk Coding Transactions - Requirements Document

Based on analysis of the master cljs implementation (src/cljs/auto_ap/views/pages/transactions/bulk_updates.cljs) and GraphQL resolver (src/clj/auto_ap/graphql/transactions.clj).

Feature Overview

Bulk coding allows admin users to apply vendor, approval status, and expense account allocations to multiple transactions simultaneously from the transactions grid page.

Functional Requirements

1. Access Control

• FR-1.1: Bulk coding must be restricted to admin users only
• FR-1.2: The bulk code button should only be visible/enabled when transactions are selected

2. Transaction Selection

• FR-2.1: Users can select specific transactions via checkboxes in the grid
• FR-2.2: Users can select all visible transactions via a header checkbox
• FR-2.3: The system must filter out locked transactions (where client's locked-until date is after transaction date)
• FR-2.4: The modal must display the count of transactions that will actually be coded (after filtering locked ones)

3. Bulk Code Form Fields

• FR-3.1: Vendor (optional): Searchable typeahead to select a vendor
• FR-3.2: Approval Status (optional): Select from:
  • No Change (empty)
  • Approved
  • Unapproved
  • Suppressed
  • Requires Feedback
• FR-3.3: Expense Accounts (optional): One or more account allocations with:
  • Account: Searchable typeahead for expense accounts
  • Location: Dropdown with "Shared" and client-specific locations
  • Percentage: Numeric input (0-100), must total exactly 100% across all accounts

4. Account Location Validation

• FR-4.1: If an account has a fixed location configured, the selected location MUST match it
• FR-4.2: If an account has no fixed location, the selected location must be either "Shared" or one of the client's locations
• FR-4.3: Invalid locations must be rejected with a clear error message

5. Percentage Validation

• FR-5.1: When accounts are provided, the sum of all percentages must equal exactly 100%
• FR-5.2: Values must be between 0 and 100
• FR-5.3: Invalid totals must be rejected with a clear error message showing the actual total

6. Amount Distribution

• FR-6.1: Percentages are converted to dollar amounts per transaction based on each transaction's amount
• FR-6.2: For "Shared" location, amounts are distributed evenly across all client locations (with proper cent handling)
• FR-6.3: Rounding errors are absorbed by the last account row
• FR-6.4: Each transaction gets its own set of transaction-account entities

7. Submission Behavior

• FR-7.1: Submitting with no accounts, no vendor, and no status should be a no-op (or rejected)
• FR-7.2: On success, all selected non-locked transactions are updated
• FR-7.3: Success response triggers a table refresh
• FR-7.4: Modal closes on success

UI/UX Requirements (from Master)

SSR-Specific Adaptations

• The SSR version uses a modal wizard with HTMX instead of a re-frame modal
• Form state is managed server-side via multi-form-state
• Percentage inputs display as whole numbers (50 for 50%) but are stored as decimals (0.5)

Test Scenarios

Happy Path

1. Select single transaction, code with 100% to one account
2. Select multiple transactions, code with vendor + status + accounts
3. Select all visible transactions via header checkbox

Validation

4. Submit without any changes (no vendor, no status, no accounts)
5. Submit with accounts totaling < 100%
6. Submit with accounts totaling > 100%
7. Submit with invalid location for account
8. Submit with location not belonging to client

Edge Cases

9. All selected transactions are locked (count should be 0)
10. Mix of locked and unlocked transactions (only unlocked should be coded)
11. "Shared" location distributes across multiple client locations

Known Issues to Verify

1. Missing location validation: The SSR version (bulk_code.clj) does not validate account locations against client locations or account fixed locations (present in GraphQL version)
2. Approval status options: Verify "excluded" vs "suppressed" naming consistency