reservas/AGENTS.md

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.

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.