147 lines
7.1 KiB
Markdown
147 lines
7.1 KiB
Markdown
# Runbook de desenvolvimento e operação
|
|
|
|
## Desenvolvimento local
|
|
|
|
1. Copiar `.env.example` para `.env`.
|
|
2. Executar `docker compose build`.
|
|
3. Gerar a chave com `docker compose run --rm app php artisan key:generate`.
|
|
4. Iniciar com `docker compose up -d`.
|
|
5. Preparar dados com `docker compose exec app php artisan migrate --seed`.
|
|
6. Abrir o portal em `http://localhost:8000` e emails em `http://localhost:8025`.
|
|
|
|
## Diagnóstico
|
|
|
|
```bash
|
|
docker compose ps
|
|
docker compose logs --tail=100 app
|
|
docker compose logs --tail=100 queue
|
|
docker compose exec app php artisan about
|
|
docker compose exec app php artisan migrate:status
|
|
docker compose exec postgres pg_isready -U reserva -d reserva
|
|
docker compose exec redis redis-cli ping
|
|
```
|
|
|
|
### Página em branco no desenvolvimento
|
|
|
|
Se o HTML responder mas a interface React não aparecer, confirmar que `public/hot` contém `http://localhost:5173` e não `http://0.0.0.0:5173`. Depois validar os módulos:
|
|
|
|
```bash
|
|
curl -I -H 'Origin: http://localhost:8000' http://localhost:5173/@vite/client
|
|
curl -I -H 'Origin: http://localhost:8000' http://localhost:5173/resources/js/app.tsx
|
|
```
|
|
|
|
Para executar a validação backend use `docker compose exec app composer test`, não `php artisan test` diretamente. O script isola as variáveis de teste das variáveis `local` injetadas pelo Docker Compose e evita que jobs únicos deixem locks no Redis de desenvolvimento.
|
|
|
|
Ambos devem responder com estado 200 e `Access-Control-Allow-Origin: http://localhost:8000`. Reiniciar o serviço com `docker compose restart node` se o ficheiro `public/hot` estiver desatualizado.
|
|
|
|
Confirmar também que o HTML inicial já contém conteúdo SSR:
|
|
|
|
```bash
|
|
curl -s http://localhost:8000/login | grep 'data-server-rendered="true"'
|
|
```
|
|
|
|
Se o endpoint Vite devolver um erro SSR, procurar primeiro componentes globais montados em `withApp` que chamem hooks Inertia como `usePage()`. Os elementos irmãos do argumento `app` não pertencem ao respetivo contexto; devem receber as propriedades através do segundo argumento de `withApp`.
|
|
|
|
## Atualização de código
|
|
|
|
```bash
|
|
docker compose exec app composer install
|
|
docker compose exec node npm install
|
|
docker compose exec app php artisan migrate --force
|
|
docker compose exec app php artisan optimize:clear
|
|
docker compose restart queue scheduler
|
|
```
|
|
|
|
## Integração Snipe-IT
|
|
|
|
Definir no ambiente, sem colocar tokens no repositório:
|
|
|
|
```dotenv
|
|
SNIPE_IT_URL=https://inventario.exemplo.pt
|
|
SNIPE_IT_READ_TOKEN=
|
|
SNIPE_IT_OPERATIONAL_TOKEN=
|
|
SNIPE_IT_TIMEOUT=10
|
|
SNIPE_IT_PAGE_SIZE=100
|
|
SNIPE_IT_RETRIES=3
|
|
SNIPE_IT_RETRY_DELAY_MS=250
|
|
```
|
|
|
|
O token de leitura deve pertencer a uma conta técnica com acesso apenas de leitura aos ativos. O token operacional deve ser separado e ter apenas as permissões necessárias para checkout/check-in. A aplicação acrescenta `/api/v1` automaticamente quando a URL não o contém.
|
|
|
|
Operações:
|
|
|
|
```bash
|
|
# Sincronização imediata e resultado no terminal
|
|
docker compose exec app php artisan snipe:sync-assets
|
|
|
|
# Colocar na fila
|
|
docker compose exec app php artisan snipe:sync-assets --queue
|
|
|
|
# Confirmar o agendamento horário
|
|
docker compose exec app php artisan schedule:list
|
|
```
|
|
|
|
Administradores podem testar a ligação, iniciar uma execução e consultar as últimas dez sincronizações em `http://localhost:8000/administracao/snipe-it`. Uma execução falhada mantém o último catálogo válido e não desativa registos ausentes. Consultar `sync_runs`, os logs do worker e o painel antes de repetir.
|
|
|
|
## Entregas, devoluções e reconciliação
|
|
|
|
Utilizadores com perfil `inventory_operator` ou `administrator` acedem a `http://localhost:8000/operacoes`. A fila inclui as reservas do dia e todos os processos entregues, atrasados, devolvidos ou com incidente ainda pendente. O campo inicial aceita referência, nome, email, etiqueta, ID Snipe-IT ou a saída de um leitor QR/código de barras configurado como teclado.
|
|
|
|
Procedimento de entrega:
|
|
|
|
1. preparar a requisição;
|
|
2. confirmar fisicamente todos os equipamentos e o estado à saída;
|
|
3. confirmar o ID do destinatário no Snipe-IT;
|
|
4. registar a entrega e verificar a mensagem de sucesso;
|
|
5. se existir erro, não voltar a submeter antes de consultar o estado do ativo no Snipe-IT.
|
|
|
|
Procedimento de devolução:
|
|
|
|
1. localizar a requisição ou ler a etiqueta;
|
|
2. verificar equipamento, acessórios, danos e localização;
|
|
3. registar a devolução;
|
|
4. criar um incidente e bloqueio temporal quando o ativo não deva voltar ao catálogo;
|
|
5. concluir o processo apenas depois de todos os itens estarem devolvidos.
|
|
|
|
Uma operação parcial fica em `incident`. Consultar `handover_records` para movimentos confirmados e os eventos `reservation.delivery_failed`/`reservation.return_failed` em `audit_logs`. Comparar cada item com o estado atual no Snipe-IT; corrigir apenas os itens ainda `ready` ou `delivered`. Não alterar estados diretamente na base de dados nem repetir em bloco, porque as escritas externas são deliberadamente não idempotentes e não têm retry automático.
|
|
|
|
## Ciclo de vida das pré-reservas
|
|
|
|
As requisições pendentes têm, por defeito, um prazo de decisão de 48 horas. O scheduler coloca a expiração na fila a cada cinco minutos. Para operar ou diagnosticar manualmente:
|
|
|
|
```bash
|
|
# Expirar imediatamente os pedidos vencidos
|
|
docker compose exec app php artisan reservations:expire
|
|
|
|
# Colocar a operação na fila
|
|
docker compose exec app php artisan reservations:expire --queue
|
|
|
|
# Confirmar ambos os agendamentos
|
|
docker compose exec app php artisan schedule:list
|
|
```
|
|
|
|
Uma expiração ou cancelamento muda itens `held`, `reserved`, `ready` e `delivered` para `cancelled`, libertando o período. Confirmar os eventos `reservation.expired` ou `reservation.cancelled` em `audit_logs` quando existir uma divergência operacional.
|
|
|
|
## Aprovações
|
|
|
|
Utilizadores com perfil `approver` ou `administrator` acedem a `http://localhost:8000/aprovacoes`. Uma decisão válida deve criar uma linha em `approval_actions` e outra em `audit_logs`. Se a aprovação indicar que a disponibilidade mudou, confirmar primeiro a atribuição/estado sincronizado do ativo e conflitos entretanto criados; não alterar o estado diretamente na base de dados.
|
|
|
|
As decisões geram jobs de notificação. Em desenvolvimento, confirmar o email em `http://localhost:8025` e a notificação interna em `http://localhost:8000/notificacoes`. Se uma mensagem não chegar, consultar primeiro `docker compose logs --tail=100 queue` e a tabela `failed_jobs`; não repetir a decisão já confirmada.
|
|
|
|
## Produção
|
|
|
|
Antes de disponibilizar:
|
|
|
|
- definir `APP_ENV=production`, `APP_DEBUG=false` e HTTPS;
|
|
- substituir todas as palavras-passe do exemplo;
|
|
- montar segredos fora do repositório;
|
|
- remover exposição pública das portas PostgreSQL, Vite e Mailpit;
|
|
- configurar volumes persistentes e backups cifrados;
|
|
- executar `php artisan optimize` e frontend compilado;
|
|
- definir health checks, alertas e rotação de logs;
|
|
- testar recuperação de backup e falha Snipe-IT.
|
|
|
|
## Backups
|
|
|
|
Salvaguardar diariamente PostgreSQL e uploads. Manter retenção semanal/mensal e uma cópia fora do servidor. Segredos são salvaguardados através de procedimento separado. Executar um teste de restauro periódico e registar o resultado.
|