integreat/docs/testing/behaviors/legacy-spa.md

# Legacy SPA Behaviors

## Overview

These pages are rendered client-side via Reagent/Re-frame. They use GraphQL for data fetching. They are being migrated to HTMX SSR. Behavior docs exist for reference but **NO UI tests should be written for these pages until migrated**.

### Architecture
- **Routing**: Bidi client-side routes (`src/cljc/auto_ap/client_routes.cljc`)
- **State**: Re-frame subscriptions and events
- **Data**: GraphQL via custom `graphql` effect (`auto-ap.effects`)
- **Permissions**: `auto-ap.permissions/can?` with role-based checks

### Role Permissions Summary
| Role | Transaction Page | Ledger Page | Vendor Create/Edit |
|------|-----------------|-------------|-------------------|
| admin | full | full | full |
| power-user | full | full | full |
| manager | full | blocked | full |
| user | full | full | full |
| read-only | blocked | full | blocked |

---

## Pages

### Home (`/`)

#### Purpose
Dashboard showing financial overview for the selected client: top expense categories (pie chart), upcoming bills (bar chart), and cash flow projection (interactive bar chart with table).

#### User Flows
1. User lands on `/`
2. Page loads data for currently selected client
3. If user has access to multiple clients, shows note: "these reports are for [client]. Please choose a specific customer for their report."
4. User can switch cash flow range: 7/30/60/90/120/150/180 days
5. Cash flow bars are clickable and redirect to unpaid invoices for that date

#### GraphQL Queries Used
```graphql
query HomeDashboard($clientId: id) {
  expense_account_stats(client_id: $clientId) {
    account { id name }
    total
  }
  invoice_stats(client_id: $clientId) {
    name
    paid
    unpaid
  }
  cash_flow(client_id: $clientId) {
    beginning_balance
    outstanding_payments
    invoices_due_soon { due outstanding_balance invoice_number vendor { id name } }
    upcoming_credits { date amount identifier }
    upcoming_debits { date amount identifier }
  }
}
```

#### Behaviors to Test (when migrated)
- **Happy path**: Dashboard loads with all three chart sections
- **Multi-client note**: Displays when user hasn't selected a specific client
- **Cash flow ranges**: Switching between 7-180 day views updates chart and table
- **Cash flow table**: Shows invoices, upcoming debits/credits with days-until
- **Edge case**: No data for client shows empty charts gracefully
- **Error states**: GraphQL errors show loading state appropriately

---

### Login (`/login`)

#### Purpose
Authentication page with Google OAuth login.

#### User Flows
1. User visits `/login`
2. Shows "Login with Google" button
3. Button links to Google OAuth with optional `redirect-to` query param
4. After auth failure/logout, may show logout reason notification

#### GraphQL Queries/Mutations Used
None.

#### Behaviors to Test (when migrated)
- **Happy path**: Shows login button linking to Google OAuth
- **Redirect**: Preserves `redirect-to` query parameter in OAuth URL
- **Logout reason**: Displays warning notification when `logout-reason` is set
- **Edge case**: Already authenticated user visiting login page

---

### Needs Activation (`/needs-activation`)

#### Purpose
Shown when authenticated user's account is not yet activated.

#### User Flows
1. User logs in but account is inactive
2. Shows message: "Sorry, your user is not activated yet. Please have Ben Skinner enable your account."
3. "here" link clears user state and redirects to login

#### GraphQL Queries/Mutations Used
None.

#### Behaviors to Test (when migrated)
- **Happy path**: Shows activation required message
- **Relogin link**: Clears user state and redirects to login

---

### Transactions (`/transactions/`, `/transactions/unapproved`, `/transactions/approved`, `/transactions/requires-feedback`, `/transactions/excluded`)

#### Purpose
Transaction list with filtering, editing, and bulk admin operations. Different routes show different approval statuses.

#### User Flows
1. User navigates to transactions page
2. Default date filter: last 1 month
3. Side bar allows filtering by: vendor, account, bank account, date range, amount range, location, import batch, description, linked status
4. Table shows transactions with checkbox selection (admin only)
5. Clicking row opens edit side bar
6. Admin can: bulk code, bulk delete, suppress, or manual Yodlee import

