# QA Plan: User Preferences API

## Test Scenarios

### Happy Path

| ID | Scenario | Input | Expected Output | Derived From |
|----|----------|-------|-----------------|--------------|
| HP-1 | GET returns stored preferences for a user | `GET /api/preferences-api/preferences/{valid_uuid}` where user has preferences `{theme: "dark", language: "en", notifications_enabled: true}` | `200` with `{data: {user_id, preferences: {theme: "dark", language: "en", notifications_enabled: true}, updated_at}, meta}` | AC-1 |
| HP-2 | GET returns empty preferences for user with no stored preferences | `GET /api/preferences-api/preferences/{valid_uuid}` where user has no row | `200` with `{data: {user_id, preferences: {}, updated_at}, meta}` | AC-2 |
| HP-3 | PUT creates preferences for new user (upsert - insert path) | `PUT /api/preferences-api/preferences/{valid_uuid}` with body `{preferences: {theme: "light"}}` where no row exists | `200` with `{data: {user_id, preferences: {theme: "light"}, updated_at}, meta}` | AC-4, AC-5, AC-6 |
| HP-4 | PUT updates preferences for existing user (upsert - update path) | `PUT /api/preferences-api/preferences/{valid_uuid}` with body `{preferences: {theme: "dark"}}` where user already has `{theme: "light", language: "en"}` | `200` with merged preferences `{theme: "dark", language: "en"}` | AC-4, AC-6 |
| HP-5 | PUT with all known preference keys valid | `PUT` with `{preferences: {theme: "system", language: "ja", notifications_enabled: false}}` | `200` with all preferences stored correctly | AC-7 |
| HP-6 | PUT with unknown preference keys accepted | `PUT` with `{preferences: {custom_key: "custom_value", another: 42}}` | `200` with unknown keys stored as-is | AC-9 |
| HP-7 | PUT with mix of known and unknown keys | `PUT` with `{preferences: {theme: "dark", custom_flag: true}}` | `200` with both keys stored | AC-7, AC-9 |
| HP-8 | Preferences survive service restart | PUT preferences, restart service, GET same user | GET returns previously stored preferences | AC-10 |
| HP-9 | All responses follow envelope pattern | Any successful GET or PUT | Response has `{data, meta}` structure with `meta` containing `request_id` and `timestamp` | AC-11 |
| HP-10 | PUT validates theme "light" accepted | `PUT` with `{preferences: {theme: "light"}}` | `200` success | AC-7 |
| HP-11 | PUT validates theme "dark" accepted | `PUT` with `{preferences: {theme: "dark"}}` | `200` success | AC-7 |
| HP-12 | PUT validates theme "system" accepted | `PUT` with `{preferences: {theme: "system"}}` | `200` success | AC-7 |
| HP-13 | PUT validates various BCP-47 language tags | `PUT` with `{preferences: {language: "en"}}`, then `"fr"`, `"es"`, `"de"`, `"ja"` | `200` for each | AC-7 |
| HP-14 | PUT validates notifications_enabled true | `PUT` with `{preferences: {notifications_enabled: true}}` | `200` success | AC-7 |
| HP-15 | PUT validates notifications_enabled false | `PUT` with `{preferences: {notifications_enabled: false}}` | `200` success | AC-7 |
| HP-16 | PUT is idempotent | Same PUT request sent twice | Both return `200` with identical preferences; second call does not create duplicate | AC-4 |

### Edge Cases

