====== [ER_006] Requisitos - Consulta de Ofícios Web ======

**Descrição**: Funcionalidade que permite ao usuário pesquisar ofícios públicos emitidos pelo TCE-GO por diferentes critérios (número de processo, número do ofício, data, órgão de origem ou interessado), visualizar os detalhes de cada ofício retornado e navegar para o detalhamento do processo vinculado.

**Menu / Local de acesso**: Portal TCE-GO | Serviços | Consulta de Ofícios

===== Atores =====

^Nível^Perfil^Autenticação^Abrangência|
|**PÚBLICO**| Orgãos fiscalizados, Partes Processuais (Advogados e Interessados)|Não obrigatória|Consulta de ofícios públicos com data de notificação registrada e visualização de detalhes do ofício.|


===== Telas =====

==== Tela 01 - Consulta de Ofícios ====

Tela responsável por permitir a pesquisa de ofícios a partir de critérios selecionados pelo usuário.

^Elemento^Tipo^Obrigatório^Valores Possíveis^Valor Padrão^Observação|
|Tipo de Consulta|Seleção (Select)|Sim|Número do Processo; Número do Ofício; Data do Ofício; Órgão de Origem; Interessado|Número do Processo|Define o conjunto de campos exibidos para a consulta.|
|Número do Processo|Campo Texto (somente números)|Sim (quando tipo = Processo)|Numérico, máx. 18 dígitos|Vazio|Exibido apenas quando tipo = Número do Processo.|
|Número do Ofício|Campo Texto (somente números)|Sim (quando tipo = Número do Ofício)|Numérico, máx. 18 dígitos|Vazio|Exibido junto com o campo Ano do Ofício.|
|Ano do Ofício|Campo Data (yyyy)|Sim (quando tipo = Número do Ofício)|Ano, máx. 4 dígitos|Vazio|Obrigatório em conjunto com Número do Ofício.|
|Data Inicial|Campo Data (datepicker)|Sim (quando tipo = Data do Ofício)|Data válida|Vazio|Data inicial do intervalo de pesquisa.|
|Data Final|Campo Data (datepicker)|Sim (quando tipo = Data do Ofício)|Data válida|Vazio|Deve ser maior ou igual à Data Inicial (RN03).|
|Situação|Seleção (Select)|Não (quando tipo = Data do Ofício)|Situações cadastradas + "TODOS"|TODOS|Carregado dinamicamente via ''VWEB_CONSOFICIO'' (RN04). Situações restritas não aparecem (RN04).|
|Código ou Nome do Órgão|Campo Texto|Não (quando tipo = Órgão de Origem)|Texto livre|Vazio|Utilizado para pesquisar e popular o dropdown de órgãos.|
|Órgão de Origem|Seleção (Select)|Sim (quando tipo = Órgão de Origem)|Órgãos retornados pela pesquisa|Desabilitado|Habilitado somente após pesquisa com resultado (RN05).|
|CPF/CNPJ|Campo Texto com máscara|Não (quando tipo = Interessado)|CPF: XXX.XXX.XXX-XX \\ CNPJ: XX.XXX.XXX/XXXX-XX|Vazio|A máscara é aplicada automaticamente conforme o comprimento digitado. CPF ou Nome é obrigatório (ao menos um). O CPF/CNPJ informado deve ser válido (RN06).|
|Nome do Interessado|Campo Texto|Não (quando tipo = Interessado)|Texto livre|Vazio|O usuário informa Nome **ou** CPF/CNPJ. Ao menos um dos dois campos deve ser preenchido.|
|Código de Segurança (Captcha)|Componente de Segurança|Sim|–|Vazio|Obrigatório para execução da consulta (RN01). Pode ser atualizado pelo usuário.|
|Botão "Consulta"|Botão|Sim|–|–|Executa a consulta conforme o tipo selecionado.|

==== Tela 02 - Resultado da Consulta de Ofícios ====

Tela responsável por exibir os ofícios retornados pela consulta, com suporte a paginação e filtro por coluna.

