Índice do curso
Lição 26 — Acompanhar um pedido
Por Dorian Chávez · cofundador e Chief Executive Officer da Hábil ·
O que será alcançado: responder «o que aconteceu com o pedido 4006?» com uma única consulta: cada canal, cada tentativa, o que saiu em cada uma por inteiro, o que o parceiro respondeu e se o pedido ficou completo. E servir essa resposta por HTTP, buscando pelo número do pedido.
Antes de começar é preciso ter: as lições 15 e 25 concluídas e o ambiente da 00 ligado.
A novidade de hoje, em uma frase
São onze lições guardando coisas na base de estado: o pedido (15), cada operação e cada tentativa (15), os conflitos (18), as confirmações do parceiro (21), os alertas e o que está completo (25). Cada peça responde a uma pergunta pequena. Hoje elas são reunidas para responder à grande, a que faz um cliente ou alguém do suporte: «meu pedido não chegou, o que aconteceu com ele?». E responde-se pela chave de negócio, o número do pedido, que é a única coisa que quem pergunta traz.
A imagem: o rastreamento de um pacote na página de uma transportadora. Digita-se o código de rastreio e vê-se a história completa: recebido na agência, em trânsito, tentativa de entrega frustrada porque não havia ninguém, entregue. Não se vê só o estado de hoje: vê-se cada passo, com a hora. Se dissesse apenas «entregue», não daria para saber que houve uma tentativa frustrada, nem por que demorou dois dias.
1. Prepare a pasta
cd lecciones/26-seguir-una-orden
cp -R inicio mio
O router tem dois arquivos novos:
| Arquivo | O que é | É para escrever? |
|---|---|---|
orden-router/recorrido.camel.yaml |
Ao iniciar, declara a view com o que recorrido.sql disser. E serve GET /ordenes/{orden}/recorrido |
Não, só leia |
orden-router/recorrido.sql |
A view recorrido da base de estado |
Sim |
Uma view é uma consulta guardada com nome. Lê-se como se fosse uma tabela (SELECT * FROM recorrido WHERE orden = '4006'), mas não guarda nada próprio: cada vez que é lida, volta a juntar as tabelas de verdade. Por isso não
fica desatualizada.
E há uma tabela nova a partir de hoje, payload. Cada tentativa guarda em intento a impressão digital (sha256) e o
tamanho, e o corpo completo do que saiu vive em payload, uma vez por impressão digital. Se duas tentativas mandaram a
mesma coisa, compartilham a linha.
Abra infra/postgres/01-estado.sql e localize as tabelas que serão juntadas: operacion, intento, payload, acuse,
alerta e completitud.
2. Faça a previsão
Responda em um papel:
- Um cliente diz que o pedido 4006 não chegou. O que consultar primeiro: o log do router, a API, o ERP ou a base de estado? Por quê?
- A API estava fora do ar quando o 4006 chegou; depois alguém fez um rerun. Se a view mostra só a última tentativa de cada canal, que parte da história se perde?
- O pedido 4007 traz 150 linhas. O log do router o mostra por inteiro?
Veja como está hoje:
./verifica inicio
A view existe e o GET responde, mas é um painel de hoje: uma linha por operação, com a última tentativa. A
história do canal rest do 4006 aparece como um único aceptada, sem a primeira tentativa em que não se soube nem quem fez o
rerun. E a coluna cuerpo sai vazia: não diz o que saiu.
3. Monte o percurso
Abra mio/orden-router/recorrido.sql. É um CREATE VIEW com um SELECT que já traz as colunas com o nome
final; algumas saem em NULL por enquanto. Tem três TODO:
| TODO | O que mudar | Para quê |
|---|---|---|
| 1 | O LEFT JOIN LATERAL (… LIMIT 1) u por um LEFT JOIN intento i ON i.operacion = p.id, e as colunas u. por i. |
Uma linha para cada tentativa, não só a última |
| 2 | Um LEFT JOIN payload d ON d.sha256 = i.sha256, e cuerpo sai de d.cuerpo |
O que saiu em cada tentativa, por inteiro |
| 3 | Três colunas que hoje são NULL: acuses, alertas e completa |
O que veio depois do envio |
Para o TODO 3, duas das colunas são uma subconsulta que junta várias linhas em um texto com string_agg:
(SELECT string_agg(a.codigo, ',' ORDER BY a.id) FROM acuse a WHERE a.operacion = p.id) AS acuses,
Essa dá, por exemplo, A ou R: o que o parceiro disse dessa operação. A de alertas é igual, sobre a tabela
alerta, para o mesmo pedido, o mesmo evento do ciclo de vida e o mesmo canal, com l.tipo || ' en ' || l.estado. E completa
sai de um LEFT JOIN completitud c ON c.orden = p.orden AND c.momento = p.momento, com c.completa.
Por que LEFT JOIN e não JOIN? Porque uma operação que ainda não tem tentativas, ou uma tentativa sem confirmação, ou um
evento que não se completou, também tem de aparecer. Com JOIN desapareceriam, e o que falta é justamente o
que mais importa ao acompanhar um pedido.
E por que subconsultas para confirmações e alertas, e não mais JOIN? Porque um JOIN contra uma tabela com várias linhas por
operação multiplica as linhas: cada tentativa sairia uma vez para cada confirmação. A subconsulta as junta em uma única
célula.
Deixe os nomes das colunas como estão: o GET os usa.
4. Quebre um de propósito
Com a view concluída, tire o LEFT JOIN completitud e deixe completa como CAST(NULL AS timestamptz). Rode
./verifica.
Antes, faça a previsão: o 4007 se completou. O que diz o percurso?
Que não. Sai em vermelho a última marca: a view diz que nem o 4007 nem o 4006 ficaram completos. Nada falhou:
a view simplesmente não olhava essa tabela, e uma célula vazia se lê como «não aconteceu». Um percurso que não mostra algo
não prova que não aconteceu. Por isso ele é montado com LEFT JOIN contra tudo o que a base sabe. Devolva a linha.
5. Confira
./verifica
O verifica desliga a API, manda o 4006 (que pede um produto que o parceiro não conhece) e o 4007 (grande, com 150
linhas); volta a ligar a API, faz um rerun do canal rest dos dois e pede o percurso. Está concluída
quando aparecem as oito marcas verdes:
✅ Arrancaron el router (con su GET /ordenes/{orden}/recorrido), los tres canales y el sondeo
✅ El router declaró la vista recorrido al arrancar
✅ GET /ordenes/4006/recorrido: (…) filas, una por cada intento de la 4006
✅ El canal rest de la 4006 cuenta su historia: (…)
✅ El canal del socio de la 4006: rechazada, con su 997 de rechazo (R) en el recorrido
✅ Cada intento del recorrido trae lo que salió en él (cuerpo)
✅ La 4007 (grande): su cuerpo está entero en el recorrido, (…) bytes con su huella y sus 150 renglones
✅ El recorrido dice que la 4007 quedó COMPLETA y la 4006 no
Agora peça o percurso à mão:
curl -s localhost:8080/ordenes/4006/recorrido | python3 -m json.tool | less
Não roda? ./verifica solucion testa a nossa, e
diff mio/orden-router/recorrido.sql solucion/orden-router/recorrido.sql mostra em que são diferentes.
| O que aparece | O que fazer |
|---|---|
No existe la vista recorrido |
O recorrido.sql tem um erro de SQL: o router o diz no log, embaixo dessa marca |
la vista tiene … y la 4006 tiene … intentos |
Continua o LATERAL … LIMIT 1, ou o JOIN de uma confirmação multiplicou as linhas |
El canal rest de la 4006 en el recorrido: «aceptada/manual» sem o que veio antes |
Só aparece a última tentativa: falta o TODO 1 |
intentos del recorrido sin su cuerpo |
Falta o LEFT JOIN payload, ou ele une por outra coluna: é sha256 |
El canal del socio de la 4006 … (esperaba «rechazada R») |
A coluna acuses continua em NULL |
Completa en el recorrido |
Falta o LEFT JOIN completitud |
El puerto 8080 está ocupado |
Os serviços de outra execução ficaram no ar: DONDE=mio docker compose -f compose.yaml down |
Se recorrido.sql for alterado com os serviços no ar, reinicie o router: a view é declarada ao iniciar.
O que isto ensina fora do curso
Busca-se pelo que quem pergunta traz. Ninguém do suporte sabe o id de uma operação nem o número de controle
de um X12. Sabe o número do pedido. O percurso é montado a partir daí.
O log não é o registro. O log corta os corpos grandes, mistura-se com o de outros pedidos e vai embora com o contêiner. A base guarda cada tentativa com o que saiu, por inteiro, enquanto ninguém o apagar de propósito.
A história vale mais que o estado. «Aceito» diz como terminou; a história diz que primeiro não se soube, que o
disjuntor não o mandou (lição 22), que alguém da mesa de controle fez um rerun e que a API respondeu 201. No
verifica aparece assim: no_se_sabe/auto no_enviado/auto aceptada/manual. Com isso se
explica por que demorou.
Uma view não fica desatualizada. Não copia os dados: volta a juntá-los a cada vez. É a forma mais barata de ter uma resposta nova sem uma segunda fonte de verdade.
Exercício: o pedido problema
Com a versão própria concluída, rode ./verifica e depois:
- Peça o percurso do 4006 e, só com ele, escreva um parágrafo para o cliente que diz que o pedido dele «não chegou». Chegou à API? Ao ERP? Ao parceiro? O que aconteceu com o parceiro, em que linha e com que produto? (Dica: o corpo da tentativa do parceiro e o 997 da lição 21.)
- Procure o 4007 no log do router:
DONDE=mio docker compose -f compose.yaml logs orden-router | grep 4007. Dá para ver as 150 linhas dele? Compare com a colunatamanodo percurso. - Escreva a consulta que seria entregue a alguém do suporte para ver só os canais que não terminaram bem de um
pedido, com o último desfecho. Comece com
SELECT canal, estado_canal, … FROM recorrido WHERE orden = '4006'.
Por que foi feito assim
O que decidimos nesta lição, com o que descartamos e o que nos faria mudar de ideia:
- O percurso é uma view
Revisão
- O que é uma view, e por que não fica desatualizada?
- Por que o percurso é buscado pelo número do pedido?
- O que a tabela
payloadguarda, e como ela se une a cada tentativa? - Por que
LEFT JOINe nãoJOIN? Por que subconsultas para as confirmações? - A pergunta de encerramento: um cliente diz que o pedido dele não chegou. O que consultar primeiro, e por que o percurso e não o log?
A seguir: na lição 27 volta-se a olhar o percurso do 4008. Ele traz o nome, o endereço, o telefone e o e-mail de uma pessoa. Quem deveria poder vê-los?
Prefere e-mail? Escreva para hola@habil.mx