Ciclo de vida do resultado
Um modelo de dados para resultados de registro no Telegram e novas tentativas de atualização
Armazene os campos da resposta de registro no Telegram, diferencie resultados concluídos de erros da API e preserve uma data e hora local da resposta.
Por que um único booleano não basta
Um resultado de registro no Telegram é uma observação com data e hora produzida por uma verificação concluída, e não uma verdade permanente associada a um número de telefone.
Um campo como telegram_valid perde um contexto essencial. Ele não informa qual número normalizado foi verificado, quando a verificação foi executada, se o false foi uma decisão concluída nem se a requisição, na verdade, falhou. O banco de dados deve preservar essas distinções para que um aplicativo possa exibir e atualizar o resultado com honestidade.
O TG Validator retorna uma decisão concluída de forma síncrona, o que significa que a observação pode ser gravada assim que a resposta HTTP chega. Os campos retornados devem ser armazenados como estão, sem inventar outro conjunto de status de produto.
Separe o objeto das suas observações
Use um registro interno estável para o telefone e vincule a ele várias observações de verificação. Isso evita reescrever o histórico e torna uma atualização posterior fácil de entender.
| Registro | Campos sugeridos | Finalidade |
|---|---|---|
| Telefone de origem | phone_id, source_phone, source_system |
Preserva o registro de negócio original |
| Telefone normalizado | phone_id, e164_phone, normalized_at |
Registra o valor canônico usado nas verificações |
| Observação de verificação | phone_id, service_type, registered, received_at |
Armazena um resultado síncrono |
Se a normalização mudar porque o contexto de país original foi corrigido, crie ou versione o registro canônico. Não vincule silenciosamente um resultado antigo do Telegram a um número de telefone interpretado de outra forma.
Use exatamente os formatos de resposta documentados
| Formato retornado | Valor de registered |
Significado |
|---|---|---|
code=0, data.registered=true |
true | A verificação concluída informou registrado |
code=0, data.registered=false |
false | A verificação concluída informou não registrado |
code da API diferente de zero |
Ausente | Nenhuma decisão de registro; erro da API, não um resultado de registro |
A distinção é proposital. Um código de API diferente de zero significa que o serviço não tem uma resposta booleana para armazenar. Entrada inválida, rejeições por concorrência, saldo insuficiente, manutenção e falhas internas não acrescentam outros valores a data.registered.
Mantenha o estado atual e a última tentativa como duas visões
Duas perguntas costumam ser úteis:
- Qual é a observação de registro concluída mais recente?
- O que aconteceu na tentativa de requisição mais recente?
Elas podem apontar para linhas diferentes. Se um resultado true concluído em T1 for seguido de um erro da API em T2, a observação concluída mais recente continua sendo true em T1, enquanto um log de requisições separado pode registrar o status HTTP e o código da API de T2. Isso impede que um operador confunda T1 com um resultado recente ou T2 com false.
Quando uma chamada posterior é concluída com false em T3, a visão concluída atual avança para T3. Os registros de T1 e T2 continuam disponíveis para auditoria e solução de problemas.
Defina quando uma atualização é necessária
O TG Validator fornece uma observação síncrona atual quando é chamado, mas o aplicativo integrador é responsável pela sua política de atualização. Escolha uma idade máxima aceitável com base na decisão a ser tomada e deixe essa idade visível na interface.
Uma política de atualização deve especificar:
- a idade máxima aceita para cada fluxo de trabalho;
- se os operadores podem usar um resultado concluído mais antigo após um erro da API posterior;
- quais respostas da API com código diferente de zero devem ser reenviadas mais tarde;
- como o limite de concorrência por usuário influencia o agendamento;
- se todas as tentativas ou apenas as observações concluídas são mantidas a longo prazo.
Não repita uma verificação concluída com registered=false só porque o resultado é false. Repita quando for necessária uma observação mais recente ou quando a tentativa anterior não produziu decisão.
Uma consulta precisa do estado atual
O estado de registro atual deve selecionar a observação mais recente em que a resposta externa teve code=0 e, então, retornar juntos o seu valor registered e o received_at local. Nunca retorne o booleano sem a data e hora correspondente.
O estado da última tentativa deve selecionar a observação mais recente de qualquer status. Se ela não estiver concluída, a interface pode explicar que houve a tentativa de uma verificação mais recente, sem substituir o último resultado de registro conhecido.
O princípio de um design durável
Acrescente observações, preserve suas datas e horas e nunca force uma incerteza operacional a virar um valor de registro no Telegram.
Esse modelo corresponde exatamente ao produto. O TG Validator responde de forma síncrona a uma única pergunta sobre registro; ele não fornece dados de identidade nem de perfil da conta. O aplicativo do cliente fornece o registro estável, a política de retenção, o cronograma de atualização e a decisão de negócio em torno de cada observação.