integreat/docs/testing/behaviors/admin.md

# Admin Behaviors

## Overview

The Admin section is a server-side rendered (SSR) HTMX interface for superuser operations in Integreat. All admin pages require the `admin` user role. Non-admin users are redirected away. The admin area includes dashboards, entity management grids, background job orchestration, audit history, and bulk import tools.

## Routes & Pages

| Page | Route | Handler Namespace |
|------|-------|-------------------|
| Admin Dashboard | `/admin` | `auto-ap.ssr.admin` |
| Clients | `/admin/clients` | `auto-ap.ssr.admin.clients` |
| Accounts | `/admin/accounts` | `auto-ap.ssr.admin.accounts` |
| Vendors | `/admin/vendors` | `auto-ap.ssr.admin.vendors` |
| Transaction Rules | `/admin/transaction-rules` | `auto-ap.ssr.admin.transaction-rules` |
| Background Jobs | `/admin/jobs` | `auto-ap.ssr.admin.background-jobs` |
| History / Audit | `/admin/history` | `auto-ap.ssr.admin.history` |
| Import Batches | `/admin/import-batches` | `auto-ap.ssr.admin.import-batch` |
| Excel Invoices | `/admin/excel-invoices` | `auto-ap.ssr.admin.excel-invoice` |
| Sales Summaries | `/admin/sales-summaries` | `auto-ap.ssr.admin.sales-summaries` |

All routes are wrapped with `wrap-client-redirect-unauthenticated` followed by `wrap-admin`.

## Behaviors by Page

### Admin Dashboard

**Display**
- Shows two Chartist charts:
  - **Growth in clients**: Bar chart showing client count at 2 years ago, 1 year ago, and today (uses `dc/as-of` against Datomic history).
  - **Changes by hour**: Line chart showing Datomic transaction counts per hour over the last 24 hours.
- Uses the standard admin page layout with `admin-aside-nav`.

**Access Control**
- Only accessible to users with admin role.
- Unauthenticated users are redirected to login.

### Client Management

**Grid Display**
- Columns: Name, Code, Locations (as pills), Emails (as pills), Status.
- Status column shows:
  - Lock status: "Locked <date>" with color coding (green < 90 days, yellow < 365 days, red otherwise).
  - "Not locked" in red if no lock date.
  - Bank account integration status pills (red for failed/unauthorized).
- Row actions: Biweekly Sales PowerQuery button, Edit button (pencil icon).
- Global action: "New Client" button opens wizard.

**Filtering**
- Name (case-insensitive substring match).
- Code (exact match, upper-cased).
- Group (exact match on client groups, upper-cased).
- Select filter: "All" or "Only mine" (filters to clients assigned to current user).
- Filters trigger HTMX request with 500ms debounce on change, 1000ms on keyup.

**Sorting**
- By name, code.
- Pagination: 25 per page default.

**Client Wizard (Create / Edit)**
- Multi-step linear wizard with steps: Info → Matches → Contact → Bank Accounts → Integrations → Cash Flow → Other Settings.
- **Info step**: Name (required), Code (immutable on edit), Locked Until date, Locations (dynamic grid).
- **Matches step**: String match patterns, location match patterns (match → location mapping).
- **Contact step**: Address (street1, street2, city, state, zip), Email contacts grid (description + email).
- **Bank Accounts step**: Sortable card list of existing accounts. Add new cash/credit/checking accounts. Each account has type-specific form.
  - Cash account: nickname, code, financial code (numeric), start date, include-in-reports, visible-for-payment.
  - Credit card: same + bank name, account number, Plaid/Yodlee/Intuit integration selectors.
  - Checking: same + routing number, bank code, check number.
  - Validation: financial code is required if "Include in Reports" is true.
- **Integrations step**: Square auth token input, refresh Square locations button, Square location → client location mapping grid.
- **Cash Flow step**: Week A/B credits and debits (4 numeric fields).
- **Other Settings step**: Feature flags (dropdown with known flags), Groups (free text grid).

**Save Behavior**
- POST for create, PUT for update.
- Code uniqueness validation on create.
- Groups are upper-cased on save.
- Bank account start dates coerced to dates.
- After save: row flashes in grid, modal closes, Solr reindexes client.

