RF-007 Requisitos - Validação de Documentos [Wiki TCE-GO]

Essa página está em modo somente de leitura. Você pode visualizar a fonte, mas não alterá-la. Informe-se com o administrador do Wiki, caso você ache que isso está incorreto.
====== RF-007 Requisitos - Validação de Documentos ======
Permite que qualquer pessoa verifique a autenticidade de um documento processual do TCE-GO a partir de uma chave criptografada informada via URL ou digitada manualmente. Após validação via CAPTCHA, o sistema valida o documento e exibe o resultado; se válido, o cidadão pode abrir o PDF em nova aba. | Menu/Local de Acesso: `/validar-documento`

===== Atores =====

^ Nível ^ Perfil ^ Autenticação ^ Abrangência ^
| Público | Cidadão | Não requerida | Acesso irrestrito via link externo ou acesso direto à rota |

===== Telas =====

==== Tela 01 - Formulário de Validação ====

{{:pres:gerti:gestao_de_ativos:portal:pasted:20260330-203912.png}}

^ Elemento ^ Tipo ^ Obrigatório ^ Observação ^
| Número do Documento | Campo de texto | Sim | Pré-preenchido com o valor do parâmetro `?key` quando presente na URL |
| Confirmação CAPTCHA | Checkbox "Não sou um robô" | Sim | Padrão visual do projeto (simulado); deve ser resetado após abertura do PDF |
| Botão "Consultar" | Ação | — | Submete o formulário; habilitado somente com CAPTCHA confirmado |
| Botão "Limpar" | Ação | — | Limpa o campo, remove mensagens de erro e desmarca o CAPTCHA |

==== Tela 02 - Loading ====

^ Elemento ^ Tipo ^ Observação ^
| Indicador de progresso | Ícone animado (Loader2) | Exibido enquanto aguarda resposta da API |
| Texto informativo | Rótulo estático | "Validando documento..." |

==== Tela 03 - Sucesso ====

{{:pres:gerti:gestao_de_ativos:portal:pasted:20260330-203702.png}}

^ Elemento ^ Tipo ^ Observação ^
| Faixa verde | Cabeçalho do card | Exibe ícone ShieldCheck + "Documento autêntico e válido" |
| Metadados da consulta | Painel informativo | Exibe: chave consultada, data/hora da consulta e validade do link (10 minutos) |
| Botão "Abrir Documento PDF" | Ação | Abre o PDF em nova aba via `window.open`; ao clicar, reseta o CAPTCHA |
| Botão "Nova Consulta" | Ação | Retorna ao estado `form` com campos limpos |

==== Tela 04 - Acesso Restrito (Sigilo) ====

{{:pres:gerti:gestao_de_ativos:portal:pasted:20260330-204032.png}}
^ Elemento ^ Tipo ^ Observação ^
| Faixa amber | Cabeçalho do card | Exibe ícone Lock + "Acesso restrito — Processo em sigilo" |
| Mensagem de sigilo | Texto | Mensagem retornada pela API (HTTP 403) |
| Painel informativo | Bloco amber | Explica o sigilo processual e orienta o cidadão a contatar o TCE-GO |
| Botão "Nova Consulta" | Ação | Retorna ao estado `form` com campos limpos |

==== Tela 05 - Erro Geral ====

{{:pres:gerti:gestao_de_ativos:portal:pasted:20260330-204341.png}}

^ Elemento ^ Tipo ^ Observação ^
| Faixa vermelha | Cabeçalho do card | Exibe ícone AlertTriangle + "Não foi possível processar a solicitação" |
| Mensagem de erro | Texto | Mensagem retornada pela API ou mensagem padrão de falha de conexão |
| Painel de causas | Lista | Possíveis causas: falha de comunicação, serviço indisponível, tempo excedido |
| Botão "Nova Consulta" | Ação | Retorna ao estado `form` com campos limpos |

===== Fluxos =====

==== Fluxo 01 - Acesso com Chave via URL ====

