====== RF-008 – TCE-Push – Serviço de Acompanhamento de Processos por E-mail ======

Funcionalidade que permite a qualquer cidadão ou entidade receber notificações por e-mail sobre movimentações em processos autuados no Tribunal de Contas do Estado de Goiás, sem necessidade de cadastro com senha. O acesso ao serviço ocorre diretamente na página do processo, via widget inline, e o gerenciamento das inscrições é realizado por links presentes nos próprios e-mails recebidos.

**Local de acesso:**
  * Widget de inscrição: ''/processo/{id}'' (bloco abaixo do cabeçalho do processo)
  * Página de confirmação: ''/acompanhar-processo/confirmar?token={token}''
  * Página de gerenciamento: ''/acompanhar-processo/gerenciar?token={token}''
  * Página de cancelamento: ''/acompanhar-processo/cancelar?token={token}&processo={id}''

----

===== Atores =====

^ Nível ^ Perfil ^ Autenticação ^ 
| Público | Cidadão, advogado, empresa, contador ou qualquer interessado | Não requerida |

----

===== Telas =====
Bloco exibido inline na página do processo, logo abaixo do cabeçalho, permitindo ao usuário se inscrever para receber notificações por e-mail. O widget transita entre estados sem recarregar a página.

==== Tela 01 – Widget de Inscrição (/processo/{id}) ====

---
//Estado idle//\\

{{:pres:gerti:gestao_de_ativos:portal:pasted:20260706-190742.png}}

---
// Estados formulario e loading//\\
{{:pres:gerti:gestao_de_ativos:portal:pasted:20260706-191118.png}}

---
//Estado confirmacao-pendente//\\
{{:pres:gerti:gestao_de_ativos:portal:pasted:20260706-195832.png}}

---
//Estado inscrito//\\
{{:pres:gerti:gestao_de_ativos:portal:pasted:20260706-194215.png}}

^Elemento^Tipo^Obrigatório^Valores Possíveis^Valor Padrão^Observação|
|Botão "Quero acompanhar"|Botão|-|-|-|Exibido no estado //idle//. Abre o formulário de e-mail ao ser clicado.|
|Cabeçalho do formulário|Texto|-|-|"Acompanhar processo nº {numero}"|Exibido nos estados //formulario// e //loading//. O número do processo é preenchido dinamicamente.|
|E-mail|Campo texto|Sim|Formato RFC 5322|Vazio|Exibido nos estados //formulario// e //loading//. Deve conter um endereço de e-mail válido (RN01). Exibe mensagem de erro inline "Informe um e-mail válido." quando inválido.|
|Botão "Quero acompanhar" (submit)|Botão submit|-|-|-|Exibido no estado //formulario//. No estado //loading//, é substituído por spinner com texto "Enviando...". Desabilitado durante o processamento.|
|Botão "Cancelar"|Botão|-|-|-|Exibido no estado //formulario//. Retorna o widget ao estado //idle// sem enviar a solicitação. Desabilitado durante o processamento.|
|Mensagem "Verifique seu e-mail para confirmar"|Alerta informativo|-|-|-|Exibido no estado //confirmacao-pendente//. Inclui o e-mail informado na mensagem: "Enviamos uma mensagem para {email}. Clique no link para ativar o acompanhamento deste processo." (RN02 RN03)|
|Botão "Fechar" (confirmação pendente)|Botão|-|-|-|Exibido no estado //confirmacao-pendente//. Retorna ao estado //idle//.|
|Mensagem "Você já está acompanhando este processo"|Alerta de aviso|-|-|-|Exibido no estado //inscrito//. Inclui o e-mail informado na mensagem: "O e-mail {email} já está inscrito para receber notificações." Acionado quando a resposta do servidor é JA_INSCRITO (RN04).|
|Botão "Fechar" (já inscrito)|Botão|-|-|-|Exibido no estado //inscrito//. Retorna ao estado //idle//.|
|Mensagem "Não foi possível processar sua solicitação"|Alerta de erro|-|-|-|Exibido no estado //erro//. Exibe a mensagem retornada pelo servidor ou "Tente novamente em instantes." como fallback.|
|Botão "Tentar novamente"|Botão|-|-|-|Exibido no estado //erro//. Retorna ao estado //formulario// com o e-mail preservado.|

==== Tela 02 – Confirmação de Inscrição (/acompanhar-processo/confirmar) ====

Tela acessada pelo link presente no e-mail de confirmação. Valida o token recebido e exibe o resultado da operação. Não possui campos editáveis além do redirecionamento.

---
//Confirmação bem sucedida//\\
{{:pres:gerti:gestao_de_ativos:portal:pasted:20260706-195941.png}}

---
//Link expirado//\\
{{:pres:gerti:gestao_de_ativos:portal:pasted:20260706-200100.png}}

