## Instruções rápidas para agentes de codificação (Copilot / AI)

Este repositório é um serviço de integração entre Vetor (ERP) e Bling construído como uma aplicação Laravel. Aqui estão os pontos essenciais que ajudam um agente a ser imediatamente produtivo.

- Contexto arquitetural: fluxo principal é
  Vetor ERP ←→ Serviço de Integração (Laravel) ←→ Bling
  O serviço é orientado por jobs agendados que: atualizam estoque (Vetor → Bling) e importam pedidos faturados (Bling → Vetor).

- Comandos e fluxos de desenvolvedor já estabelecidos (extraídos de `INSTRUCOES.md`):
  - Configurar `.env` com as variáveis BLING_* e VETOR_* (ver `INSTRUCOES.md`).
  - Migrar banco: `php artisan migrate`
  - Autorizar Bling (execução única inicial): `php artisan bling:authorize`
  - Rodar scheduler persistente: `php artisan schedule:work`
  - Painel web (opcional, ambiente local): `php artisan serve`

- Autenticação e tokens:
  - Bling usa OAuth2. Após `bling:authorize` são salvos `access_token` e `refresh_token` em banco.
  - O código espera renovar automaticamente `access_token` usando `refresh_token` quando necessário.
  - Tabelas relacionadas: `bling_tokens`, `bling_sync_state`, `integration_logs` (descritas em `INSTRUCOES.md`).

- Jobs e agendamento (importante para alterações de comportamento):
  - Jobs nomeados (exemplo do plano): `SyncStockJob` (a cada 4h) e `ImportOrdersJob` (a cada 15min).
  - Ao modificar lógica de sincronização, mantenha idempotência e registre eventos em `integration_logs`.

- Convenções e expectativas específicas deste projeto:
  - Preferir comandos `php artisan` para operações de manutenção (migrations, autorização, scheduler).
  - Estado de sincronização mínimo é mantido em tabela (`last_order_id`) — ao ajustar a importação, preserve e atualizar esse marcador.
  - Tokens e segredos esperam-se em `.env`; não altere nomes de variáveis (ex.: `BLING_CLIENT_ID`, `VETOR_AUTHORIZATION`).

- O que procurar ao editar/estender o código:
  - Pontos de integração com Bling: rotinas que usam refresh token antes de chamar a API externa. Se for refatorar, garanta o fluxo "tentar usar access_token → se expirar usar refresh_token → persistir novo token".
  - Locais para logs de integração (usar `integration_logs`/mesma estrutura JSON para contexto).
  - Jobs agendados — qualquer mudança de frequência deve refletir no scheduler e na documentação.

- Exemplo de prompt para gerar/alterar código:
  - "Implementar tratamento para resposta 429 (rate limit) na chamada ao Bling: tentar 3 vezes com backoff exponencial e registrar falhas no `integration_logs` mantendo a estrutura JSON atual. Atualize onde o refresh de token é feito para que não seja duplicado durante o retry." 

Notas e suposições (informações inferidas):
- Assumi que o projeto é Laravel (comandos `php artisan` no `INSTRUCOES.md`) e que os jobs estarão em `app/Jobs` e a lógica de integração em `app/Services` ou `app/Console` — confirme caminhos reais antes de mudanças invasivas.

Se precisar, eu atualizo este arquivo adicionando exemplos de trechos de código (onde estão as chamadas HTTP ao Bling), caminhos reais para jobs/controllers e comandos de build (composer/npm) após você confirmar que quer que eu leia o diretório do projeto em mais detalhes.

---
Por favor, revise: há alguma área que você espera que eu documente com mais detalhe (ex.: esquema de tabelas SQL, arquivos exatos onde estão os jobs, ou exemplos de chamadas à API do Bling)?
