slack5-1770574304/.sdlc/features/user-preferences/qa-plan.md

QA Plan: User Preferences API

Test Scenarios

Happy Path

ID	Scenario	Input	Expected Output	Derived From
HP-1	GET own preferences (existing)	GET /api/preferences-api/preferences/usr_123 with JWT for usr_123, preferences already saved	200 with {data: {user_id, theme, language, notifications, updated_at}, meta: {...}}	AC: GET returns preferences in {data, meta} envelope
HP-2	GET own preferences (no saved prefs)	GET /api/preferences-api/preferences/usr_new with JWT for usr_new, no preferences stored	200 with defaults: {theme: "system", language: "en", notifications: {email: true, push: true, digest: "weekly"}}	AC: GET for no saved prefs returns 200 with defaults
HP-3	PUT own preferences (create)	PUT /api/preferences-api/preferences/usr_123 with valid body, no prior prefs	200 with saved preferences in {data, meta} envelope	AC: PUT creates or replaces (upsert)
HP-4	PUT own preferences (update)	PUT /api/preferences-api/preferences/usr_123 with valid body, prefs already exist	200 with updated preferences, updated_at reflects new timestamp	AC: PUT creates or replaces (upsert)
HP-5	PUT with all valid theme values	Three requests with theme: "light", "dark", "system"	All return 200 with matching theme	AC: theme must be one of light/dark/system
HP-6	PUT with all valid language values	Five requests with language: "en", "fr", "es", "de", "ja"	All return 200 with matching language	AC: language must be valid BCP-47 tag
HP-7	PUT with all valid digest values	Three requests with digest: "none", "daily", "weekly"	All return 200 with matching digest	AC: notifications.digest must be one of none/daily/weekly
HP-8	PUT with boolean notification fields	notifications: {email: false, push: false, digest: "none"}	200 with matching boolean values	AC: notifications.email/push must be boolean
HP-9	Admin reads another user's preferences	GET /api/preferences-api/preferences/usr_456 with JWT for admin user usr_admin	200 with usr_456's preferences	AC: admin read access (design: admin role can read any)
HP-10	GET then PUT then GET roundtrip	PUT prefs, then GET same user	GET returns exactly what was PUT	AC: preferences persisted
HP-11	Default values match spec	GET for user with no saved prefs	theme: "system", language: "en", notifications.email: true, notifications.push: true, notifications.digest: "weekly"	AC: default preference values
HP-12	Health endpoint still works	GET /api/preferences-api/health	200 OK	Design: health endpoint preserved

Edge Cases

ID	Scenario	Input	Expected Output	Derived From
EC-1	PUT replaces all fields (full replace, not merge)	First PUT with theme: "dark", second PUT with theme: "light" (all fields sent both times)	Second GET returns theme: "light"	AC: PUT fully replaces preferences
EC-2	Concurrent updates to same user	Two simultaneous PUT requests for same user_id with different values	Both return 200; final state is one of the two (last-write-wins)	Design: upsert is atomic via ON CONFLICT
EC-3	User ID with special characters	GET /api/preferences-api/preferences/usr_abc-123.456	200 (or appropriate handling)	Design: user_id is TEXT, matches JWT subject
EC-4	Very long user ID	GET /api/preferences-api/preferences/{256-char-string}	Handled gracefully (200 with defaults or appropriate error)	Design: user_id is TEXT PK
EC-5	PUT immediately after service start (schema just created)	PUT to newly initialized service	200, table created via EnsureSchema	Design: schema creation at startup
EC-6	Multiple GETs for non-existent user	Repeated GET for user with no prefs	Always returns same defaults, 200	AC: GET returns defaults for no prefs
EC-7	Updated_at omitted for default preferences	GET for user with no saved preferences	updated_at is zero/omitted in response	Design: updated_at omitted for defaults
EC-8	Updated_at populated after PUT	PUT then GET	updated_at is a valid timestamp	Design: updated_at set to NOW() on upsert

Error Cases