#### GraphQL Queries/Mutations Used
```graphql
query TransactionPage($filters: transaction_filters) {
  transaction_page(filters: $filters) {
    data { 
      id amount memo location approval_status check_number is_locked
      matched_rule { note id }
      vendor { name id }
      accounts { id amount location account { name id location numeric_code } }
      date yodlee_merchant { name yodlee_id id } plaid_merchant { name id }
      post_date expected_deposit { id date } forecast_match { id identifier }
      status description_original
      payment { check_number s3_url id date }
      client { name id }
      bank_account { name yodlee_account_id current_balance }
    }
    total start end count
  }
}

mutation EditTransaction($transaction: edit_transaction) {
  edit_transaction(transaction: $transaction) { ... }
}

mutation DeleteTransactions($filters: transaction_filters, $ids: [id], $suppress: Boolean) {
  delete_transactions(filters: $filters, ids: $ids, suppress: $suppress) { message }
}

mutation BulkCodeTransactions($filters: transaction_filters, $ids: [id], $vendor: id, $approval_status: transaction_approval_status, $accounts: [edit_percentage_account]) {
  bulk_code_transactions(filters: $filters, ids: $ids, vendor: $vendor, approval_status: $approval_status, accounts: $accounts) { message }
}
```

#### Behaviors to Test (when migrated)
- **Happy path**: Loads transaction list with default 1-month filter
- **Route variants**: Each approval-status route applies correct default filter
- **Filtering**: Side bar filters trigger debounced data refresh (800ms)
- **Pagination**: Start/per-page params work correctly
- **Edit transaction**: Update vendor, approval status, memo, expense accounts
- **Edit validation**: Account total must equal transaction amount; locations must be valid
- **Bulk delete (admin)**: Delete selected transactions or all visible transactions
- **Bulk suppress (admin)**: Mark transactions as suppressed instead of deleting
- **Bulk code (admin)**: Apply vendor/account rules to multiple transactions
- **Manual import (admin)**: Import transactions via manual Yodlee import dialog
- **Error states**: Locked transactions cannot be edited/deleted; validation errors display inline
- **Permissions**: Non-admin users don't see checkboxes or action buttons

---

### Ledger (`/ledger/`)

#### Purpose
General ledger showing journal entries with line items. Supports filtering and CSV export.

#### User Flows
1. User navigates to `/ledger/`
2. Default date filter: last 1 month
3. Side bar filters: vendor, account, bank account, date range, amount range, location
4. Table shows journal entries with expandable line items
5. Admin can export to CSV

#### GraphQL Queries/Mutations Used
```graphql
query LedgerPage($filters: ledger_filters) {
  ledger_page(filters: $filters) {
    journal_entries {
      id source original_entity amount note cleared_against alternate_description
      vendor { name id } client { name id }
      line_items { id debit credit location running_balance account { id name } }
      date
    }
    total start end
  }
}

query LedgerCsv($filters: ledger_filters) {
  ledger_csv(filters: $filters) { csv_content_b64 }
}
```

#### Behaviors to Test (when migrated)
- **Happy path**: Loads ledger with default 1-month filter
- **Filtering**: Date range, vendor, account, location filters work
- **CSV export**: Admin can export filtered results as base64 CSV download
- **Pagination**: Virtual pagination controls
- **Permissions**: Manager role sees "Not authorized"

---

### Profit and Loss (`/ledger/profit-and-loss`)

#### Purpose
Financial report showing revenue and expenses over configurable periods. Supports multi-company and PDF export.

#### User Flows
1. User selects companies (multi-select typeahead)
2. User selects period preset (13 periods, 12 months, last week, week-to-date, last month, month-to-date, year-to-date, last calendar year, full year)
3. Optional: Include deltas, Column per location
4. Click "Run" to generate report
5. Admin can "Export" to PDF
6. Clicking report cells opens ledger detail side bar

