
# Painel Interativo de Proveniência de Evidências Baseado em Mermaid para Auditorias de Questionários em Tempo Real

## Introdução  

Questionários de segurança, auditorias de conformidade e avaliações de risco de fornecedores têm sido tradicionalmente gargalos para empresas SaaS de ritmo acelerado. Embora a IA possa rascunhar respostas em segundos, auditores e revisores internos ainda perguntam: *“De onde veio essa resposta? Ela mudou desde a última auditoria?”* A resposta está na **proveniência de evidências** — a capacidade de rastrear cada resposta até sua fonte, versão e trilha de aprovação.

A pilha de recursos de próxima geração da Procurize introduz um **painel interativo Mermaid** que visualiza a proveniência de evidências em tempo real. O painel é alimentado por um **Dynamic Compliance Knowledge Graph (DCKG)**, continuamente sincronizado com repositórios de políticas, armazéns de documentos e feeds externos de conformidade. Ao renderizar o grafo como um diagrama Mermaid intuitivo, as equipes de segurança podem:

* **Navegar** na linhagem de cada resposta com um clique.
* **Validar** a atualidade das evidências via alertas automáticos de desvio de políticas.
* **Exportar** instantâneos prontos para auditoria que incorporam a visualização de proveniência nos relatórios de conformidade.

As seções a seguir detalham a arquitetura, o modelo Mermaid, padrões de integração e passos de implantação recomendados.

---

## 1. Por que a Proveniência Importa em Questionários Automatizados  

| Ponto de Dor | Remédio Tradicional | Risco Residual |
|--------------|---------------------|----------------|
| **Obsolescência da Resposta** | Notas manuais de “última atualização” | Alterações de políticas perdidas |
| **Fonte Opaca** | Rodapés textuais | Auditores não podem verificar |
| **Caos no Controle de Versão** | Repositórios Git separados para documentos | Snapshots inconsistentes |
| **Sobrecarga de Colaboração** | Tópicos de e‑mail sobre aprovações | Aprovações perdidas, trabalho duplicado |

A proveniência elimina essas lacunas ao **vincular cada resposta gerada por IA a um nó de evidência único** em um grafo que registra:

* **Documento‑Fonte** (arquivo de política, atestado de terceiros, evidência de controle)  
* **Hash da Versão** (impressão criptográfica que garante imutabilidade)  
* **Proprietário / Aprovador** (identidade humana ou de bot)  
* **Timestamp** (horário UTC automático)  
* **Sinalizador de Desvio de Política** (gerado automaticamente pelo Motor de Detecção de Desvios em Tempo Real)

Quando um auditor clica em uma resposta no painel, o sistema expande instantaneamente o nó, revelando todos esses metadados.

---

## 2. Arquitetura Central  

A seguir, um diagrama Mermaid de alto nível do pipeline de proveniência. O diagrama usa **rótulos de nó entre aspas duplas** conforme exigido pela especificação.

```mermaid
graph TD
    subgraph AI Engine
        A["LLM Answer Generator"]
        B["Prompt Manager"]
    end
    subgraph Knowledge Graph
        KG["Dynamic Compliance KG"]
        V["Evidence Version Store"]
        D["Drift Detection Service"]
    end
    subgraph UI Layer
        UI["Interactive Mermaid Dashboard"]
        C["Audit Export Service"]
    end
    subgraph Integrations
        R["Policy Repo (Git)"]
        S["Document Store (S3)"]
        M["External Compliance Feed"]
    end

    B --> A
    A --> KG
    KG --> V
    V --> D
    D --> KG
    KG --> UI
    UI --> C
    R --> V
    S --> V
    M --> KG
```

**Fluxos principais**

1. O **Prompt Manager** seleciona um prompt contextualizado que referencia nós relevantes do KG.  
2. O **LLM Answer Generator** produz uma resposta preliminar.  
3. A resposta é **registrada** no KG como um novo *Answer Node* com arestas para os *Evidence Nodes* subjacentes.  
4. O **Evidence Version Store** grava um hash criptográfico de cada documento‑fonte.  
5. O **Drift Detection Service** compara continuamente os hashes armazenados com snapshots de políticas ao vivo; qualquer discrepância sinaliza automaticamente a resposta para revisão.  
6. O **Interactive Dashboard** lê o KG via um endpoint GraphQL, gerando código Mermaid em tempo real.  
7. O **Audit Export Service** agrupa o SVG Mermaid atual, o JSON de proveniência e o texto da resposta em um único pacote PDF.