ID	Scenario	Input	Expected Output	Derived From
ER-1	GET without authentication	GET /api/preferences-api/preferences/usr_123 with no JWT	401 Unauthorized	AC: both endpoints require auth
ER-2	PUT without authentication	PUT /api/preferences-api/preferences/usr_123 with no JWT	401 Unauthorized	AC: both endpoints require auth
ER-3	GET another user's preferences (non-admin)	GET /api/preferences-api/preferences/usr_456 with JWT for usr_123 (no admin role)	403 Forbidden: "access denied: cannot access another user's preferences"	AC: user_id must match JWT UserID
ER-4	PUT another user's preferences (non-admin)	PUT /api/preferences-api/preferences/usr_456 with JWT for usr_123	403 Forbidden	AC: user_id must match JWT UserID
ER-5	PUT another user's preferences (admin)	PUT /api/preferences-api/preferences/usr_456 with JWT for admin user	403 Forbidden (admin write not permitted)	Design: no admin write, PUT strictly self-access
ER-6	PUT with invalid theme	{theme: "purple", ...}	400 Bad Request: "theme must be one of: light, dark, system"	AC: theme validation
ER-7	PUT with invalid language	{language: "zh", ...}	400 Bad Request: "language must be one of: en, fr, es, de, ja"	AC: language validation
ER-8	PUT with invalid digest	{notifications: {digest: "monthly"}}	400 Bad Request: "notifications.digest must be one of: none, daily, weekly"	AC: digest validation
ER-9	PUT with unknown preference keys	{theme: "dark", ..., "custom_key": "value"}	400 Bad Request (strict binding rejects unknown fields)	AC: unknown keys return 400
ER-10	PUT with non-boolean email notification	{notifications: {email: "yes", ...}}	400 Bad Request with per-field validation error	AC: notifications.email must be boolean
ER-11	PUT with non-boolean push notification	{notifications: {push: 1, ...}}	400 Bad Request with per-field validation error	AC: notifications.push must be boolean
ER-12	PUT with empty body	Empty request body {}	400 Bad Request (required fields missing)	AC: validation, Design: struct tag required
ER-13	PUT with malformed JSON	{theme: dark} (unquoted)	400 Bad Request	Design: app.BindAndValidateStrict
ER-14	PUT with missing notifications object	{theme: "dark", language: "en"}	400 Bad Request (notifications required)	Design: validate:"required" on notifications
ER-15	PUT with missing theme field	{language: "en", notifications: {...}}	400 Bad Request (theme required)	Design: validate:"required" on theme
ER-16	PUT with missing language field	{theme: "dark", notifications: {...}}	400 Bad Request (language required)	Design: validate:"required" on language
ER-17	PUT with missing digest in notifications	{..., notifications: {email: true, push: true}}	400 Bad Request (digest required)	Design: validate:"required" on digest
ER-18	Expired JWT token	Any request with expired JWT	401 Unauthorized	AC: auth.Middleware()
ER-19	Invalid JWT signature	Any request with tampered JWT	401 Unauthorized	AC: auth.Middleware()
ER-20	PUT with multiple validation errors	{theme: "neon", language: "zz", notifications: {email: true, push: true, digest: "yearly"}}	400 with per-field validation errors	AC: per-field validation errors

Test Data Requirements

Fixtures

• Authenticated user JWT: Valid JWT for user usr_test_123 with no admin role
• Admin user JWT: Valid JWT for user usr_admin_001 with admin role
• Second user JWT: Valid JWT for user usr_test_456 for cross-user tests
• Expired JWT: JWT with past expiration for auth failure tests
• Invalid JWT: Malformed/tampered JWT for signature validation tests

Test Preferences Data

• Full valid preferences: {theme: "dark", language: "fr", notifications: {email: false, push: true, digest: "daily"}}
• Default preferences: {theme: "system", language: "en", notifications: {email: true, push: true, digest: "weekly"}}
• All enum boundary values: Each valid value for theme (3), language (5), digest (3)

Database State

• Empty state: No rows in user_preferences table (for default behavior tests)
• Seeded state: Pre-existing preferences for usr_test_123 (for GET/PUT existing tests)
• In-memory adapter: Used for unit and handler tests (no real DB needed)

Integration Test Plan

Handler-to-Service-to-Repository Integration

Test the full request path using httptest.Server with the in-memory adapter:

Test	Scope	What It Validates
Full GET flow	Handler → Service → InMemoryRepo	URL param extraction, auth check, default hydration, response envelope
Full PUT flow	Handler → Service → InMemoryRepo	Request binding, validation, domain validation, upsert, response envelope
PUT then GET roundtrip	Handler → Service → InMemoryRepo	Data persisted correctly through full write/read cycle
Auth middleware integration	Middleware → Handler	JWT extraction and rejection at middleware level before handler
Error propagation	Handler → Service → Domain	Domain validation errors bubble up as correct HTTP status codes

Cross-Component Boundary Tests

Boundary	Test Approach
Handler ↔ Service	Mock service interface to verify handler maps errors correctly
Service ↔ Repository	Use in-memory adapter to verify service applies defaults and validates
Domain ↔ Service	Verify service calls domain Validate() and handles returned errors
Request ↔ Handler	Verify strict JSON binding rejects unknown fields
Handler ↔ Response	Verify {data, meta} envelope structure matches spec