#### GraphQL Queries/Mutations Used
```graphql
query ProfitAndLoss($clientIds: [id], $periods: [date_range], $includeDeltas: Boolean, $columnPerLocation: Boolean) {
  profit_and_loss(client_ids: $clientIds, periods: $periods, include_deltas: $includeDeltas, column_per_location: $columnPerLocation) {
    periods { accounts { name amount client_id account_type id count numeric_code location } }
  }
}

query ProfitAndLossPdf($clientIds: [id], $periods: [date_range], $includeDeltas: Boolean, $columnPerLocation: Boolean) {
  profit_and_loss_pdf(...) { url name }
}
```

#### Behaviors to Test (when migrated)
- **Happy path**: Generate P&L for single client with default period
- **Multi-company**: Select multiple clients and generate combined report
- **Period presets**: All preset buttons populate correct date ranges
- **Advanced mode**: Custom period date pickers
- **Include deltas**: Shows period-over-period changes
- **Column per location**: Breaks out by location (mutually exclusive with deltas)
- **PDF export**: Admin can generate and download PDF; single-client shows email link
- **Ledger drill-down**: Clicking cells opens ledger entries side bar for that account/period
- **Permissions**: Manager role sees "Not authorized"

---

### Cash Flows (`/ledger/cash-flows`)

#### Purpose
Statement of cash flows report. Same control structure as P&L but different report format.

#### User Flows
Same as Profit and Loss but generates cash flow statement.

#### GraphQL Queries/Mutations Used
```graphql
query CashFlows($clientIds: [id], $periods: [date_range], $includeDeltas: Boolean, $columnPerLocation: Boolean) {
  profit_and_loss(client_ids: $clientIds, periods: $periods, include_deltas: $includeDeltas, column_per_location: $columnPerLocation) {
    periods { accounts { name amount debits credits client_id account_type id count numeric_code location } }
  }
}

query CashFlowsPdf($clientIds: [id], $periods: [date_range], $includeDeltas: Boolean, $columnPerLocation: Boolean) {
  cash_flows_pdf(...) { url name }
}
```

#### Behaviors to Test (when migrated)
- **Happy path**: Generate cash flows report
- **Same controls as P&L**: Companies, periods, deltas, location columns
- **PDF export**: Admin-only export button
- **Ledger drill-down**: Clicking cells opens ledger detail
- **Permissions**: Manager role sees "Not authorized"

---

### Profit and Loss Detail (`/ledger/profit-and-loss-detail`)

#### Purpose
Detailed journal entry report broken down by category (sales, COGS, payroll, controllable, fixed overhead, ownership controllable).

#### User Flows
1. Select companies
2. Select date range (start/end date pickers)
3. Click "Run" to generate detail report
4. Shows journal entries grouped by category and account with running balances
5. Admin can export to PDF

#### GraphQL Queries/Mutations Used
```graphql
query JournalDetailReport($clientIds: [id], $dateRange: date_range, $categories: [category]) {
  journal_detail_report(client_ids: $clientIds, date_range: $dateRange, categories: $categories) {
    categories {
      category client_id location
      account { numeric_code name }
      journal_entries { description date debit credit location running_balance account { id name } }
      total
    }
  }
}

query JournalDetailReportPdf($clientIds: [id], $dateRange: date_range, $categories: [category]) {
  journal_detail_report_pdf(...) { url name }
}
```

#### Behaviors to Test (when migrated)
- **Happy path**: Generate detail report with default 2-week range
- **Category breakdown**: Report includes all 6 category sections plus Gross Profit, Overhead, Net Profit summaries
- **Date range filtering**: Start/end dates filter journal entries
- **PDF export**: Admin can export to PDF with email link for single client
- **Permissions**: Manager role sees "Not authorized"

---

### Balance Sheet (`/ledger/balance-sheet`)

#### Purpose
Balance sheet report as of a specific date, with optional prior-year comparison.

#### User Flows
1. Select companies
2. Select report date
3. Optionally enable "Include comparison" and select comparison date
4. Click "Run" to generate balance sheet
5. Admin can export to PDF
6. Clicking cells opens ledger detail side bar