| ID | Scenario | Input | Expected Output | Derived From |
|----|----------|-------|-----------------|--------------|
| EC-1 | GET with UUID that has never had preferences | `GET /api/preferences-api/preferences/{new_uuid}` | `200` with empty preferences `{}` (not 404) | AC-2 |
| EC-2 | PUT with empty preferences object | `PUT` with `{preferences: {}}` | `200` success, no preferences changed (or empty stored) | AC-5 |
| EC-3 | PUT preserves existing keys not in request | User has `{theme: "dark", language: "en"}`, PUT with `{preferences: {theme: "light"}}` | Stored preferences: `{theme: "light", language: "en"}` - language preserved | AC-4 (merge behavior from design) |
| EC-4 | PUT with unknown key containing complex JSON value | `PUT` with `{preferences: {custom: {nested: {deeply: true}}}}` | `200` with nested value stored as-is | AC-9 |
| EC-5 | PUT with unknown key containing array value | `PUT` with `{preferences: {tags: ["a", "b", "c"]}}` | `200` with array stored | AC-9 |
| EC-6 | PUT with unknown key containing null value | `PUT` with `{preferences: {optional_field: null}}` | `200` with null stored | AC-9 |
| EC-7 | GET with lowercase UUID | `GET` with `{550e8400-e29b-41d4-a716-446655440000}` | `200` success | AC-1 |
| EC-8 | GET with uppercase UUID | `GET` with `{550E8400-E29B-41D4-A716-446655440000}` | `200` success (UUIDs are case-insensitive) | AC-1 |
| EC-9 | PUT with large number of preference keys | `PUT` with 100 different key-value pairs | `200` success, all keys stored | AC-9 |
| EC-10 | PUT with unicode string values for unknown keys | `PUT` with `{preferences: {greeting: "こんにちは"}}` | `200` with unicode preserved | AC-9 |
| EC-11 | PUT with numeric values for unknown keys | `PUT` with `{preferences: {max_items: 50, ratio: 3.14}}` | `200` with numeric types preserved | AC-9 |
| EC-12 | Sequential PUTs accumulate preferences | PUT `{theme: "dark"}`, then PUT `{language: "fr"}` | GET returns `{theme: "dark", language: "fr"}` | AC-4, merge behavior |
| EC-13 | PUT with boolean-like string for notifications_enabled | `PUT` with `{preferences: {notifications_enabled: "true"}}` (string, not bool) | `400` validation error - must be boolean | AC-7 |

### Error Cases

| ID | Scenario | Input | Expected Output | Derived From |
|----|----------|-------|-----------------|--------------|
| ER-1 | GET with invalid UUID format | `GET /api/preferences-api/preferences/not-a-uuid` | `400` Bad Request | AC-3 |
| ER-2 | GET with empty string as user_id | `GET /api/preferences-api/preferences/` | `404` (route not matched) or `400` | AC-3 |
| ER-3 | PUT with invalid UUID format | `PUT /api/preferences-api/preferences/abc123` | `400` Bad Request | AC-3 |
| ER-4 | PUT with invalid theme value | `PUT` with `{preferences: {theme: "midnight"}}` | `400` with details: `{theme: "must be one of: light, dark, system"}` | AC-7, AC-8 |
| ER-5 | PUT with invalid language tag | `PUT` with `{preferences: {language: "not-a-language-!!"}}` | `400` with details: `{language: "must be a valid BCP-47 language tag"}` | AC-7, AC-8 |
| ER-6 | PUT with invalid notifications_enabled type | `PUT` with `{preferences: {notifications_enabled: "yes"}}` | `400` with details: `{notifications_enabled: "must be a boolean"}` | AC-7, AC-8 |
| ER-7 | PUT with multiple validation errors | `PUT` with `{preferences: {theme: "neon", language: "???", notifications_enabled: 42}}` | `400` with details containing all three field errors | AC-8 |
| ER-8 | PUT with missing request body | `PUT` with empty body | `400` Bad Request | AC-5 |
| ER-9 | PUT with missing preferences field | `PUT` with `{}` (empty JSON object) | `400` Bad Request | AC-5 |
| ER-10 | PUT with malformed JSON body | `PUT` with `{not json` | `400` Bad Request | AC-5 |
| ER-11 | PUT with preferences as non-object type | `PUT` with `{preferences: "string"}` | `400` Bad Request | AC-5 |
| ER-12 | PUT with preferences as array | `PUT` with `{preferences: [1, 2, 3]}` | `400` Bad Request | AC-5 |
| ER-13 | PUT with integer theme value | `PUT` with `{preferences: {theme: 123}}` | `400` with details for theme | AC-7, AC-8 |
| ER-14 | PUT with null theme value | `PUT` with `{preferences: {theme: null}}` | `400` with details for theme | AC-7, AC-8 |
| ER-15 | Database unavailable on GET | Database connection dropped | `500` Internal Server Error | Design: Error Handling |
| ER-16 | Database unavailable on PUT | Database connection dropped | `500` Internal Server Error | Design: Error Handling |
| ER-17 | GET non-existent route | `GET /api/preferences-api/nonexistent` | `404` Not Found | Standard routing |
| ER-18 | POST to preferences endpoint (wrong method) | `POST /api/preferences-api/preferences/{uuid}` | `405` Method Not Allowed | Standard routing |
| ER-19 | DELETE to preferences endpoint (wrong method) | `DELETE /api/preferences-api/preferences/{uuid}` | `405` Method Not Allowed | Standard routing |

