Referência de estados¶

Enum e transições¶

Fonte: SessionState, LEGAL_TRANSITIONS e TERMINAL_STATES em src/core/domain/states.py. O enum tem 9 valores, dos quais CLOSED e OUT_OF_SCOPE são terminais. A tabela abaixo enumera todos os destinos e origens legais; permanência sem chamar transition_to() não cria uma nova aresta.

Valor	Finalidade	Entradas legais	Saídas legais	Consumidor automático
`NEW`	Sessão recém-criada	Construção, não transição de outra sessão	TRIAGE	Caso de uso
`TRIAGE`	Classificação inicial	NEW, TRIAGE	TRIAGE, QUALIFYING, HANDOFF_PENDING, OUT_OF_SCOPE, CLOSED	Triagem
`QUALIFYING`	Qualificação técnica	TRIAGE, QUALIFYING	QUALIFYING, DATA_COLLECT, HANDOFF_PENDING, CLOSED	Qualificação
`DATA_COLLECT`	Cadastro e correções	QUALIFYING, DATA_COLLECT, CONFIRM	DATA_COLLECT, CONFIRM, HANDOFF_PENDING, CLOSED	Coleta
`CONFIRM`	Aceite do resumo	DATA_COLLECT	DATA_COLLECT, HANDOFF_PENDING, CLOSED	Coleta
`HANDOFF_PENDING`	Fila humana	TRIAGE, QUALIFYING, DATA_COLLECT, CONFIRM	HUMAN	Webhook/inbox/renotificação, sem agente
`HUMAN`	Atendimento assumido	HANDOFF_PENDING	CLOSED	Painel do operador, sem agente
`CLOSED`	Encerramento	TRIAGE, QUALIFYING, DATA_COLLECT, CONFIRM, HUMAN	Nenhuma	Novo inbound pode criar outra sessão
`OUT_OF_SCOPE`	Fora do portfólio	TRIAGE	Nenhuma	Novo inbound pode criar outra sessão

Total de arestas: NEW 1 + TRIAGE 5 + QUALIFYING 4 + DATA_COLLECT 4 + CONFIRM 3 + HANDOFF_PENDING 1 + HUMAN 1 = 19.

Contrato de alteração¶

session.transition_to(SessionState.QUALIFYING, agent=AgentName.QUALIFICACAO)

Em uma sessão TRIAGE, o exemplo altera estado, agente e updated_at. A entrada em estado terminal também preenche closed_at. O método não persiste no banco; o repository faz isso. A mesma chamada em HUMAN lança IllegalStateTransitionError.

Session.transition_to() é a validação em memória. DynamoSessionRepository.transition_state() implementa condições atômicas de estado/ownership, mas seus consumidores são responsáveis pela validade de domínio. Rotas administrativas de debug podem fechar diretamente estados ativos e não acrescentam arestas legais ao enum.

Relação com códigos e persistência¶

s=97 mantém estado e guarda possível novo assunto; s=98 fecha a sessão atual e cria outra ligada por previous_session_id; s=99 mantém estado enquanto injeta conhecimento. CONFIRM → CONFIRM não existe, embora uma validação recusada mantenha o estado sem transição. Em HANDOFF_PENDING, o cliente pode continuar escrevendo e recebe ACK fixo; em HUMAN, a mensagem somente entra no histórico/inbox.

Sessões são indexadas como GSI1PK=STATE#{state} e GSI1SK=created_at. ACTIVE aponta para a sessão de um telefone. Uma sessão terminal não muda de volta para NEW: outra entidade é criada, com outro UUID. As datas, motivo de handoff e IDs comerciais são campos separados; nenhum deles deve ser deduzido apenas de uma mensagem textual do agente.

Testes e referência detalhada¶

tests/unit/domain/test_states.py testa todas as combinações legais/ilegais e o total 19. tests/unit/domain/test_session.py testa efeitos na entidade; tests/unit/application/test_action_mapping.py testa códigos; tests/unit/application/test_human_conversation.py testa operações humanas. Ao editar o enum, revise seleção de agente, serialização, índices, UI e projeção CRM.

Leia a máquina de estados completa para gatilhos por aresta e os action codes para condições por agente.