slack5-1770544098/.sdlc/features/user-preferences/tasks.md

Tasks: User Preferences API

Task Order (dependency sequence)

T1: Domain layer - preferences entity, validation, and errors

• Scope: Create UserPreferences struct, preference key/value validation functions, and domain error definitions. Implement ValidatePreferences, ValidatePreferenceKey, and ValidatePreferenceValue with the closed key set (theme, language, notifications_enabled) and per-key value rules.
• Files:
  • Create services/preferences-api/internal/domain/preferences.go
  • Replace services/preferences-api/internal/domain/errors.go
• Depends on: None
• Acceptance criteria:
  • UserPreferences struct has UserID, Preferences, CreatedAt, UpdatedAt fields
  • ValidatePreferences rejects unknown keys with ErrInvalidPreferenceKey
  • ValidatePreferenceValue validates theme accepts only "light" and "dark"
  • ValidatePreferenceValue validates language matches ^[a-z]{2}$
  • ValidatePreferenceValue validates notifications_enabled is a boolean
  • Error messages include the offending key/value for debuggability
  • ErrInvalidPreferenceKey and ErrInvalidPreferenceValue sentinel errors defined

T2: Port layer - PreferencesRepository interface

• Scope: Define the PreferencesRepository interface with Get and Upsert methods. This is a thin interface file replacing the Example port.
• Files:
  • Create services/preferences-api/internal/port/preferences.go
• Depends on: T1
• Acceptance criteria:
  • PreferencesRepository interface defined with Get(ctx, userID) (*UserPreferences, error) and Upsert(ctx, userID, prefs) (*UserPreferences, error)
  • Uses domain types from internal/domain
  • Context parameter on all methods for cancellation/timeout support

T3: Database migration and PostgreSQL adapter

• Scope: Create the SQL migration for the user_preferences table and implement the PostgreSQL repository adapter that satisfies the PreferencesRepository port.
• Files:
  • Create services/preferences-api/migrations/001_create_user_preferences.sql
  • Create services/preferences-api/internal/adapter/postgres/preferences.go
• Depends on: T2
• Acceptance criteria:
  • Migration creates user_preferences table with user_id UUID PRIMARY KEY, preferences JSONB NOT NULL DEFAULT '{}', created_at TIMESTAMPTZ, updated_at TIMESTAMPTZ
  • Migration uses IF NOT EXISTS for idempotency
  • Get returns nil (not error) when no row found, so handler returns empty preferences
  • Upsert uses INSERT ... ON CONFLICT (user_id) DO UPDATE with JSONB merge (preferences || $2)
  • Upsert returns the full merged row after upsert
  • All queries use parameterized statements (no SQL injection)
  • Repository struct accepts *sql.DB or pool via constructor

T4: Service layer - PreferencesService with Get and Update

• Scope: Implement PreferencesService with Get and Update methods. Get retrieves preferences (returning empty object for new users). Update validates input via domain layer, then delegates to repository upsert.
• Files:
  • Create services/preferences-api/internal/service/preferences.go
• Depends on: T1, T2
• Acceptance criteria:
  • Get(ctx, userID) returns *UserPreferences — empty preferences struct for new users (not nil, not error)
  • Update(ctx, userID, prefs) calls domain.ValidatePreferences before persisting
  • Update returns the full merged preferences after upsert
  • Validation errors from domain layer propagate to caller unchanged
  • Repository errors propagate to caller unchanged (will become 500s)
  • Structured logging with user_id context on operations

T5: Service layer unit tests

• Scope: Write table-driven unit tests for PreferencesService with a mock repository. Cover valid operations, validation failures, and repository errors.
• Files:
  • Create services/preferences-api/internal/service/preferences_test.go
• Depends on: T4
• Acceptance criteria:
  • Tests use mock repository implementing port.PreferencesRepository
  • Test Get for existing user (returns preferences) and new user (returns empty)
  • Test Update with valid preferences succeeds
  • Test Update with unknown key returns ErrInvalidPreferenceKey
  • Test Update with invalid theme value returns ErrInvalidPreferenceValue
  • Test Update with invalid language format returns ErrInvalidPreferenceValue
  • Test Update with non-boolean notifications_enabled returns ErrInvalidPreferenceValue
  • Tests use logging.Nop() for no-op logger
  • All tests pass with go test -v ./internal/service/...

