Usuários e Históricos
=====================

Esta seção detalha a gestão inteligente de perfis, a sincronização de contextos globais e as regras de persistência da memória de chat do Menthor.

Fluxo Getter (Cadastro e Atualização)
-------------------------------------

O endpoint principal para a gestão de perfis é o ``/add_user_getter``. Ele foi projetado para ser o ponto único de entrada de dados do usuário, garantindo integridade e performance.

1. **Idempotência**: O sistema realiza um *checksum* dos dados enviados. O banco de dados só é atualizado se houver mudança real nos campos ``name``, ``phone`` ou no dicionário de ``payload``.
2. **Sincronização de Contextos**: Este fluxo atua como sincronizador da **Lista Global de Contextos**. Sempre que dados de contextos inéditos são enviados no payload do usuário, o sistema atualiza automaticamente as definições globais para que a IA possa alternar entre bases de dados dinamicamente.

Manutenção de Usuários
----------------------

* **Listagem Geral**: Utilize ``/list_users`` para recuperar a relação de todos os usuários cadastrados.
* **Remoção Definitiva**: Utilize ``/delete_user/{email}``. Esta ação é permanente e remove todos os vínculos do usuário com o sistema.

Gestão de Memória e Histórico
-----------------------------

O Menthor armazena as interações em arquivos JSON temporários localizados no diretório ``datasets/messages``. O endpoint ``/user_history/{id_context}`` permite recuperar essas conversas de forma segmentada por origem.

Mapeamento de Origens
^^^^^^^^^^^^^^^^^^^^^

O sistema identifica a origem da conversa através do padrão de nomenclatura do arquivo físico, permitindo que a aplicação cliente saiba por onde o usuário interagiu:

* **WhatsApp**: Identificado pelo sufixo ``#wpp-``.
* **Web (Email)**: Identificado pelo padrão ``#{email}-``.
* **Web (Phone)**: Demais padrões capturados no diretório.

Regras de Persistência e Volatilidade
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A memória do assistente é otimizada para manter a coerência com a estrutura de dados atual. Por isso, as seguintes regras se aplicam:

.. warning::
   **Arquivos .lock**: 
   Arquivos com a extensão ``.lock`` são ignorados pelo endpoint de histórico. Eles indicam uma sessão em escrita ativa (conversa em processamento), e os dados só ficam disponíveis após a conclusão da resposta da IA.

.. important::
   **Higiene de Dados (Reset de Memória)**: 
   Sempre que o metadado de um banco de dados (Menthor DB) é atualizado via ``/receive_documents_db``, os arquivos de histórico do respectivo contexto são **automaticamente arquivados**. Isso impede que a IA utilize memórias obsoletas de tabelas ou colunas que não existem mais.

.. note::
   Caso o endpoint de histórico retorne um erro **404**, a aplicação cliente deve tratar como "Início de Jornada" (usuário novo) ou "Histórico Expirado" (histórico arquivado).