## Test Data Requirements

### Fixtures
- **Valid UUIDs:** Generate at least 3 unique UUIDs for test isolation (e.g., `550e8400-e29b-41d4-a716-446655440000`, `660e8400-e29b-41d4-a716-446655440001`, `770e8400-e29b-41d4-a716-446655440002`)
- **Pre-seeded preferences row:** One user with `{theme: "dark", language: "en", notifications_enabled: true}` for GET and merge tests
- **Empty database state:** Tests must handle both seeded and unseeded user_ids

### Mocks
- **Mock `PreferenceRepository`:** For handler and service unit tests, providing controllable `Get` and `Upsert` behavior
- **Mock returning nil:** Simulates user with no preferences
- **Mock returning error:** Simulates database failures (connection errors, query errors)
- **Mock tracking calls:** Verifies correct arguments passed to repository methods

### Test Data Values
| Key | Valid Values | Invalid Values |
|-----|-------------|----------------|
| `theme` | `"light"`, `"dark"`, `"system"` | `"midnight"`, `123`, `null`, `""`, `true` |
| `language` | `"en"`, `"fr"`, `"es"`, `"de"`, `"ja"`, `"zh-Hans"` | `"not-a-language-!!"`, `123`, `null`, `""` |
| `notifications_enabled` | `true`, `false` | `"true"`, `"false"`, `1`, `0`, `"yes"`, `null` |

## Integration Test Plan

### Component Boundary Tests

| ID | Test | Components | What to Verify |
|----|------|------------|----------------|
| IT-1 | Handler → Service → Repository (GET, no preferences) | Handler, Service, Mock Repo | Full request/response cycle; empty preferences returned for unknown user |
| IT-2 | Handler → Service → Repository (GET, with preferences) | Handler, Service, Mock Repo | Full request/response cycle; stored preferences returned |
| IT-3 | Handler → Service → Repository (PUT, create) | Handler, Service, Mock Repo | Request binding, validation, upsert delegation, response mapping |
| IT-4 | Handler → Service → Repository (PUT, update with merge) | Handler, Service, Mock Repo | Merge logic: existing keys preserved, new keys added, changed keys updated |
| IT-5 | Handler → Service (PUT, validation failure) | Handler, Service | Validation errors mapped to structured HTTP error response with per-field details |
| IT-6 | Service → PostgreSQL Adapter (GET) | Service, Postgres Adapter, PostgreSQL | Real database round-trip for GET (requires running PostgreSQL) |
| IT-7 | Service → PostgreSQL Adapter (Upsert) | Service, Postgres Adapter, PostgreSQL | Real database round-trip for INSERT and UPDATE paths |
| IT-8 | Full stack: HTTP → Handler → Service → Postgres (GET) | All layers | End-to-end GET via HTTP with real database |
| IT-9 | Full stack: HTTP → Handler → Service → Postgres (PUT then GET) | All layers | End-to-end PUT followed by GET, verifying persistence |
| IT-10 | Migration creates correct schema | Migration, PostgreSQL | Table structure, column types, index existence |

### Database Integration Tests (require PostgreSQL)

| ID | Test | Verification |
|----|------|-------------|
| DB-1 | Adapter Get returns nil for non-existent user | `Get` returns `nil, nil` (not error) |
| DB-2 | Adapter Upsert inserts new row | Row exists after Upsert, `Get` returns it |
| DB-3 | Adapter Upsert updates existing row | `updated_at` changes, preferences updated |
| DB-4 | Adapter Upsert is atomic (ON CONFLICT) | Concurrent Upserts don't produce duplicate rows |
| DB-5 | JSONB marshaling round-trip | Complex nested JSON preserved through write→read cycle |
| DB-6 | Migration is idempotent | Running migration twice doesn't error |

## Performance Considerations

### Latency Budgets
| Operation | Target P50 | Target P99 | Rationale |
|-----------|-----------|-----------|-----------|
| GET preferences | < 5ms | < 20ms | Single primary key lookup, no joins |
| PUT preferences (new user) | < 10ms | < 50ms | Single INSERT with conflict check |
| PUT preferences (existing user) | < 10ms | < 50ms | Single UPDATE on primary key |

### Load Expectations
- **Read:Write ratio:** ~10:1 (preferences read on every page load, written on settings changes)
- **Expected QPS:** Low to moderate; preferences are per-user, not global
- **Connection pool:** Default 25 open / 5 idle connections should be sufficient