^Elemento^Tipo^Obrigatório^Valores Possíveis^Valor Padrão^Observação|
|Indicador de carregamento|Spinner|-|-|-|Exibido no estado //loading// enquanto o token é validado. Acompanha o texto "Validando seu link de confirmação…".|
|Título "Inscrição confirmada!"|Texto|-|-|-|Exibido no estado //sucesso// após validação bem-sucedida do token (RN02).|
|Mensagem de confirmação|Texto|-|-|-|Exibido no estado //sucesso//. Texto: "Você receberá notificações por e-mail sempre que o processo nº {numero} for movimentado." O número do processo é extraído do token.|
|Botão "Consultar processo"|Botão|-|-|-|Exibido no estado //sucesso//. Redireciona para ''/processos/{id}'' do processo recém-confirmado.|
|Botão "Gerenciar meus acompanhamentos"|Botão|-|-|-|Exibido no estado //sucesso//. Redireciona para ''/acompanhar-processo/gerenciar?token=...''.|
|Lista "Seus processos acompanhados"|Lista de cards|-|-|-|Exibida no estado //sucesso//. Lista os **3 processos mais recentes** vinculados ao e-mail confirmado (ordenados pela data de inclusão do acompanhamento, do mais recente para o mais antigo), incluindo o processo recém-confirmado (RN13). Para ver a lista completa, o usuário acessa "Gerenciar meus acompanhamentos".|
|Título "Link inválido ou expirado"|Texto|-|-|-|Exibido no estado //erro// quando o token é inválido ou expirou após 48h (RN02).|
|Mensagem de erro|Texto|-|-|-|Exibido no estado //erro//. Texto: "Este link de confirmação não é mais válido. Os links expiram em 48 horas após o envio. Retorne à página do processo e solicite um novo link."|
|Botão "Tentar novamente"|Botão|-|-|-|Exibido no estado //erro//. Redireciona para ''/processos''.|

==== Tela 03 – Gerenciamento de Acompanhamentos (/acompanhar-processo/gerenciar) ====

Tela acessada pelo link presente nos e-mails de notificação. Exibe a lista de processos acompanhados pelo e-mail associado ao token e permite o cancelamento individual de acompanhamentos. Em caso de token expirado, exibe formulário para reenvio do link.

^Elemento^Tipo^Obrigatório^Valores Possíveis^Valor Padrão^Observação|
|Indicador de carregamento|Spinner|-|-|-|Exibido no estado //loading// enquanto o token é validado e a lista é carregada. Acompanha o texto "Carregando seus acompanhamentos…".|
|Identificação do e-mail|Texto|-|-|-|Exibido no estado //lista//. Texto: "Processos acompanhados pelo e-mail: {email mascarado}". O e-mail é parcialmente ocultado pelo servidor.|
|Card de processo|Card|-|-|-|Exibido no estado //lista// para cada processo acompanhado. Contém: número do processo (link clicável para ''/processos/{id}''), interessado, assunto e ano.|
|Botão "Parar de acompanhar"|Botão|-|-|-|Exibido em cada card no estado //lista//. Abre a confirmação inline no próprio card (RN11).|
|Confirmação inline de remoção|Expansão inline|-|-|Recolhido|Exibida no card após clique em "Parar de acompanhar". Exibe o alerta "Deseja parar de acompanhar este processo?" com os botões "Confirmar" e "Cancelar" (RN11).|
|Botão "Confirmar" (remoção)|Botão destrutivo|-|-|-|Executa a remoção do processo. Exibe spinner no item durante o processamento. Remove o card da lista ao concluir, sem recarregar a página (RN11).|
|Botão "Cancelar" (remoção)|Botão|-|-|-|Fecha a confirmação inline sem executar nenhuma ação (RN11).|
|Mensagem de lista vazia|Texto|-|-|-|Exibida quando todos os processos são removidos ou quando o e-mail não possui acompanhamentos ativos. Texto: "Você não está acompanhando nenhum processo no momento." Acompanha link "Consultar processos no portal" → ''/processos''.|
|Paginação|Componente de paginação|-|-|-|Exibida no estado //lista// somente quando a quantidade de processos acompanhados ultrapassa **12 itens**. Reaproveita o componente ''Pagination'' já usado em ''/processos'' (mesmo padrão visual). Necessária porque não há limite máximo de processos por e-mail (RN10, RN14).|
|Título "Link expirado"|Texto|-|-|-|Exibido no estado //token-expirado// quando o token é inválido (RN02).|
|E-mail (reenvio de link)|Campo texto|Sim|Formato RFC 5322|Vazio|Exibido no estado //token-expirado//. Utilizado para solicitar novo link de gerenciamento (RN08).|
|Botão "Receber novo link"|Botão submit|-|-|-|Exibido no estado //token-expirado//. Envia a solicitação de reenvio. Após o envio, exibe a mensagem: "Se este endereço possui acompanhamentos ativos, você receberá o link de acesso em breve." (RN08)|

==== Tela 04 - Cancelamento de Acompanhamento (/acompanhar-processo/cancelar) ====

