sistema-de-chamados/docs/OPERATIONS.md

Operações — Sistema de Chamados (Prod)

Este documento consolida as mudanças recentes, o racional por trás delas e o procedimento de operação/deploy (Web e Convex self‑hosted) do ambiente em produção.

1) Mudanças Funcionais (Front + Server)

• Empresas (admin)

  • “Slug” renomeado para “Apelido” (mensagens e placeholders ajustados).

• Fila padrão ao criar tickets

  • Todo novo ticket entra na fila “Chamados”.
  • Implementado no backend (fallback) e pré‑seleção na UI.

• Status de tickets e interações

  • Nomes/cores atualizados:
    • Pendente (cinza), Em andamento (azul), Pausado (amarelo), Resolvido (verde).
  • Transições automáticas:
    • Iniciar (play) → status “Em andamento”.
    • Pausar → status “Pausado”.
  • “Encerrar” permanece manual. O dropdown foi substituído por badge + botão “Encerrar”.
  • Diálogo de encerramento: botão “Cancelar” adicionado (além de “Limpar mensagem”/“Encerrar ticket”).

• Dashboard — Últimos chamados

  • Prioridade: sem responsável primeiro (dos mais antigos para os mais recentes), depois demais chamados.

• Filtros de tickets

  • Filtro por “Responsável” (agente/admin) adicionado.
  • Salvar filtro como padrão por usuário (localStorage) + “Limpar padrão”.
  • Empresas no filtro: lista completa via API admin (não só empresas presentes em tickets).
  • Produção: filtro “Responsável” agora é feito no servidor (assigneeId); o front não envia mais parâmetros inválidos.

• Editor de comentários (Tiptap)

  • Correção: reativar edição quando um responsável é atribuído (o editor agora reflete mudanças em disabled via setEditable).

2) Convex (Self‑Hosted) — Ajustes e Motivo

• Problema observado: deploy do Convex falhava no CI por:

  • Ausência de convex.json (link do projeto) no servidor.
  • Uso incorreto de CONVEX_DEPLOYMENT junto a CONVEX_SELF_HOSTED_URL + CONVEX_SELF_HOSTED_ADMIN_KEY (não suportado pelo CLI ao usar self‑hosted).
  • Divergência de schema (campo provisioningCode já existente nos dados, mas ausente no schema do Convex no servidor).