**Biweekly Sales PowerQuery**
- Generates 6 saved queries per client (sales summary, category, expected deposits, tenders, refunds, cash drawer shifts).
- Opens modal with copy-to-clipboard buttons for Excel Power Query M-code.

### Account Management

**Grid Display**
- Columns: Code (numeric), Name, Type (pill), Location.
- Row action: Edit button.
- Global action: "New Account" button.

**Filtering**
- Name (case-insensitive substring on upper-cased name).
- Code (exact numeric match).
- Type: All, Dividend, Asset, Equity, Liability, Expense, Revenue, None.

**Sorting**
- By code, name, type, location.
- Default sort by upper-cased numeric code.

**Account Dialog (Create / Edit)**
- Modal card with live-updating header showing code and name.
- Fields:
  - Numeric Code (required, unique on create; hidden on edit).
  - Name (required).
  - Account Type (required, enum: asset, liability, equity, revenue, expense, dividend, none).
  - Location (optional string).
  - Invoice Allowance (enum: allowed, denied, warn).
  - Vendor Allowance (enum: allowed, denied, warn).
  - Applicability (enum: global, customized).
  - Client Overrides grid: client typeahead + override name. Validates no duplicate clients.

**Save Behavior**
- POST for create, PUT for update.
- Numeric code uniqueness check on create.
- Client override uniqueness validation.
- After save: Solr reindexes account + all client overrides.

### Vendor Management

**Grid Display**
- Columns: Name (with usage pills), Email, Default Account.
- Usage pills: "Unused" (red) if 0 clients, "Used by N clients" (primary), "Used N times" (secondary).
- Row action: Edit button (opens wizard).
- Global actions: "Merge" button, "New Vendor" button.

**Filtering**
- Name (case-insensitive substring on upper-cased name).
- Type: All, Only hidden, Only global.

**Vendor Wizard (Create / Edit)**
- Timeline steps: Info → Terms → Account → Address → Legal.
- **Info step**: Name (required, 3+ chars), Print As (optional, toggleable), Hidden (admin-only checkbox).
- **Terms step**: Terms in days (integer), Terms Overrides grid (client + days), Automatically Paid When Due grid (client list).
- **Account step**: Default Account (typeahead), Account Overrides grid (client + account typeahead). Account typeahead is scoped by selected client.
- **Address step**: Street1, Street2, City, State (2 chars), Zip (5 chars).
- **Legal step**: Legal Entity Name OR First/Middle/Last name, TIN, TIN Type (EIN/SSN), 1099 Type (enum).

**Vendor Merge**
- Modal with Source Vendor (to be deleted) and Target Vendor.
- Validation: source and target must differ.
- On merge: all references to source vendor are retracted and asserted as target vendor. Source vendor entity is retracted.
- Shows success notification after merge.

**Save Behavior**
- POST for create, PUT for update.
- Solr reindexes vendor name + hidden flag.

### Transaction Rules

**Grid Display**
- Columns: Client (or group pill), Bank Account, Description, Amount (gte/lte pills), Note.
- Row actions: Delete (with confirmation), Execute (play icon), Edit (pencil icon).
- Global action: "New Transaction Rule" button.

**Filtering**
- Vendor (entity typeahead).
- Note (case-insensitive regex match).
- Description (case-insensitive substring).
- Client Group (exact upper-cased match).

**Transaction Rule Wizard**
- Two-step wizard: Edit → Test.
- **Edit step**:
  - Description (required, regex pattern, 3+ chars).
  - Optional togglable filters: Client, Client Group, Bank Account, Amount range (gte/lte), Day of Month range (gte/lte).
  - Bank account selector is scoped by selected client.
  - Outcomes: Assign Vendor (typeahead), Accounts grid (account + location + percentage), Approval Status (radio: unapproved/approved).
  - Account location is derived from account's fixed location, client locations, or "Shared".
  - Validation: account percentages must sum to 100%, bank account must belong to selected client, location must match account's fixed location if set.
- **Test step**: Shows matching transactions (up to 15) with client, bank, date, description. Badge shows total count ("99+" if ≥99).

**Execute**
- Opens dialog with checkbox-selectable transactions that match the rule AND are unapproved.
- Only transactions on or after client's `locked-until` date are included.
- Can select "All" or individual transactions.
- On execution: applies rule coding to each transaction via `upsert-transaction`, touches Solr index.
- Shows notification: "Successfully coded X of Y transactions!"

