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

Tasks: User Preferences API

Task Order (dependency sequence)

T1: Domain layer - UserPreferences model and domain errors

• Scope: Create the UserPreferences domain model and preference-specific domain errors. The model uses map[string]any for flexible key-value storage. Add ErrInvalidUserID and ErrInvalidPreferenceValue sentinel errors.
• Files:
  • Create services/preferences-api/internal/domain/preference.go
  • Modify services/preferences-api/internal/domain/errors.go (replace example errors with preference errors)
• Depends on: None
• Acceptance criteria:
  • UserPreferences struct exists with fields: UserID string, Preferences map[string]any, CreatedAt time.Time, UpdatedAt time.Time
  • ErrInvalidUserID sentinel error defined
  • ErrInvalidPreferenceValue sentinel error defined
  • Example domain errors removed
  • Package compiles without errors

T2: Port layer - PreferenceRepository interface

• Scope: Define the PreferenceRepository interface with Get and Upsert methods. Get returns nil, nil for non-existent users (not an error). Upsert handles both create and update atomically.
• Files:
  • Create services/preferences-api/internal/port/preference.go
• Depends on: T1
• Acceptance criteria:
  • PreferenceRepository interface defined with Get(ctx context.Context, userID string) (*domain.UserPreferences, error) method
  • PreferenceRepository interface has Upsert(ctx context.Context, prefs *domain.UserPreferences) error method
  • Method signatures document expected nil behavior for Get (nil, nil when no row exists)
  • Package compiles without errors

T3: Service layer - PreferenceService with validation logic and tests

• Scope: Implement PreferenceService with Get and Upsert methods. The Upsert method validates known preference keys (theme, language, notifications_enabled), merges incoming preferences with existing ones, and delegates to the repository. Includes a custom ValidationError type that wraps domain.ErrInvalidPreferenceValue and carries per-field error details. Write comprehensive unit tests with a mock repository.
• Files:
  • Create services/preferences-api/internal/service/preference.go
  • Create services/preferences-api/internal/service/preference_test.go
• Depends on: T1, T2
• Acceptance criteria:
  • PreferenceService struct with constructor NewPreferenceService(repo, logger)
  • Get method delegates to repository and returns result
  • Upsert method validates theme against ["light", "dark", "system"]
  • Upsert method validates language as a valid BCP-47 tag
  • Upsert method validates notifications_enabled as boolean
  • Unknown preference keys accepted without validation
  • Multiple validation errors collected and returned together in ValidationError
  • ValidationError type implements error and Unwrap() returning domain.ErrInvalidPreferenceValue
  • ValidationError.Details is map[string]string with per-field messages
  • Merge strategy: incoming keys overwrite existing, unmentioned keys preserved
  • Tests cover: valid preferences, invalid theme, invalid language, invalid notifications_enabled, multiple errors, unknown keys accepted, merge behavior
  • All tests pass

T4: Database migration and PostgreSQL adapter

• Scope: Create the SQL migration for the preferences table and implement the PostgreSQL adapter for PreferenceRepository. Uses sqlx with parameterized queries. Get returns nil, nil on sql.ErrNoRows. Upsert uses ON CONFLICT for atomic create-or-update.
• Files:
  • Create services/preferences-api/migrations/001_create_preferences.sql
  • Create services/preferences-api/internal/adapter/postgres/preference.go
• Depends on: T1, T2
• Acceptance criteria:
  • Migration creates preferences table with columns: user_id UUID PRIMARY KEY, preferences JSONB NOT NULL DEFAULT '{}', created_at TIMESTAMPTZ, updated_at TIMESTAMPTZ
  • Migration creates index idx_preferences_updated_at on updated_at
  • Migration uses CREATE TABLE IF NOT EXISTS for idempotency
  • PostgreSQL adapter implements PreferenceRepository interface (compile-time check)
  • Get uses parameterized query and returns nil, nil for sql.ErrNoRows
  • Upsert uses INSERT ... ON CONFLICT ... DO UPDATE with parameterized values
  • JSONB marshaling/unmarshaling handled correctly for map[string]any
  • Package compiles without errors

T5: HTTP handlers - GET and PUT preference endpoints with tests

• Scope: Implement preference handlers for GET and PUT. GET extracts user_id from URL, validates UUID format, calls service, and returns response in {data, meta} envelope. PUT additionally binds the request body and maps validation errors to structured HTTP error responses. Write handler tests using httptest with a mock service/repository.
• Files:
  • Create services/preferences-api/internal/api/handlers/preference.go
  • Create services/preferences-api/internal/api/handlers/preference_test.go
• Depends on: T1, T2, T3
• Acceptance criteria:
  • Preference handler struct with constructor NewPreference(svc, logger)
  • Get handler extracts user_id via chi.URLParam, validates UUID, calls service, returns httpresponse.OK
  • Get handler returns 200 with empty preferences {} when service returns nil
  • Get handler returns 400 for invalid UUID format
  • Upsert handler binds request body with app.Bind(), validates preferences field is not nil
  • Upsert handler calls service and returns httpresponse.OK with updated preferences
  • Upsert handler maps ValidationError to httperror with details
  • PreferenceResponse struct has json tags for user_id, preferences, updated_at
  • mapDomainError function handles ErrInvalidPreferenceValue with details
  • Tests cover: GET success, GET empty preferences, GET invalid UUID, PUT success, PUT validation error, PUT missing body
  • All tests pass

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

• Scope: Update routes to register preference endpoints (replacing example routes). Update OpenAPI spec to document preference schemas and endpoints (removing example schemas). Update main.go to wire PostgreSQL connection, run migrations, create postgres adapter, and inject into the service. Add golang.org/x/text/language dependency for BCP-47 validation.
• 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
  • Modify services/preferences-api/go.mod (add golang.org/x/text dependency)
• Depends on: T3, T4, T5
• Acceptance criteria:
  • Routes register GET /preferences/{user_id} and PUT /preferences/{user_id} under /api/preferences-api
  • Example routes removed
  • Both routes wrapped with app.Wrap()
  • OpenAPI spec defines UserPreferences schema and UpdatePreferencesRequest schema
  • OpenAPI spec documents GET and PUT endpoints with parameters, request bodies, and response schemas
  • Example schemas removed from spec
  • main.go connects to PostgreSQL via database.MustConnect
  • main.go runs migrations via database.MustRunMigrations
  • main.go creates postgres.NewPreferenceRepository and service.NewPreferenceService
  • main.go defers pool.Close()
  • golang.org/x/text/language dependency added
  • Service compiles and starts successfully

T7: Cleanup - Remove example scaffolding files

• Scope: Delete all example-related files that have been replaced by preference implementations. This is done last to ensure nothing breaks.
• Files:
  • Delete services/preferences-api/internal/domain/example.go
  • Delete services/preferences-api/internal/service/example.go
  • Delete services/preferences-api/internal/service/example_test.go
  • Delete services/preferences-api/internal/port/example.go
  • Delete services/preferences-api/internal/adapter/memory/example.go
  • Delete services/preferences-api/internal/api/handlers/example.go
  • Delete services/preferences-api/internal/api/handlers/example_test.go
• Depends on: T6
• Acceptance criteria:
  • All example files deleted
  • No imports reference example types
  • go test ./... passes with no compilation errors
  • Service compiles cleanly