SurfSense/_bmad-output/implementation-artifacts/5-6-admin-only-model-config.md

Story 5.6: Admin-only Model Configuration (LLM / Image / Vision)

Status: done

Story

As a Quản trị viên (Admin), I want chỉ mình có quyền thêm/sửa/xóa cấu hình LLM, Image Generation, và Vision models, so that người dùng thông thường chỉ có thể chọn model để sử dụng mà không thể thêm BYOK credentials hay thay đổi cấu hình model.

Acceptance Criteria

1. Chỉ superuser (is_superuser=TRUE) mới có thể gọi POST/PUT/DELETE cho cả 3 loại model config — non-superuser nhận HTTP 403 Forbidden.
2. Regular user vẫn có thể GET (đọc/liệt kê) model configs trong search space của họ.
3. Trong chat interface, nút "Add Model", "Add Image Model", "Add Vision Model" bị ẩn hoàn toàn với regular user.
4. Trong search space settings dialog (LLM/Image/Vision tabs), nút Add/Edit/Delete bị ẩn với regular user — chỉ hiển thị danh sách model read-only.
5. Admin-created configs lưu với user_id=NULL (không gắn với user cụ thể) — visible cho tất cả members trong search space.
6. DB migration: user_id trên cả 3 bảng config trở thành nullable để cho phép admin configs với user_id=NULL.

As-Is (Code trước Story này)

Component	Hiện trạng
new_llm_configs.user_id	NOT NULL — mọi config đều gắn với user cụ thể
image_generation_configs.user_id	NOT NULL
vision_llm_configs.user_id	NOT NULL
Backend CUD permissions	RBAC per search space (check_permission) — bất kỳ member có llm_configs:create đều tạo được
Frontend Add buttons	Hiển thị dựa theo RBAC permissions — owner và editor đều thấy

Tasks / Subtasks

• Task 1: DB Migration

  • Subtask 1.1: Tạo migration 128_make_model_config_user_id_nullable.py
  • Subtask 1.2: ALTER TABLE new_llm_configs ALTER COLUMN user_id DROP NOT NULL
  • Subtask 1.3: Tương tự cho image_generation_configs và vision_llm_configs
  • Subtask 1.4: Downgrade: xóa rows có user_id=NULL rồi re-add NOT NULL

• Task 2: Shared Superuser Dependency

  • Subtask 2.1: Thêm current_superuser = fastapi_users.current_user(active=True, superuser=True) vào users.py
  • Subtask 2.2: Cập nhật admin_routes.py để import current_superuser từ users.py thay vì định nghĩa lại

• Task 3: Backend — Gate CUD endpoints với superuser

  • Subtask 3.1: new_llm_config_routes.py — POST/PUT/DELETE dùng Depends(current_superuser), set user_id=None, xóa check_permission
  • Subtask 3.2: image_generation_routes.py — tương tự (POST/PUT/DELETE config endpoints)
  • Subtask 3.3: vision_llm_routes.py — tương tự

• Task 4: Frontend — Settings dialog managers

  • Subtask 4.1: model-config-manager.tsx — import currentUserAtom, replace RBAC flags (canCreate/Update/Delete) với currentUser.is_superuser
  • Subtask 4.2: image-model-manager.tsx — tương tự
  • Subtask 4.3: vision-model-manager.tsx — tương tự

• Task 5: Frontend — Chat interface model selector

  • Subtask 5.1: model-selector.tsx — thêm ? vào onAddNewLLM prop (optional), wrap "Add Model" button với {onAddNewLLM && (...)}
  • Subtask 5.2: chat-header.tsx — import currentUserAtom, compute isAdmin, truyền onAddNew*={isAdmin ? handler : undefined} cho cả 3 model types

Dev Notes

Tại sao làm optional thay vì truyền boolean?

ModelSelector đã có pattern {onAddNewImage && (...)} cho Image và Vision — consistent nhất là làm onAddNewLLM optional và dùng cùng pattern, thay vì thêm prop showAddButton.

Existing model configs (có user_id)

Existing configs của các user trước kia vẫn hoạt động bình thường — migration chỉ làm nullable, không xóa data. Tuy nhiên, vì GET endpoint không filter theo user_id nên tất cả configs (kể cả cũ) đều visible cho mọi member trong search space.

Image/Vision edit buttons trong model selector

onEditImage và onEditVision props không được gated — regular user vẫn có thể click edit nhưng sẽ xem ở mode "view" (dialog opens in view mode for global configs). Việc submit edit sẽ bị 403 từ backend. Đây là acceptable — UX nhất quán đủ dùng.

Dev Agent Record

Verification Results (2026-04-15)

Regular user (epic5user@example.com):

