# 2.1 Question Bank Service (Port 8081) - Detailed Implementation Plan

## Summary
Implement the Question Bank Service as the source of truth for quiz questions and themes, with public random/get endpoints and admin CRUD/bulk workflows. Runtime stack: Fiber HTTP, PostgreSQL persistence, Redis-backed random-question cache, and shared packages for auth/validation/errors/observability.

## Objectives
1. Provide `/questions/random` and `/questions/{id}` for gameplay.
2. Provide admin endpoints for create/update/delete/list themes/bulk import.
3. Implement 85% fuzzy answer matching helper for downstream game-session usage.
4. Add observability, health/readiness, and test coverage.

## API Endpoints
- `POST /questions/random`
- `GET /questions/{id}`
- `POST /admin/questions`
- `PUT /admin/questions/{id}`
- `DELETE /admin/questions/{id}`
- `GET /admin/themes`
- `POST /admin/questions/bulk`

## Data Model
Question fields:
- `id` (UUID)
- `theme` (max 100)
- `text` (max 1000)
- `answer` (max 500)
- `hint` (optional, max 500)
- `difficulty` (`easy|medium|hard`, default `medium`)
- `is_active` (default `true`)
- `created_at`, `updated_at`

Indexes:
- `(theme, is_active)`
- `(difficulty, is_active)`

## Core Logic
1. Random selection with exclusion list and optional theme/difficulty filters.
2. Cache key format: `qb:random:v1:{sha256(filters+sorted_exclusions)}`.
3. Cache TTL: `5m`.
4. Cache invalidation on admin writes via namespace version bump.
5. Fuzzy matching utility:
- normalize strings (trim/lower/collapse spaces/remove punctuation)
- compute Levenshtein similarity
- match when score `>= 0.85`

## Security
1. Public endpoints are open for internal service usage.
2. Admin endpoints protected by Zitadel JWT middleware.
3. Admin authorization requires `admin` role + MFA.

## Observability
1. Shared logger initialized with service metadata.
2. Shared metrics registered and `/metrics` exposed.
3. Shared tracer initialization and shutdown.
4. `/health` and `/ready` endpoints available.

## Configuration
- `QUESTION_BANK_PORT` (default `8081`)
- `QUESTION_CACHE_TTL` (default `5m`)
- `QUESTION_RANDOM_MAX_EXCLUSIONS` (default `200`)
- `QUESTION_BULK_MAX_ITEMS` (default `5000`)
- shared `POSTGRES_*`, `REDIS_*`, `TRACING_*`, `METRICS_*`, `LOG_LEVEL`, `ZITADEL_*`

## Testing Strategy
1. Unit tests:
- fuzzy matching threshold behavior
- random selection no-result and cache paths
2. HTTP integration tests:
- random/get success
- admin auth guard behavior
- metrics endpoint
3. Repository integration test scaffold (optional, DB-backed when env is set)

## Verification
From `backend/services/question-bank-service`:
```bash
go test ./...
go vet ./...
```