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`):

```bash
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).