• Model selector popup: "No models found" — NO Add/Add Image Model/Add Vision Model buttons ✅
• POST /api/v1/new-llm-configs with regular user token → HTTP 403 Forbidden ✅

Admin (admin@surfsense.local):

• POST /api/v1/new-llm-configs → HTTP 422 (schema validation error, NOT 403) → superuser check passed ✅

DB:

• new_llm_configs.user_id: is_nullable=YES ✅
• image_generation_configs.user_id: is_nullable=YES ✅
• vision_llm_configs.user_id: is_nullable=YES ✅

File List

• surfsense_backend/alembic/versions/128_make_model_config_user_id_nullable.py — NEW migration
• surfsense_backend/app/users.py — added current_superuser export
• surfsense_backend/app/routes/admin_routes.py — import current_superuser from users.py instead of defining locally
• surfsense_backend/app/routes/new_llm_config_routes.py — superuser gate on POST/PUT/DELETE, user_id=None
• surfsense_backend/app/routes/image_generation_routes.py — superuser gate on config POST/PUT/DELETE
• surfsense_backend/app/routes/vision_llm_routes.py — superuser gate on POST/PUT/DELETE
• surfsense_web/components/settings/model-config-manager.tsx — is_superuser replaces RBAC flags
• surfsense_web/components/settings/image-model-manager.tsx — same
• surfsense_web/components/settings/vision-model-manager.tsx — same
• surfsense_web/components/new-chat/model-selector.tsx — onAddNewLLM made optional, LLM Add button gated
• surfsense_web/components/new-chat/chat-header.tsx — isAdmin check gates all 3 onAddNew* props

Change Log

• 2026-04-15: Implement admin-only model configuration — superuser gate on backend CUD, hide Add/Edit/Delete UI for regular users in both chat selector and settings dialog.

---

Post-Story Bug Fixes & Enhancements (2026-04-15)

Bug 1: "No models found" for regular users

Root Cause: Admin configs scoped to search_space_id=5. Each user has their own space. GET filtered strictly by space ID → configs invisible to other users.

Fix:

• Migration 129: search_space_id nullable in all 3 config tables
• db.py: search_space_id = nullable=True in all 3 SQLAlchemy models (also fixed user_id mismatch)
• Schemas: search_space_id: int | None = None in Create/Read for all 3 types
• GET list query: WHERE search_space_id = :id OR search_space_id IS NULL
• Re-seeded all configs without search_space_id → global (visible to all spaces)

Bug 2: Chat error with stale config ID

Root Cause: Frontend kept agent_llm_id pointing to a deleted config.

Fix: model-selector.tsx — useEffect auto-resets agent_llm_id to null when saved preference ID no longer exists in fetched configs.

Bug 3: db.py nullable=False mismatch

Root Cause: Migration 128 made DB columns nullable but SQLAlchemy models still said nullable=False.

Fix: All 3 models in db.py updated to nullable=True for both user_id and search_space_id.

Security: api_key exposed in GET list

Fix: GET list response model changed from *Read (exposes api_key) to *Public (hides it) for all 3 config types.

New: Image configs (3 global, via v98store)

Name	model_name
DALL-E 3	dall-e-3
GPT-Image 1	gpt-image-1
Flux Pro	flux-pro

New: Vision configs (3 global, via v98store)

Name	model_name
GPT-4o Vision	gpt-4o
Claude Sonnet 4 Vision	claude-sonnet-4-20250514
Gemini 2.5 Flash Vision	gemini-2.5-flash

Enhancement: Edit buttons admin-only in model selector

Fix: onEditLLM prop in ModelSelectorProps changed from required → optional. In chat-header.tsx, all 3 onEdit* props now gated with isAdmin ? handler : undefined — consistent với onAdd* pattern đã có. Regular users thấy model list read-only, không có edit button trên hover.

Additional Files Changed

• surfsense_backend/alembic/versions/129_make_model_config_search_space_id_nullable.py
• surfsense_backend/app/db.py
• surfsense_backend/app/schemas/new_llm_config.py, image_generation.py, vision_llm.py
• surfsense_backend/app/routes/new_llm_config_routes.py, image_generation_routes.py, vision_llm_routes.py
• surfsense_web/components/new-chat/model-selector.tsx
• surfsense_web/components/new-chat/chat-header.tsx

Review Findings (2026-04-15)

• [Review][Patch] Superuser config update/delete can modify any config (not just global ones) [new_llm_config_routes.py:274,357, image_generation_routes.py:373,405, vision_llm_routes.py:222,254] — Fixed: Added user_id.is_(None) filter to all superuser PUT/DELETE endpoints
• [Review][Patch] admin_approval_mode field missing from CreateSubscriptionCheckoutResponse — Already fixed: field was already present in schemas/stripe.py with bool = False default