From f5b3abd27796bb28978b35240a3b09e1fc7d6406 Mon Sep 17 00:00:00 2001 From: codex-bot Date: Mon, 20 Oct 2025 16:24:16 -0300 Subject: [PATCH] docs: reorganize and simplify - Add docs/README.md as index - Consolidate ops in docs/operations.md; mark legacy runbooks as archive - Create docs/desktop/ and docs/admin/ structure and move relevant docs - Update root README to link docs index - Keep historical and planning notes under docs/archive/ --- README.md | 9 +- docs/OPERACAO-PRODUCAO.md | 4 +- docs/OPERATIONS.md | 144 ++++++++++++++++++ docs/README.md | 25 +++ docs/admin/.gitkeep | 1 + docs/{ => admin}/admin-inventory-ui.md | 0 docs/archive/.gitkeep | 1 + docs/{ => archive}/convex-self-hosted-env.md | 5 +- .../deploy-runbook.md} | 4 +- .../plano-app-desktop-maquinas.md | 2 +- .../setup-historico.md} | 4 +- .../status-2025-10-16.md} | 2 +- docs/{desktop-build.md => desktop/build.md} | 0 .../handshake-troubleshooting.md} | 0 .../updater.md} | 0 15 files changed, 190 insertions(+), 11 deletions(-) create mode 100644 docs/OPERATIONS.md create mode 100644 docs/README.md create mode 100644 docs/admin/.gitkeep rename docs/{ => admin}/admin-inventory-ui.md (100%) create mode 100644 docs/archive/.gitkeep rename docs/{ => archive}/convex-self-hosted-env.md (96%) rename docs/{DEPLOY-RUNBOOK.md => archive/deploy-runbook.md} (97%) rename docs/{ => archive}/plano-app-desktop-maquinas.md (99%) rename docs/{SETUP-HISTORICO.md => archive/setup-historico.md} (97%) rename docs/{STATUS-2025-10-16.md => archive/status-2025-10-16.md} (99%) rename docs/{desktop-build.md => desktop/build.md} (100%) rename docs/{desktop-handshake-troubleshooting.md => desktop/handshake-troubleshooting.md} (100%) rename docs/{desktop-updater.md => desktop/updater.md} (100%) diff --git a/README.md b/README.md index fe49ec3..b237ae1 100644 --- a/README.md +++ b/README.md @@ -42,10 +42,11 @@ Aplicação Next.js 15 com Convex e Better Auth para gestão de tickets da Rever > Se o CLI perguntar sobre configuração do projeto Convex, escolha criar um novo deployment local (opção padrão) e confirme. As credenciais são armazenadas em `.convex/` automaticamente. -### Deploy em produção (Traefik + Convex self‑hosted) -- Guia completo: `docs/OPERACAO-PRODUCAO.md:1`. -- Histórico de setup/decisões: `docs/SETUP-HISTORICO.md:1`. -- Stack Swarm: `stack.yml:1` (roteado por Traefik, rede `traefik_public`). +### Documentação +- Índice de docs: `docs/README.md` +- Operações (produção): `docs/operations.md` +- Guia de DEV: `docs/DEV.md` +- Stack Swarm: `stack.yml` (roteado por Traefik, rede `traefik_public`). ### Variáveis de ambiente diff --git a/docs/OPERACAO-PRODUCAO.md b/docs/OPERACAO-PRODUCAO.md index e2a7417..699fe55 100644 --- a/docs/OPERACAO-PRODUCAO.md +++ b/docs/OPERACAO-PRODUCAO.md @@ -1,4 +1,6 @@ -# Runbook de Operação — Produção (Traefik + Convex Self‑Hosted) +# Runbook de Operação — Produção (Traefik + Convex Self‑Hosted) — Arquivo + +Nota: este documento foi substituído por `docs/operations.md` e permanece aqui como histórico. > Documento vivo. Guia completo para (1) preparar a VPS, (2) fazer deploy com Traefik/Swarm, (3) publicar o backend Convex self‑hosted, (4) popular seeds e (5) operar/atualizar com ou sem CI/CD. Tudo em PT‑BR. diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md new file mode 100644 index 0000000..aaac97e --- /dev/null +++ b/docs/OPERATIONS.md @@ -0,0 +1,144 @@ +# 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). + diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..ff2f724 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,25 @@ +# Documentação — Sistema de Chamados + +Este índice consolida a documentação viva e move conteúdos históricos para um arquivo. O objetivo é simplificar o onboarding e a operação. + +## Visão Geral +- Operações (produção): `docs/operations.md` +- Guia de desenvolvimento: `docs/DEV.md` +- Desktop (Tauri): + - Build: `docs/desktop/build.md` + - Updater: `docs/desktop/updater.md` + - Handshake/troubleshooting: `docs/desktop/handshake-troubleshooting.md` +- Tickets: `docs/ticket-snapshots.md` +- Administração (UI): `docs/admin/admin-inventory-ui.md` + +## Arquivo (histórico/planejamento) +- `docs/archive/operacao-producao.md` (substituído por `docs/operations.md`) +- `docs/archive/deploy-runbook.md` +- `docs/archive/setup-historico.md` +- `docs/archive/status-2025-10-16.md` +- `docs/archive/convex-self-hosted-env.md` +- `docs/archive/plano-app-desktop-maquinas.md` +- `docs/archive/historico-agente-desktop-2025-10-10.md` + +Se algum conteúdo arquivado voltar a ser relevante, mova-o de volta, atualizando a data e o escopo. + diff --git a/docs/admin/.gitkeep b/docs/admin/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/docs/admin/.gitkeep @@ -0,0 +1 @@ + diff --git a/docs/admin-inventory-ui.md b/docs/admin/admin-inventory-ui.md similarity index 100% rename from docs/admin-inventory-ui.md rename to docs/admin/admin-inventory-ui.md diff --git a/docs/archive/.gitkeep b/docs/archive/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/docs/archive/.gitkeep @@ -0,0 +1 @@ + diff --git a/docs/convex-self-hosted-env.md b/docs/archive/convex-self-hosted-env.md similarity index 96% rename from docs/convex-self-hosted-env.md rename to docs/archive/convex-self-hosted-env.md index 753b307..6fce6e2 100644 --- a/docs/convex-self-hosted-env.md +++ b/docs/archive/convex-self-hosted-env.md @@ -1,4 +1,6 @@ -Convex Self‑Hosted — Configurar env e testar provisionamento +Convex Self‑Hosted — Configurar env e testar provisionamento (Arquivo) + +Nota: este documento foi arquivado. O fluxo atual de deploy/ops está em `docs/operations.md`. Pré‑requisitos - Rodar na VPS com Docker. @@ -52,4 +54,3 @@ TOKEN=$(node -e 'try{const j=require("fs").readFileSync("resp.json","utf8");proc [ -n "$TOKEN" ] && curl -sS -o /dev/null -w "%{http_code}\n" -X POST 'https://tickets.esdrasrenan.com.br/api/machines/heartbeat' \ -H 'Content-Type: application/json' \ -d '{"machineToken":"'"$TOKEN"'","status":"online","metrics":{"cpuPct":12,"memFreePct":61}}' - diff --git a/docs/DEPLOY-RUNBOOK.md b/docs/archive/deploy-runbook.md similarity index 97% rename from docs/DEPLOY-RUNBOOK.md rename to docs/archive/deploy-runbook.md index 1bcaa41..27a5914 100644 --- a/docs/DEPLOY-RUNBOOK.md +++ b/docs/archive/deploy-runbook.md @@ -1,4 +1,6 @@ -# Deploy runbook (Swarm) +# Deploy runbook (Swarm) — Arquivo + +Nota: este runbook foi arquivado. Utilize `docs/operations.md` para o fluxo atualizado de deploy. Este guia documenta o fluxo de deploy atual e os principais passos de diagnóstico/correção que resolveram o problema do front não atualizar mesmo com o CI verde. diff --git a/docs/plano-app-desktop-maquinas.md b/docs/archive/plano-app-desktop-maquinas.md similarity index 99% rename from docs/plano-app-desktop-maquinas.md rename to docs/archive/plano-app-desktop-maquinas.md index cb0b2cb..fb3a520 100644 --- a/docs/plano-app-desktop-maquinas.md +++ b/docs/archive/plano-app-desktop-maquinas.md @@ -1,4 +1,4 @@ -# Plano Integrado – App Desktop & Inventário por Máquina +# Plano Integrado – App Desktop & Inventário por Máquina (Arquivo) > Documento vivo. Atualize após cada marco relevante. diff --git a/docs/SETUP-HISTORICO.md b/docs/archive/setup-historico.md similarity index 97% rename from docs/SETUP-HISTORICO.md rename to docs/archive/setup-historico.md index 7e6e6ea..2ccc043 100644 --- a/docs/SETUP-HISTORICO.md +++ b/docs/archive/setup-historico.md @@ -1,4 +1,6 @@ -# Histórico de Setup e Decisões — Sistema de Chamados +# Histórico de Setup e Decisões — Sistema de Chamados (Arquivo) + +Conteúdo mantido como registro. Para operação e deploy atuais, ver `docs/operations.md`. > Registro das etapas realizadas, problemas encontrados e decisões tomadas para colocar o projeto em produção (Traefik + Swarm + Convex self‑hosted) com CI/CD via runner self‑hosted. diff --git a/docs/STATUS-2025-10-16.md b/docs/archive/status-2025-10-16.md similarity index 99% rename from docs/STATUS-2025-10-16.md rename to docs/archive/status-2025-10-16.md index 2a9a43b..69488df 100644 --- a/docs/STATUS-2025-10-16.md +++ b/docs/archive/status-2025-10-16.md @@ -1,4 +1,4 @@ -# Status do Projeto — 16/10/2025 +# Status do Projeto — 16/10/2025 (Arquivo) Documento de referência sobre o estado atual do sistema (web + desktop), melhorias recentes e pontos de atenção. diff --git a/docs/desktop-build.md b/docs/desktop/build.md similarity index 100% rename from docs/desktop-build.md rename to docs/desktop/build.md diff --git a/docs/desktop-handshake-troubleshooting.md b/docs/desktop/handshake-troubleshooting.md similarity index 100% rename from docs/desktop-handshake-troubleshooting.md rename to docs/desktop/handshake-troubleshooting.md diff --git a/docs/desktop-updater.md b/docs/desktop/updater.md similarity index 100% rename from docs/desktop-updater.md rename to docs/desktop/updater.md