---

## 3. Construindo o Painel Mermaid  

### 3.1 Transformação de Dados → Diagrama  

A camada UI consulta o KG por um ID de questionário específico. A resposta inclui uma estrutura aninhada:

```json
{
  "questionId": "Q-101",
  "answer": "We encrypt data at rest using AES‑256.",
  "evidence": [
    {
      "docId": "policy-iso27001",
      "versionHash": "0x9f2c...",
      "approvedBy": "alice@example.com",
      "timestamp": "2025-11-20T14:32:00Z",
      "drift": false
    },
    {
      "docId": "cloud‑kbs‑report",
      "versionHash": "0x4c1a...",
      "approvedBy": "bob@example.com",
      "timestamp": "2025-09-05T09:10:00Z",
      "drift": true
    }
  ]
}
```

Um **renderizador cliente‑side** converte cada entrada de evidência em um sub‑grafo Mermaid:

```mermaid
graph LR
    A["Answer Q‑101"] --> E1["policy‑iso27001"]
    A --> E2["cloud‑kbs‑report"]
    E1 -->|hash: 0x9f2c| H1["Hash"]
    E2 -->|hash: 0x4c1a| H2["Hash"]
    E2 -->|drift| D["⚠️ Drift Detected"]
```

A UI sobrepõe indicadores visuais:

* **Nó verde** – evidência atualizada.  
* **Nó vermelho** – desvio sinalizado.  
* **Ícone de cadeado** – hash criptográfico verificado.

