Contrato v3: contas, painéis, envio pela cidadã, dúvidas ao advogado

Acréscimos ao serviço (apps/llm-service) e ao app (apps/web) decididos em 13/09 à tarde. JSON, UTF-8, campos em snake_case como no serviço. Autenticação por token Bearer (o cookie sessao continua para os templates internos). O app roda em outra origem (Vercel), por isso cookie não serve; o token é o mesmo Usuario.session_token.

Papéis

papel em usuario: cidadao (usa a plataforma por conta própria), advogado (envia documentos e responde dúvidas), fornecedor (admin: vê tudo). O admin inicial vem de ADMIN_EMAIL/ADMIN_PASSWORD. Cadastro aberto para cidadao; para advogado só quando ADVOGADO_SIGNUP=true (padrão true no hackathon).

Autenticação

usuario_atual passa a aceitar Authorization: Bearer <token> além do cookie. Um token por usuário (login novo invalida o anterior).

Tarefas (documentos) de quem está logado

Cidadã (rotas públicas, governadas pelo convite)

O hash já foi o segredo inteiro: quem tivesse o endereço abria o documento, para sempre, e não havia como desfazer. Agora o documento pode ter um convite, que acrescenta validade, cancelamento e, quando quem enviou sabe o endereço, uma destinatária única.

Documento sem convite se comporta como sempre, para não quebrar link que já circulou. Quem enviou o documento e a cidadã já vinculada entram sempre.

O convite trabalha em duas camadas, e a diferença é deliberada:

Ler e perguntar não exigem conta, de propósito. Exigir cadastro para ler é barreira justamente para quem este produto atende, que pode estar num celular emprestado. O que a destinatária protege é o comprovante, que afirma que uma pessoa entendeu o documento. Quem não é ela lê tudo, tira dúvidas, e recebe 403 ao tentar gravar o registro.

Destinatária é uma conta, não um endereço. Enquanto a comparação era por e-mail, a conta criada pela confirmação de nome nunca passava, porque ela não tem e-mail nenhum para comparar: pôr o endereço no convite desligava justamente o caminho sem digitação. O convite guarda agora de quem ele passou a ser, e reivindicar é outro ato — POST /api/t/{hash}/confirm-name confere só a validade do link, porque confirmar o nome é virar a destinatária. Quem desfaz o vínculo (DELETE /api/tarefas/{id}/cidadao) devolve o convite ao estado sem dona, senão o documento ficaria trancado para todo mundo, inclusive para a pessoa certa.

GET /api/t/{hash} traz convite: { enderecado: bool, para: "ma***@exemplo.com" | null, expira_em } | null, para a tela avisar antes de a pessoa responder. O endereço vai mascarado: serve para ela reconhecer o próprio e-mail, não para alguém coletá-lo.

Quem confere o trecho

A posição do trecho é sempre encontrada pelo serviço, nunca lida do que o modelo escreveu. Modelo de linguagem não conta caractere, então a posição que ele devolve é palpite com cara de fato: pode parecer válida e apontar para a cláusula errada, ou para uma cláusula qualquer quando o trecho foi inventado. Acreditar nela transforma o selo de trecho conferido, que é a promessa central do produto, em decoração.

A busca tem três estágios, e o item diz qual deles achou:

Sem nenhum dos três, conferido é falso, pos é nulo e conferencia não vem.

O registro de consentimento é congelado, não remontado

Quando a tentativa é aprovada, o serviço grava o JSON canônico publicado, o hash dele, o SHA-256 do PDF que a pessoa recebeu e o SHA-256 da explicação que ela leu. A verificação serve o que foi gravado.

Isso resolve duas coisas ao mesmo tempo. O comprovante passa a dizer a que documento se refere, em vez de provar apenas que houve uma tentativa com N acertos. E a prova para de mudar quando o banco muda: antes o payload era remontado a cada visita, então alterar uma linha alterava o registro publicado e o carimbo de tempo passava a vouchar por algo que não existia mais.

Comprovante emitido antes disso não tem registro gravado e continua sendo remontado, para não parar de abrir.

O contrato de cada etapa do pipeline

Etapa que declara tipo_saida: json e devolve algo que não é JSON falha, e o documento falha com ela. Antes o texto cru virava a saída da etapa, era gravado e entrava no contexto da próxima, tudo reportado como sucesso: um resumo construído sobre lixo é pior que um erro honesto.

Oito etapas declaram também quais campos precisam existir, no campo schema do protocolo:

"schema": { "campos": { "sintese_fatos": { "tipo": "objeto", "obrigatorios": ["valor", "lastro"] } } }

A verificação é pequena de propósito, e exige só o que o produto consome. Etapa sem schema declarado passa apenas pela checagem de JSON válido.

Uma etapa pode declarar opcional: true, e aí a regra acima muda para ela: quando falha, o documento não falha junto. É o caso de T0_TIPO_DOCUMENTO. Ela melhora o resto e não pode derrubá-lo: antes de a classificação existir o documento era explicado, então uma etapa nova capaz de matar a rodada seria regressão para quem só quer entender o próprio papel. Espécie que não dá para ler vira indefinido, que é o vocabulário de sempre.

De onde vem o trecho de cada tópico

Os títulos das seções do resumo são fixos: quem os define é a tarefa que escreve o resumo, em protocolo_pdf.json. Por isso o vínculo entre seção e trecho é declarado ali, no campo ancoras_por_secao, e não reconstruído depois por semelhança de palavras. O trecho sai do lastro que a própria síntese daquela classe declara ter usado, e ainda precisa passar pela conferência acima.

