feat: refine admin access management

docs/DEV.md

@@ -1,4 +1,4 @@
-# Guia de Desenvolvimento — 16/10/2025
+# Guia de Desenvolvimento — 18/10/2025
 
 Este documento consolida o estado atual do ambiente de desenvolvimento, descreve como rodar lint/test/build localmente (e no CI) e registra erros recorrentes com as respectivas soluções.
 
@@ -28,6 +28,7 @@ Este documento consolida o estado atual do ambiente de desenvolvimento, descreve
    ```
 
 3. Credenciais padrão (seed): `admin@sistema.dev / admin123`.
+4. Herdou dados antigos? Execute `node scripts/remove-legacy-demo-users.mjs` para limpar contas demo legadas.
 
 > **Por quê inline?** Evitamos declarar `DATABASE_URL` em `prisma/.env` porque o Prisma lê também o `.env` da raiz (produção). O override inline garante isolamento do banco DEV.
 
@@ -59,6 +60,62 @@ Etapas:
 
 O workflow dispara em todo `push`/`pull_request` para `main` e fornece feedback imediato sem depender do pipeline de deploy.
 
+## Testes rápidos via curl (Convites & acessos)
+
+1. Rode `pnpm dev` e autentique-se em `http://localhost:3000/login` usando `admin@sistema.dev / admin123`.
+2. Copie o valor do cookie `BETTER_AUTH_SESSION` e exporte no shell: `export COOKIE="BETTER_AUTH_SESSION=<valor>"`.
+
+### Usuários
+
+```bash
+# Listar usuários com acesso web
+curl -s http://localhost:3000/api/admin/users \
+  -H "Cookie: $COOKIE" \
+  -H "Accept: application/json" | jq '.users | map({ id, email, role })' # remova o pipe se não tiver jq
+
+# Criar usuário gestor (ajuste o e-mail se necessário)
+NEW_EMAIL="api.teste.$(date +%s)@sistema.dev"
+curl -s -X POST http://localhost:3000/api/admin/users \
+  -H "Cookie: $COOKIE" \
+  -H "Content-Type: application/json" \
+  -d "{\"name\":\"Usuário via curl\",\"email\":\"$NEW_EMAIL\",\"role\":\"manager\",\"tenantId\":\"tenant-atlas\"}" \
+  | tee /tmp/user-created.json
+
+# Remover o usuário recém-criado
+USER_ID=$(jq -r '.user.id' /tmp/user-created.json)
+curl -i -X DELETE http://localhost:3000/api/admin/users/$USER_ID \
+  -H "Cookie: $COOKIE"
+```
+
+> Os exemplos acima utilizam `jq` para facilitar a leitura. Se não estiver disponível, remova os pipes e leia o JSON bruto.
+
+### Convites
+
+```bash
+# Criar convite válido por 7 dias
+INVITE_EMAIL="convite.$(date +%s)@sistema.dev"
+curl -s -X POST http://localhost:3000/api/admin/invites \
+  -H "Cookie: $COOKIE" \
+  -H "Content-Type: application/json" \
+  -d "{\"email\":\"$INVITE_EMAIL\",\"name\":\"Convite via curl\",\"role\":\"collaborator\",\"tenantId\":\"tenant-atlas\",\"expiresInDays\":7}" \
+  | tee /tmp/invite-created.json
+
+# Revogar convite pendente
+INVITE_ID=$(jq -r '.invite.id' /tmp/invite-created.json)
+curl -i -X PATCH http://localhost:3000/api/admin/invites/$INVITE_ID \
+  -H "Cookie: $COOKIE" \
+  -H "Content-Type: application/json" \
+  -d '{"reason":"Revogado via curl"}'
+
+# Reativar (até 7 dias após a revogação)
+curl -i -X PATCH http://localhost:3000/api/admin/invites/$INVITE_ID \
+  -H "Cookie: $COOKIE" \
+  -H "Content-Type: application/json" \
+  -d '{"action":"reactivate"}'
+```
+
+> Dica: ao receber `409` na criação de convite, há outro convite pendente/aceito para o mesmo e-mail. Revogue ou remova o usuário antes.
+
 ## Desktop (Tauri)
 
 - Tabs Radix + estilos shadcn: `apps/desktop/src/components/ui/tabs.tsx`.
@@ -102,5 +159,5 @@ Artefatos: `apps/desktop/src-tauri/target/release/bundle/`.
 - **Plano do agente desktop / heartbeat**: `docs/plano-app-desktop-maquinas.md`.
 - **Histórico de incidentes**: `docs/historico-agente-desktop-2025-10-10.md`.
 
-> Última revisão: 16/10/2025. Atualize este guia sempre que o fluxo de DEV ou automações mudarem.
+> Última revisão: 18/10/2025. Atualize este guia sempre que o fluxo de DEV ou automações mudarem.
 - **Next.js 16 (beta)**: comportamento sujeito a mudanças. Antes de subir para stable, acompanhe o changelog oficial (quebra: `revalidateTag` com segundo argumento, params assíncronos, etc.). Já estamos compatíveis com os breaking changes atuais.