**Delete**
- Confirms before delete.
- Retracts entity from Datomic.
- Row fades out with "live-removed" class.

### Background Jobs

**Grid Display**
- Columns: Start time, End time, Duration (minutes), Name, Status.
- Status values: `:running`, `:pending`, `:succeeded`, `:failed`.
- Data source: ECS tasks filtered by `INTEGREAT_JOB` environment variable.
- Global action: "Run job" button.

**Job Start Dialog**
- Job type dropdown: Yodlee Import, Yodlee Account Import, Intuit Import, Plaid Import, Bulk Journal Import, Square Import, Register Invoice Import, Upsert recent ezcater orders, Load Historical Square Sales, Export Backup.
- Dynamic subform based on job type:
  - Bulk Journal Import: S3 URL path input.
  - Register Invoice Import: S3 URL path input.
  - Load Historical Sales: Client typeahead + Days (1-120).
- Validation: cannot start a job that is already running.
- On submit: runs ECS Fargate Spot task with selected task definition.

### History / Audit

**Display**
- Search box for entity ID (numeric Datomic entity ID).
- History table shows: Date, User, Field, From value, To value.
- Values are formatted: dates → local format, large integers (>1M) → clickable links to that entity's history, nil → "(none)", others → pr-str.
- Entity ID links load that entity's history inline.
- Snapshot link opens inspector showing full entity pull `[*]`.
- No pagination (all history rows shown).

**Inspector**
- Card showing all attributes of an entity at current database value.
- Clickable entity IDs recurse into history.

### Import Batches

**Grid Display**
- Columns: Date, Source, Status, User, Imported, Pre-existing, Suppressed.
- Row action: External link to transactions filtered by import batch.

**Filtering**
- Date range (start/end).
- Source (enum: import-source values).

**Sorting**
- By date, source, status, user.

### Excel Invoices

**Display**
- Single-page form with large textarea for tab-separated invoice data.
- Shows sample data as placeholder.

**Import Behavior**
- Parses tab-separated rows with columns: raw-date, vendor-name, check, location, invoice-number, amount, client-name, bill-entered, bill-rejected, added-on, exported-on, account-numeric-code.
- Validates and resolves: client by code or name, vendor by name, account by numeric code.
- Groups rows into: new, existing (by vendor+client+invoice-number), errors.
- For new rows: creates invoice, optionally payment (if "Cash" check), and cash transaction.
- Cash invoices get status "paid" with zero outstanding balance.
- Non-cash invoices get status "unpaid" with full outstanding balance.
- Results shown as pills: imported count, extant count, vendors not found (hover tooltip), error grid.

### Sales Summaries

**Grid Display**
- Columns: Client (hidden if only one client), Date, Debits (itemized list), Credits (itemized list).
- Each item shows category, amount, and "missing account" pill in red if no account mapped.
- Total row shows "Total: $X" with green pill if balanced, red if unbalanced.
- Row action: Edit button.

**Filtering**
- Date range (start/end).
- Scoped to user's valid clients.

**Edit Wizard**
- Shows all sales summary items in a grid: Category, Account, Debits, Credits.
- Manual items: editable category, account typeahead, debit/credit inputs, removable.
- Auto items: read-only category and amount, editable account.
- Account typeahead is scoped by client and filtered for invoice-purpose accounts.
- Live total row and unbalanced row update on amount changes.
- Validation: each item must have exactly one of credit or debit, not both.
- Validation: debits must equal credits (balanced).
- Save updates ledger-mapped account assignments. Manual items get `manual?` flag and ledger-side/amount attached.

## Cross-Cutting Behaviors

### Admin-only Access
- All admin routes use `wrap-admin` middleware.
- Non-admin authenticated users receive an authorization failure (typically redirect or error).
- Unauthenticated users are redirected to login via `wrap-client-redirect-unauthenticated`.

### Impersonation
- Admin users can select a client from the global client selector.
- Some admin grids (clients, transaction rules, sales summaries) respect the selected client and filter results accordingly.

### History Tracking
- All mutating admin operations use `audit-transact` or `audit-transact-batch`.
- Transactions record `:audit/user` attribute.
- The History page queries Datomic's history database (`dc/history`) to show all changes to an entity.

