# Component: UserProfileService

## Responsabilidad
Gestionar el perfil de usuario: consulta, actualización de datos básicos (nombre, avatar) y preferencias (idioma).

## Tipo
- [x] Microservicio
- [ ] Library/Biblioteca
- [ ] Shared Component
- [ ] External Integration

## Interfaces

### API REST

```
GET /api/v1/users/{user_id}/profile
Authorization: Bearer <token>
Output: {
  "id": string,
  "name": string,
  "avatar_url": string,
  "language": "en" | "es" | "fr" | "de",
  "created_at": ISO8601,
  "updated_at": ISO8601
}
Errors: 401 (unauthorized), 404 (user not found)

PUT /api/v1/users/{user_id}/profile
Authorization: Bearer <token>
Input: {
  "name": string (optional),
  "avatar_url": string (optional),
  "language": string (optional)
}
Output: { perfil actualizado }
Errors: 400 (validation), 401, 403 (not owner), 404
```

### Eventos (si aplica)
- `profile.updated.v1` — publicado cuando perfil se actualiza

## Dependencias

| Servicio/Biblioteca | Tipo | Notas |
|---------------------|------|-------|
| PostgreSQL | Database | Datos de usuarios y perfiles |
| Redis | Cache | Cache de perfil (TTL 5min) |
| Storage Service | External | Almacenamiento de avatares |

## Límites

### Alcance
- ✅ CRUD de perfil de usuario
- ✅ Cambio de idioma
- ❌ NO maneja autenticación (AuthService)
- ❌ NO maneja permisos de otros usuarios

### Constraints
- Timeout máximo: 300ms
- Rate limit: 50 req/min por usuario
- name: 2-50 caracteres, solo letras y espacios
- avatar_url: max 500 caracteres, URL válida (http/https)
- language: uno de ['en', 'es', 'fr', 'de']

## Criterios de éxito

| Criterio | Métrica | Target |
|----------|---------|--------|
| Disponibilidad | uptime | 99.9% |
| Latencia | p99 get_profile | < 100ms |
| Latencia | p99 update_profile | < 200ms |
| Cache hit rate | | > 80% |

## Diagrama

```mermaid
graph LR
    A[Client] -->|GET /profile| B[UserProfileService]
    B -->|cache| C[(Redis)]
    B -->|fetch| D[(PostgreSQL)]
    
    E[Client] -->|PUT /profile| B
    B -->|validate| F[Storage]
```

## Estados

| Estado | Trigger | Acción |
|--------|---------|--------|
| Initial | started | Connect to DB, Redis |
| Ready | all_connected | Accept requests |
| Degraded | redis_down | Fallback to DB-only |
| Error | db_failure | Return 503 + alert |

## Seguridad

- Authentication: JWT Bearer token required
- Authorization: Solo el dueño puede modificar su perfil
- Input validation: Pydantic, sanitización XSS
- Rate limiting: 50 req/min por user_id

## Observabilidad

- Metrics: `profile_get_total`, `profile_update_total`, `profile_latency_ms`
- Logs: structured JSON con user_id (masked)
- Traces: OpenTelemetry span por request

## Tests BDD

- Ver `spec/bdd/features/profile/user-profile.feature`