• Medidas aplicadas:

  • Atualização do schema do Convex no servidor: inclusão de provisioningCode?: string na tabela companies (e índice opcional by_provisioning_code).
  • Criação do link de projeto (convex.json) no servidor via wizard do CLI (ver Passo a passo abaixo).
  • Ajustes no workflow do GitHub Actions para self‑hosted:
    • Adicionado passo “Acquire Convex admin key” no job de deploy do Convex.
    • Removido CONVEX_DEPLOYMENT quando CONVEX_SELF_HOSTED_URL + CONVEX_SELF_HOSTED_ADMIN_KEY estão definidos.
    • Cópia automática do convex.json de /srv/apps/sistema para o diretório de build temporário.
  • Forçar redeploy das funções: tocar arquivos sob convex/** para acionar o filtro do job “Deploy Convex functions”.

3) CI/CD — Visão Geral

• Pipeline “CI/CD Web + Desktop” (GitHub Actions)

  • Job “Detect changes” usa filtros por paths.
  • Job “Deploy (VPS Linux)” cuida do Web (Next.js) e stack do Swarm.
  • Job “Deploy Convex functions” roda quando há mudanças em convex/** ou via workflow_dispatch.
    • Passos relevantes:
      • “Acquire Convex admin key” (via container sistema_convex_backend).
      • “Bring convex.json from live app if present” (usa o arquivo de link do projeto em /srv/apps/sistema).
      • “convex env list” e “convex deploy” com CONVEX_SELF_HOSTED_URL + CONVEX_SELF_HOSTED_ADMIN_KEY.
    • Importante: não usar CONVEX_DEPLOYMENT em conjunto com URL + ADMIN_KEY.

• Como forçar o deploy do Convex

  • Faça uma alteração mínima em convex/** (ex.: comentário em convex/tickets.ts) ou rode o workflow em “Run workflow” (workflow_dispatch).

4) Convex — Provisionamento inicial (self‑hosted)

Executar apenas 1x na VPS para criar o link do projeto (convex.json):

cd /srv/apps/sistema
export CONVEX_SELF_HOSTED_URL="https://convex.esdrasrenan.com.br"
CID=$(docker ps --format '{{.ID}} {{.Names}}' | awk '/sistema_convex_backend/{print $1; exit}')
export CONVEX_SELF_HOSTED_ADMIN_KEY="$(docker exec -i "$CID" /bin/sh -lc './generate_admin_key.sh' | tr -d '\r' | grep -o 'convex-self-hosted|[^ ]*' | tail -n1)"

npx convex dev --once --configure=new
# Siga o wizard (self-hosted) e vincule/crie o projeto/deployment (ex.: "sistema" / "default").
# Isso gera /srv/apps/sistema/convex.json

Depois disso, o job “Deploy Convex functions” funciona em modo não interativo.

5) VPS — Acesso e Serviços

• Acesso

  • Host: 31.220.78.20
  • Usuário: root
  • Chave SSH (repo raiz): ./codex_ed25519 (Atenção: manter permissões 600)
    • Exemplo: ssh -i ./codex_ed25519 root@31.220.78.20
  • Opcional (endurecimento): desabilitar login por senha após validar a chave.

• Diretórios principais

  • Código do app: /srv/apps/sistema
  • Arquivo do projeto Convex: /srv/apps/sistema/convex.json
  • Stack do Swarm: stack.yml (no repositório; aplicado no servidor via CI).

• Serviços (Docker Swarm + Traefik)

  • Web (Next.js): serviço sistema_web, exposto em tickets.esdrasrenan.com.br.
  • Convex backend: serviço sistema_convex_backend, exposto em convex.esdrasrenan.com.br.
  • Convex dashboard: convex-admin.esdrasrenan.com.br.
  • Comandos úteis:
    • docker service ls
    • docker service ps sistema_web
    • docker service update --force sistema_web (reiniciar)
    • docker service update --force sistema_convex_backend (reiniciar Convex)

• Convex admin key (diagnóstico)

  • docker exec -i $(docker ps | awk '/sistema_convex_backend/{print $1; exit}') /bin/sh -lc './generate_admin_key.sh'
  • Usada no CI para convex env list e convex deploy.

6) Notas de Segurança

• A chave privada codex_ed25519 está na raiz do repo (ambiente atual). Em produção, recomenda‑se:
  • Remover a chave do repositório ou armazená‑la em Secrets/Deploy keys do provedor.
  • Desabilitar login por senha no SSH (apenas chave).
  • Manter permissões: chmod 600 ./codex_ed25519.

7) Testes, Build e Lint

• Local

  • pnpm build (Next + typecheck)
  • pnpm lint
  • pnpm test

• CI garante build, lint e testes antes do deploy.

8) Troubleshooting Rápido

• “No CONVEX_DEPLOYMENT set” durante o deploy do Convex

  • Certifique‑se de que /srv/apps/sistema/convex.json existe (rodar wizard npx convex dev --once --configure=new).
  • Não usar CONVEX_DEPLOYMENT com CONVEX_SELF_HOSTED_URL + CONVEX_SELF_HOSTED_ADMIN_KEY.

• “Schema validation failed” (campo extra provisioningCode)

  • Atualize o schema do Convex no servidor para incluir provisioningCode?: string em companies.
  • Refaça o deploy.

• Filtro “Responsável” não funciona

  • Front envia assigneeId e o backend Convex deve aceitar esse parâmetro (função tickets.list).
  • Se necessário, forçar redeploy das funções (convex/**).

---

Última atualização: sincronizado após o deploy bem‑sucedido do Convex e do Front (20/10/2025).