^Elemento^Tipo^Obrigatório^Valores Possíveis^Valor Padrão^Observação|
|Processo|Link|Sim|Número do processo formatado|–|Link clicável que abre o **[[pres:gerti:gestao_de_ativos:portal:er_002#fluxo_02_-_visualizar_detalhamento_do_processo|ER_002: Fluxo 02 –  Visualizar Detalhamento do Processo ]]** em nova aba (RN08).|
|Órgão de Origem|Texto|Sim|Nome do órgão|–|Campo ''SetorOrigemProcesso''.|
|Situação|Texto|Sim|Situação do ofício|–|Campo ''Situacao''.|
|Número do Ofício|Numérico|Sim|Número do ofício|–|Campo ''NumeroOficio''.|
|Ano Ofício|Numérico|Sim|Ano|–|Campo ''AnoOficio''.|
|Data|Data (dd/MM/yyyy)|Sim|Data válida|–|Campo ''DataOficio''.|
|Botão "Detalhar"|Botão / Ação|Sim|–|–|Abre a Tela 03 com os detalhes do ofício selecionado.|
|Paginação|Componente de Paginação|–|20 / 30 / 50 registros por página|20 registros por página|Exibido quando houver mais registros que o limite da página (RN07).|

==== Tela 03 - Detalhamento do Ofício ====

Tela responsável por exibir as informações complementares do ofício selecionado na Tela 02.

^Elemento^Tipo^Obrigatório^Valores Possíveis^Valor Padrão^Observação|
|Interessado|Texto|Não|Nome do interessado|–|Campo ''NomeInteressado''.|
|CPF/CNPJ|Texto|Não|CPF ou CNPJ formatado|–|Campo ''CpfInteressado''.|
|Nome Notificado|Texto|Não|Nome da pessoa notificada|–|Campo ''NomeNotificado''.|
|Data de Notificação|Data (dd/MM/yyyy)|Não|Data válida|–|Campo ''DataNotificacao''.|
|Dias de Prazo|Numérico|Não|Número inteiro|–|Campo ''NumeroDiasPazo''.|
|Data de Vencimento do Prazo|Data (dd/MM/yyyy)|Não|Data válida|–|Campo ''DataVencimentoPrazo''.|

===== Fluxos =====

==== Fluxo 01 - Executar Consulta de Ofícios (Fluxo Principal) ====

^Passo^Ação^Regra^Tela|
|01|O usuário acessa a funcionalidade "Consulta de Ofícios".| |Tela 01|
|02|O sistema gera e exibe o Captcha de segurança.|RN01|Tela 01|
|03|O usuário seleciona o tipo de consulta desejado.| |Tela 01|
|03.1|Caso o tipo selecionado seja "Data do Ofício", o sistema executa o **[[#fluxo_09_-_carregar_situacoes_do_oficio|Fluxo 09]]** para popular o dropdown de Situação.| | |
|03.2|Caso o tipo selecionado seja "Órgão de Origem", o usuário deve acionar o **[[#fluxo_10_-_pesquisar_orgao_de_origem|Fluxo 10]]** para selecionar o órgão antes de consultar.| | |
|04|O usuário preenche os campos do tipo selecionado e informa o Código de Segurança (Captcha) e aciona a ação "Consulta".|RN01|Tela 01|
|05|O sistema valida o Captcha informado.|RN01| |
|06.1|Caso o Captcha esteja vazio, o sistema apresenta a mensagem: "O valor do Captcha deve ser informado." e interrompe a execução.|RN01| |
|06.2|Caso o Captcha não confira com o valor da sessão, o sistema apresenta a mensagem: "O código de segurança não confere." e interrompe a execução.|RN01| |
|07|O sistema valida os parâmetros e o tipo de consulta informado e direciona a execução para o fluxo correspondente ao tipo selecionado:| | |
|07.1|Tipo "Número do Processo" → o sistema executa o **[[#fluxo_02_-_consulta_por_numero_de_processo|Fluxo 02]]**.| | |
|07.2|Tipo "Número do Ofício" → o sistema executa o **[[#fluxo_03_-_consulta_por_numero_do_oficio|Fluxo 03]]**.| | |
|07.3|Tipo "Data do Ofício" → o sistema executa o **[[#fluxo_04_-_consulta_por_data_do_oficio|Fluxo 04]]**.| | |
|07.4|Tipo "Órgão de Origem" → o sistema executa o **[[#fluxo_05_-_consulta_por_orgao_de_origem|Fluxo 05]]**.| | |
|07.5|Tipo "Interessado" → o sistema executa o **[[#fluxo_06_-_consulta_por_interessado|Fluxo 06]]**.| | |
|08|O sistema exibe os resultados no grid da Tela 02.|RN07|Tela 02|
|08.1|Caso a consulta não retorne registros, o sistema executa o **[[#fluxo_07_-_sem_resultados|Fluxo 07]]**.| | |
|09|O usuário pode acionar o botão "Detalhar" em um ofício para visualizar as informações complementares.| |Tela 02|
|09.1|O sistema executa o **[[#fluxo_08_-_detalhar_oficio|Fluxo 08]]**.| | |

==== Fluxo 02 - Consulta por Número de Processo ====

^Passo^Ação^Regra^Tela|
|01|O sistema verifica se o campo Número do Processo foi informado.| | |
|01.1|Caso não informado, o sistema apresenta a mensagem: "Número do processo deve ser informado." e interrompe a execução.| | |
|02|O sistema consulta na base de dados todos os ofícios vinculados ao número do processo informado.|RN02| |
|03|O sistema aplica o filtro de ofícios com Data de Notificação preenchida.|RN02| |
|04|O sistema ordena os resultados pela Data do Ofício em ordem decrescente (mais atual) e retorna a lista.| | |

==== Fluxo 03 - Consulta por Número do Ofício ====

^Passo^Ação^Regra^Tela|
|01|O sistema verifica se os campos Número do Ofício e Ano do Ofício foram informados.| | |
|01.1|Caso Número do Ofício não seja informado, o sistema apresenta a mensagem: "Número do Ofício deve ser informado." e interrompe a execução.| | |
|01.2|Caso Ano do Ofício não seja informado, o sistema apresenta a mensagem: "Ano do Ofício deve ser informado." e interrompe a execução.| | |
|02|O sistema consulta na base de dados os ofícios correspondentes ao número e ano informados.|RN02| |
|03|O sistema aplica o filtro de ofícios com Data de Notificação preenchida.|RN02| |
|04|O sistema ordena os resultados pela Data do Ofício em ordem decrescente (mais atual) e retorna a lista.| | |

==== Fluxo 04 - Consulta por Data do Ofício ====

^Passo^Ação^Regra^Tela|
|01|O sistema verifica se os campos Data Inicial e Data Final foram informados.| | |
|01.1|Caso Data Inicial não seja informada, o sistema apresenta a mensagem: "Data inicial deve ser informada." e interrompe a execução.| | |
|01.2|Caso Data Final não seja informada, o sistema apresenta a mensagem: "Data final deve ser informada." e interrompe a execução.| | |
|02|O sistema verifica se a Data Inicial é menor ou igual à Data Final.|RN03| |
|02.1|Caso a Data Inicial seja maior que a Data Final, o sistema apresenta a mensagem: "Data final deve ser maior que a data inicial." e interrompe a execução.|RN03| |
|03|O sistema verifica o valor do campo Situação.|RN04| |
|03.1|Caso Situação seja "TODOS", o sistema consulta todos os ofícios no intervalo de datas sem filtro de situação.|RN04| |
|03.2|Caso uma situação específica esteja selecionada, o sistema consulta os ofícios no intervalo de datas filtrando pelo identificador da situação (''DescritorQuantificadorId'').|RN04| |
|04|O sistema aplica o filtro de ofícios com Data de Notificação preenchida.|RN02| |
|05|O sistema ordena os resultados ppela Data do Ofício em ordem decrescente (mais atual) e retorna a lista.| | |

==== Fluxo 05 - Consulta por Órgão de Origem ====

^Passo^Ação^Regra^Tela|
|01|O sistema verifica se um órgão foi selecionado no dropdown.|RN05| |
|01.1|Caso nenhum órgão tenha sido selecionado, o sistema apresenta a mensagem: "Selecione um órgão para consultar." e interrompe a execução.|RN05| |
|02|O sistema consulta na base de dados os ofícios cujo campo ''SetorOrigemProcesso'' contenha o nome do órgão selecionado (busca parcial, insensível a maiúsculas/minúsculas).|RN05| |
|03|O sistema aplica o filtro de ofícios com Data de Notificação preenchida.|RN02| |
|04|O sistema ordena os resultados pela Data do Ofício em ordem decrescente (mais atual) e retorna a lista.| | |

==== Fluxo 06 - Consulta por Interessado ====

^Passo^Ação^Regra^Tela|
|01|O sistema verifica se ao menos um dos campos (CPF/CNPJ ou Nome do Interessado) foi informado.| | |
|01.1|Caso ambos os campos estejam vazios, o sistema apresenta a mensagem: "Informe o CPF ou CNPJ do interessado." e interrompe a execução.| | |
|02|Caso o campo CPF/CNPJ esteja preenchido, o sistema valida o documento informado.|RN06| |
|02.1|Caso o CPF/CNPJ seja inválido, o sistema apresenta a mensagem correspondente e interrompe a execução.|RN06| |
|03|O sistema determina o filtro de consulta conforme o campo preenchido pelo usuário:| | |
|03.1|Somente CPF/CNPJ informado: filtra por CpfInteressado (correspondência exata).| | |
|03.2|Somente Nome informado: filtra por NomeInteressado (contém, insensível a maiúsculas/minúsculas).| | |
|04|O sistema aplica o filtro de ofícios com Data de Notificação preenchida.|RN02| |
|05|O sistema ordena os resultados pela Data do Ofício em ordem decrescente (mais atual) e retorna a lista.| | |

==== Fluxo 07 - Sem Resultados ====

^Passo^Ação^Regra^Tela|
|01|O sistema não localiza ofícios para o critério informado.|RN02|Tela 02|
|02|O sistema exibe o grid com a mensagem: "Sem Resultados".| |Tela 02|
|03|O sistema permanece na tela permitindo nova tentativa.| |Tela 01|

==== Fluxo 08 - Detalhar Ofício ====

^Passo^Ação^Regra^Tela|
|01|O usuário aciona o botão "Detalhar" em um registro do grid.| |Tela 02|
|02|O sistema recupera as informações complementares do ofício selecionado.| | |
|03|O sistema exibe a Tela 03 com os dados do ofício: Interessado, CPF/CNPJ, Nome Notificado, Data de Notificação, Dias de Prazo e Data de Vencimento do Prazo.| |Tela 03|

==== Fluxo 09 - Carregar Situações do Ofício ====

^Passo^Ação^Regra^Tela|
|01|O sistema detecta a seleção do tipo "Data do Ofício" e consulta as situações disponíveis.|RN04|Tela 01|
|02|O sistema consulta as situações via ''GET /api/oficio/situacao'' no Catálogo de Serviços.|RN04| |
|03|O sistema suprime as situações restritas da lista (IDs 528, 536, 1647) antes de retorná-las ao usuário, caso o catálogo não faça esse filtro.|RN04| |
|04|O sistema ordena as situações restantes em ordem alfabética pela descrição e insere a opção "TODOS" como primeira entrada.| | |
|05|O sistema popula o dropdown de Situação com a lista resultante.|RN04|Tela 01|

==== Fluxo 10 - Pesquisar Órgão de Origem ====

^Passo^Ação^Regra^Tela|
|01|O usuário informa código ou nome parcial do órgão e aciona o botão de pesquisa.| |Tela 01|
|02|O sistema valida se o campo foi preenchido.| | |
|02.1|Caso o campo esteja vazio, o sistema apresenta a mensagem: "O código ou o nome do Órgão de Origem ou parte do texto deve ser informado." e interrompe a execução.| | |
|03|O sistema consulta os órgãos disponíveis via ''GET /api/orgao/{nome}'' no Catálogo de Serviços.|RN05| |
|04|Caso a pesquisa retorne resultados, o sistema habilita o dropdown de órgãos e o popula com os registros encontrados.|RN05|Tela 01|
|04.1|Caso a pesquisa não retorne resultados, o sistema mantém o dropdown desabilitado e apresenta as mensagens de validação correspondentes.|RN05| |

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

^ID^Descrição^
|RN01|**Captcha Obrigatório** – A consulta de ofícios somente poderá ser executada após a validação do Captcha de segurança. O campo Captcha é obrigatório. Mensagens de erro: "O valor do Captcha deve ser informado." (campo vazio) e "O código de segurança não confere." (valor incorreto).|
|RN02|**Filtro de Ofícios sem Data de Notificação** – O sistema exclui da exibição todos os ofícios que não possuam Data de Notificação preenchida, independentemente do tipo de consulta executado. \\ No portal novo, este filtro é aplicado internamente pelo Catálogo de Serviços (''POST /api/oficio''). Referência legada: ''TCE.Compartilhado → ServicoDeOficioWeb → RemoverOficiosSemDataDeNotificacao''.|
|RN03|**Consistência do Intervalo de Datas** – A Data Inicial deve ser menor ou igual à Data Final. Caso contrário, o sistema apresenta a mensagem: "Data final deve ser maior que a data inicial."|
|RN04|**Situações Exibidas na Consulta por Data** – A lista de situações é obtida via ''GET /api/oficio/situacao'' no Catálogo de Serviços. As seguintes situações **não devem ser exibidas** ao usuário: Id 528 (OFÍCIO EMITIDO), Id 536 (OFÍCIO NÃO ATENDIDO) e Id 1647 (OFÍCIO NÃO ENTREGUE). Caso o catálogo não aplique esse filtro, ele deve ser feito na API route do portal. \\ Quando o valor selecionado for "TODOS", a consulta envia ''idSituacaoOficio: 0'' e não aplica filtro por situação. Quando uma situação específica for selecionada, envia o ''id'' correspondente no campo ''idSituacaoOficio''.|
|RN05|**Busca e Seleção de Órgão de Origem** – A pesquisa de órgãos é realizada via ''GET /api/orgao/{nome}'' no Catálogo de Serviços (busca parcial por nome ou código). O dropdown de órgãos é inicializado desabilitado e habilitado somente quando a pesquisa retorna ao menos um resultado. A seleção de um órgão é obrigatória para execução da consulta. Referência legada: ''TCE.Compartilhado → IServicoDeSetorGeralWeb → ConsulteOrgaosWeb''.|
|RN06|**Validação de CPF e CNPJ** – O CPF/CNPJ informado deve ser válido. A máscara é aplicada automaticamente conforme o comprimento digitado (CPF: XXX.XXX.XXX-XX / CNPJ: XX.XXX.XXX/XXXX-XX). A validação ocorre conforme o comprimento: \\ – Até 11 dígitos: aplica validação de CPF → mensagem de erro: "CPF informado é inválido." \\ – Acima de 11 dígitos: aplica validação de CNPJ → mensagem de erro: "CNPJ informado é inválido." \\ A validação é executada em: ''TCE.WebSites → OficioController → ValidaCpfOuCnpj''.|
|RN07|**Paginação do Grid de Resultados** – O grid de resultados é paginado com opções de 20, 30 ou 50 registros por página, sendo 20 o padrão. O grid suporta filtro por coluna. Quando não há resultados, o sistema exibe a mensagem: "Sem Resultados".|
|RN08|**Link para Consulta de Processos** – Na coluna "Processo" do grid, o número do processo é exibido como hiperlink apontando para ''/ConsultaProcesso?proc={AutuacaoId}'', abrindo em nova aba o **[[pres:gerti:gestao_de_ativos:portal:er_002#fluxo_02_-_visualizar_detalhamento_do_processo|ER_002: Fluxo 02 –  Visualizar Detalhamento do Processo ]]**.|

===== Serviços do Catálogo (já implementados) =====

Os três serviços necessários para esta funcionalidade já existem no Catálogo de Serviços TCE-GO (''https://catalogodeservicos.tce.go.gov.br'').

==== POST /api/oficio — Consulta de Ofícios ====

Endpoint unificado para todos os tipos de consulta. O campo ''tipoConsultaOficio'' determina o filtro aplicado.

**Request:**
<code json>
{
  "tipoConsultaOficio": 0,
  "numeroProcesso": 0,
  "numeroOficio": 0,
  "anoOficio": 0,
  "dataInicial": "yyyy-MM-ddTHH:mm:ss.sssZ",
  "dataFinal": "yyyy-MM-ddTHH:mm:ss.sssZ",
  "idSituacaoOficio": 0,
  "idOrgaoOrigem": "string",
  "cpfCnpjInteressado": "string",
  "nomeInteressado": "string"
}
</code>

^Valor de tipoConsultaOficio^Tipo de consulta^
|0|Número do Processo|
|1|Número do Ofício|
|2|Data do Ofício|
|3|Órgão de Origem|
|4|Interessado|

**Response:**
<code json>
[
  {
    "numeroProcesso": 0,
    "numeroOficio": 0,
    "orgao": "string",
    "situacaoOficio": "string",
    "anoOficio": 0,
    "data": "string",
    "nomeInteressado": "string",
    "cpfCnpjInteressado": "string",
    "nomeNotificado": "string",
    "dataNotificacao": "string",
    "diasPrazo": 0,
    "dataVencimentoPrazo": "string",
    "codigoPesquisaDocumento": "string"
  }
]
</code>

> **Observação:** O retorno já inclui os campos de detalhe (Tela 03), não sendo necessária uma chamada adicional para detalhar o ofício.

==== GET /api/oficio/situacao — Situações do Ofício ====

Retorna a lista de situações disponíveis para o filtro da consulta por Data do Ofício.

**Exemplo de response:**
<code json>
[
  { "id": 0, "descricao": "string" }
]
</code>

> **Atenção (RN04):** Verificar se o catálogo já suprime as situações restritas (IDs 528, 536, 1647). Caso não suprima, o filtro deve ser aplicado na API route do portal antes de retornar ao front-end.

==== GET /api/orgao/{nome} — Pesquisa de Órgãos de Origem ====

Retorna os órgãos cujo nome contenha o texto informado (busca parcial).

**Exemplo:**
<code>
GET /api/orgao/FOMENTO
</code>

**Response:**
<code json>
[
  { "nomeSetor": "AGÊNCIA DE FOMENTO DE GOIÁS S/A - GOIASFOMENTO", "id": 238 }
]
</code>