T6: HTTP handlers - Get and Update preferences

• Scope: Implement Preferences handler struct with Get and Update methods. Include UUID validation on path params, ownership check against JWT user, request binding, domain error mapping, and response envelope formatting.
• Files:
  • Create services/preferences-api/internal/api/handlers/preferences.go
• Depends on: T4
• Acceptance criteria:
  • Get extracts user_id from chi.URLParam, validates UUID format
  • Get checks ownership via auth.MustGetUser(ctx) comparison
  • Get returns 200 with {data, meta} envelope via httpresponse.OK
  • Update binds request with app.BindAndValidate
  • Update checks ownership before calling service
  • Update returns 200 with full merged preferences
  • Invalid UUID returns 400 via httperror.BadRequest
  • Ownership mismatch returns 403 via httperror.Forbidden
  • Domain errors mapped: ErrInvalidPreferenceKey → 400, ErrInvalidPreferenceValue → 400
  • Unhandled errors bubble up as 500 via app.Wrap
  • PreferencesResponse DTO with user_id, preferences, updated_at (nullable)

T7: Handler integration tests

• Scope: Write HTTP-level integration tests for the preferences handlers using httptest and chi router. Mock the repository at the port layer. Test all status codes, response shapes, and error cases.
• Files:
  • Create services/preferences-api/internal/api/handlers/preferences_test.go
• Depends on: T6
• Acceptance criteria:
  • Test GET returns 200 with preferences for existing user
  • Test GET returns 200 with empty preferences for new user
  • Test GET returns 400 for invalid UUID
  • Test PUT returns 200 with merged preferences on success
  • Test PUT returns 400 for unknown preference keys
  • Test PUT returns 400 for invalid preference values
  • Test PUT returns 400 for missing preferences field
  • All responses use {data, meta} envelope structure
  • Tests use table-driven pattern with subtests
  • All tests pass with go test -v ./internal/api/handlers/...

T8: Routes, OpenAPI spec, and main.go wiring

• Scope: Update route registration to mount preferences endpoints under auth middleware, update OpenAPI spec with the two new endpoints, and wire the PostgreSQL adapter + service in main.go (DB connect, migrations, shutdown hook).
• Files:
  • Modify services/preferences-api/internal/api/routes.go
  • Modify services/preferences-api/internal/api/spec.go
  • Modify services/preferences-api/cmd/server/main.go
• Depends on: T3, T6
• Acceptance criteria:
  • Routes: GET /api/preferences-api/preferences/{user_id} and PUT /api/preferences-api/preferences/{user_id} registered
  • Both preference routes wrapped in auth.Middleware() group
  • URL parameters use {user_id} brace syntax (not colon)
  • Handlers wrapped with app.Wrap()
  • OpenAPI spec defines both endpoints with request/response schemas, security requirements, and error codes
  • main.go connects to PostgreSQL via database.MustConnect() with DatabaseConfig
  • main.go runs migrations via database.MustRunMigrations()
  • main.go creates postgres.PreferencesRepository and PreferencesService
  • main.go registers DB pool shutdown hook
  • Health endpoint remains functional

T9: Remove Example scaffold code

• Scope: Delete all Example scaffold files that have been replaced by preferences code. Ensure no references to Example types remain in routes, spec, main, or tests.
• Files:
  • Delete services/preferences-api/internal/domain/example.go
  • Delete services/preferences-api/internal/port/example.go
  • Delete services/preferences-api/internal/adapter/memory/example.go (and memory/ directory)
  • Delete services/preferences-api/internal/service/example.go
  • Delete services/preferences-api/internal/service/example_test.go
  • Delete services/preferences-api/internal/api/handlers/example.go
  • Delete services/preferences-api/internal/api/handlers/example_test.go
• Depends on: T8
• Acceptance criteria:
  • All Example files deleted
  • No remaining imports of Example types in any file
  • No remaining references to /examples routes
  • go build ./... succeeds with no compilation errors
  • go test ./... passes with no failures
  • Health endpoint still works