Estados de Atividade
Catálogo canônico dos estados operacionais, de display e de resultado de uma atividade na Reten — com suas transições válidas e regras de projeção.
Uma atividade expõe dois estados: um operacional, filtrável via query param (status), que reflete a situação real da atividade em seu ciclo de execução; e outro informativo (lifecycleStatus), calculado em cada resposta, com valores mais amigáveis pensados para exibição em interfaces de usuário.
O resultado (resultStatus) de uma atividade é um estado separado, reportado pelo operador a partir da plataforma da Reten ou de um provedor externo. Uma atividade COMPLETED indica apenas que ela foi executada, independentemente de o resultado de negócio ter sido positivo ou negativo: por exemplo, uma visita a um cliente com o objetivo de fechar uma venda permanece como COMPLETED mesmo que a venda não se concretize.
Esta página documenta os estados de uma atividade: o operacional, o informativo e o de resultado.
status (operacional, filtrável)
É a state machine real da atividade. As transições entre valores são restringidas por regras rígidas do backend (veja o diagrama abaixo). É a única dimensão filtrável via query param status nos endpoints de listagem.
READYPronta
Atividade está completamente resolvida e pronta para ser acionada. Se o cliente tiver um provedor configurado para fazer o despacho das atividades, a próxima ação do sistema tenta despachá-la; caso contrário, a atividade permanece READY e poderá ser acionada na plataforma interna por algum operador.
Transições manuais
- Cancelar atividade — cancela a atividade (→ CANCELED)
RETRYINGTentando novamente
Falhou ao menos uma tentativa de despacho; o sistema tentará novamente de forma automática. Cada nova tentativa mantém a atividade neste status. Passa a DISPATCHED quando uma tentativa tem sucesso, ou a FAILED quando as tentativas disponíveis se esgotam.
Transições manuais
- Cancelar atividade — cancela a atividade (→ CANCELED)
DISPATCHEDDespachada
Atividade foi entregue ao provedor externo. Aplica-se apenas quando o cliente tem um provedor de despacho configurado para a atividade; clientes que operam exclusivamente na plataforma interna da Reten não passam por este status. Ter provedor de despacho não impede que o resultado seja registrado na plataforma interna: o outcome pode chegar tanto do provedor externo quanto da plataforma interna.
COMPLETEDConcluída
Atividade alcançou um status terminal bem-sucedido por um de três caminhos: (a) o provedor externo reportou um resultado; (b) um operador registrou o resultado na plataforma interna da Reten; (c) um processo de fechamento de fim de dia marcou como não executados os resultados das atividades que ficaram sem outcome no encerramento da jornada. COMPLETED indica apenas que a atividade foi finalizada, ou seja, completou seu ciclo, independentemente de o operador ter registrado um resultado; o outcome de negócio (positivo ou negativo) é reportado separadamente no resultado da atividade.
CANCELEDCancelada
Atividade foi cancelada explicitamente a partir de um status não terminal (READY ou RETRYING) porque a razão de negócio que a motivou deixou de se aplicar antes do envio (por exemplo, o cliente já fez a ação alvo por outro canal, decidiu não recebê-la, ou o destinatário deixou de ser válido). O cancelamento é terminal: não se produz resultado nem ocorre despacho.
Transições manuais
- Cancelar atividade — cancelamento direto da atividade (caminho canônico, usado tanto na plataforma interna da Reten quanto no sistema externo que criou a atividade)
FAILEDFalhou
Atividade alcançou um status terminal de falha por uma de duas vias: (a) as tentativas de despacho se esgotaram sem sucesso; ou (b) um processo de fechamento de fim de dia detectou uma atividade que ficou tentando novamente e a marcou como FAILED com resultado NOT_EXECUTED. Embora seja terminal, uma atividade FAILED pode ser recuperada manualmente por um endpoint dedicado, que a tenta novamente uma vez; a tentativa pode terminar em DISPATCHED, RETRYING ou novamente FAILED.
Transições manuais
- Forçar nova tentativa de despacho — tenta o despacho novamente uma vez; pode terminar em DISPATCHED, RETRYING ou novamente FAILED(ignora a state machine)
Subconjunto filtrável (utilizável como query param status nos endpoints de listagem):
READY, RETRYING, DISPATCHED, COMPLETED, CANCELED, FAILED
lifecycleStatus (display, somente leitura)
É um estado calculado em cada resposta a partir do status e de informações contextuais da atividade (data de execução, se tem provedor, se há erros, se está em novas tentativas, entre outros). Não é filtrável. Existe para exibir um estado enriquecido em interfaces — tanto internas quanto as do provedor — embora o provedor possa derivar seu próprio estado conforme suas regras, se preferir.
CANCELEDCancelada
Status informativo exibido quando a atividade foi cancelada (`status` = CANCELED).
COMPLETEDConcluída
Status informativo exibido quando a atividade foi concluída (`status` = COMPLETED).
FAILEDFalhou
Status informativo exibido quando a atividade falhou definitivamente (`status` = FAILED).
RETRYING_DISPATCHTentando Despacho Novamente
Status informativo exibido quando a atividade está tentando o despacho novamente (`status` = RETRYING).
SCHEDULEDAgendada
Status informativo exibido quando a atividade está agendada para um dia futuro no calendário do cliente. A comparação é feita no nível de dia inteiro (não de horário exato): só conta como agendada de amanhã em diante.
READYPronta
Status informativo exibido quando a atividade está pronta e o cliente não tem um provedor de despacho configurado para ela.
PENDING_DISPATCHPendente de Despacho
Status informativo exibido quando a atividade está pronta e o cliente tem um provedor de despacho configurado para ela. O sistema ainda não tentou o despacho; tentará na próxima passagem automática.
DISPATCHEDDespachada
Status informativo exibido quando a atividade foi despachada ao provedor externo (`status` = DISPATCHED).
UNKNOWNUnknown
Valor de fallback usado quando nenhum outro status informativo se aplica. Não deveria ocorrer em operação normal; se aparecer, indica um caso não previsto. Para diagnosticar, consulte o `status` operacional da atividade.
Estes valores NÃO são filtráveis. Para filtrar listagens, use
statuscom os valores da seção anterior.
resultStatus (independente)
Estado terminal reportado pelo operador (a partir da plataforma da Reten ou de um provedor externo) depois que a atividade é executada — ou descartada. Não deriva de status: uma atividade COMPLETED pode ter qualquer resultado, e o resultado é rastreado à parte para que o outcome de negócio não se confunda com a execução.
COMPLETEDExecutada
A atividade foi executada pelo operador — a ação atribuída foi realizada (visitar o comércio, contatar o cliente, etc.) conforme o previsto. É atribuído SEMPRE de forma interna ao registrar um resultado (ambas as audiências: operador interno e externo); nunca é escrito pelo caller. NÃO implica que o objetivo de negócio subjacente tenha sido cumprido: uma visita comercial fica COMPLETED tanto se a venda se concretizou quanto se não, desde que o operador tenha executado a tentativa. O outcome mais específico (venda sim/não, resposta do cliente, etc.) é capturado na entidade de detalhe do resultado, não no status.
NOT_EXECUTEDNão Executada
Resultado terminal que indica que a atividade foi encerrada sem ter sido executada pelo operador. Único produtor: o job de fechamento automático de fim de dia, que registra NOT_EXECUTED para atividades que cruzaram o corte de fechamento automático sem outcome. Nenhum fluxo interativo o produz. Uma atividade que não pôde ser resolvida não fica como NOT_EXECUTED — essa falha é anterior e não é atribuível ao operador.
Diagrama de transições
Diagrama da state machine operacional (não inclui lifecycleStatus, que é derivado, nem o resultado, que é ortogonal). São mostradas apenas as arestas válidas segundo o backend; qualquer transição não listada é rejeitada.
┌─────────┐
│ READY │ (estado inicial)
└────┬────┘
│
├────────────► ┌──────────┐
│ │ CANCELED │ (terminal)
│ └──────────┘
│
│ ┌────────────────────────────────────────────┐
│ │ a partir de READY: │
│ │ → RETRYING, DISPATCHED, CANCELED, │
│ │ FAILED, COMPLETED │
│ └────────────────────────────────────────────┘
│
├─────────────► ┌───────────────┐
│ │ RETRYING │
│ └───────┬───────┘
│ │
│ a partir de RETRYING:│
│ → DISPATCHED, │
│ FAILED, │
│ RETRYING, │
│ CANCELED │
│ │
├──────────────┐ │
▼ ▼ ▼
┌────────────┐ ┌────────────────┐
│ DISPATCHED │──►│ COMPLETED │ (terminal)
└─────┬──────┘ └────────────────┘
│
└──► ┌──────────┐
│ FAILED │ (terminal)
└──────────┘Arestas literais da state machine:
READY → RETRYING, DISPATCHED, CANCELED, FAILED, COMPLETED(estado inicial de uma atividade)RETRYING → DISPATCHED, FAILED, RETRYING, CANCELEDDISPATCHED → COMPLETED, FAILEDCOMPLETED,CANCELED,FAILED→ terminal (sem saídas)
As transições manuais (cancelamentos, force-retry-dispatch) estão listadas por estado na seção
status— cada card de estado documenta suastransições manuais.