55 lines
3.4 KiB
Markdown
55 lines
3.4 KiB
Markdown
# 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.
|