# Arquitetura do ServiceGPT

## Visão geral

```text
ChatGPT / WhatsApp
        ↓
ServiceGPT (Laravel)
        ↓
Bling
```

O ServiceGPT será o ponto central de validação, orquestração e auditoria. Canais externos não devem criar Ordens de Serviço diretamente no Bling.

## Responsabilidades por camada

### Controllers

- recebem requests HTTP;
- validam a entrada, preferencialmente por Form Requests quando a complexidade justificar;
- delegam o processamento a Services;
- retornam responses HTTP.

Controllers devem permanecer enxutos e não devem concentrar regras de negócio ou detalhes de integração.

### Services

- contêm e coordenam regras de negócio;
- encapsulam integrações externas;
- executam casos de uso;
- preservam as regras de confirmação, idempotência e rastreabilidade.

As integrações do Bling ficam em `app/Services/Bling`.

### DTOs

- transferem dados de maneira estruturada entre as camadas;
- tornam contratos internos explícitos;
- evitam o transporte indiscriminado de arrays quando houver benefício concreto.

DTOs não devem conter persistência nem efeitos colaterais.

### Enums

- representam estados e valores controlados;
- reduzem strings livres em regras sensíveis;
- centralizam os estados válidos de uma solicitação de Ordem de Serviço.

### Models

- representam a persistência;
- definem casts, atributos e relacionamentos;
- não devem assumir a orquestração de integrações externas.

### API

- fornece contratos REST versionáveis e respostas previsíveis;
- valida entrada e autenticação antes de acionar casos de uso;
- não expõe segredos nem detalhes internos de exceções.

### Logs

- registram eventos relevantes para auditoria e diagnóstico;
- correlacionam operações com a solicitação de Ordem de Serviço;
- devem omitir tokens, segredos, senhas e outros dados sensíveis;
- devem permitir rastrear tentativas, respostas e falhas sem comprometer credenciais.

### Integrações externas

- usam apenas APIs oficiais e documentadas;
- ficam isoladas em Services com responsabilidade clara;
- aplicam timeouts, tratamento de erros e proteção contra duplicidade quando forem implementadas;
- não criam Ordens de Serviço sem confirmação explícita.

## Fluxo futuro de uma Ordem de Serviço

1. Um canal envia a solicitação ao ServiceGPT.
2. O sistema interpreta e estrutura os dados recebidos.
3. O cliente é localizado no Bling.
4. Uma solicitação de Ordem de Serviço é preparada localmente em estado de rascunho.
5. Os dados completos são apresentados ao usuário.
6. O usuário confirma explicitamente a operação.
7. O ServiceGPT valida o estado e a idempotência e cria a Ordem de Serviço no Bling.
8. O resultado, o identificador externo e os logs de auditoria são persistidos.

Interpretação de linguagem natural, isoladamente, nunca autoriza a etapa 7.

## API preparada para IA (Fase 6)

Clientes de IA enviam dados estruturados para `POST /api/ai/service-order-requests`. O DTO específico transforma somente campos permitidos no formato interno da Fase 5. A solicitação segue o fluxo `awaiting_confirmation → confirmed → sent → completed/failed/unknown`; o envio ao Bling permanece exclusivamente no Service da Fase 5, protegido por lock e confirmação explícita.

A prontidão é calculada a partir do cliente, descrição e itens informados. A representação pública informa `ready_for_confirmation` e `missing_fields`, sem expor payload interno, logs ou segredos. Solicitações incompletas podem ser complementadas por PATCH antes da confirmação.
## Interpretação OpenAI (Fase 7)

`User/Channel → POST /api/ai/interpret → OpenAI Responses API → interpretação estruturada → validação → resolução de cliente no Bling → POST /api/ai/prepare-service-order → ServiceOrderRequest → awaiting_confirmation → confirmação explícita → Bling`. A interpretação não pode confirmar nem enviar uma OS. A mensagem é dado não confiável e a saída estruturada passa por DTO e validação antes da preparação.


## Operação local (Fase 8.5)

O instalador cria explicitamente o primeiro administrador e grava um marcador local de instalação. As rotas administrativas exigem sessão autenticada e `is_admin`. A configuração de ambiente usa uma allowlist; nunca há editor genérico de variáveis nem registro de valores sensíveis. Backups e a auditoria administrativa ficam em Services separados dos Controllers.
