Componente Ocorrência

1. Visão Geral

Este documento descreve o "Componente Ocorrência" da plataforma Mobile Saúde, uma funcionalidade que permite a criação e registro de "Ocorrências" diretamente através de interações via chatbot. As ocorrências registradas são persistidas na base de dados da Mobile Saúde e ficam acessíveis para consulta e gerenciamento no Painel do Atendente.

2. Objetivo

O principal objetivo do Componente Ocorrência é automatizar e padronizar o processo de coleta de informações e registro de solicitações ou eventos por parte dos beneficiários, utilizando o chatbot como interface primária. Isso visa:

Agilizar o atendimento ao beneficiário.
Centralizar o registro de interações.
Facilitar o acompanhamento das solicitações pela equipe de atendimento no Painel do Atendente.
Permitir a captura de dados estruturados e anexos relevantes para cada ocorrência.

3. Conceito da Entidade "Ocorrência"

No contexto da Mobile Saúde, uma "Ocorrência" é uma entidade fundamental utilizada para registrar diversos tipos de eventos, solicitações ou interações relacionadas a um beneficiário ou a processos internos.

Armazenamento: Cada ocorrência é registrada com um protocolo único e pode conter um histórico detalhado de todas as interações e informações associadas.
Dados Associados: Permite a vinculação de dados como identificação do beneficiário, tipo de solicitação, assunto, descrição detalhada e anexos.
Acessibilidade: As ocorrências são persistidas na plataforma Mobile Saúde e podem ser acessadas e gerenciadas no Painel do Atendente.

4. Arquitetura e Integrações

O Componente Ocorrência opera dentro do ecossistema da Mobile Saúde, integrando-se principalmente com:

Chatbot: Interface de interação com o usuário final (beneficiário).
Componente Input: Utilizado dentro do fluxo do chatbot para coletar dados textuais e arquivos (anexos) dos usuários.
Backend da Mobile Saúde: Onde a entidade Ocorrência é persistida e gerenciada.
Painel do Atendente: Interface web para que os atendentes possam visualizar, filtrar e gerenciar as ocorrências criadas pelo chatbot.

Suposição: A comunicação entre o chatbot e o backend da Mobile Saúde é realizada via APIs RESTful.

5. Fluxo de Operação do Componente

O fluxo de utilização do Componente Ocorrência geralmente segue os seguintes passos dentro de um diálogo de chatbot:

Seleção do Componente: O beneficiário seleciona uma opção no chatbot que invoca um fluxo que utiliza o Componente Ocorrência.
Exibição de Informações: O chatbot exibe uma mensagem explicativa sobre a funcionalidade do Componente Ocorrência.
Coleta de Dados: Utilizando instâncias do Componente Input, o chatbot solicita e coleta as informações necessárias do beneficiário (ex: endereço, motivo, anexos).
Criação da Ocorrência: O Componente Ocorrência é invocado, recebendo os dados coletados.
Persistência: O componente interage com o backend da Mobile Saúde para criar um novo registro de ocorrência.
Geração de Protocolo: Um número de protocolo único é gerado e associado à nova ocorrência.
Notificação: O chatbot informa ao beneficiário o número do protocolo gerado e o nome do solicitante (beneficiário identificado).
Disponibilização no Painel: A ocorrência recém-criada fica imediatamente visível e disponível para a equipe de atendimento no Painel do Atendente, com todos os detalhes e anexos.

6. Configuração do Componente

O Componente Ocorrência requer configurações para definir o contexto da ocorrência a ser criada:

Tipo de Ocorrência: Define a categoria da ocorrência (ex: "Atualização Cadastral", "Solicitação de Autorização", "Reembolso").
- Origem: Os tipos de ocorrência são pre-cadastrados em um "configurador público" ou painel administrativo da plataforma.
- Seleção: O desenvolvedor ou configurador do fluxo do chatbot seleciona o tipo de ocorrência adequado para o contexto.
Assunto da Ocorrência: Define o assunto específico da ocorrência.
- Origem: Os assuntos são pre-cadastrados no "cadastro de assuntos da plataforma".
- Seleção: Similar ao tipo, o assunto é configurado no fluxo do chatbot.
Anotação/Descrição da Ocorrência: Permite a inclusão de um texto descritivo detalhado que será gravado na ocorrência.
- Conteúdo Dinâmico: É possível usar variáveis do fluxo do chatbot para construir uma anotação dinâmica, como nome do beneficiário, dados coletados via Input (ex: occorrenciaAtualizacaoCadastralEndereco), e URLs de anexos (ex: occorrenciaAtualizacaoCadastralAnexo.link).

7. Exemplo de Caso de Uso: Atualização Cadastral

Este exemplo ilustra um fluxo de chatbot que utiliza o Componente Ocorrência para permitir que um beneficiário atualize seu endereço e anexe um comprovante de residência.

7.1. Cenário de Teste

Objetivo: O beneficiário atualiza seu endereço e anexa um comprovante de residência.
Dados de Teste: Utilizar o CPF 39639639636 para identificação, pois já está cadastrado na base de testes da Mobile Saúde.

7.2. Fluxo do Chatbot (Pseudocódigo)

// Início do Fluxo: "Atualização Cadastral"

// 1. Identificação do Beneficiário
// Chama um componente de identificação para validar o usuário.
CALL_COMPONENT "Identificação"
    PARAMETER "CPF_PARA_TESTE" = "39639639636"
    OUTPUT_VARIABLE "beneficiarioIdentificado"

