Módulos
Steam Integration
OpenID link Steam + import de games via pg-boss workers com throttle.
Visão geral
Integração com Steam permite:
- Vincular conta Steam via OpenID 2.0 (sem precisar API key pra link)
- Setar Steam Web API key pessoal pra autorizar consultas
- Listar jogos owned via
IPlayerService/GetOwnedGames - Importar jogos selecionados em batch — workers
steam.import-game(lista) esteam.enrich-game(detalhes via appdetails, com throttle)
Importação roda assíncrona via pg-boss (queue persistida em PG). Frontend pode acompanhar via socket events import:progress / import:done ou polling GET /import/:batchId/status.
Entidades principais
| Tabela | Papel |
|---|---|
users | steam_id, steam_linked_at, steam_api_key |
items | Items criados/atualizados pela importação |
collections | Destino dos jogos importados |
import_batch_finalized | Marca atomica de fim de batch |
Endpoints
8 endpoints em /integrations/steam:
| Endpoint | Resumo |
|---|---|
POST /login | Iniciar OpenID (retorna URL pra redirect) |
GET /callback | Callback OpenID Steam |
DELETE /link | Desvincular |
PUT /api-key | Definir Steam Web API key |
DELETE /api-key | Limpar API key |
GET /games | Listar jogos owned (via API) |
POST /import | Iniciar importação selecionada |
GET /import/:batchId/status | Status do batch |
Fluxos
Vincular Steam (OpenID)
Setar API key (necessária pra import)
Listar e importar jogos
Workers e finalização atomica
Desvincular
Eventos de socket
| Evento | Quando |
|---|---|
import:progress | Cada job processado (incremental counter) |
import:done | Batch finalizado |
notification:new (steam_import_done) | Sucesso completo |
notification:new (steam_import_partial) | Batch com falhas |
Edge cases e regras especiais
- Steam profile precisa ser público — caso contrário GetOwnedGames retorna
EResult_AccessDenied. Backend mapeia praSTEAM_PROFILE_PRIVATE. - API key fica em DB — opção do user. Backend só usa em consultas dele. Considerar criptografar at-rest (pendência).
- Throttle agressivo no enrich —
appdetailsda Steam Store API tem rate limit. 1 worker concurrency=1 → ~1 req/sec. import_batch_finalizedPK = batch_id — primeiro INSERT vence, outros falham com unique constraint silenciosamente. É a "race condition resolution".- Importação re-rodada — se user importar o mesmo jogo de novo, é UPDATE em vez de INSERT (lookup por appId nos items existentes da coleção).
gamesSnapshotopcional — frontend envia o que listou (incluindo playtime no momento). Workers usam pra fallback se Steam API ficar offline durante o batch.- Itens importados mantêm fields preenchidos mesmo após desvincular conta Steam — não é "sync contínuo", é snapshot.
STEAM_REPLACE_REQUIRES_UNLINK— se user já tem steam_id vinculado e tenta vincular outro, precisa desvincular primeiro.
Dependências entre módulos
- Items — workers populam ITEMs em batch
- Collections — destino dos jobs (auto-create se newCollectionName)
- Field Definitions — campos de sistema (Plataforma, Horas jogadas, App ID) usados nos fields
- Notifications — steam_import_done / steam_import_partial
- Chat (gateway) — emit import:progress / import:done