# Instruções para agentes

Estas instruções aplicam-se a todo o repositório.

## Antes de começar

1. Leia integralmente `README.md`, `docs/PROJECT_STATUS.md`, `docs/ARCHITECTURE.md` e `docs/DECISIONS.md`.
2. Inspecione o estado do Git e preserve alterações do utilizador que não pertençam à tarefa.
3. Confirme a próxima tarefa em `docs/PROJECT_STATUS.md`; se o pedido do utilizador for diferente, o pedido mais recente prevalece.
4. Não peça autorização para decisões técnicas reversíveis e coerentes com os documentos. Registe a decisão e avance.

## Regras de arquitetura

- Manter o monólito modular Laravel + Inertia. Não criar um backend ou frontend separado.
- Colocar lógica de negócio em `app/Domain`; controladores apenas coordenam HTTP.
- A integração Snipe-IT vive exclusivamente em `app/Integrations/SnipeIt` e usa a API REST oficial.
- Nunca aceder diretamente à base de dados do Snipe-IT.
- Tratar períodos como intervalos semiabertos `[início, fim)`.
- Alterações de estado, aprovações, entregas e devoluções devem ser transacionais e auditadas.
- Segredos ficam apenas em variáveis de ambiente; nunca em código, testes, documentação ou logs.
- A interface e os textos destinados ao utilizador são em português de Portugal.

## Snipe-IT de produção — restrições obrigatórias

- A instância configurada é de produção; todas as chamadas remotas devem ser tratadas como operações sobre dados reais.
- São proibidos criação, edição e eliminação de equipamentos/produtos no Snipe-IT. Não implementar nem executar `POST`, `PUT`, `PATCH` ou `DELETE` remotos fora dos endpoints estritos de checkout e check-in já documentados.
- Nunca executar checkout/check-in como teste de conectividade. Diagnóstico, sincronização e validação de tokens usam exclusivamente pedidos `GET`.
- Antes de cada checkout, consultar o equipamento por `GET` no Snipe-IT. Se `assigned_to` estiver preenchido, abortar sem qualquer escrita.
- Um check-in só pode ocorrer para um item cujo checkout tenha sido confirmado pelo próprio portal e cuja atribuição remota atual continue a corresponder ao destinatário registado. Qualquer divergência exige reconciliação humana sem escrita automática.
- Escritas de checkout/check-in nunca têm retry automático. Um timeout ou resultado ambíguo interrompe o fluxo até validação manual no Snipe-IT.
- Nunca revelar URL privada, tokens, payloads sensíveis ou respostas completas de produção em logs, documentação, testes ou mensagens.

## Isolamento de testes e dados locais

- Nunca executar `php artisan test` diretamente com a configuração local: pode aplicar `RefreshDatabase` à base PostgreSQL de desenvolvimento. Usar sempre `docker compose exec -T app composer test`, que força SQLite em memória, ou declarar explicitamente o mesmo ambiente isolado.
- O `DatabaseSeeder` contém credenciais conhecidas e só pode atuar em `local`/`testing`. Quando o Snipe-IT está configurado ou já existe cache de inventário, não pode criar ativos fictícios.

## Definição de concluído

Uma alteração só está concluída quando:

1. possui testes proporcionais ao risco;
2. `composer test`, `npm run lint:check`, `npm run format:check`, `npm run types:check` e `npm run build` passam;
3. migrations funcionam em PostgreSQL e os testes continuam isolados em SQLite, salvo teste específico de PostgreSQL;
4. a interface foi verificada visualmente quando alterada;
5. `CHANGELOG.md` e `docs/PROJECT_STATUS.md` foram atualizados;
6. qualquer decisão estrutural foi acrescentada a `docs/DECISIONS.md`.

## Handoff obrigatório

No fim de cada sessão, atualizar `docs/PROJECT_STATUS.md` com:

- data;
- resumo do que foi feito;
- testes executados e resultados;
- dívida ou riscos encontrados;
- próxima tarefa concreta e primeiro ficheiro a abrir.

Registar alterações em `CHANGELOG.md` sob `Não publicado`. Não apagar histórico anterior: mover itens entre secções quando necessário.