IF beneficiarioIdentificado IS NOT NULL THEN

    // 2. Coleta do Novo Endereço
    ASK_USER "Para atualizar seu cadastro, por favor, digite seu novo endereço completo."
    CALL_COMPONENT "Input"
        PARAMETER "tipo" = "TEXT" // Espera uma entrada de texto
        OUTPUT_VARIABLE "occorrenciaAtualizacaoCadastralEndereco" // Armazena o endereço

    // 3. Coleta do Comprovante de Residência (Anexo)
    ASK_USER "Envie uma foto ou PDF do seu comprovante de residência."
    CALL_COMPONENT "Input"
        PARAMETER "tipo" = "FILE_UPLOAD" // Espera um arquivo
        OUTPUT_VARIABLE "occorrenciaAtualizacaoCadastralAnexo" // Armazena dados do anexo, incluindo URL

    // 4. Criação da Ocorrência
    CALL_COMPONENT "Ocorrência"
        PARAMETER "tipoOcorrencia" = "Atualização Cadastral"
        PARAMETER "assuntoOcorrencia" = "Endereço" // Exemplo, pode ser selecionado da plataforma
        PARAMETER "anotacao" = `
            Ocorrência criada para o beneficiário: ${beneficiarioIdentificado.nome}.
            Solicitada atualização cadastral de endereço.
            Novo Endereço: ${occorrenciaAtualizacaoCadastralEndereco}.
            Comprovante de Residência (URL): ${occorrenciaAtualizacaoCadastralAnexo.link}.
        `
        OUTPUT_VARIABLE "ocorrenciaCriada" // Retorna dados da ocorrência criada (ex: protocolo)

    // 5. Feedback ao Usuário
    DISPLAY_MESSAGE `Sua solicitação de atualização cadastral foi registrada!`
    DISPLAY_MESSAGE `Número do Protocolo: ${ocorrenciaCriada.numeroProtocolo}`
    DISPLAY_MESSAGE `Solicitante: ${beneficiarioIdentificado.nome}`
    DISPLAY_MESSAGE "Aguarde, sua solicitação será analisada pela nossa equipe."

ELSE

    // Em caso de falha na identificação
    DISPLAY_MESSAGE "Não foi possível identificá-lo. Por favor, tente novamente ou entre em contato com nosso atendimento."

END IF

// Fim do Fluxo: "Atualização Cadastral"

7.3. Detalhes Técnicos do Exemplo

Identificação: O componente de identificação preenche a variável beneficiarioIdentificado com dados como beneficiarioIdentificado.nome.
Entrada de Endereço: O Componente Input para texto salva o valor diretamente em occorrenciaAtualizacaoCadastralEndereco.
Anexo: O Componente Input para arquivo realiza o upload do documento e salva a URL gerada (onde o arquivo foi armazenado) na variável occorrenciaAtualizacaoCadastralAnexo.link.
Anotação Dinâmica: A anotação da ocorrência utiliza interpolação de strings para incluir o nome do beneficiário, o novo endereço e a URL do anexo.
Saída da Ocorrência: O Componente Ocorrência retorna um objeto ocorrenciaCriada contendo, no mínimo, numeroProtocolo e nomeSolicitante.

8. Verificação no Painel do Atendente

Após a execução do fluxo no chatbot, a ocorrência pode ser verificada no Painel do Atendente:

Acessar o Painel do Atendente.
Utilizar os filtros disponíveis (ex: por tipo "Atualização Cadastral", por data).
A ocorrência recém-criada estará listada, exibindo:
- Tipo: "Atualização Cadastral"
- Beneficiário: O nome do beneficiário identificado.
- Data/Hora da criação.
- Detalhes na anotação, incluindo o endereço informado e a URL do anexo.
A URL do anexo no Painel do Atendente é clicável, permitindo o acesso direto ao comprovante de residência enviado pelo beneficiário.

9. Observações Técnicas

Persistência de Dados: Todos os dados da ocorrência, incluindo a anotação e as referências aos anexos, são armazenados no backend da Mobile Saúde.
Gestão de Anexos: O Componente Input é responsável por orquestrar o upload de arquivos para um sistema de armazenamento (Blob Storage, S3, etc.) e retornar a URL pública/privada do arquivo para ser gravada na ocorrência.
Variáveis de Fluxo: A utilização de variáveis (ex: beneficiarioIdentificado, occorrenciaAtualizacaoCadastralEndereco, occorrenciaAtualizacaoCadastralAnexo) é crucial para o dinamismo e a passagem de dados entre os componentes do chatbot.
Contexto de Teste: O dump é uma ferramenta de depuração e não deve estar presente em ambientes de produção.

10. Limitações Conhecidas

Apenas Criação: O Componente Ocorrência, conforme descrito, foca exclusivamente na criação de novas ocorrências. Não há indicação de capacidades para consultar, atualizar ou encerrar ocorrências existentes diretamente via chatbot.
Configuração Externa: Os "Tipos de Ocorrência" e "Assuntos" devem ser previamente configurados fora do fluxo do chatbot, em painéis administrativos da plataforma.
Dependência de Componentes: O uso efetivo do Componente Ocorrência depende da correta implementação e integração com componentes de Identificação e Input para coletar os dados necessários.

Vídeo explicativo - componente ocorrência