Seção sem fonte declarada não recebe trecho. "Resumo em uma linha" é assim de propósito: ela conta o caso inteiro, não uma cláusula. Trecho conferido embaixo do assunto errado é uma mentira diferente, e não menos grave. Na jornada, o tópico só recebe trecho quando ele foi encontrado, e a frase que a tela exibe muda conforme o método: cópia exata só é afirmada quando foi exata.

Banco e escala

• DATABASE_URL (Postgres, postgresql+psycopg://...) quando definido; senão SQLite em DB_PATH. Tabelas via SQLModel.metadata.create_all; as migrações ALTER TABLE só rodam no SQLite. Novas colunas: tarefa.cidadao_id (nulo), tarefa.origem (advogado | cidadao); nova tabela duvida (id, tarefa_id, texto, contexto (json), criada_em, respondida, resposta, respondida_em).
• Pipelines em paralelo limitados por PIPELINE_CONCURRENCY (padrão 3) com semáforo; cada tarefa tem seu próprio estado e uma falha não afeta as outras. Rotas públicas de escrita (/quiz, /chat, /duvida, cadastro) com limite por IP (RATE_LIMIT_PER_MINUTE, padrão 30) em memória.
• Rotas do painel interno (templates) continuam funcionando com cookie.

App (apps/web)

O navegador nunca chama o serviço direto: ele chama as rotas do próprio app em app/api/*, que encaminham para SERVICE_URL acrescentando o Authorization: Bearer lido do cookie de sessão. Sem SERVICE_URL, essas mesmas rotas respondem pelo mock interno, com dados em memória do processo.

Revisão do advogado antes de liberar (13/09, 18h)

Espelha o fluxo "Resumo estruturado" do painel do Carlos (Status → Resumo → Visualizar → Dna): o advogado revisa o que o workflow extraiu e concluiu antes de a cliente receber o link.

Estados: pronta = pronta para revisão do advogado; enviada = liberada para a cliente; assinada = entendimento registrado. Tarefas com origem = cidadao não passam por revisão: pronta já libera.

Gate público: para tarefa com advogado (origem = advogado) em pronta, GET /api/t/{hash} devolve tarefa.status = "revisao" com resumo_md: null, topicos: null, questoes: [] (e tem_advogado, advogado), e GET /api/t/{hash}/inferencias, POST .../quiz e POST .../chat respondem 409 "Em revisão pelo advogado". O app mostra "O advogado está revisando a explicação" na tela de espera.

Tela no app: /painel/{id}/revisao com abas Marcações (classes com "Ver no texto" e selo "conferido no texto"), Texto (documento com destaques por classe), Conclusões (sínteses com lastro), Explicação (o que a cliente vai ler), Perguntas (com a resposta certa marcada) e o botão "Aprovar e liberar para a cliente".

Preparação visível e tarefas do fluxo externo (13/09, 18h40)

Pedido do Daniel: a tela de espera deve mostrar todas as etapas do processo (não uma por vez), o documento e o que a assistente está marcando, com score quando existir; e explicar por que um link gerado pelo fluxo "Resumo estruturado" chega sem explicação.

Causa do link sem explicação. O fluxo "Resumo estruturado" do painel do Carlos manda o PDF a uma API externa e grava só resumo_estruturado.json (o fluxo externo, já removido); a página da cidadã e o nosso JSON leem resumo_humanizado.md e questoes.json, que só o pipeline local (T1..T14, fluxo "Anexar PDF" / "Nova tarefa") produz. Resultado: pronta sem explicação nem perguntas ("resumo indisponível", app_gestao.py:608-610).

Cada pergunta de GET /api/t/{hash} traz secao (o título exato da seção da explicação de onde ela nasceu), trecho (a fatia literal do documento que sustenta a resposta) e conferencia { metodo, score }. Nunca traz correta nem justificativa. A pergunta cujo trecho o locate não acha no documento não é publicada, e abaixo de QUIZ_MIN_QUESTIONS (4) o serviço publica zero perguntas em vez de uma conferência fraca: a jornada termina em sem_perguntas, sem comprovante. POST /api/t/{hash}/quiz aceita consultas, o mapa { id_da_pergunta: vezes } de quantas vezes ela reabriu o trecho, que entra no preimage do hash da tentativa (leia.attempt.v3) e no comprovante (leia.payload.v4, campo consulted).

GET /api/t/{hash} traz também tipo_documento: { tipo, rotulo, trecho, pos, conferido, revisado_por_advogado, aplicado } ou null antes da primeira rodada. É a espécie com que o motor leu o documento, e é ela que escolhe o vocabulário das extrações: conferido diz se trecho foi achado no documento pelo locate, revisado_por_advogado que quem respondeu foi uma pessoa, e aplicado se a explicação na tela foi mesmo produzida com ela.

Nomes das etapas (pt-BR): T0 Reconhecer o tipo do documento · T1 Identificar as partes · T2 Datas e valores · T3 Fatos · T4 Fundamentos, leis e decisões · T5 Pedidos · T6 Juntar a memória · T7 Resumir os fatos · T8 Resumir os fundamentos · T9 Resumir os pedidos · T10 Quem é quem · T11 Contexto do processo · T12 Marcar o texto · T13 Explicar em linguagem simples · T14 Preparar as perguntas.

App: a tela de espera mostra a espécie reconhecida ("Lido como: Contrato"), a lista das 15 etapas com estado e tempo, barra "n de 15", e abaixo "O que a assistente está lendo agora": o documento com as marcações parciais e a contagem por classe (atualiza a cada 8 s). Documento sem perguntas (fluxo externo) termina a jornada em "Você viu todos os pontos", sem conferência e sem comprovante.