#### GraphQL Queries/Mutations Used
```graphql
query BalanceSheet($clientIds: [id], $date: iso_date, $comparisonDate: iso_date, $includeComparison: Boolean) {
  balance_sheet(client_ids: $clientIds, date: $date, comparison_date: $comparisonDate, include_comparison: $includeComparison) {
    balance_sheet_accounts { name amount account_type id numeric_code client_id }
    comparable_balance_sheet_accounts { name amount account_type id client_id numeric_code }
  }
}

query BalanceSheetPdf($clientIds: [id], $date: iso_date, $comparisonDate: iso_date, $includeComparison: Boolean) {
  balance_sheet_pdf(...) { url name }
}
```

#### Behaviors to Test (when migrated)
- **Happy path**: Generate balance sheet for current date
- **Comparison mode**: Shows prior period side-by-side
- **Multi-company**: Combines multiple clients
- **PDF export**: Admin-only with email composition link for single client
- **Ledger drill-down**: Clicking cells opens ledger entries filtered by account and date range
- **Permissions**: Manager role sees "Not authorized"

---

### External Ledger (`/ledger/external`)

#### Purpose
Shows only externally-imported journal entries. Admin can delete entries.

#### User Flows
1. Admin navigates to `/ledger/external`
2. Shows external journal entries with external_id
3. Can select entries and delete them
4. Admin can export to CSV

#### GraphQL Queries/Mutations Used
```graphql
query ExternalLedger($filters: ledger_filters) {
  ledger_page(filters: $filters) {
    journal_entries { id external_id source ... }
    total start end
  }
}

mutation DeleteExternalLedger($filters: ledger_filters, $ids: [id]) {
  delete_external_ledger(filters: $filters, ids: $ids) { message }
}
```

#### Behaviors to Test (when migrated)
- **Happy path**: Loads external-only ledger entries
- **Delete**: Admin can delete selected entries (max 1000 at once)
- **CSV export**: Same as main ledger
- **Permissions**: Admin-only; non-admin sees "Not authorized"

---

### External Import (`/ledger/external-import`)

#### Purpose
Manual import of ledger entries via tab-separated text paste.

#### User Flows
1. Admin pastes tab-separated data into textarea
2. Optional: indicates whether first row is header
3. Click "Parse" to convert to table
4. Table shows parsed rows: Id, Client, Source, Vendor, Date, Account, Location, Debit, Credit, Note, Cleared against
5. Click "Import" to submit
6. Results show: success count, ignored count, error count
7. Errors show inline with dropdown explanations
8. "Only show errors" filter available

#### GraphQL Queries/Mutations Used
```graphql
mutation ImportLedger($entries: [ledger_entry_input]) {
  import_ledger(entries: $entries) {
    successful { external_id }
    existing { external_id }
    ignored { external_id }
    errors { external_id error }
  }
}
```

#### Behaviors to Test (when migrated)
- **Happy path**: Paste TSV data, parse, import successfully
- **Header row**: Checkbox to skip first row
- **Validation**: Client code must exist, vendor must exist, date must be MM/dd/yyyy, debits=credits, amounts > 0
- **Lock check**: Entries must be after client's locked-until date
- **Location validation**: Location must belong to client or be "A"
- **Account validation**: Account must exist and location must match account's required location
- **Error display**: Errors show per-row with dropdown explanation
- **Success/ignored/existing**: Status icons show import result per row
- **Permissions**: Admin-only

---

### Payments (`/payments/`)

#### Purpose
**Already migrated to SSR.** Legacy client route exists for navbar highlighting only. Actual payments page is served by `payment` SSR routes at `/payment/`.

#### GraphQL Queries/Mutations Used
N/A (SSR page)

#### Behaviors to Test (when migrated)
Already migrated. Test via SSR routes.

---

### Reports (`/reports/`)

#### Purpose
**Already migrated to SSR.** Legacy client route exists for navbar highlighting only. Actual reports page is served by `company/reports` SSR routes.

#### GraphQL Queries/Mutations Used
N/A (SSR page)

#### Behaviors to Test (when migrated)
Already migrated. Test via SSR routes.

---

### Admin Vendors (`/admin/vendors`)

