# Instruções para agentes de desenvolvimento

Este arquivo é a principal referência para agentes que trabalham no ServiceGPT.

## Antes de qualquer alteração

1. Leia integralmente:
   - `README.md`;
   - `docs/ARCHITECTURE.md`;
   - `docs/ROADMAP.md`;
   - `docs/BLING.md`;
   - `docs/SECURITY.md`;
   - `docs/CONTRIBUTING.md`.
2. Verifique a fase atual do projeto em `docs/ROADMAP.md`.
3. Não implemente funcionalidades de fases futuras sem solicitação explícita.
4. Antes de alterar um arquivo existente, leia seu conteúdo, entenda sua responsabilidade e preserve a compatibilidade com a arquitetura documentada.
5. Nunca invente endpoints, campos ou comportamentos da API do Bling. Consulte a documentação oficial correspondente à fase em implementação.

## Segurança e dados

- Nunca exponha nem registre access tokens, refresh tokens, client secrets, senhas ou chaves de API.
- Mantenha tokens e segredos apenas em variáveis de ambiente ou em armazenamento seguro apropriado.
- Não execute `php artisan migrate:fresh`, `php artisan db:wipe` ou outros comandos destrutivos em bancos com dados existentes.
- Preserve, nesta ordem, segurança, integridade dos dados, proteção contra duplicidade, rastreabilidade, simplicidade e manutenibilidade.

## Arquitetura e implementação

- Mantenha controllers enxutos.
- Coloque regras de negócio em Services ou classes apropriadas.
- Não crie abstrações desnecessárias.
- Não use Repository Pattern sem necessidade explícita.
- Não crie interfaces apenas por abstração.
- Não instale dependências externas sem justificar a necessidade.
- Não expanda o escopo da tarefa sem solicitação.

## Git e entrega

- Nunca trabalhe diretamente na branch `main`.
- Use branches no padrão `feature/fase-N-descricao`.
- Ao concluir, execute os testes disponíveis, informe os arquivos alterados, explique resumidamente o trabalho, relate erros ou limitações e não faça merge automático.

## Regra crítica para ordens de serviço

Uma Ordem de Serviço nunca deve ser criada automaticamente apenas com base em interpretação de linguagem natural.

O fluxo obrigatório futuro é:

1. receber a solicitação;
2. interpretar a solicitação;
3. localizar o cliente;
4. preparar a Ordem de Serviço;
5. apresentar os dados para confirmação;
6. receber confirmação explícita;
7. criar a Ordem de Serviço no Bling;
8. salvar o resultado e os logs.

## Atualizações operacionais

Pacotes de atualização devem ser versionados, inspecionados antes da instalação e aplicados somente pelo fluxo administrativo. Nunca use `git pull`, `git checkout`, `git reset`, comandos arbitrários, `migrate:fresh`, `migrate:reset` ou `db:wipe` como parte de atualização. Migrations precisam ser aditivas e compatíveis com rollback de arquivos; rollback completo de banco não é prometido.