> **Nota:** A referência a *policy‑iso27001* alinha‑se ao padrão ISO 27001 — veja a especificação oficial: [ISO 27001](https://www.iso.org/standard/27001).

### 3.2 Funcionalidades Interativas  

| Funcionalidade | Interação | Resultado |
|----------------|-----------|-----------|
| **Clique no Nó** | Clicar em qualquer nó de evidência | Abre um modal com pré‑visualização completa do documento, diferenças de versões e comentários de aprovação |
| **Alternar Visão de Desvio** | Botão de alternância na barra de ferramentas | Realça apenas nós com `drift = true` |
| **Exportar Snapshot** | Clicar no botão “Exportar” | Gera bundle SVG + JSON de proveniência para auditores |
| **Busca** | Digitar ID de doc ou e‑mail do proprietário | Foca automaticamente no sub‑grafo correspondente |

Todas as interações são **apenas no cliente**, evitando viagens adicionais ao servidor. O código Mermaid subjacente é armazenado em um `<textarea>` oculto para fácil cópia‑e‑cola.

---

## 4. Integrando a Proveniência nos Fluxos Existentes  

### 4.1 Porta de Conformidade CI/CD  

Adicione uma etapa no seu pipeline que **falhe o build** se alguma resposta na próxima versão possuir um sinalizador de desvio não resolvido. Exemplo de GitHub Action:

```yaml
name: Evidence Provenance Gate
on: [pull_request]
jobs:
  provenance-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Drift Scanner
        run: |
          curl -s https://api.procurize.io/drift?pr=${{ github.event.pull_request.number }} \
          | jq '.drifted | length > 0' && exit 1 || exit 0
```

### 4.2 Alertas no Slack / Teams  

Configure o **Drift Detection Service** para enviar um snippet Mermaid conciso a um canal sempre que ocorrer um desvio. O snippet é renderizado automaticamente pelos bots suportados, proporcionando visibilidade instantânea aos líderes de segurança.

### 4.3 Automação de Revisão Jurídica  

Equipes jurídicas podem acrescentar uma aresta **“Legal Sign‑Off”** aos nós de evidência. O painel então exibe um ícone de cadeado ao lado do nó, sinalizando que a evidência passou por uma checklist jurídica.

---

## 5. Segurança & Privacidade  

| Preocupação | Mitigação |
|-------------|-----------|
| **Exposição de Documentos Sensíveis** | Armazene documentos crus em buckets S3 criptografados; o painel exibe apenas metadados e hash, não o conteúdo dos arquivos. |
| **Violação dos Dados de Proveniência** | Use assinaturas no estilo **EIP‑712** para cada transação do grafo; qualquer modificação invalida o hash. |
| **Residência de Dados** | Implante o KG e o repositório de evidências na mesma região dos seus dados de conformidade primários (EU, US‑East, etc.). |
| **Controle de Acesso** | Aproveite o modelo RBAC da Procurize: somente usuários com `provenance:read` podem visualizar o painel; `provenance:edit` é necessário para aprovações. |

---

## 6. Impacto Real: Estudo de Caso  

**Empresa:** SecureFinTech Ltd.  
**Cenário:** Auditoria **[SOC 2](https://secureframe.com/hub/soc-2/what-is-soc-2)** trimestral exigia evidências para 182 controles de criptografia.  
**Antes do Painel:** A consolidação manual levava 12 dias; auditores questionavam a atualidade das evidências.  
**Depois do Painel:**  

| Métrica | Linha de Base | Com o Painel |
|---------|---------------|--------------|
| Tempo Médio de Resposta | 4,2 horas | **1,1 horas** |
| Retrabalho por Desvio | 28 % das respostas | **3 %** |
| Índice de Satisfação do Auditor (1‑5) | 2,8 | **4,7** |
| Tempo para Exportar Pacote de Auditoria | 6 horas | **45 minutos** |

A visualização da proveniência reduziu o tempo de preparação da auditoria em **70 %**, e os alertas automáticos de desvio economizaram cerca de **160 horas‑pessoa ao ano**.

---

## 7. Guia de Implementação Passo‑a‑Passo  

1. **Habilitar Sincronização do Knowledge Graph** – Conecte seu repositório de políticas Git, armazém de documentos e feeds externos de conformidade nas configurações da Procurize.  
2. **Ativar Serviço de Proveniência** – Ative “Versionamento de Evidências & Detecção de Desvios” no console de administração da plataforma.  
3. **Configurar Painel Mermaid** – Adicione `dashboard.provenance.enabled = true` ao arquivo `procurize.yaml`.  
4. **Definir Workflows de Aprovação** – Use o “Workflow Builder” para anexar etapas “Legal Sign‑Off” e “Security Owner” a cada nó de evidência.  
5. **Treinar Times** – Realize uma demo ao vivo de 30 minutos cobrindo interação com nós, tratamento de desvios e procedimentos de exportação.  
6. **Incorporar em Portais de Auditoria** – Use o snippet IFrame fornecido para hospedar o painel dentro do seu portal externo de auditoria.  

```html
<iframe src="https://dashboard.procurize.io/q/2025-Q101"
        width="100%" height="800"
        style="border:none;"></iframe>
```

7. **Monitorar Métricas** – Acompanhe “Eventos de Desvio”, “Contagem de Exportações” e “Tempo Médio de Resposta” no dashboard analítico da Procurize para quantificar o ROI.

---

## 8. Futuras Melhorias  

| Item do Roadmap | Descrição |
|-----------------|-----------|
| **Previsão de Desvios por IA** | Utilizar análise de tendências baseada em LLM nos logs de mudanças de políticas para prever desvios antes que ocorram. |
| **Compartilhamento de Proveniência Multi‑Tenant** | Modo KG federado que permite que empresas parceiras visualizem evidências compartilhadas sem expor documentos crus. |
| **Navegação por Voz** | Integrar com o Procurize Voice Assistant para que revisores solicitem “Mostre a fonte da resposta 34”. |
| **Colaboração ao Vivo** | Edição multi‑usuário em tempo real de nós de evidência, com indicadores de presença renderizados diretamente no Mermaid. |

---

## 9. Conclusão  

O **painel interativo Mermaid de proveniência de evidências da Procurize** transforma o mundo opaco da automação de questionários de segurança em uma experiência transparente, auditável e colaborativa. Ao acoplar respostas geradas por IA a um grafo de conhecimento de conformidade ao vivo, as organizações ganham **visibilidade instantânea da linhagem**, **mitigação automática de desvios** e **artefatos prontos para auditoria** — tudo sem sacrificar velocidade.

Adotar essa camada visual de proveniência não apenas reduz os ciclos de auditoria, mas também constrói confiança entre reguladores, parceiros e clientes de que suas declarações de segurança são **fundamentadas por evidências imutáveis e em tempo real**.