notid/integreat
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

refactor(all): rewrite all behavior docs in table format with checkboxes

Browse Source 
Rewrite all 11 remaining behavior documents to match the streamlined
invoice.md format:

- dashboard.md: 250 lines, 62 behaviors
- payment.md: 260 lines, behaviors for list, void, check printing, ACH
- transaction.md: 310 lines, list, import, admin insights
- ledger.md: 519 lines, entries, P&L, balance sheet, cash flows
- company.md: 320 lines, profile, 1099s, Plaid/Yodlee, reports
- admin.md: 494 lines, clients, accounts, vendors, rules, jobs, history
- pos.md: 405 lines, sales, deposits, tenders, refunds, shifts
- search-indicators.md: 167 lines, search modal, indicators
- auth.md: 184 lines, login, logout, impersonation, sessions
- outgoing-invoice.md: 192 lines, create, line items, PDF
- legacy-spa.md: 340 lines, all legacy pages (docs only)

All documents now use:
- Testing Patterns section with reusable abstractions
- Numbered tables: # | Behavior | Test Strategy | Status
- It should... behavior descriptions
- Checkboxes [ ]/[x] for tracking implementation
- Cross-Cutting Behaviors for permissions, lock dates, etc.
- Test Data Requirements tables
- Existing Tests to Preserve sections

Total: 3,844 lines of behavior documentation across 12 subsystem docs.
This commit is contained in:
Bryce
2026-05-04 13:48:51 -07:00
parent e14a23ff54
commit d627e3c5d0
11 changed files with 2837 additions and 2500 deletions
Download Patch File Download Diff File Expand all files Collapse all files

727
docs/testing/behaviors/admin.md
View File