Tela acessada pelo link "Parar de receber este acompanhamento" presente nos e-mails de notificação. Executa o cancelamento imediato do processo referenciado no token e exibe o resultado da operação. Não possui campos editáveis.

---
//Cancelamnto bem sucedido//\\
{{:pres:gerti:gestao_de_ativos:portal:pasted:20260706-205654.png}}

---
//Link expirado ou já utilizado//\\
{{:pres:gerti:gestao_de_ativos:portal:pasted:20260706-205738.png}}

^Elemento^Tipo^Obrigatório^Valores Possíveis^Valor Padrão^Observação|
|Indicador de carregamento|Spinner|-|-|-|Exibido no estado //loading// enquanto o token é validado e o cancelamento é processado. Acompanha o texto "Processando cancelamento…".|
|Título "Acompanhamento cancelado"|Texto|-|-|-|Exibido no estado //sucesso// após remoção bem-sucedida (RN06).|
|Mensagem de cancelamento|Texto|-|-|-|Exibido no estado //sucesso//. Texto: "Você não receberá mais notificações sobre o processo nº {numero}." O número do processo é extraído do token.|
|Botão "Ver todos os meus acompanhamentos"|Botão|-|-|-|Exibido no estado //sucesso//. Redireciona para ''/acompanhar-processo/gerenciar?token=...'' (RN07).|
|Botão "Consultar processos"|Botão|-|-|-|Exibido no estado //sucesso//. Redireciona para ''/processos''.|
|Título "Link inválido"|Texto|-|-|-|Exibido no estado //erro// quando o token é inválido ou já foi utilizado.|
|Mensagem de erro|Texto|-|-|-|Exibido no estado //erro//. Texto: "Este link de cancelamento não é mais válido ou já foi utilizado. Acesse seu painel para gerenciar os acompanhamentos."|
|Botão "Acessar painel de acompanhamentos"|Botão|-|-|-|Exibido no estado //erro//. Redireciona para ''/acompanhar-processo/gerenciar?token=...''.|

----

===== E-mails Enviados =====

Todos os e-mails seguem o padrão visual institucional do TCE-GO, são remetidos pelo endereço **`push@tce.go.gov.br`** e despachados pelo servidor **`smtp.tce.go.gov.br`**, reaproveitando a camada de serviço compartilhada `IServicoDeEmail`/`ServicoDeEmail` (`TCE.Compartilhado.Servico.Servicos.Contato`), a mesma já utilizada por `ServicoDeUsuarioPush` no legado. O RF-008 não deve implementar um novo mecanismo de envio — apenas montar `DtoEmail` (remetente, destinatário, assunto, corpo HTML) e chamar essa camada compartilhada, como já ocorre em `ServicoDeUsuarioPush.EnviaEmail`. Nenhuma ação dos e-mails depende de login — cada link carrega o token correspondente (RN02, RN09) e o ID de autuação do processo, quando aplicável.

==== E-mail 01 – Confirmação de Inscrição ====
{{:pres:gerti:gestao_de_ativos:portal:confirme_-_tce_go_push.png?direct&600|}} \\

Disparado ao final do Fluxo 01 (passo 07.1), sempre que uma inscrição em um processo aguarda confirmação — inclusive para e-mails que já confirmaram outros processos anteriormente (RN03).

^Elemento^Conteúdo^Observação|
|Remetente|`push@tce.go.gov.br`|Endereço institucional único para os três e-mails do RF-008.|
|Assunto|"Serviço de acompanhamento de processos TCE-GO — Confirme o acompanhamento do processo Nº {numero}"|O número do processo é usado apenas para exibição; a comunicação interna do link usa o ID de autuação.|
|Corpo|"Você solicitou o acompanhamento do processo Nº {numero} no Serviço de acompanhamento de processos TCE-GO. Clique no link abaixo para confirmar este acompanhamento."|Não há saudação por nome nem qualquer referência a cadastro/senha — o usuário não preenche esses dados (RN12).|
|Botão "Confirmar acompanhamento"|Redireciona para ''/acompanhar-processo/confirmar?token={token}''|Aciona o **Fluxo 02**. Token de confirmação, uso único, validade de 48h (RN02).|
|Rodapé|"Se você não solicitou este acompanhamento, ignore este e-mail."|Nenhum vínculo é criado até o clique de confirmação — mitigação de abuso (RN03).|

==== E-mail 02 – Notificação de Movimentação ====
{{:pres:gerti:gestao_de_ativos:portal:movimentacao_-_tce_go_push-_localhost_.png?direct&600|}} \\

Disparado pelo backend sempre que houver uma movimentação em um processo já confirmado (evento externo ao protótipo, originado de job/scheduler que monitora `PRO_AUTUACAO`).