### Benchmarks to Run
| Benchmark | What to Measure |
|-----------|----------------|
| BenchmarkServiceValidation | Time to validate known preference keys (no I/O) |
| BenchmarkJSONBMarshal | Time to marshal/unmarshal preference maps to JSONB |
| BenchmarkGetEndpoint | End-to-end GET latency with real database |
| BenchmarkPutEndpoint | End-to-end PUT latency with real database |

### Scalability Notes
- Primary key index ensures O(1) lookups regardless of table size
- No table scans in either GET or PUT queries
- JSONB stored in decomposed binary format; efficient for full-object reads/writes
- `updated_at` index not used by current queries but supports future cleanup/analytics

## Manual Verification Steps

### OpenAPI Documentation
1. Start the service locally (`./scripts/dev.sh` or direct `go run`)
2. Navigate to the Scalar docs UI (typically at `/api/preferences-api/docs`)
3. Verify both GET and PUT endpoints are documented
4. Verify request/response schemas match the spec
5. Verify parameter descriptions for `user_id` are present
6. Try executing sample requests from the docs UI

### Database Migration
1. Start with a clean database (no `preferences` table)
2. Start the service — migration should run automatically
3. Verify table exists: `\d preferences` in psql
4. Verify columns: `user_id UUID PK`, `preferences JSONB`, `created_at TIMESTAMPTZ`, `updated_at TIMESTAMPTZ`
5. Verify index: `\di idx_preferences_updated_at`
6. Restart the service — migration should be idempotent (no errors)

### End-to-End Smoke Test
1. Start the service with a clean database
2. `GET /api/preferences-api/preferences/{uuid}` — expect `200` with empty preferences
3. `PUT /api/preferences-api/preferences/{uuid}` with `{preferences: {theme: "dark"}}` — expect `200`
4. `GET /api/preferences-api/preferences/{uuid}` — expect `200` with `{theme: "dark"}`
5. `PUT /api/preferences-api/preferences/{uuid}` with `{preferences: {language: "fr"}}` — expect `200` with merged `{theme: "dark", language: "fr"}`
6. `PUT /api/preferences-api/preferences/{uuid}` with `{preferences: {theme: "invalid"}}` — expect `400` with validation details
7. `GET /api/preferences-api/preferences/not-a-uuid` — expect `400`

### Health Check
1. `GET /api/preferences-api/health` — expect `200` (verify health endpoint still works after route changes)

## Acceptance Criteria Coverage Matrix

| AC | Description | Test IDs |
|----|-------------|----------|
| AC-1 | GET returns all preferences as key-value pairs | HP-1, HP-7, HP-8 |
| AC-2 | GET returns 200 with empty preferences for no stored prefs | HP-2, EC-1 |
| AC-3 | GET returns 404 (400) for invalid UUID format | ER-1, ER-2, ER-3 |
| AC-4 | PUT creates or updates (upsert) | HP-3, HP-4, HP-16, EC-3, EC-12 |
| AC-5 | PUT accepts JSON body with preferences object | HP-3, HP-5, EC-2, ER-8, ER-9, ER-10, ER-11, ER-12 |
| AC-6 | PUT returns 200 with updated preferences | HP-3, HP-4, HP-5 |
| AC-7 | PUT validates known keys (theme, language, notifications_enabled) | HP-5, HP-10–HP-15, EC-13, ER-4, ER-5, ER-6, ER-13, ER-14 |
| AC-8 | PUT returns 400 with details on validation failure | ER-4, ER-5, ER-6, ER-7 |
| AC-9 | Unknown keys accepted and stored | HP-6, HP-7, EC-4, EC-5, EC-6, EC-9, EC-10, EC-11 |
| AC-10 | Preferences persisted in PostgreSQL | HP-8, IT-6–IT-9, DB-2, DB-3 |
| AC-11 | All responses follow {data, meta} envelope | HP-9 (verified across all HP tests) |
| AC-12 | OpenAPI spec documents both endpoints | Manual: OpenAPI verification |
| AC-13 | Handler tests cover success and error cases | HP-1–HP-16, ER-1–ER-19 |
| AC-14 | Service-layer tests cover business logic | IT-1–IT-5, HP tests via service unit tests |
| AC-15 | Database migration creates preferences table | IT-10, DB-6, Manual: Migration |