^ Passo ^ Ação ^ Regra ^ Tela ^
| 01 | O cidadão acessa a rota `/validar-documento?key=<chave_criptografada>` | | — |
| 02 | O sistema detecta o parâmetro `?key` na URL via `useSearchParams()` | RN07 | Tela 01 |
| 03 | O sistema pré-preenche o campo "Número do Documento" com o valor da chave | | Tela 01 |
| 04 | O sistema exibe o formulário no estado `form` aguardando confirmação do CAPTCHA | RN01 | Tela 01 |
| 05 | O cidadão confirma o CAPTCHA e clica em "Consultar" | RN01 | Tela 01 |
| 06 | O sistema executa o [[#fluxo_03_validacao_do_documento|Fluxo 03]] | | — |

==== Fluxo 02 - Acesso Manual sem Chave ====

^ Passo ^ Ação ^ Regra ^ Tela ^
| 01 | O cidadão acessa a rota `/validar-documento` sem parâmetro `?key` | | — |
| 02 | O sistema detecta ausência do parâmetro e exibe o formulário com campo vazio | RN07 | Tela 01 |
| 03 | O cidadão digita a chave manualmente no campo "Número do Documento" | | Tela 01 |
| 04 | O cidadão confirma o CAPTCHA e clica em "Consultar" | RN01 | Tela 01 |
| 05 | O sistema executa o [[#fluxo_03_validacao_do_documento|Fluxo 03]] | | — |

==== Fluxo 03 - Validação do Documento ====

^ Passo ^ Ação ^ Regra ^ Tela ^
| 01 | O sistema valida se o campo "Número do Documento" está preenchido | RN02 | Tela 01 |
| 01.1 | Campo vazio: o sistema exibe mensagem inline no campo: "O número do Documento deve ser informado." | RN02 | Tela 01 |
| 02 | O sistema valida se o CAPTCHA foi confirmado | RN01 | Tela 01 |
| 03 | O sistema altera o estado para `loading` | | Tela 02 |
| 04 | O sistema realiza `POST /api/validar-documento/obter` com `{ key, captcha }` | | — |
| 05 | O backend descriptografa a chave extraindo `idProcesso`, `idDocumento`, `tipoDocumento` | | — |
| 06 | O backend executa a verificação de liberação conforme o tipo do documento | RN09, RN10, RN11, RN12 | — |
| 06.1 | `tipoDocumento ∈ {A, R, H}`: integração com [[#rn09|serviço de autuação]] para verificar decisões julgadas | RN09 | — |
| 06.2 | `tipoDocumento = GED`: integração com [[#rn10|serviço de documento]] para verificar existência ativa | RN10 | — |
| 06.3 | Demais tipos (andamento processual): integração com [[#rn11|serviço de andamento]] para verificar `FoiJulgado` ou `UltimaSituacaoId = 11` | RN11 | — |
| 06.4 | `tipoDocumento = K1`: caso andamento não encontrado, verifica andamento pai via `PRO_ANEXOS` | RN12 | — |
| 07 | Processo em sigilo: a API retorna HTTP 403; o sistema altera o estado para `erro-sigilo` | RN08 | Tela 04 |
| 08 | Chave inválida ou documento inexistente: o sistema exibe mensagem inline: "O documento não é válido ou não existe." e retorna ao estado `form` | RN03 | Tela 01 |
| 09 | Documento não julgado: o sistema exibe mensagem inline: "Este documento só poderá ser visualizado após o julgamento." e retorna ao estado `form` | RN04 | Tela 01 |
| 10 | Erro de conexão (catch de rede): o sistema altera o estado para `erro-geral` com a mensagem "Não foi possível conectar ao servidor. Tente novamente." | | Tela 05 |
| 11 | Erro inesperado de API: o sistema altera o estado para `erro-geral` e exibe a mensagem retornada | | Tela 05 |
| 12 | Validação bem-sucedida: a API retorna `{ success: true, keyValid: <chave_temporaria> }` | RN05 | — |
| 13 | O sistema altera o estado para `sucesso`, registra data/hora da consulta e aguarda ação do cidadão | | Tela 03 |

==== Fluxo 04 - Abertura do PDF ====

^ Passo ^ Ação ^ Regra ^ Tela ^
| 01 | O cidadão clica em "Abrir Documento PDF" na Tela 03 | | Tela 03 |
| 02 | O sistema chama `window.open('/api/validar-documento/pdf?keyValid=<keyValid>', '_blank')` | RN05, RN06 | — |
| 03 | O sistema reseta o CAPTCHA na tela de origem | RN06 | Tela 03 |
| 04 | O backend descriptografa `keyValid` extraindo `idProcesso`, `idDocumento`, `tipoDocumento`, `dataLink` | | — |
| 05 | O backend verifica se `dataLink + 10 minutos > agora` | RN05 | — |
| 05.1 | Token expirado: o sistema retorna erro; o cidadão deve iniciar nova consulta | RN05 | Tela 03 |
| 06 | O backend baixa os bytes do PDF conforme o tipo do documento | | — |
| 06.1 | `tipoDocumento = GED`: integração com `DOC_DOCUMENTO + GER_ANEXO` via `DownloadDocumentoNaoProcessual` | | — |
| 06.2 | `tipoDocumento = K1`: leitura do arquivo físico via `PRO_ANEXOS + GER_ANEXO` (fileserver) | | — |
| 06.3 | Demais tipos processuais: integração com `VWEB_BUSCADOCUMENTOS.TEXT_DOCASSINADO_B` via `DownloadDocumento` | | — |
| 07 | O backend retorna stream `application/pdf` | | — |

===== RN – Regras de Negócio =====

^ Regra ^ Descrição ^
| RN01 | O formulário não pode ser submetido sem que o CAPTCHA seja confirmado pelo cidadão. |
| RN02 | Quando o campo "Número do Documento" estiver vazio no momento da submissão, o sistema exibe a mensagem: "O número do Documento deve ser informado." |
| RN03 | Quando a chave informada não puder ser descriptografada ou não corresponder a um documento existente, o sistema exibe a mensagem: "O documento não é válido ou não existe." |
| RN04 | Quando o documento existir mas não estiver liberado para visualização (não julgado), o sistema exibe a mensagem: "Este documento só poderá ser visualizado após o julgamento." |
| RN05 | O token `keyValid` possui validade de 10 minutos a partir da emissão. Após esse prazo, a requisição de PDF é bloqueada. O `keyValid` não deve ser armazenado em localStorage ou cookie. |
| RN06 | Após o cidadão clicar em "Abrir Documento PDF", o CAPTCHA deve ser resetado na tela de origem, exigindo nova confirmação para consulta subsequente. |
| RN07 | O acesso à rota `/validar-documento` sem o parâmetro `?key` exibe o formulário com o campo vazio. Não há redirecionamento externo. |
| RN08 | Quando o processo estiver marcado como em sigilo (`INDR_BLOQUEIODOC_A = 'T'`), a API retorna HTTP 403 e o sistema exibe a Tela 04 (Acesso Restrito), distinta da Tela 05 (Erro Geral). |
| RN09 | Para documentos do tipo `A`, `R` ou `H` (Acórdão, Resolução, Histórico), a liberação ocorre somente se existirem registros na consulta de decisões julgadas (`VWEB_BUSCADECISOES_DOE + VWEB_PROCJULGAMENTO WHERE JULGADO = 'JULGADO'`). Lista vazia bloqueia o documento. |
| RN10 | Para documentos do tipo `GED` (não-processual), a liberação ocorre somente se o documento existir e estiver ativo (`INDR_CANCELADO_N = 0` e `INDR_TIPOPROCESSUAL_N = 0`). |
| RN11 | Para demais tipos de andamento processual, a liberação ocorre quando `FoiJulgado = true` ou `UltimaSituacaoId = 11` no andamento correspondente ao `idDocumento` da chave. |
| RN12 | Para documentos do tipo `K1` (anexo processual), quando o andamento não for localizado diretamente, o sistema busca pelo andamento pai via `PRO_ANEXOS`. A liberação segue a mesma regra de julgamento do andamento pai. |