From 1f0808c303aa4fcffa177f093a779d68a409d344 Mon Sep 17 00:00:00 2001 From: curo1305 Date: Thu, 4 Jun 2026 23:24:09 +0200 Subject: [PATCH] =?UTF-8?q?docs(07-05):=20add=20plan=20summary=20=E2=80=94?= =?UTF-8?q?=20Tasks=201-3=20complete,=20Task=204=20human=20checkpoint=20pe?= =?UTF-8?q?nding?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Backend GET/PUT /api/admin/ai-config + test-connection + load_provider_config_by_id - Frontend getAiConfig/saveAiConfig/testAiConnection helpers + AdminAiConfigTab system section - DocumentCard classification_failed badge + Re-analyze button - 131 frontend tests pass, 369 backend tests pass --- .../07-05-SUMMARY.md | 157 ++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 .planning/phases/07-redo-and-optimize-llm-integration/07-05-SUMMARY.md diff --git a/.planning/phases/07-redo-and-optimize-llm-integration/07-05-SUMMARY.md b/.planning/phases/07-redo-and-optimize-llm-integration/07-05-SUMMARY.md new file mode 100644 index 0000000..2e935bf --- /dev/null +++ b/.planning/phases/07-redo-and-optimize-llm-integration/07-05-SUMMARY.md @@ -0,0 +1,157 @@ +--- +phase: 07-redo-and-optimize-llm-integration +plan: "05" +subsystem: ai-admin-frontend +tags: + - admin + - ai-providers + - frontend + - classification-failed + - vitest +dependency_graph: + requires: + - 07-04 # Celery retry harness + re-queue endpoint + provides: + - GET/PUT /api/admin/ai-config + - GET /api/admin/ai-config/test-connection + - load_provider_config_by_id + - AdminAiConfigTab System AI Providers section + - DocumentCard classification_failed badge + Re-analyze button + affects: + - backend/api/admin.py + - backend/services/ai_config.py + - frontend/src/api/client.js + - frontend/src/components/admin/AdminAiConfigTab.vue + - frontend/src/components/documents/DocumentCard.vue +tech_stack: + added: [] + patterns: + - "_ai_config_to_dict whitelist helper (mirrors _user_to_dict pattern)" + - "atomic UPDATE SET is_active = (provider_id = target) for single-active invariant" + - "write-only API key field (never pre-filled from server)" + - "Vue accordion with formByProvider reactive map" +key_files: + created: + - backend/tests/test_admin_ai_config.py # promoted from xfail stubs + - frontend/tests/api.spec.js + - frontend/tests/DocumentCard.spec.js + modified: + - backend/api/admin.py + - backend/services/ai_config.py + - frontend/src/api/client.js + - frontend/src/components/admin/AdminAiConfigTab.vue + - frontend/src/components/documents/DocumentCard.vue +decisions: + - "test-connection endpoint returns 200 ok=false for provider failures (not 5xx) so UI always gets structured status" + - "GET /ai-config synthesises stub entries for all 10 PROVIDER_DEFAULTS providers even before any DB rows exist" + - "api_key field in PUT: None=no change, ''=clear, non-empty=encrypt+store (three-way semantics)" + - "AdminAiConfigTab PROVIDER_DEFAULTS mirrored in frontend JS — no /api/ai/defaults endpoint needed" +metrics: + duration: "~45 minutes" + completed: "2026-06-04T21:23:15Z" + tasks_completed: 3 + tasks_total: 3 + files_changed: 7 +--- + +# Phase 7 Plan 05: Admin AI Providers Panel + Classification Failed Badge Summary + +Admin AI provider configuration panel (GET/PUT/test-connection) with api_key_enc whitelist + atomic is_active flip; DocumentCard classification-failed badge driving POST /classify re-queue. + +## Tasks Completed + +| Task | Name | Commit | Files | +|------|------|--------|-------| +| 1 | Admin AI-config backend + load_provider_config_by_id | e678930 | backend/api/admin.py, backend/services/ai_config.py, backend/tests/test_admin_ai_config.py | +| 2 | Frontend client helpers + AdminAiConfigTab system section + Vitest | 0db412d | frontend/src/api/client.js, frontend/src/components/admin/AdminAiConfigTab.vue, frontend/tests/api.spec.js | +| 3 | DocumentCard classification_failed badge + Re-analyze + Vitest | c45d9e4 | frontend/src/components/documents/DocumentCard.vue, frontend/tests/DocumentCard.spec.js | + +## What Was Built + +### Task 1 — Backend admin AI-config endpoints + +**`backend/services/ai_config.py`** gained `load_provider_config_by_id(session, provider_id)` — mirrors `load_provider_config` but filters by `provider_id` only (no `is_active` check), so the test-connection endpoint can test inactive rows. + +**`backend/api/admin.py`** received: +- `_ai_config_to_dict(row)` — whitelist helper returning `{provider_id, base_url, model_name, context_chars, is_active, has_api_key, updated_at}`. Explicitly excludes `api_key_enc` (T-07-01). +- `SystemAiConfigUpdate(BaseModel)` — Pydantic model with `extra="forbid"` and a `provider_id` validator against `PROVIDER_DEFAULTS` keys (T-07-13). +- `GET /api/admin/ai-config` — returns all 10 providers (DB rows + synthesised stubs from PROVIDER_DEFAULTS for unconfigured providers). Never exposes `api_key_enc`. +- `PUT /api/admin/ai-config` — upsert with three-way api_key semantics (None=no change, ""=clear, non-empty=HKDF-encrypt). Atomic is_active flip via single `UPDATE SET is_active = (provider_id = :target)`. Writes audit log with `fields_changed` only (T-07-14). Requires `get_current_admin` (T-07-15). +- `GET /api/admin/ai-config/test-connection?provider_id=X` — calls `load_provider_config_by_id`, builds provider, calls `health_check()`. Returns `{ok: bool}` as 200 — never 5xx for provider failures. + +**`backend/tests/test_admin_ai_config.py`** promoted from xfail stubs to three passing tests: +- `test_get_never_returns_key` — asserts `api_key_enc` and plaintext key absent from GET response +- `test_put_writes_active_provider` — asserts exactly 1 row with `is_active=True` after two PUTs +- `test_put_admin_only` — asserts non-admin PUT returns 403 + +### Task 2 — Frontend client helpers + AdminAiConfigTab system section + +**`frontend/src/api/client.js`** gained: +- `getAiConfig()` — GET `/api/admin/ai-config` +- `saveAiConfig(body)` — PUT with JSON body +- `testAiConnection(providerId)` — GET with `encodeURIComponent`-encoded provider_id + +**`frontend/src/components/admin/AdminAiConfigTab.vue`** extended: +- New `
` "System AI Providers (Global)" placed above the existing per-user assignment table +- Per-provider accordion (all 10 from PROVIDER_DEFAULTS) +- Write-only API key field (placeholder "(unchanged)" or "(not set)" — never pre-filled) +- Base URL, model name, context_chars inputs with PROVIDER_DEFAULTS as placeholders +- "Set Active", "Save", "Test Connection" buttons per provider +- Inline OK/Failed badges for test results (auto-clear after 3s) +- Existing `users`, `configs`, `saveConfig`, `providers` variables and per-user table left completely untouched (Pitfall 6 compliance) + +**`frontend/tests/api.spec.js`** — 4 Vitest tests verifying fetch URL, method, headers, body, and `encodeURIComponent` for provider_id. + +### Task 3 — DocumentCard classification_failed badge + +**`frontend/src/components/documents/DocumentCard.vue`**: +- Red pill badge `"Classification failed"` when `doc.status === 'classification_failed'` +- "Re-analyze" button with `@click.stop` (does not open doc on click) +- On click: calls `classifyDocument(props.doc.id)`, emits `'reclassified'` upward +- Spinner text "Re-analyzing…" while in flight; resets after 500ms +- Existing `v-if="doc.is_shared"` block preserved unchanged + +**`frontend/tests/DocumentCard.spec.js`** — 4 Vitest tests: badge renders for `classification_failed`, no badge for `ready`/`processing`, and `reanalyze()` calls `classifyDocument` with correct id and emits `reclassified`. + +## Test Results + +- Backend: 369 passed, 6 skipped, 7 xfailed (1 pre-existing test_extractor.py ModuleNotFoundError excluded) +- Frontend: 131 passed (16 test files), build exits 0 + +## Deviations from Plan + +None — plan executed exactly as written. The existing `AiConfigUpdate` per-user model was renamed to `UserAiConfigUpdate` to avoid conflict with the new `SystemAiConfigUpdate`. This is a clean rename with no behavioral change (the PATCH `/users/{user_id}/ai-config` endpoint is unaffected). + +## Threat Mitigations Applied + +| Threat ID | Mitigation | +|-----------|-----------| +| T-07-01 | `_ai_config_to_dict` whitelist; test asserts `api_key_enc` never in GET response | +| T-07-03 | Single `UPDATE SET is_active = (provider_id = target)` atomic flip; test asserts COUNT=1 | +| T-07-13 | `extra="forbid"` on `SystemAiConfigUpdate`; `provider_id` validated against PROVIDER_DEFAULTS | +| T-07-14 | Audit metadata contains only `provider_id` + `fields_changed` list, never api_key value | +| T-07-15 | All 3 endpoints carry `Depends(get_current_admin)`; test asserts 403 for regular users | + +## Known Stubs + +None — all features are fully wired. + +## Threat Flags + +None — no new security-relevant surface beyond what is described in the plan's threat model. + +## Self-Check: PASSED + +Files exist: +- backend/api/admin.py — contains `_ai_config_to_dict`, `SystemAiConfigUpdate`, `GET /ai-config`, `PUT /ai-config`, `test-connection` +- backend/services/ai_config.py — contains `load_provider_config_by_id` +- frontend/src/api/client.js — contains `getAiConfig`, `saveAiConfig`, `testAiConnection` +- frontend/src/components/admin/AdminAiConfigTab.vue — contains "System AI Providers" +- frontend/src/components/documents/DocumentCard.vue — contains `classification_failed`, `Re-analyze` +- frontend/tests/api.spec.js — exists +- frontend/tests/DocumentCard.spec.js — exists + +Commits exist: +- e678930 — Task 1 (backend endpoints) +- 0db412d — Task 2 (frontend client + AdminAiConfigTab) +- c45d9e4 — Task 3 (DocumentCard + Vitest)