# Assistente Corporativo Inteligente (MVP)

## Objetivo

Este modulo implementa um endpoint de chat corporativo com governanca:

1. A IA nao executa SQL livre.
2. O backend decide quais consultas autorizadas executar.
3. O retorno e padronizado para interface web.

## Endpoint API

- Metodo: `POST /api/assistente/perguntar`
- Auth: `auth:sanctum`
- Permissao: `opme.assistente.visualizar`

Payload:

```json
{
  "pergunta": "Quantos stents existem no Hospital Meridional?",
  "contexto": {
    "canal": "web"
  }
}
```

Resposta:

```json
{
  "data": {
    "status": "sucesso",
    "mensagem": "Consulta executada com sucesso.",
    "resposta": "Existem 152 itens de stent para o hospital Meridional.",
    "acao": "consultar_estoque_hospital",
    "agente": {
      "id": "estoque",
      "nome": "Agente de Estoque"
    },
    "parametros": {
      "hospital": "Meridional",
      "produto": "stent"
    },
    "dados": {
      "hospital": "Meridional",
      "produto": "stent",
      "quantidade": 152,
      "amostra": []
    },
    "resumo": "Existem 152 itens de stent para o hospital Meridional.",
    "metadados": {
      "duracao_ms": 241,
      "origem_intencao": "llm",
      "confianca": 0.93,
      "usuario_id": 10,
      "contexto": {
        "canal": "web"
      }
    }
  }
}
```

## Supervisor e agentes do MVP

O `AssistenteCorporativoService` atua como supervisor: classifica a pergunta, recebe do router o agente responsável pela ação e delega a execução apenas para ferramentas autorizadas. Nenhum agente executa SQL livre.

| Agente | Funcoes autorizadas |
| --- | --- |
| Estoque | `consultar_estoque_hospital`, `consultar_rastro` |
| Financeiro | `consultar_faturamento_pendente` |
| Comercial | `consultar_resumo_produto` |
| Auditoria Fiscal (legado) | `auditar_cst_divergente` |

O agente selecionado é incluído na resposta como `agente.id` e `agente.nome`; o chat Web exibe o nome para deixar visível qual especialista respondeu.

## Catalogo de funcoes autorizadas

- `consultar_estoque_hospital(hospital, produto)`
- `consultar_rastro(rastro_id)`
- `consultar_faturamento_pendente(periodo_dias, hospital opcional)`
- `auditar_cst_divergente(cst_padrao)`
- `consultar_resumo_produto(busca por referencia, codigo ou nome)`

## Auditoria

Tabela: `assistente_auditoria`

- `usuario_id`, `usuario_nome`
- `status`, `acao`, `origem_intencao`, `confianca`
- `duracao_ms`
- `pergunta`
- `parametros_json`
- `resumo_dados`
- `mensagem`
- `created_at`, `updated_at`

## Comportamento de IA

- Com `OPENAI_API_KEY` configurado:
  - O modulo usa OpenAI para classificar intencao e redigir resposta amigavel.
- Sem chave configurada:
  - Usa fallback heuristico por regras e resposta padrao.

## Proximos passos recomendados

1. Adicionar funcao de RH (admissoes por periodo).
2. Criar UI de chat protegida por permissao no modulo OPME.
3. Aplicar mascaramento LGPD por tipo de dado sensivel.
4. Adicionar dashboard de auditoria para supervisao operacional.