import_batch_finalized
Marca de finalização de lotes de importação Steam — usado pra detectar fim do batch.
Mecanismo auxiliar do fluxo de importação Steam (workers steam.import-game + steam.enrich-game). Como a importação é distribuída em N jobs paralelos, precisa-se de uma forma de saber qual job terminou por último pra emitir o evento "import done" e disparar a notificação.
Cada batch (importação completa de um user) tem um batch_id (UUID gerado no início). Workers checam atomicamente se já houve finalização pra evitar duplicação. O primeiro job a achar que todos terminaram insere aqui — o INSERT atomico (PK batch_id impede duplicatas) é o sinal de finalização.
Colunas
| Coluna | Tipo | Nullable | Default |
|---|---|---|---|
| batch_id ● | uuid | NOT NULL | — |
| user_id | uuid | NOT NULL | — |
| collection_id | uuid | NOT NULL | — |
| total | integer | NOT NULL | — |
| imported | integer | NOT NULL | — |
| updated | integer | NOT NULL | — |
| failed | integer | NOT NULL | — |
| finalized_at | timestamp | NOT NULL | now() |
● primary key ◆ unique
Funcionalidade dos campos
batch_id— UUID, PK (não háidseparado). Identificador do batch — também usado em queues e logs.user_id— quem fez a importação (cascade)collection_id— coleção destino dos jogos importados (cascade)total— quantos jogos no inputimported— quantos foram inseridos como itens novosupdated— quantos já existiam e foram atualizadosfailed— quantos falharam (erro Steam API, formato inválido)finalized_at— momento exato da finalização
Foreign keys
| Coluna(s) | Referência | ON DELETE | ON UPDATE |
|---|---|---|---|
| user_id | users.id | cascade | no action |
| collection_id | collections.id | cascade | no action |
Índices
| Nome | Único | Colunas | WHERE (parcial) |
|---|---|---|---|
| import_batch_finalized_user_idx | não | user_id, finalized_at | — |
import_batch_finalized_user_idx — usado pra "histórico de importações do user X".
Constraints
PRIMARY KEY (batch_id)
PK em batch_id é o que torna a finalização atômica — se dois workers tentam inserir, apenas um sucede; o outro recebe constraint violation e silencia.
Como o batch detecta fim
Lógica em ImportBatchFinalizationRepository.tryFinalize(batchId, ...):
- Worker termina seu job (sucesso ou falha)
- Decremente o pending counter (em pg-boss state ou tabela auxiliar)
- Se
pending === 0: tentaINSERT INTO import_batch_finalized (...) - Se INSERT sucede → este job é o "finalizador"; dispara
notifySafe({type: 'steam_import_done' | 'steam_import_partial'}) - Se INSERT falha por unique violation → outro job já finalizou; este sai silencioso
Padrões de uso
- INSERT atomico — pelo último worker do batch
- Lookup de histórico —
GET /integrations/steam/imports?userId=...
Tabelas relacionadas
users— quem importou (cascade)collections— destino dos itens (cascade)items— alvo dos jobsnotifications—steam_import_done/steam_import_partial