### Permissions
- Admin role is required for all admin handlers.
- No finer-grained permissions within admin area.

### Form Validation Patterns
- Malli schemas enforce form structure.
- `wrap-schema-enforce` validates query params, route params, and form params.
- `wrap-form-4xx-2` re-renders dialogs with validation errors on 400 responses.
- HTMX response targets (`#form-errors .error-content`) display field-level errors.

### Solr Indexing
- After create/update of clients, accounts, and vendors, Solr documents are reindexed.
- This affects search typeaheads across the application.

## Edge Cases

**Client Management**
- Client code must be unique on create; immutable on edit.
- Bank account code is immutable after creation.
- Financial code (numeric) required when "Include in Reports" is true.
- Square location refresh times out after 2 seconds → shows "No locations found."
- Bank accounts are sortable via drag-and-drop (sortable.js integration via `hx-trigger="end"`).

**Account Management**
- Numeric code must be unique on create.
- A client can only have one override per account.
- Applicability and allowances are enums with specific values.

**Vendor Management**
- Vendor merge fails if source equals target.
- Account override typeahead depends on client selection; changing client updates available accounts.
- Terms override requires unique clients (no duplicate client overrides).

**Transaction Rules**
- Rule execution only affects unapproved transactions.
- Transactions before client's `locked-until` date are excluded from execution.
- Account percentages must sum to exactly 100%.
- If account has a fixed location, the rule location must match.

**Background Jobs**
- Cannot start a job that is already running (based on ECS task status).
- ECS API failures propagate as exceptions.

**Excel Invoices**
- Vendor name resolution is case-sensitive exact match.
- Location format expected: `CLIENTCODE-LOCATION`.
- Missing client code or location adds error row.
- Cash check type creates paid invoice with transaction; others create unpaid invoice.

**Sales Summaries**
- Debits and credits must balance to save.
- Manual items require both category and amount.
- Account typeahead is scoped to client + invoice-purpose accounts.

**History**
- Entity ID must be parseable as a Long; otherwise shows error notification.
- Very old entities may have no history if created before audit attributes.

## Test Data Requirements

### Users
- Admin user with `:user/role :user-role/admin`.
- Non-admin user with `:user/role :user-role/user` for access control tests.

### Clients
- Client with `:client/name`, `:client/code` (unique), `:client/locations`.
- Client with `:client/locked-until` in the past and future.
- Client with bank accounts (cash, credit, checking types).
- Client with Square auth token for integration tests.
- Client with feature flags and groups.

### Accounts
- Account with `:account/numeric-code` (unique), `:account/name`, `:account/type`.
- Account with `:account/location` fixed.
- Account with client overrides.

### Vendors
- Vendor with `:vendor/name`, `:vendor/default-account`.
- Vendor with terms overrides and account overrides.
- Hidden and non-hidden vendors.
- Vendor with 1099 legal entity info.

### Transaction Rules
- Rule with description pattern, client, bank account, amount gte/lte.
- Rule with account assignments summing to 100%.
- Unapproved transactions matching rule criteria.
- Transactions before and after client's locked-until date.

### Background Jobs
- ECS cluster with task definitions containing `INTEGREAT_JOB` env var.
- Or mock ECS responses for unit tests.

### Import Batches
- Import batch entities with `:import-batch/date`, `:import-batch/source`, `:import-batch/status`.

### Sales Summaries
- Sales summary with items having `:ledger-mapped/ledger-side` and `:ledger-mapped/amount`.
- Both manual and auto-generated items.

## Dependencies

- Datomic (history, transactions, pull API)
- HTMX (frontend interactivity)
- Alpine.js (modal state, conditional visibility)
- Chartist (dashboard charts)
- Solr (search indexing)
- ECS API (background jobs)
- Malli (schema validation)
- Bidi (routing)

## Related Test Files

- `test/clj/auto_ap/integration/graphql/users.clj` - User role and permission tests
- `test/clj/auto_ap/integration/graphql/accounts.clj` - Account search and override tests
- `test/clj/auto_ap/integration/graphql/vendors.clj` - Vendor management tests
- `test/clj/auto_ap/integration/graphql/transaction_rules.clj` - Rule matching and execution tests