fixes and refactor

README.md

@@ -21,6 +21,25 @@ Modern database system for legal practice management, financial tracking, and do
 - **Authentication**: JWT with bcrypt password hashing
 - **Validation**: Pydantic v2
 
+## ⚡ Search Performance (FTS + Cache)
+
+- Full-text search is enabled via SQLite FTS5 for Customers (`rolodex`), Files, Ledger, and QDRO.
+  - The app creates virtual FTS tables and sync triggers at startup.
+  - On engines without FTS5, search falls back to standard `ILIKE` queries.
+- Common filter columns are indexed for faster filtering: `files(status, file_type, empl_num)` and `ledger(t_type, empl_num)`.
+- Response caching (optional) uses Redis for global search and suggestions.
+  - Cache TTL: ~90s for global search, ~60s for suggestions.
+  - Cache is auto-invalidated on create/update/delete affecting customers, files, ledger, or QDROs.
+
+Enable cache:
+```bash
+export CACHE_ENABLED=true
+export REDIS_URL=redis://localhost:6379/0
+```
+
+Diagnostics:
+- `GET /api/search/_debug` reports whether FTS tables exist and Redis is available (requires auth).
+
 ## 📊 Database Structure
 Based on analysis of legacy Pascal system:
 
@@ -134,6 +153,48 @@ delphi-database/
 
 ## 🔧 API Endpoints
 
+### Common pagination, sorting, and totals
+- Many list endpoints support the same query parameters:
+  - `skip` (int): offset for pagination. Default varies per endpoint.
+  - `limit` (int): page size. Most endpoints cap at 200–1000.
+  - `sort_by` (str): whitelisted field name per endpoint.
+  - `sort_dir` (str): `asc` or `desc`.
+  - `include_total` (bool): when `true`, the response is an object `{ items, total }`; otherwise a plain list is returned for backwards compatibility.
+- Some endpoints also support `search` (tokenized across multiple columns with AND semantics) for simple text filtering.
+
+Examples:
+```bash
+# Support tickets (admin)
+curl \
+  "http://localhost:6920/api/support/tickets?include_total=true&limit=10&sort_by=created&sort_dir=desc"
+
+# My support tickets (current user)
+curl \
+  "http://localhost:6920/api/support/my-tickets?include_total=true&limit=10&sort_by=updated&sort_dir=desc"
+
+# QDROs for a file
+curl \
+  "http://localhost:6920/api/documents/qdros/FILE-123?include_total=true&sort_by=updated&sort_dir=desc"
+
+# Ledger entries for a file
+curl \
+  "http://localhost:6920/api/financial/ledger/FILE-123?include_total=true&sort_by=date&sort_dir=desc"
+
+# Customer phones
+curl \
+  "http://localhost:6920/api/customers/CUST-1/phones?include_total=true&sort_by=location&sort_dir=asc"
+```
+
+Allowed sort fields (high level):
+- Support tickets: `created`, `updated`, `resolved`, `priority`, `status`, `subject`
+- My tickets: `created`, `updated`, `resolved`, `priority`, `status`, `subject`
+- QDROs (list and by file): `file_no`, `version`, `status`, `created`, `updated`
+- Ledger by file: `date`, `item_no`, `amount`, `billed`
+- Templates: `form_id`, `form_name`, `category`, `created`, `updated`
+- Files: `file_no`, `client`, `opened`, `closed`, `status`, `amount_owing`, `total_charges`
+- Admin users: `username`, `email`, `first_name`, `last_name`, `created`, `updated`
+- Customer phones: `location`, `phone`
+
 ### Authentication
 - `POST /api/auth/login` - User login
 - `POST /api/auth/register` - Register user (admin only)
@@ -156,19 +217,28 @@ delphi-database/
 - `DELETE /api/files/{file_no}` - Delete file
 
 ### Financial (Ledger)
-- `GET /api/financial/ledger/{file_no}` - Get ledger entries
+- `GET /api/financial/ledger/{file_no}` - Get ledger entries (supports pagination, sorting, `include_total`)
 - `POST /api/financial/ledger/` - Create transaction
 - `PUT /api/financial/ledger/{id}` - Update transaction
 - `DELETE /api/financial/ledger/{id}` - Delete transaction
 - `GET /api/financial/reports/{file_no}` - Financial reports
 
 ### Documents (QDROs)
-- `GET /api/documents/qdros/{file_no}` - Get QDROs for file
+- `GET /api/documents/qdros/{file_no}` - Get QDROs for file (supports pagination, sorting, `include_total`)
 - `POST /api/documents/qdros/` - Create QDRO
 - `GET /api/documents/qdros/{file_no}/{id}` - Get specific QDRO
 - `PUT /api/documents/qdros/{file_no}/{id}` - Update QDRO
 - `DELETE /api/documents/qdros/{file_no}/{id}` - Delete QDRO
 
+### Support
+- `POST /api/support/tickets` - Create support ticket (public; auth optional)
+- `GET /api/support/tickets` - List tickets (admin; supports filters, search, pagination, sorting, `include_total`)
+- `GET /api/support/tickets/{id}` - Get ticket details (admin)
+- `PUT /api/support/tickets/{id}` - Update ticket (admin)
+- `POST /api/support/tickets/{id}/responses` - Add response (admin)
+- `GET /api/support/my-tickets` - List current user's tickets (supports status filter, search, pagination, sorting, `include_total`)
+- `GET /api/support/stats` - Ticket statistics (admin)
+
 ### Search
 - `GET /api/search/customers?q={query}` - Search customers
 - `GET /api/search/files?q={query}` - Search files