^Elemento^Conteúdo^Observação|
|Remetente|`push@tce.go.gov.br`|Endereço institucional único para os três e-mails do RF-008.|
|Assunto|"Serviço de acompanhamento de processos TCE-GO — Movimentação no processo Nº {numero}"| |
|Corpo|Número do processo, descrição da movimentação e data|Dados somente para leitura; não há ação além dos links abaixo.|
|Link "Ver processo completo"|Redireciona para ''/processos/{id}''|Consulta pública do processo, sem necessidade de token.|
|Link "Gerenciar meus acompanhamentos"|Redireciona para ''/acompanhar-processo/gerenciar?token={token}''|Aciona o **Fluxo 03**. Token de gerenciamento, uso múltiplo dentro da validade (RN09).|
|Link "Parar de acompanhar este processo"|Redireciona para ''/acompanhar-processo/cancelar?token={token}&processo={id}''|Aciona o **Fluxo 04**. Remove apenas o processo referenciado neste link — não afeta os demais acompanhamentos do e-mail (RN07).|

==== E-mail 03 – Reenvio de Link de Gerenciamento ====
{{:pres:gerti:gestao_de_ativos:portal:gerenciar_-_tce_go_push-_localhost_.png?direct&600|}}\\

Disparado ao final do Fluxo 05, **somente** quando o e-mail informado possui acompanhamentos ativos na base — o backend nunca confirma nem nega essa condição na resposta exibida ao usuário (RN08). O envio (ou não) deste e-mail é a única diferença observável entre "e-mail existe" e "e-mail não existe".

^Elemento^Conteúdo^Observação|
|Remetente|`push@tce.go.gov.br`|Endereço institucional único para os três e-mails do RF-008.|
|Assunto|"Serviço de acompanhamento de processos TCE-GO — Seu link de gerenciamento"| |
|Corpo|Link de acesso ao painel de gerenciamento|O reenvio não invalida tokens de gerenciamento já emitidos e ainda válidos (RN09) — pode haver mais de um link de gerenciamento válido simultaneamente para o mesmo e-mail.|
|Link "Gerenciar meus acompanhamentos"|Redireciona para ''/acompanhar-processo/gerenciar?token={token}''|Aciona o **Fluxo 03**.|

----

===== Fluxos =====

==== Fluxo 01 – Inscrição no Acompanhamento ====

^Passo^Ação^Regra^Tela|
|01|Usuário acessa a página de um processo autuado em ''/processos/{id}''| |Tela 01|
|02|O sistema exibe o widget TCE-Push no estado idle com o botão "Quero acompanhar"| |Tela 01|
|03|Usuário clica em "Quero acompanhar"| |Tela 01|
|04|O sistema exibe o formulário com o campo "Seu e-mail" e o cabeçalho "Acompanhar processo nº {numero}"| |Tela 01|
|05|Usuário informa o e-mail e clica em "Quero acompanhar"|RN01|Tela 01|
|05.1|E-mail inválido: o sistema exibe mensagem de erro inline "Informe um e-mail válido." e aguarda nova entrada|RN01|Tela 01|
|06|O sistema transiciona o widget para o estado loading e processa a solicitação| |Tela 01|
|07|O sistema valida que o e-mail não está inscrito neste processo|RN03 RN04| |
|07.1|O sistema envia o e-mail de confirmação com token de validade de 48h. A confirmação é obrigatória para qualquer inscrição, independentemente de histórico anterior do e-mail|RN02 RN03|E-mail 01|
|07.2|O sistema exibe o estado confirmacao-pendente: "Verifique seu e-mail para confirmar"|RN02 RN03|Tela 01|
|08|O sistema identifica que o e-mail já está inscrito para este processo|RN04| |
|08.1|O sistema exibe o estado inscrito: "Você já está acompanhando este processo" com o e-mail informado|RN04|Tela 01|
|10|O sistema identifica que o número do processo não existe|RN05| |
|10.1|O sistema exibe o estado erro com a mensagem retornada pelo servidor|RN05|Tela 01|

==== Fluxo 02 – Confirmação de Inscrição ====

^Passo^Ação^Regra^Tela|
|01|Usuário recebe o e-mail de confirmação com o assunto "Serviço de acompanhamento de processos TCE-GO — Confirme o acompanhamento do processo Nº {numero_processo}"| |E-mail 01|
|02|Usuário clica no link "Confirmar acompanhamento" contido no e-mail| | |
|03|O sistema redireciona para ''/acompanhar-processo/confirmar?token={token}''| |Tela 02|
|04|O sistema exibe o estado loading: "Validando seu link de confirmação…" e processa o token|RN02|Tela 02|
|05|Token válido e não expirado|RN02| |
|05.1|O sistema vincula o processo ao e-mail|RN02| |
|05.2|O sistema exibe o estado sucesso: "Inscrição confirmada!" com o número do processo|RN02|Tela 02|
|05.3|O sistema exibe os 3 processos mais recentes acompanhados pelo e-mail|RN13|Tela 02|
|06|Token inválido ou expirado|RN02| |
|06.1|O sistema exibe o estado erro: "Link inválido ou expirado" com botão "Tentar novamente"|RN02|Tela 02|
|06.2|Usuário clica em "Tentar novamente": o sistema redireciona para ''/processos''| |Tela 02|

