Docs: document Users/Machines unification, company filter in Machines, Windows OS label, and identity/email/history guidance in OPERATIONS.md

docs/OPERATIONS.md

@@ -142,3 +142,41 @@ Depois disso, o job “Deploy Convex functions” funciona em modo não interati
 
 Última atualização: sincronizado após o deploy bem‑sucedido do Convex e do Front (20/10/2025).
 
+## 9) Admin ▸ Usuários e Máquinas — Unificação e UX
+
+Resumo das mudanças aplicadas no painel administrativo para simplificar “Usuários” e “Agentes de máquina” e melhorar o filtro em Máquinas:
+
+- Unificação de “Usuários” e “Agentes de máquina”
+  - Antes: abas separadas “Usuários” (pessoas) e “Agentes de máquina”.
+  - Agora: uma só aba “Usuários” com filtro de tipo (Todos | Pessoas | Máquinas).
+  - Onde: `src/components/admin/admin-users-manager.tsx:923`, aba `value="users"` em `:1147`.
+  - Motivo: evitar confusão entre “usuário” e “agente”; agentes são um tipo especial de usuário (role=machine). A unificação torna “Convites e Acessos” mais direta.
+
+- Máquinas ▸ Filtro por Empresa com busca e remoção do filtro de SO
+  - Adicionado dropdown de “Empresa” com busca (Popover + Input) e removido o filtro por Sistema Operacional.
+  - Onde: `src/components/admin/machines/admin-machines-overview.tsx:1038` e `:1084`.
+  - Motivo: fluxo real usa empresas com mais frequência; filtro por SO era menos útil agora.
+
+- Windows ▸ Rótulo do sistema sem duplicidade do “major”
+  - Exemplo: “Windows 11 Pro (26100)” em vez de “Windows 11 Pro 11 (26100)”.
+  - Onde: `src/components/admin/machines/admin-machines-overview.tsx` (função `formatOsVersionDisplay`).
+  - Motivo: legibilidade e padronização em chips/cartões.
+
+- Vínculos visuais entre máquinas e pessoas
+  - Cards de máquinas mostram “Usuário vinculado” quando disponível (assignment/metadata): `src/components/admin/machines/admin-machines-overview.tsx:3198`.
+  - Editor de usuário exibe “Máquinas vinculadas” (derivado de assign/metadata): `src/components/admin/admin-users-manager.tsx` (seção “Máquinas vinculadas” no sheet de edição).
+  - Observação: por ora é leitura; ajustes detalhados de vínculo permanecem em Admin ▸ Máquinas.
+
+### Identidade, e‑mail e histórico (reinstalação)
+
+- Identificador imutável: o histórico (tickets, eventos) referencia o `userId` (imutável). O e‑mail é um atributo mutável.
+- Reinstalação do desktop para o mesmo colaborador: reutilize a mesma conta de usuário (mesmo `userId`); se o e‑mail mudou, atualize o e‑mail dessa conta no painel. O histórico permanece, pois o `userId` não muda.
+- Novo e‑mail como nova conta: se criar um usuário novo (novo `userId`), será considerado um colaborador distinto e não herdará o histórico.
+- Caso precise migrar histórico entre contas diferentes (merge), recomendamos endpoint/rotina de “fusão de contas” (remapear `userId` antigo → novo). Não é necessário para a troca de e‑mail da mesma conta.
+
+### Onde editar
+
+- Usuários (pessoas): editar nome, e‑mail, papel, tenant e empresa; redefinir senha pelo painel. Arquivo: `src/components/admin/admin-users-manager.tsx`.
+- Agentes (máquinas): provisionamento automático; edição detalhada/vínculo principal em Admin ▸ Máquinas. Arquivo: `src/components/admin/machines/admin-machines-overview.tsx`.
+
+> Observação operacional: mantivemos o provisionamento de máquinas inalterado (token/e‑mail técnico), e o acesso web segue apenas para pessoas. A unificação é de UX/gestão.