T10: Monitoring, Performance, Documentation & Environment Config — 38 tests, ruff clean, docs OK

- Extended health endpoint: DB+Redis+Storage+Worker checks with degraded status - Prometheus metrics endpoint: admin-only, text/plain format - Metrics: http_requests_total, db_pool_connections, arq_jobs_total - Structured JSON logging (structlog): timestamp, level, method, path, status, duration_ms, tenant_id - Performance: page_size max 100 enforced (422), streaming CSV export (StreamingResponse) - Scripts: seed_perf_data.py, check_indexes.py - Docs: admin-guide.md (Deploy, Backup, Restore, Env-Vars, Troubleshooting), api-overview.md - README updated: prod setup, API section, env profiles, admin-guide link - .env.example: added SECRET_KEY, STORAGE_PATH, SMTP_* vars - 38 new tests, full regression 564/564 pass (0 failures) - Ruff: all checks passed
2026-07-01 23:15:35 +02:00
parent 0070fb3aea
commit 69e91fd5d0
24 changed files with 2249 additions and 266 deletions
@@ -0,0 +1,187 @@
+# LeoCRM API Overview
+
+> Summary of all API endpoints, grouped by domain.
+
+## Base URL
+
+```
+http://localhost:8000/api/v1
+```
+
+## Authentication
+
+All endpoints (except `/health` and `/auth/login`) require a valid session cookie obtained via login.
+
+| Endpoint | Method | Auth | Description |
+|---|---|---|---|
+| `/api/v1/auth/login` | POST | No | Login with email + password, returns session cookie |
+| `/api/v1/auth/register` | POST | No | Register first user (bootstrap) |
+| `/api/v1/auth/logout` | POST | Yes | Logout and destroy session |
+| `/api/v1/auth/me` | GET | Yes | Get current user profile |
+| `/api/v1/auth/refresh` | POST | Yes | Refresh session token |
+
+## Health & Monitoring
+
+| Endpoint | Method | Auth | Description |
+|---|---|---|---|
+| `/api/v1/health` | GET | No | Health check (DB, Redis, storage, worker) |
+| `/api/v1/metrics` | GET | Admin | Prometheus metrics (text/plain) |
+
+## Contacts
+
+| Endpoint | Method | Auth | Description |
+|---|---|---|---|
+| `/api/v1/contacts` | GET | Yes | List contacts (pagination, search, sort) — page_size max 100 |
+| `/api/v1/contacts` | POST | Yes | Create a contact (with optional company links) |
+| `/api/v1/contacts/export` | GET | Yes | Stream contacts as CSV (StreamingResponse) |
+| `/api/v1/contacts/{id}` | GET | Yes | Get a single contact with companies |
+| `/api/v1/contacts/{id}` | PUT | Yes | Update a contact |
+| `/api/v1/contacts/{id}` | DELETE | Yes | Delete a contact (soft or GDPR hard-delete) |
+
+### Query Parameters (List)
+
+| Parameter | Type | Default | Constraints |
+|---|---|---|---|
+| `page` | int | 1 | ≥1 |
+| `page_size` | int | 20 | ≥1, ≤100 (max 100 enforced) |
+| `search` | string | _(none)_ | Searches first_name, last_name, email |
+| `sort_by` | string | last_name | Column name |
+| `sort_order` | string | asc | `asc` or `desc` |
+
+## Companies
+
+| Endpoint | Method | Auth | Description |
+|---|---|---|---|
+| `/api/v1/companies` | GET | Yes | List companies (pagination, FTS, industry filter) — page_size max 100 |
+| `/api/v1/companies` | POST | Yes | Create a company |
+| `/api/v1/companies/export` | GET | Yes | Stream companies as CSV or XLSX |
+| `/api/v1/companies/{id}` | GET | Yes | Get a single company with contacts |
+| `/api/v1/companies/{id}` | PUT | Yes | Update a company |
+| `/api/v1/companies/{id}` | DELETE | Yes | Soft-delete a company |
+| `/api/v1/companies/{id}/contacts/{cid}` | POST | Yes | Link a contact to a company (N:M) |
+| `/api/v1/companies/{id}/contacts/{cid}` | DELETE | Yes | Unlink a contact from a company |
+| `/api/v1/companies/{id}/emails` | GET | Yes | Get emails for a company |
+
+## Users & Roles
+
+| Endpoint | Method | Auth | Description |
+|---|---|---|---|
+| `/api/v1/users` | GET | Admin | List users |
+| `/api/v1/users` | POST | Admin | Create/invite a user |
+| `/api/v1/users/{id}` | GET | Yes | Get user details |
+| `/api/v1/users/{id}` | PATCH | Admin | Update user (activate/deactivate, role) |
+| `/api/v1/users/{id}` | DELETE | Admin | Delete a user |
+| `/api/v1/roles` | GET | Admin | List roles |
+| `/api/v1/roles` | POST | Admin | Create a custom role |
+| `/api/v1/roles/{id}` | PUT | Admin | Update a role |
+| `/api/v1/roles/{id}` | DELETE | Admin | Delete a custom role |
+
+## Tenants
+
+| Endpoint | Method | Auth | Description |
+|---|---|---|---|
+| `/api/v1/tenants` | GET | Yes | List tenants for current user |
+| `/api/v1/tenants/current` | GET | Yes | Get current tenant |
+| `/api/v1/tenants/switch` | POST | Yes | Switch active tenant |
+
+## Notifications
+
+| Endpoint | Method | Auth | Description |
+|---|---|---|---|
+| `/api/v1/notifications` | GET | Yes | List notifications |
+| `/api/v1/notifications/{id}/read` | POST | Yes | Mark notification as read |
+| `/api/v1/notifications/read-all` | POST | Yes | Mark all as read |
+
+## Import/Export
+
+| Endpoint | Method | Auth | Description |
+|---|---|---|---|
+| `/api/v1/import/contacts` | POST | Yes | Import contacts from CSV/JSON |
+| `/api/v1/import/companies` | POST | Yes | Import companies from CSV/JSON |
+
+## Plugins
+
+| Endpoint | Method | Auth | Description |
+|---|---|---|---|
+| `/api/v1/plugins` | GET | Admin | List available plugins |
+| `/api/v1/plugins/{name}/install` | POST | Admin | Install a plugin |
+| `/api/v1/plugins/{name}/activate` | POST | Admin | Activate a plugin |
+| `/api/v1/plugins/{name}/deactivate` | POST | Admin | Deactivate a plugin |
+| `/api/v1/plugins/{name}/uninstall` | POST | Admin | Uninstall a plugin |
+
+## AI Copilot
+
+| Endpoint | Method | Auth | Description |
+|---|---|---|---|
+| `/api/v1/ai/chat` | POST | Yes | Send a message to the AI copilot |
+| `/api/v1/ai/conversations` | GET | Yes | List AI conversations |
+| `/api/v1/ai/conversations/{id}` | GET | Yes | Get conversation with messages |
+
+## Workflows
+
+| Endpoint | Method | Auth | Description |
+|---|---|---|---|
+| `/api/v1/workflows` | GET | Yes | List workflows |
+| `/api/v1/workflows` | POST | Admin | Create a workflow |
+| `/api/v1/workflows/{id}` | GET | Yes | Get workflow details |
+| `/api/v1/workflows/{id}/start` | POST | Yes | Start a workflow instance |
+
+## Pagination
+
+All list endpoints use cursor-based pagination with the following response format:
+
+```json
+{
+  "items": [...],
+  "total": 1234,
+  "page": 1,
+  "page_size": 20
+}
+```
+
+- `page_size` is capped at **100** (values >100 return HTTP 422).
+- `page` starts at 1.
+
+## CSV Export
+
+Contacts and companies support streaming CSV export:
+
+```
+GET /api/v1/contacts/export?format=csv
+GET /api/v1/companies/export?format=csv
+```
+
+- Uses `StreamingResponse` — does not buffer the entire file in memory.
+- Streams rows in batches of 500 for memory efficiency.
+- Supports `search` filter for filtered exports.
+
+## Swagger UI
+
+Interactive API documentation is available at:
+
+- **Swagger UI**: `http://localhost:8000/docs`
+- **ReDoc**: `http://localhost:8000/redoc`
+
+## Error Format
+
+All errors return a consistent JSON structure:
+
+```json
+{
+  "detail": {
+    "detail": "Human-readable error message",
+    "code": "error_code"
+  }
+}
+```
+
+Common status codes:
+- `200` — Success
+- `201` — Created
+- `204` — No content (delete success)
+- `400` — Bad request (invalid input)
+- `401` — Not authenticated
+- `403` — Forbidden (insufficient permissions)
+- `404` — Not found
+- `422` — Validation error (e.g., page_size > 100)
+- `500` — Internal server error