==== Fluxo 03 – Gerenciamento de Acompanhamentos ====

^Passo^Ação^Regra^Tela|
|01|Usuário recebe o e-mail de notificação de movimentação com link "Gerenciar meus acompanhamentos"| |E-mail 02|
|02|Usuário clica no link| | |
|03|O sistema redireciona para ''/acompanhar-processo/gerenciar?token={token}''| |Tela 03|
|04|O sistema exibe o estado loading: "Carregando seus acompanhamentos…" e valida o token|RN09|Tela 03|
|05|Token válido|RN09| |
|05.1|O sistema exibe a primeira página da lista de processos acompanhados pelo e-mail associado ao token, com o e-mail mascarado|RN09|Tela 03|
|05.2|Lista vazia: o sistema exibe o empty state "Você não está acompanhando nenhum processo no momento."| |Tela 03|
|05.3|Lista com mais de 12 processos: o sistema exibe o componente de paginação; usuário navega entre páginas sem recarregar a tela|RN14|Tela 03|
|06|Usuário clica em "Parar de acompanhar" em um processo|RN11| |
|06.1|O sistema exibe, inline no card, o alerta "Deseja parar de acompanhar este processo?" com os botões "Confirmar" e "Cancelar"|RN11|Tela 03|
|06.2|Usuário clica em "Cancelar": o sistema fecha a confirmação sem executar nenhuma ação|RN11| |
|06.3|Usuário clica em "Confirmar": o sistema exibe spinner no item e executa a remoção|RN11|Tela 03|
|06.4|O sistema remove o processo da lista sem recarregar a página e oculta o spinner| |Tela 03|
|06.5|Lista esvaziada: o sistema exibe o empty state automaticamente| |Tela 03|
|07|Token inválido ou expirado|RN02| |
|07.1|O sistema exibe o estado token-expirado: "Link expirado" com o formulário de reenvio|RN02|Tela 03|
|07.2|Executa o **[[#fluxo_05_reenvio_de_link_de_gerenciamento|Fluxo 05]]**| | |

==== Fluxo 04 – Cancelamento via Link de E-mail ====

^Passo^Ação^Regra^Tela|
|01|Usuário recebe o e-mail de notificação com link "Parar de receber este acompanhamento"| |E-mail 02|
|02|Usuário clica no link| | |
|03|O sistema redireciona para ''/acompanhar-processo/cancelar?token={token}&processo={id}''| |Tela 04|
|04|O sistema exibe o estado loading: "Processando cancelamento…" e valida o token|RN06|Tela 04|
|05|Token válido|RN06| |
|05.1|O sistema remove imediatamente o processo da lista de acompanhamentos do e-mail|RN06| |
|05.2|O sistema exibe o estado sucesso: "Acompanhamento cancelado" com o número do processo|RN06|Tela 04|
|05.3|O sistema exibe o link "Ver todos os meus acompanhamentos" → ''/acompanhar-processo/gerenciar?token=...''|RN07|Tela 04|
|06|Token inválido| | |
|06.1|O sistema exibe o estado erro: "Link inválido" com botão "Acessar painel de acompanhamentos"| |Tela 04|

==== Fluxo 05 – Reenvio de Link de Gerenciamento ====

^Passo^Ação^Regra^Tela|
|01|Usuário informa o e-mail no formulário da Tela 03 (estado token-expirado)|RN08|Tela 03|
|02|Usuário clica em "Receber novo link"| |Tela 03|
|03|O sistema processa a solicitação|RN08| |
|03.1|Se o e-mail possuir acompanhamentos ativos, o sistema despacha o e-mail de reenvio com o link de gerenciamento (passo interno, não observável pelo usuário)|RN08 RN09|E-mail 03|
|04|O sistema exibe a mensagem: "Se este endereço possui acompanhamentos ativos, você receberá o link de acesso em breve."|RN08|Tela 03|
|04.1|Nota: o sistema não confirma nem nega a existência do e-mail na base de dados, independentemente do resultado interno|RN08| |

----

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

^ Regra ^ Descrição ^
|RN01|**Validação de formato de e-mail** – O e-mail informado deve ser válido conforme o formato RFC 5322. E-mails inválidos bloqueiam o envio do formulário com mensagem de erro inline.|
|RN02|**Expiração de token** – O token de confirmação de inscrição expira em 48 horas a partir do envio. Após a expiração, o sistema exibe a mensagem de link inválido e o usuário deve solicitar novo acompanhamento.|
|RN03|**Confirmação obrigatória por inscrição (controle de abuso)** – Toda inscrição em um processo requer confirmação explícita por e-mail, independentemente de o endereço ter sido confirmado em processos anteriores. Como o serviço não possui autenticação, a confirmação por link é o único mecanismo que garante que apenas o titular do endereço pode ativar um vínculo processo/e-mail. Sem essa exigência, qualquer usuário poderia inscrever endereços de terceiros em processos arbitrários sem o consentimento do titular.|
|RN04|**Vedação de inscrição duplicada** – O mesmo e-mail não pode ser inscrito duas vezes no mesmo processo. O sistema retorna a resposta JA_INSCRITO e exibe a mensagem: "Você já está acompanhando este processo".|
|RN05|**Existência do processo** – O número de processo informado deve existir no sistema antes de aceitar a inscrição. Processos inexistentes bloqueiam o cadastro com mensagem de erro.|
|RN06|**Cancelamento imediato via link** – O cancelamento acionado pelo link do e-mail é executado imediatamente após a validação do token, sem etapa de confirmação adicional. O processo é removido no mesmo request.|
|RN07|**Escopo do cancelamento por link** – O link "Parar de receber este acompanhamento" presente nos e-mails remove apenas o processo referenciado naquele link. O link "Gerenciar meus acompanhamentos" dá acesso à lista completa.|
|RN08|**Resposta neutra no reenvio de link** – Ao solicitar reenvio do link de gerenciamento, o sistema sempre retorna a mensagem: "Se este endereço possui acompanhamentos ativos, você receberá o link de acesso em breve.", independentemente de o e-mail existir ou não na base de dados.|
|RN09|**Token de gerenciamento de uso múltiplo** – O token enviado no link de gerenciamento pode ser utilizado múltiplas vezes enquanto estiver dentro do prazo de validade, ao contrário do token de confirmação de inscrição.|
|RN10|**Sem limite de processos por e-mail** – Não há limite máximo de processos que podem ser associados a um único e-mail.|
|RN11|**Confirmação antes de remover na tela de gerenciamento** – Na página de gerenciamento, ao clicar em "Parar de acompanhar", o sistema exibe uma confirmação inline no card do processo com os botões "Confirmar" e "Cancelar". A remoção só é executada após o usuário clicar em "Confirmar".|
|RN12|**Cadastro implícito de usuário (sem tela de cadastro)** – Não existe formulário de nome/senha para o usuário. Internamente, porém, o backend deve localizar ou criar um registro de usuário Push a partir do e-mail informado (reaproveitando a estrutura de dados existente do legado), preenchendo os campos obrigatórios do legado (nome e senha) com valores técnicos não expostos ao usuário. Essa criação/localização de registro é transparente e não pode alterar nome, senha ou o estado "Habilitado" de um cadastro que já exista para aquele e-mail (ver [[#reaproveitamento_de_estruturas_do_legado|Reaproveitamento de Estruturas do Legado]]).|
|RN13|**Lista resumida na tela de confirmação** – Na tela de confirmação de inscrição (Tela 02), a lista "Seus processos acompanhados" exibe apenas os **3 processos mais recentes** vinculados ao e-mail, ordenados pela data de inclusão do acompanhamento (mais recente primeiro), incluindo o processo recém-confirmado. Não há paginação nesta tela — para consultar a lista completa, o usuário deve acessar "Gerenciar meus acompanhamentos" (Tela 03).|
|RN14|**Paginação na tela de gerenciamento** – Como não há limite máximo de processos por e-mail (RN10), a lista de acompanhamentos da Tela 03 é paginada em **12 processos por página**, exibindo o componente de paginação somente quando esse total é ultrapassado. Reaproveita o componente ''Pagination'' já utilizado em ''/processos'' (mesmo padrão visual e de navegação).|

----

===== Reaproveitamento de Estruturas do Legado =====

Esta seção documenta, para o time de backend, quais estruturas do sistema legado (banco de dados, rotinas armazenadas e API) devem ser **reaproveitadas** na implementação do RF-008 modernizado, e quais precisam ser **substituídas ou criadas**. A diretriz central é: **o novo modelo não expõe cadastro de usuário ao público, mas continua persistindo um registro de usuário "por baixo dos panos"**, reutilizando a tabela e as rotinas já existentes, de modo a não quebrar os vínculos de quem já se cadastrou pelo fluxo antigo (Portal legado `/Push`).

==== Tabelas de Banco de Dados (Oracle) ====

^ Tabela ^ Papel no legado ^ Reaproveitamento no novo modelo ^
|`TCE_GO.PSH_USUARIOS`|Cadastro do usuário do serviço Push (nome, e-mail, senha, dados de contato, flag `Habilitado`)|**Reaproveitada como cadastro implícito.** Ao inscrever um e-mail em um processo (RN03), o backend deve verificar se já existe uma linha com aquele e-mail; se não existir, criar uma nova (cadastro invisível ao usuário); se já existir, **reutilizar o registro sem sobrescrever dados preexistentes** (RN12).|
|`PRO_ACOMPANHAPROCESSO`|Tabela de associação entre `PSH_USUARIOS` (`PSHUSUA_ID`) e `PRO_AUTUACAO` (`PROAUTU_ID`) — representa "quais processos este usuário acompanha"|**Reaproveitada integralmente.** É exatamente a estrutura que already sustenta a lista exibida nas telas de Confirmação e Gerenciamento (RF-008). Não requer alteração de schema.|
|`PRO_AUTUACAO`|Tabela de processos autuados|**Reaproveitada apenas para leitura** (validação de existência do processo — RN05 — e composição dos dados exibidos: número, interessado, assunto, ano).|

==== Mapeamento de Campos — `PSH_USUARIOS` ====

^ Coluna (Oracle) ^ Campo na entidade (`UsuarioPush`) ^ Uso no legado ^ Uso no RF-008 (novo modelo) ^
|`PSHUSUA_ID`|`Id`|Chave primária, gerada pelo banco|Mantido — é o identificador interno vinculado ao token emitido por e-mail.|
|`DESC_EMAIL_A`|`Email`|Identificação do usuário, único por cadastro|Mantido como chave de busca/upsert. É o único dado realmente fornecido pelo cidadão.|
|`DESC_NOME_A`|`Nome`|Obrigatório (`NOT NULL`), informado no formulário de cadastro|**Não coletado do usuário.** Como a coluna é obrigatória no legado, o backend deve gerar um valor técnico (ex.: o próprio e-mail, ou literal "Usuário Push") apenas para satisfazer a constraint — nunca exibido nem solicitado nas telas do RF-008.|
|`DESC_SENHA_A`|`Senha`|Obrigatório (`NOT NULL`), armazenado e comparado em **texto puro** no `Logar` (S1/S3 do relatório técnico)|**Não coletado nem utilizado.** O backend deve gerar um valor aleatório apenas para satisfazer a constraint. O endpoint `api/push/login` e qualquer comparação de senha **não fazem parte do novo fluxo** — a autenticação passa a ser 100% por token de e-mail (contrato da seção 7 do PRD).|
|`HABILITADO_N`|`Habilitado`|No legado, fica em `0` até o usuário clicar no link de ativação de conta (cadastro geral); operações de acompanhamento verificam esse flag e bloqueiam quem não ativou|**Ressignificado.** No RF-008 não existe "ativação de conta" separada — a confirmação é por processo (RN03). O backend deve tratar o e-mail como habilitado assim que a primeira inscrição for confirmada, para não herdar a mensagem legada "ative sua conta" (ver `ServicoDeUsuarioPush.AcompanharProcesso`, retorno `"0"` com `Habilitado == 0`).|
|`NUMR_CPF_A`, `DESC_ENDERECO_A`, `NUMR_CEP_A`, `NUMR_FONE_A`, `INDR_SEXO_A`|`Cpf`, `Endereco`, `Cep`, `Telefone`, `Sexo`|Campos opcionais do cadastro completo do legado|**Fora de escopo.** Não são coletados nem exibidos no RF-008; permanecem nulos nos novos registros.|

==== Rotinas Armazenadas (PL/SQL) Reaproveitadas ====

**Padrão adotado no RF-008:** toda a comunicação entre telas, e-mails e API é feita pelo **ID interno da autuação** (`PROAUTU_ID`). O número público do processo (`CODG_PROCESSO_N`) é usado **apenas para exibição** ao usuário — nunca como identificador em requisições, tokens ou parâmetros de rota.

^ Rotina ^ Parâmetros ^ Retorno ^ Reaproveitamento ^
|`WEB_PACKAGE.PWEB_ACOMPANHAPROCESSO`|Código do processo (`P_CODGPROCESSO_N` — número público), ID do usuário Push (`P_PSHUSUA_ID`)|`"0"` sucesso · `"00001"` já inscrito · `"00002"` processo inválido|**Não segue o padrão do RF-008.** É a única rotina legada que recebe o número público em vez do ID de autuação. O backend deve resolver ID de Autuação → número **apenas nesta chamada pontual** (conversão interna, nunca propagada para o restante do contrato do RF-008) — ou, preferencialmente, solicitar ao DBA uma versão da rotina que aceite `PROAUTU_ID` diretamente, eliminando a conversão.|
|`WEB_PACKAGE.PWEB_REMOVEACOMPPROCESSO`|ID interno da autuação (`P_PROAUTU`), ID do usuário Push (`P_PSHUSUA`)|`"0"` sucesso|**Já alinhada ao padrão do RF-008** — recebe o ID de autuação diretamente, sem necessidade de conversão.|

==== Endpoints da API do Catálogo (`api/push/*`) ====

^ Endpoint legado ^ Reaproveitamento no RF-008 ^
|`POST api/push/login`|**Descontinuado.** Dependia de senha; o novo modelo não tem login.|
|`POST api/push/email` (cadastro)|**Substituído** pelo cadastro implícito descrito acima — o novo `POST /api/push/inscrever` (PRD §7) deve criar o registro em `PSH_USUARIOS` internamente, sem expor os campos `Nome`/`Senha` ao cliente.|
|`GET api/push/verifica/{numeroProcesso}`|**Reaproveitável como base, com correção de parâmetro:** no RF-008 o parâmetro deve ser `idAutuacao`, não o número público — a página do processo (`/processos/{id}`) já tem o ID de autuação em contexto, o usuário não precisa informá-lo.|
|`PUT api/push/adiciona/processos`|**Reaproveitável como base, com a mesma correção:** a lista recebida deve conter IDs de autuação, não números de processo, antes de repassar para `WEB_PACKAGE.PWEB_ACOMPANHAPROCESSO` (que exigirá a conversão pontual citada acima).|
|`DELETE api/push/remove/{numeroProcesso}`|**Reaproveitável como base:** apesar do nome do parâmetro na rota legada, o valor é repassado como ID interno para `RemoveAcompanhamentoDeProcesso`. No RF-008 o parâmetro deve se chamar explicitamente `idAutuacao`, para não sugerir que aceita o número público.|
|`GET api/push/processos`|**Reaproveitável** como base para `GET /api/push/gerenciar`.|
|Autenticação `BasicAuthorizationPush` (header `Authorization: Basic {id}@{tokenCriptografado}`, sem expiração — risco S4 do relatório técnico)|**Não reaproveitada.** O RF-008 exige token de e-mail com expiração (RN02) e sem exigência de login prévio; é necessário um mecanismo novo de emissão/validação de token (ex.: JWT com `exp`).|

==== Serviço de Envio de E-mail Reaproveitado ====

^ Componente ^ Papel no legado ^ Reaproveitamento no RF-008 ^
|`IServicoDeEmail` / `ServicoDeEmail` (`TCE.Compartilhado.Servico.Servicos.Contato`)|Camada compartilhada de envio, usada por `ServicoDeUsuarioPush`, `ServicoDeFaleConosco`, `ServicoDeOuvidoriaEletronica` e outros serviços do Compartilhado|**Reaproveitada integralmente.** O RF-008 deve montar um `DtoEmail` (remetente `push@tce.go.gov.br`, destinatário, assunto, corpo HTML) e um `DtoConfiguracaoEmail { HostName = "smtp.tce.go.gov.br" }` e chamar `IServicoDeEmail.EnviaEmail(...)` — exatamente como já faz `ServicoDeUsuarioPush.EnviaEmail` para os e-mails de cadastro/alteração/lembrete de senha do Push legado. Não é necessário criar um novo mecanismo de disparo.|
|`smtp.tce.go.gov.br`|Host SMTP institucional, configurado via `SmtpClient` do .NET (`ServicoDeEmail.EnviaEmail`)|**Confirmado como servidor a ser utilizado.** Os três e-mails do RF-008 (seção "E-mails Enviados") devem ser despachados por este host, seguindo o mesmo padrão do restante do portal.|
|`push@tce.go.gov.br`|—|**Endereço de remetente institucional definido para o RF-008.** Utilizado no campo `From` do `DtoEmail` para os três e-mails (Confirmação, Notificação, Reenvio).|

==== Riscos e Pontos de Atenção para o Backend ====

  * **Não sobrescrever cadastros existentes:** e-mails que já possuem registro em `PSH_USUARIOS` (vindos do Push legado, com `Nome`/`Senha`/`Habilitado` reais) devem ser localizados por `DESC_EMAIL_A` e reaproveitados como estão — o upsert do cadastro implícito (RN12) só deve **inserir** quando não houver registro; nunca deve **atualizar** `Nome`, `Senha` ou rebaixar `Habilitado` de um cadastro pré-existente.
  * **Descolar "Habilitado" de "ativação de conta":** o significado de `HABILITADO_N` muda de "conta ativada" (legado) para "e-mail confirmado em ao menos um processo" (RF-008); é preciso garantir que usuários migrados do legado com `Habilitado = 0` (nunca ativaram a conta) não fiquem bloqueados ao usar o novo fluxo de confirmação por processo.
  * **ID de Autuação como identificador único do processo:** todo o contrato do RF-008 (requisições da API, tokens de confirmação/gerenciamento/cancelamento, parâmetros de rota) deve referenciar o processo pelo ID de autuação. O número público do processo é apenas informação de exibição nas telas e nos e-mails. A única exceção no legado é `WEB_PACKAGE.PWEB_ACOMPANHAPROCESSO`, que exige o número público — tratar como conversão isolada no ponto de integração, sem propagar o número para o restante do fluxo (ver tabela de rotinas acima).
  * **Nenhuma estrutura de token existente é reaproveitável tal como está:** o legado não possui tabela/mecanismo de token com expiração para os links de confirmação/gerenciamento/cancelamento; isso é **desenvolvimento novo**, não reaproveitamento.

---
//Gerado com: documentar-funcionalidade-v1.md// \\
//Revisado por: Paulo Ricardo Amorim Silva - pramorim@tce.go.gov.br//