You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
80 lines
2.6 KiB
Markdown
80 lines
2.6 KiB
Markdown
# 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 ./...
|
|
```
|