@@ -4,383 +4,487 @@
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
**Testing Philosophy**
- Prefer unit tests for pure business logic (calculations, validations, transformations)
- Use integration tests for database interactions and cross-system flows
- Use UI tests only for end-to-end happy paths that touch multiple pages
- Every behavior must be user-visible; no tests for implementation details
| 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`.
## Testing Patterns
## Behaviors by Page
### Pattern: Grid Page Behaviors
Most list pages in Integreat follow the same pattern:
1. Fetch IDs via Datomic query with filters
2. Hydrate results via `pull-many`
3. Render table with sortable columns
4. Support selection (individual / all / all-filtered)
5. Action buttons appear conditionally based on permissions and selection state
### Admin Dashboard
**Test implications:** Validate the query generation, not the rendering. UI tests only need to verify one filter and one sort work end-to-end.
**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`.
### Pattern: Wizard Behaviors
Wizards are multi-step forms with HTMX-driven navigation:
1. Each step is a GET that renders a form fragment
2. Form submissions are POST/PUT with validation
3. Navigation between steps updates the wizard state
4. Final submit creates/updates the entity
**Access Control**
- Only accessible to users with admin role.
- Unauthenticated users are redirected to login.
**Test implications:** Unit test validation logic and state transitions. Integration test the full wizard flow once. UI test only the happy path.
### Client Management
### Pattern: Admin Permission Gates
Every admin operation checks:
1. `wrap-client-redirect-unauthenticated` — redirects unauthenticated users to login
2. `wrap-admin` — blocks non-admin authenticated users
3. `assert-can-see-client` — when impersonating, user has access to the client
**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.
**Test implications:** Integration test each gate independently. UI tests only verify the happy path with an admin user.
**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.
## Dashboard
**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).
### Display Behaviors
**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.
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 1.1 | It should display a bar chart showing client count at 2 years ago, 1 year ago, and today | UI | [ ] |
| 1.2 | It should display a line chart showing Datomic transaction counts per hour over the last 24 hours | UI | [ ] |
| 1.3 | It should render the standard admin page layout with the admin-aside-nav sidebar | UI | [ ] |
**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.
### Access Control Behaviors
### Account Management
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 2.1 | It should redirect unauthenticated users to the login page | Integration | [ ] |
| 2.2 | It should show an authorization failure for authenticated non-admin users | Integration | [ ] |
**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.
## Clients
**Sorting**
- By code, name, type, location.
- Default sort by upper-cased numeric code.
### Grid Display Behaviors
**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.
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 3.1 | It should display a table with columns: Name, Code, Locations, Emails, Status | UI | [ ] |
| 3.2 | It should show location values as pills in the Locations column | UI | [ ] |
| 3.3 | It should show email values as pills in the Emails column | UI | [ ] |
| 3.4 | It should show lock status as "Locked <date>" with green color when less than 90 days old | UI | [ ] |
| 3.5 | It should show lock status with yellow color when between 90 days and 1 year old | UI | [ ] |
| 3.6 | It should show lock status with red color when more than 1 year old | UI | [ ] |
| 3.7 | It should show "Not locked" in red when no lock date is set | UI | [ ] |
| 3.8 | It should show bank account integration status pills in red for failed or unauthorized accounts | UI | [ ] |
| 3.9 | It should show a Biweekly Sales PowerQuery button on each row | UI | [ ] |
| 3.10 | It should show an Edit button (pencil icon) on each row | UI | [ ] |
| 3.11 | It should show a "New Client" button that opens the client wizard | UI | [ ] |
**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.
### Filtering Behaviors
### Vendor Management
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 4.1 | It should filter clients by name using case-insensitive substring match | Integration | [ ] |
| 4.2 | It should filter clients by code using exact match on upper-cased code | Integration | [ ] |
| 4.3 | It should filter clients by group using exact match on upper-cased group | Integration | [ ] |
| 4.4 | It should support an "All" or "Only mine" filter to show only clients assigned to the current user | Integration | [ ] |
| 4.5 | It should trigger HTMX requests with 500ms debounce on filter change and 1000ms debounce on keyup | Integration | [ ] |
**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.
### Sorting Behaviors
**Filtering**
- Name (case-insensitive substring on upper-cased name).
- Type: All, Only hidden, Only global.
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 5.1 | It should sort clients by name ascending/descending | Integration | [ ] |
| 5.2 | It should sort clients by code ascending/descending | Integration | [ ] |
| 5.3 | It should paginate results with 25 clients per page by default | Integration | [ ] |
**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).
### Client Wizard Behaviors
**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.
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 6.1 | It should show a multi-step linear wizard with steps: Info, Matches, Contact, Bank Accounts, Integrations, Cash Flow, Other Settings | UI | [ ] |
| 6.2 | It should require Name on the Info step | Integration | [ ] |
| 6.3 | It should prevent editing the Code field when editing an existing client | UI | [ ] |
| 6.4 | It should allow setting a Locked Until date on the Info step | UI | [ ] |
| 6.5 | It should show a dynamic grid for adding and removing locations on the Info step | UI | [ ] |
| 6.6 | It should allow configuring string match patterns and location match patterns on the Matches step | UI | [ ] |
| 6.7 | It should allow entering address fields and email contacts on the Contact step | UI | [ ] |
| 6.8 | It should show a sortable card list of existing bank accounts on the Bank Accounts step | UI | [ ] |
| 6.9 | It should allow adding cash accounts with nickname, code, financial code, start date, include-in-reports, and visible-for-payment fields | UI | [ ] |
| 6.10 | It should allow adding credit card accounts with bank name, account number, and Plaid/Yodlee/Intuit integration selectors | UI | [ ] |
| 6.11 | It should allow adding checking accounts with routing number, bank code, and check number fields | UI | [ ] |
| 6.12 | It should require a financial code when "Include in Reports" is enabled for a bank account | Unit + Integration | [ ] |
| 6.13 | It should allow entering a Square auth token and mapping Square locations to client locations on the Integrations step | UI | [ ] |
| 6.14 | It should show "No locations found" when the Square location refresh times out after 2 seconds | Integration | [ ] |
| 6.15 | It should allow entering Week A/B credits and debits on the Cash Flow step | UI | [ ] |
| 6.16 | It should allow selecting feature flags and entering groups on the Other Settings step | UI | [ ] |
| 6.17 | It should validate that the client code is unique when creating a new client | Unit + Integration | [ ] |
| 6.18 | It should upper-case group values on save | Unit | [ ] |
| 6.19 | It should flash the updated row in the grid and close the modal after a successful save | UI | [ ] |
| 6.20 | It should reindex the client in Solr after a successful save | Integration | [ ] |
**Save Behavior**
- POST for create, PUT for update.
- Solr reindexes vendor name + hidden flag.
### Biweekly Sales PowerQuery Behaviors
### Transaction Rules
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 7.1 | It should generate 6 saved queries per client (sales summary, category, expected deposits, tenders, refunds, cash drawer shifts) | Integration | [ ] |
| 7.2 | It should open a modal with copy-to-clipboard buttons for Excel Power Query M-code | UI | [ ] |
**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).
## Accounts
**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).
### Grid Display Behaviors
**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!"
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 8.1 | It should display a table with columns: Code, Name, Type, Location | UI | [ ] |
| 8.2 | It should show the account type as a colored pill | UI | [ ] |
| 8.3 | It should show an Edit button on each row | UI | [ ] |
| 8.4 | It should show a "New Account" button | UI | [ ] |
**Delete**
- Confirms before delete.
- Retracts entity from Datomic.
- Row fades out with "live-removed" class.
### Filtering Behaviors
### Background Jobs
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 9.1 | It should filter accounts by name using case-insensitive substring match on upper-cased name | Integration | [ ] |
| 9.2 | It should filter accounts by code using exact numeric match | Integration | [ ] |
| 9.3 | It should filter accounts by type: All, Dividend, Asset, Equity, Liability, Expense, Revenue, or None | Integration | [ ] |
**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.
### Sorting Behaviors
**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.
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 10.1 | It should sort accounts by code, name, type, or location ascending/descending | Integration | [ ] |
| 10.2 | It should default sort by upper-cased numeric code | Integration | [ ] |
### History / Audit
### Account Dialog Behaviors
**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).
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 11.1 | It should show a modal dialog with a live-updating header displaying the numeric code and name | UI | [ ] |
| 11.2 | It should require a numeric code when creating a new account | Integration | [ ] |
| 11.3 | It should hide the numeric code field when editing an existing account | UI | [ ] |
| 11.4 | It should require a name and account type | Integration | [ ] |
| 11.5 | It should allow setting Invoice Allowance, Vendor Allowance, and Applicability as dropdown enums | UI | [ ] |
| 11.6 | It should show a Client Overrides grid with client typeahead and override name | UI | [ ] |
| 11.7 | It should validate that no client appears more than once in the Client Overrides grid | Unit + Integration | [ ] |
| 11.8 | It should validate that the numeric code is unique when creating a new account | Unit + Integration | [ ] |
| 11.9 | It should reindex the account and all client overrides in Solr after a successful save | Integration | [ ] |
**Inspector**
- Card showing all attributes of an entity at current database value.
- Clickable entity IDs recurse into history.
---
### Import Batches
## Vendors
**Grid Display**
- Columns: Date, Source, Status, User, Imported, Pre-existing, Suppressed.
- Row action: External link to transactions filtered by import batch.
### Grid Display Behaviors
**Filtering**
- Date range (start/end).
- Source (enum: import-source values).
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 12.1 | It should display a table with columns: Name, Email, Default Account | UI | [ ] |
| 12.2 | It should show an "Unused" pill in red when a vendor has 0 clients | UI | [ ] |
| 12.3 | It should show a "Used by N clients" pill in primary color when a vendor is assigned to clients | UI | [ ] |
| 12.4 | It should show a "Used N times" pill in secondary color when a vendor has transaction usage | UI | [ ] |
| 12.5 | It should show an Edit button on each row that opens the vendor wizard | UI | [ ] |
| 12.6 | It should show a "Merge" button for merging vendors | UI | [ ] |
| 12.7 | It should show a "New Vendor" button | UI | [ ] |
**Sorting**
- By date, source, status, user.
### Filtering Behaviors
### Excel Invoices
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 13.1 | It should filter vendors by name using case-insensitive substring match on upper-cased name | Integration | [ ] |
| 13.2 | It should filter vendors by visibility: All, Only hidden, or Only global | Integration | [ ] |
**Display**
- Single-page form with large textarea for tab-separated invoice data.
- Shows sample data as placeholder.
### Vendor Wizard Behaviors
**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.
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 14.1 | It should show a multi-step wizard with steps: Info, Terms, Account, Address, Legal | UI | [ ] |
| 14.2 | It should require a name of at least 3 characters on the Info step | Unit + Integration | [ ] |
| 14.3 | It should allow toggling a "Print As" alias on the Info step | UI | [ ] |
| 14.4 | It should show a "Hidden" checkbox on the Info step visible only to admins | UI | [ ] |
| 14.5 | It should allow setting terms in days and a grid of client-specific terms overrides on the Terms step | UI | [ ] |
| 14.6 | It should allow configuring a list of clients for automatically paid when due on the Terms step | UI | [ ] |
| 14.7 | It should allow selecting a default account via typeahead on the Account step | UI | [ ] |
| 14.8 | It should show an Account Overrides grid where account typeahead is scoped by selected client | Integration | [ ] |
| 14.9 | It should allow entering address fields with a 2-character state and 5-character zip on the Address step | UI | [ ] |
| 14.10 | It should allow entering a legal entity name OR first/middle/last name, TIN, TIN type, and 1099 type on the Legal step | UI | [ ] |
| 14.11 | It should validate that terms override clients are unique with no duplicates | Unit + Integration | [ ] |
| 14.12 | It should reindex the vendor name and hidden flag in Solr after a successful save | Integration | [ ] |
### Sales Summaries
### Vendor Merge Behaviors
**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.
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 15.1 | It should open a modal with Source Vendor and Target Vendor selectors | UI | [ ] |
| 15.2 | It should validate that the source and target vendors are different | Unit + Integration | [ ] |
| 15.3 | It should retract all references to the source vendor and assert them as the target vendor on merge | Integration | [ ] |
| 15.4 | It should show a success notification after a successful merge | UI | [ ] |
**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.
## Rules
### Grid Display Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 16.1 | It should display a table with columns: Client, Bank Account, Description, Amount, Note | UI | [ ] |
| 16.2 | It should show a group pill in the Client column when the rule applies to a client group | UI | [ ] |
| 16.3 | It should show amount gte/lte filters as pills in the Amount column | UI | [ ] |
| 16.4 | It should show Delete, Execute, and Edit row action buttons | UI | [ ] |
| 16.5 | It should show a "New Transaction Rule" button | UI | [ ] |
### Filtering Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 17.1 | It should filter rules by vendor using an entity typeahead | Integration | [ ] |
| 17.2 | It should filter rules by note using case-insensitive regex match | Integration | [ ] |
| 17.3 | It should filter rules by description using case-insensitive substring match | Integration | [ ] |
| 17.4 | It should filter rules by client group using exact upper-cased match | Integration | [ ] |
### Transaction Rule Wizard Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 18.1 | It should show a two-step wizard: Edit then Test | UI | [ ] |
| 18.2 | It should require a description regex pattern of at least 3 characters on the Edit step | Unit + Integration | [ ] |
| 18.3 | It should allow toggling optional filters for Client, Client Group, Bank Account, Amount range, and Day of Month range | UI | [ ] |
| 18.4 | It should scope the bank account selector to the selected client | Integration | [ ] |
| 18.5 | It should allow assigning a vendor, configuring account grids, and setting approval status as outcomes | UI | [ ] |
| 18.6 | It should derive account location from the account's fixed location, client locations, or "Shared" | Unit | [ ] |
| 18.7 | It should validate that account percentages sum to exactly 100% | Unit + Integration | [ ] |
| 18.8 | It should validate that the selected bank account belongs to the selected client | Unit + Integration | [ ] |
| 18.9 | It should validate that the rule location matches the account's fixed location when one is set | Unit + Integration | [ ] |
| 18.10 | It should show up to 15 matching transactions on the Test step with client, bank, date, and description | Integration | [ ] |
| 18.11 | It should display a badge showing the total match count with "99+" when 99 or more transactions match | UI | [ ] |
### Rule Execution Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 19.1 | It should open a dialog with checkbox-selectable transactions that match the rule and are unapproved | UI | [ ] |
| 19.2 | It should include only transactions on or after the client's locked-until date | Integration | [ ] |
| 19.3 | It should allow selecting all matching transactions or individual transactions | UI | [ ] |
| 19.4 | It should apply rule coding to each selected transaction | Integration | [ ] |
| 19.5 | It should update the Solr index after rule execution | Integration | [ ] |
| 19.6 | It should show a notification reading "Successfully coded X of Y transactions!" after execution | UI | [ ] |
### Rule Deletion Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 20.1 | It should show a confirmation dialog before deleting a rule | UI | [ ] |
| 20.2 | It should retract the rule entity from the database on confirmation | Integration | [ ] |
| 20.3 | It should fade out the row with a "live-removed" animation after deletion | UI | [ ] |
---
## Jobs
### Grid Display Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 21.1 | It should display a table with columns: Start time, End time, Duration, Name, Status | UI | [ ] |
| 21.2 | It should show status values as running, pending, succeeded, or failed | UI | [ ] |
| 21.3 | It should display ECS tasks filtered by the INTEGREAT_JOB environment variable | Integration | [ ] |
| 21.4 | It should show a "Run job" button | UI | [ ] |
### Job Start Dialog Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 22.1 | It should show a job type dropdown with options: 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 | UI | [ ] |
| 22.2 | It should show a dynamic subform with an S3 URL path input for Bulk Journal Import and Register Invoice Import | UI | [ ] |
| 22.3 | It should show a client typeahead and days input (1-120) for Load Historical Square Sales | UI | [ ] |
| 22.4 | It should prevent starting a job that is already running | Integration | [ ] |
| 22.5 | It should launch an ECS Fargate Spot task on submit | Integration | [ ] |
---
## History
### Search Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 23.1 | It should allow searching for an entity by numeric Datomic entity ID | UI | [ ] |
| 23.2 | It should show an error notification when the entity ID cannot be parsed as a Long | Integration | [ ] |
### Display Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 24.1 | It should display a history table with columns: Date, User, Field, From value, To value | UI | [ ] |
| 24.2 | It should format date values in local format | Unit | [ ] |
| 24.3 | It should display large integers greater than 1 million as clickable links to that entity's history | UI | [ ] |
| 24.4 | It should display nil values as "(none)" | Unit | [ ] |
| 24.5 | It should allow clicking an entity ID to load that entity's history inline | Integration | [ ] |
| 24.6 | It should show a Snapshot link that opens an inspector displaying all entity attributes | UI | [ ] |
| 24.7 | It should show all history rows without pagination | Integration | [ ] |
### Inspector Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 25.1 | It should display a card showing all attributes of an entity at the current database value | UI | [ ] |
| 25.2 | It should allow clicking entity IDs within the inspector to recurse into that entity's history | Integration | [ ] |
---
## Imports
### Grid Display Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 26.1 | It should display a table with columns: Date, Source, Status, User, Imported, Pre-existing, Suppressed | UI | [ ] |
| 26.2 | It should show an external link on each row to transactions filtered by import batch | UI | [ ] |
| 26.3 | It should show a "New Import" button | UI | [ ] |
### Filtering Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 27.1 | It should filter import batches by date range | Integration | [ ] |
| 27.2 | It should filter import batches by source | Integration | [ ] |
### Sorting Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 28.1 | It should sort import batches by date, source, status, or user | Integration | [ ] |
| 28.2 | It should paginate results with 25 import batches per page by default | Integration | [ ] |
---
## Excel Invoices
### Display Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 29.1 | It should display a single-page form with a large textarea for tab-separated invoice data | UI | [ ] |
| 29.2 | It should show sample data as a placeholder in the textarea | UI | [ ] |
### Import Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 30.1 | It should parse 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 | Unit | [ ] |
| 30.2 | It should resolve the client by code or name | Integration | [ ] |
| 30.3 | It should resolve the vendor by exact case-sensitive name match | Integration | [ ] |
| 30.4 | It should resolve the account by numeric code | Integration | [ ] |
| 30.5 | It should group rows into new, existing, and error categories | Unit | [ ] |
| 30.6 | It should create a paid invoice with zero outstanding balance and a cash transaction when the check type is "Cash" | Integration | [ ] |
| 30.7 | It should create an unpaid invoice with full outstanding balance when the check type is not "Cash" | Integration | [ ] |
| 30.8 | It should display results as pills showing imported count, extant count, and vendors not found with hover tooltip | UI | [ ] |
| 30.9 | It should display an error grid for rows that failed validation | UI | [ ] |
---
## Sales Summaries
### Grid Display Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 31.1 | It should display a table with columns: Client, Date, Debits, Credits | UI | [ ] |
| 31.2 | It should hide the Client column when only one client is selected | UI | [ ] |
| 31.3 | It should show each debit/credit item with category, amount, and a red "missing account" pill when no account is mapped | UI | [ ] |
| 31.4 | It should show a total row with a green pill when debits equal credits, or a red pill when unbalanced | UI | [ ] |
| 31.5 | It should show an Edit button on each row | UI | [ ] |
### Filtering Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 32.1 | It should filter sales summaries by date range | Integration | [ ] |
| 32.2 | It should scope results to the user's valid clients | Integration | [ ] |
### Edit Wizard Behaviors
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 33.1 | It should display a grid of sales summary items with Category, Account, Debits, and Credits columns | UI | [ ] |
| 33.2 | It should allow editing the category, account, and debit/credit amounts for manual items | UI | [ ] |
| 33.3 | It should allow removing manual items from the grid | UI | [ ] |
| 33.4 | It should display auto-generated items with read-only category and amount but editable account | UI | [ ] |
| 33.5 | It should scope the account typeahead to the client and filter for invoice-purpose accounts | Integration | [ ] |
| 33.6 | It should update the live total row and unbalanced row when amounts change | UI | [ ] |
| 33.7 | It should validate that each item has exactly one of credit or debit, not both | Unit + Integration | [ ] |
| 33.8 | It should validate that total debits equal total credits before saving | Unit + Integration | [ ] |
| 33.9 | It should update ledger-mapped account assignments and flag manual items on save | Integration | [ ] |
---
## 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`.
### Admin-Only Access Behaviors
### 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.
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 34.1 | It should redirect unauthenticated users to the login page on all admin routes | Integration | [ ] |
| 34.2 | It should show an authorization failure for authenticated non-admin users on all admin routes | Integration | [ ] |
| 34.3 | It should require admin role for all mutating admin handlers | Integration | [ ] |
### 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.
### Audit History Behaviors
### Permissions
- Admin role is required for all admin handlers.
- No finer-grained permissions within admin area.
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 35.1 | It should record the admin user who performed each mutating operation via the `:audit/user` attribute | Integration | [ ] |
| 35.2 | It should write all mutating operations through `audit-transact` or `audit-transact-batch` | Integration | [ ] |
| 35.3 | It should allow querying all changes to an entity from Datomic's history database on the History page | Integration | [ ] |
### 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.
### Impersonation Behaviors
### Solr Indexing
- After create/update of clients, accounts, and vendors, Solr documents are reindexed.
- This affects search typeaheads across the application.
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 36.1 | It should allow admin users to select a client from the global client selector to filter admin grids | UI | [ ] |
| 36.2 | It should respect the selected client when filtering the Clients, Transaction Rules, and Sales Summaries grids | Integration | [ ] |
## Edge Cases
### Form Validation Behaviors
**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"`).
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 37.1 | It should enforce form structure via Malli schemas | Unit | [ ] |
| 37.2 | It should validate query params, route params, and form params via `wrap-schema-enforce` | Integration | [ ] |
| 37.3 | It should re-render dialogs with field-level validation errors on 400 responses | Integration | [ ] |
**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.
### Solr Indexing Behaviors
**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).
| # | Behavior | Test Strategy | Status |
|---|----------|---------------|--------|
| 38.1 | It should reindex Solr documents after creating or updating a client | Integration | [ ] |
| 38.2 | It should reindex Solr documents after creating or updating a vendor or account | Integration | [ ] |
**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.
| Entity | Requirements |
|--------|-------------|
| **Users** | Admin user with `:user/role :user-role/admin`; non-admin user with `:user/role :user-role/user` |
| **Clients** | Client with name, code, and locations; client with locked-until in past and future; client with bank accounts (cash, credit, checking); client with Square auth token; client with feature flags and groups |
| **Accounts** | Account with unique numeric code, name, and type; account with fixed location; account with client overrides |
| **Vendors** | Vendor with name and 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 |
| **Import Batches** | Import batch entities with date, source, and status |
| **Sales Summaries** | Sales summary with ledger-mapped items; both manual and auto-generated items |
### 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.
## Existing Tests to Preserve
### 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.
- `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
## Dependencies
- Datomic (history, transactions, pull API)
- Datomic (primary store, history, pull API)
- HTMX (frontend interactivity)
- Alpine.js (modal state, conditional visibility)
- Chartist (dashboard charts)
@@ -388,10 +492,3 @@ All routes are wrapped with `wrap-client-redirect-unauthenticated` followed by `
- 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