PostgreSQL Adapter Tests (when DB available)

Test	What It Validates
EnsureSchema idempotency	Running schema creation twice does not error
Upsert insert path	First write for a user creates a row
Upsert update path	Second write for same user updates the row
Get existing row	Reads back correct values from all columns
Get non-existent row	Returns nil, nil (not error)
Column type mapping	All Go types map correctly to/from PostgreSQL types

Performance Considerations

Load Expectations

• Read frequency: High — preferences loaded on every page load per user session
• Write frequency: Low — preferences updated occasionally by explicit user action
• Data size: ~6 columns per row, single row per user — negligible

Latency Budgets

Operation	Target	Rationale
GET (cache miss)	< 5ms	Single PK lookup on indexed TEXT column
GET (cache hit, future)	< 1ms	In-process LRU if implemented later
PUT	< 10ms	Single row upsert with index

Benchmarks to Run

Benchmark	Method
GET latency (p50/p95/p99)	go test -bench BenchmarkGetPreferences with in-memory adapter
PUT latency (p50/p95/p99)	go test -bench BenchmarkUpdatePreferences with in-memory adapter
Concurrent reads	100 goroutines reading same user's prefs simultaneously
Concurrent writes	10 goroutines writing same user's prefs simultaneously

No caching needed for MVP

Single-row PK lookups are sub-millisecond on PostgreSQL. Buffer cache handles the working set naturally.

Manual Verification Steps

1. Service Startup

• Start service with ./scripts/dev.sh or direct binary execution
• Verify health endpoint responds: curl http://localhost:8001/api/preferences-api/health
• Verify user_preferences table created in PostgreSQL (check via psql)
• Verify OpenAPI docs accessible at the docs endpoint

2. Authentication Flow

• Obtain a valid JWT from the auth service
• Verify GET without JWT returns 401
• Verify PUT without JWT returns 401

3. Preference CRUD Flow

• GET preferences for authenticated user (should return defaults first time)
• PUT preferences with valid body (theme=dark, language=fr, etc.)
• GET preferences again (should return saved values, not defaults)
• PUT preferences with different values (verify overwrite)
• GET again to confirm overwrite

4. Authorization Checks

• As user A, try to GET user B's preferences → expect 403
• As user A, try to PUT user B's preferences → expect 403
• As admin, GET user B's preferences → expect 200
• As admin, try to PUT user B's preferences → expect 403

5. Validation Checks

• PUT with theme: "invalid" → expect 400 with descriptive error
• PUT with language: "xx" → expect 400
• PUT with unknown key in JSON body → expect 400
• PUT with malformed JSON → expect 400

6. OpenAPI Documentation

• Verify Scalar docs page loads in browser
• Verify GET endpoint documented with schemas and examples
• Verify PUT endpoint documented with request body schema
• Verify error responses (400, 401, 403) documented

7. Example Scaffold Removal

• Verify no example endpoints respond (GET/POST/PUT/DELETE /api/preferences-api/examples/* → 404)
• Verify no example-related code remains in the codebase

Acceptance Criteria Coverage Matrix

Acceptance Criterion	Test Scenarios
GET returns preferences in {data, meta} envelope	HP-1, HP-2, HP-11
PUT creates or fully replaces (upsert)	HP-3, HP-4, EC-1
Both endpoints require authentication	ER-1, ER-2, ER-18, ER-19
User can only access own preferences (JWT match)	ER-3, ER-4, ER-5
Preferences stored as key-value pairs	HP-1, HP-10
Theme validation (light/dark/system)	HP-5, ER-6
Language validation (BCP-47 tags)	HP-6, ER-7
notifications.email must be boolean	HP-8, ER-10
notifications.push must be boolean	HP-8, ER-11
notifications.digest validation	HP-7, ER-8
GET returns 200 with defaults (not 404)	HP-2, HP-11, EC-6
Default values correct	HP-11
Unknown keys return 400	ER-9
Invalid values return 400 with per-field errors	ER-6, ER-7, ER-8, ER-10, ER-11, ER-20
Persisted in PostgreSQL	HP-10, Integration tests
Hexagonal architecture (domain/service/port/adapter)	Code review, Integration tests
PreferenceRepository port interface	Code review
PreferenceService orchestrates logic	Integration tests
OpenAPI spec updated	HP-12, Manual step 6
Unit tests cover domain, service, handler	Code review of test files
Integration tests with in-memory adapter	Integration test plan
Example scaffold removed	Manual step 7