#### Purpose
**Already migrated to SSR.** Legacy client route exists for navbar highlighting only. Actual vendor management is served by `admin/vendor` SSR routes.

#### GraphQL Queries/Mutations Used
N/A (SSR page)

#### Behaviors to Test (when migrated)
Already migrated. Test via SSR routes.

---

### New Vendor (`/vendor/new`)

#### Purpose
Opens the home dashboard with the vendor creation dialog pre-opened.

#### User Flows
1. User navigates to `/vendor/new`
2. Loads home dashboard
3. Opens vendor dialog if user has `:vendor :create` permission
4. Dialog allows creating new vendor with name, terms, address, contacts, default account, etc.

#### GraphQL Queries/Mutations Used
```graphql
mutation UpsertVendor($vendor: add_vendor) {
  upsert_vendor(vendor: $vendor) { id name ... }
}
```

#### Behaviors to Test (when migrated)
- **Happy path**: Home loads with vendor dialog open
- **Permission check**: Dialog only opens if user can `:vendor :create`
- **Vendor creation**: Form submission creates vendor via GraphQL mutation
- **Validation**: Only one terms override, schedule payment DOM override, and account override per client

---

## Cross-Cutting Behaviors

### GraphQL Query Patterns
- All data fetching uses re-frame `graphql` effect with JWT token from `:user` in app-db
- Queries use `owns-state` to track loading status per page
- Results flow through `::data-page/received` event which stores data and syncs URL query params
- Filter changes are debounced (800ms) via `dispatch-debounce`

### Client-Side State Management (Re-frame)
- **Data pages**: `data-page` namespace provides reusable pagination/filtering state
  - `::data-page/params` - merged filters + table params + query params
  - `::data-page/data` - GraphQL response data
  - `::data-page/checked` - selected rows for bulk operations
- **Forms**: `forms` namespace manages edit dialogs with `start-form`, `change-handler`, `save-succeeded`
- **Status**: `status` namespace tracks async operation states (`:loading`, `:complete`, `:error`)

### Navigation Between Legacy Pages
- Navbar uses Bidi `path-for` with `routes/routes` for legacy SPA links
- Some navbar items (Payments, POS, Invoices) now link to `ssr-routes/only-routes` instead
- Page components dispatch `::mounted` on mount and `::unmounted` on unmount to set up/tear down:
  - Data subscriptions
  - Forward event listeners
  - Track subscriptions (parameter change watchers)

---

## Migration Notes

### Actively Migrated / Already SSR
- **Payments** (`/payments/`) - Fully migrated to `/payment/` SSR routes
- **Reports** (`/reports/`) - Fully migrated to `/company/reports` SSR routes
- **Admin Vendors** (`/admin/vendors`) - Fully migrated to `/admin/vendor` SSR routes

### Still Legacy SPA (prioritized by complexity)
1. **Transactions** - High complexity (filters, edit form, bulk operations, manual import)
2. **Home/Dashboard** - Medium complexity (charts, cash flow calculations)
3. **Ledger** - Medium complexity (filters, CSV export)
4. **External Ledger** - Low-medium complexity (subset of ledger + delete)
5. **External Import** - Medium complexity (TSV parsing, validation, batch import)
6. **Profit and Loss** - High complexity (multi-company, periods, PDF export)
7. **Cash Flows** - High complexity (shares P&L infrastructure)
8. **Profit and Loss Detail** - Medium complexity (category filtering, running balances)
9. **Balance Sheet** - Medium complexity (comparison mode, drill-down)
10. **Login** - Low complexity (static page)
11. **Needs Activation** - Low complexity (static page)
12. **New Vendor** - Low complexity (dialog on home page)

### Migration Risks
- **Chart libraries**: Home page uses Recharts (React). Replacement needed for SSR.
- **PDF generation**: P&L, Cash Flows, Balance Sheet, P&L Detail all support PDF export via server-side generation.
- **Bulk operations**: Transactions page has complex bulk coding/deletion with validation.
- **External import**: TSV parsing and validation logic lives entirely in SPA; server-side equivalent needed.