Merge pull request #13 from assertlab/docs/atualizacao-geral

docs: revisão geral de consistência e atualização pós-migração Oracle…

Author: vinicius3w

README.md

@@ -38,21 +38,22 @@ O cutuCÃO nasce de uma filosofia simples: **o aluno é dono do próprio progres
 | `/exportar`       | Exporta registros em JSON com filtros (canal, nível, período, tudo) | Orientador |
 | `/limpar`         | Remove registros com confirmação obrigatória e opção de exportar antes | Orientador |
 | `/teste-lembrete` | Dispara manualmente o job de lembrete                              | Orientador |
+| `/teste-boas-vindas` | Simula a mensagem de boas-vindas no canal de entrada            | Orientador |
 
 **Detecção automática** — Canais com prefixo `phd-`, `msc-` ou `bsc-` na categoria "Orientações" são monitorados automaticamente. Criou um canal novo? O cutuCÃO já começa a vigiar.
 
 ## Stack
 
-- **Runtime:** Node.js 18+
+- **Runtime:** Node.js 20+
 - **Linguagem:** TypeScript
 - **Framework:** discord.js v14
 - **Banco de dados:** SQLite (via better-sqlite3)
 - **Agendamento:** node-cron
-- **Hospedagem:** Railway
+- **Hospedagem:** Oracle Cloud Free Tier (VPS com Node.js + systemd)
 
 ## Pré-requisitos
 
-- [Node.js](https://nodejs.org/) 18 ou superior
+- [Node.js](https://nodejs.org/) 20 ou superior
 - [Git](https://git-scm.com/)
 - Uma aplicação de bot criada no [Discord Developer Portal](https://discord.com/developers/applications)
 
@@ -186,14 +187,18 @@ Consulte a [seção 9 da SPEC.md](SPEC.md) para detalhes completos.
 
 ## Deploy
 
-O cutuCÃO roda em produção no [Railway](https://railway.app):
+O cutuCÃO roda em produção em uma VM gratuita do Oracle Cloud Free Tier, com o processo gerenciado por systemd. Consulte [docs/deploy-oracle-cloud.md](docs/deploy-oracle-cloud.md) para o guia completo de deploy no Oracle Cloud Free Tier, incluindo criação da instância, instalação do Node.js, serviço systemd e script de atualização.
 
-1. Conecte o repositório GitHub ao Railway
-2. Configure as variáveis de ambiente no dashboard (nunca no código)
-3. Adicione um volume montado em `/app/data` para persistência do SQLite
-4. O deploy acontece automaticamente a cada push na `main`
+Outras opções de hospedagem: Fly.io ou qualquer VPS com Node.js. Em qualquer plataforma, configure as variáveis de ambiente fora do código e garanta persistência do arquivo SQLite em disco.
 
-Outras opções de hospedagem: Fly.io, Oracle Cloud Free Tier, ou qualquer VPS com Node.js.
+## Documentação
+
+Além deste README e da [SPEC.md](SPEC.md) (especificação técnica completa), a pasta `docs/` reúne:
+
+- [docs/guia-operacional.md](docs/guia-operacional.md): premissas do servidor, convenções de nomenclatura, configuração via `config.json`, variáveis de ambiente, comandos de gestão de dados e troubleshooting.
+- [docs/deploy-oracle-cloud.md](docs/deploy-oracle-cloud.md): guia de deploy no Oracle Cloud Free Tier, do zero, com instância gratuita permanente e serviço systemd.
+- [docs/migracao-railway-oracle.md](docs/migracao-railway-oracle.md): registro da migração da hospedagem do Railway para o Oracle Cloud (referência histórica).
+- [docs/melhorias-es.md](docs/melhorias-es.md): proposta de melhorias de engenharia de software (Fases 5 e 6), com o estado de cada item.
 
 ## Contribuindo
 
@@ -229,6 +234,7 @@ Usamos [Conventional Commits](https://www.conventionalcommits.org/):
 ## Roadmap
 
 - [x] **v1.0.0** — Lembretes, cobrança, resumo semanal, boas-vindas, comandos básicos
+- [x] **v1.1.0**: Engenharia de software: mensagens externalizadas em JSON, padrão Repository, testes automatizados (Vitest)
 - [x] **v1.2.0** — Configuração por arquivo (`config.json`): categorias, prefixos, horários, escalação
 - [x] **v1.3.0** — Gestão de dados: `/uso`, `/exportar` (JSON por DM), `/limpar` (com confirmação por botão)
 - [ ] Comandos `/config` para configuração em tempo real (sem reiniciar o bot)
@@ -248,7 +254,7 @@ O cutuCÃO foi criado para o ASSERT Lab, mas pode ser adaptado para qualquer gru
 5. Copie `config.example.json` para `config.json` e ajuste categorias, prefixos, horários e demais configurações
 6. Faça deploy
 
-O bot detecta canais automaticamente — sem alterar código. Consulte o `config.example.json` para todas as opções de customização.
+O bot detecta canais automaticamente, sem alterar código. Consulte o `config.example.json` para todas as opções de customização. Para o deploy, o [guia do Oracle Cloud](docs/deploy-oracle-cloud.md) cobre a instalação completa do zero em uma VM gratuita no Oracle Cloud Free Tier.
 
 ## Licença
 

SPEC.md

@@ -1,6 +1,6 @@
 # cutuCÃO 🐕 — Especificação Técnica
 
-**Projeto:** cutuCÃO — Bot Discord do ASSERT Lab (CIn-UFPE) **Mascote:** Vira-lata caramelo com megafone **Objetivo:** Automatizar o acompanhamento de orientandos, substituindo o Carl-bot por uma solução própria com controle total. **Stack:** TypeScript + discord.js **Hospedagem:** Nuvem (gratuito ou baixo custo) **Repositório:** `cutucao-bot`
+**Projeto:** cutuCÃO — Bot Discord do ASSERT Lab (CIn-UFPE) **Mascote:** Vira-lata caramelo com megafone **Objetivo:** Automatizar o acompanhamento de orientandos, substituindo o Carl-bot por uma solução própria com controle total. **Stack:** TypeScript + discord.js **Hospedagem:** Oracle Cloud Free Tier (VPS com Node.js + systemd) **Repositório:** `cutucao-bot`
 
 ---
 
@@ -106,18 +106,29 @@ Dúvidas? É só perguntar no #café!
 
 ### 2.4. Comandos utilitários
 
+**Implementados:**
+
+| Comando             | Descrição                                                     | Quem pode usar |
+| ------------------- | ------------------------------------------------------------- | -------------- |
+| `/template`         | Exibe o template de check-in para copiar e colar              | Todos          |
+| `/ajuda`            | Exibe lista de comandos disponíveis                           | Todos          |
+| `/status`           | Mostra o status de check-in da semana (quem postou, quem não) | Orientador     |
+| `/resumo #canal`    | Mostra o histórico de check-ins do canal (semanas configuráveis) | Orientador  |
+| `/uso`              | Estatísticas do banco (registros, canais, tamanho, breakdown por nível) | Orientador |
+| `/exportar`         | Exporta registros em JSON (DM, filtros: canal/nível/período/tudo)       | Orientador |
+| `/limpar`           | Remove registros do banco com confirmação obrigatória por botão         | Orientador |
+| `/teste-lembrete`   | Dispara manualmente o job de lembrete de check-in             | Orientador     |
+| `/teste-boas-vindas`| Simula a mensagem de boas-vindas no canal de entrada          | Orientador     |
+
+**Planejados (roadmap, ainda não implementados):**
+
 | Comando              | Descrição                                                     | Quem pode usar |
 | -------------------- | ------------------------------------------------------------- | -------------- |
-| `/template`          | Exibe o template de check-in para copiar e colar              | Todos          |
-| `/status`            | Mostra o status de check-in da semana (quem postou, quem não) | Orientador     |
-| `/resumo @aluno`     | Mostra o histórico de check-ins do aluno (últimas 4 semanas)  | Orientador     |
-| `/uso`               | Estatísticas do banco (registros, canais, tamanho, breakdown por nível) | Orientador |
-| `/exportar`          | Exporta registros em JSON (DM, filtros: canal/nível/período/tudo)       | Orientador |
-| `/limpar`            | Remove registros do banco com confirmação obrigatória por botão        | Orientador |
 | `/config canais`     | Lista os canais monitorados e permite adicionar/remover       | Orientador     |
 | `/config orientador` | Define quem recebe os resumos semanais (por ID do Discord)    | Orientador     |
 | `/config horarios`   | Ajusta horários de lembrete, cobrança e resumo                | Orientador     |
-| `/ajuda`             | Exibe lista de comandos disponíveis                           | Todos          |
+
+Até que os comandos `/config` existam, categorias, prefixos, canal de boas-vindas e horários são ajustados via `config.json` (seção 10), com reinício do bot.
 
 ### 2.4.1. Comandos de gestão de dados (orientador)
 
@@ -209,24 +220,29 @@ cutucao-bot/
 │   ├── database.ts              # Setup e queries SQLite
 │   ├── commands/
 │   │   ├── template.ts          # /template
+│   │   ├── ajuda.ts             # /ajuda
 │   │   ├── status.ts            # /status
-│   │   ├── resumo.ts            # /resumo @aluno
-│   │   ├── config.ts            # /config (subcomandos)
-│   │   └── ajuda.ts             # /ajuda
+│   │   ├── resumo.ts            # /resumo #canal
+│   │   ├── uso.ts               # /uso
+│   │   ├── exportar.ts          # /exportar
+│   │   ├── limpar.ts            # /limpar (+ limparState.ts)
+│   │   ├── testeLembrete.ts     # /teste-lembrete
+│   │   └── testeBoasVindas.ts   # /teste-boas-vindas
 │   ├── events/
 │   │   ├── ready.ts             # Inicialização, registro de comandos
 │   │   ├── guildMemberAdd.ts    # Boas-vindas
 │   │   ├── messageCreate.ts     # Detecta check-ins nos canais monitorados
-│   │   └── channelCreate.ts     # Detecta novos canais na categoria Orientações
+│   │   ├── channelCreate.ts     # Detecta novos canais na categoria Orientações
+│   │   └── interactionCreate.ts # Roteia slash commands e botões
 │   ├── jobs/
 │   │   ├── scheduler.ts         # Setup do node-cron
 │   │   ├── lembrete.ts          # Job de segunda 09:00
 │   │   ├── cobranca.ts          # Job de quarta 09:00
 │   │   └── resumo.ts            # Job de sexta 18:00
-│   └── utils/
-│       ├── canais.ts            # Helpers para identificar canais de orientação
-│       ├── formatters.ts        # Formatação de mensagens
-│       └── semana.ts            # Cálculo de semana ISO, datas
+│   ├── repositories/            # Padrão Repository (checkins e configuração)
+│   ├── mensagens/               # Templates de mensagens externalizados (templates.json)
+│   ├── config/                  # Carregamento e validação do config.json
+│   └── utils/                   # Helpers (canais, formatação, semana ISO, validação, log)
 ├── package.json
 ├── tsconfig.json
 ├── .env                         # DISCORD_TOKEN, GUILD_ID, ORIENTADOR_ID
@@ -328,31 +344,23 @@ TZ=America/Recife
 
 ## 7. Hospedagem
 
-### Opção recomendada: Railway (https://railway.app)
+### Opção recomendada: Oracle Cloud Free Tier
 
-- **Plano gratuito:** $5/mês de crédito gratuito (mais que suficiente para um bot leve).
-- Deploy direto do GitHub.
-- Suporte nativo a Node.js/TypeScript.
-- Persistent disk para o SQLite.
-- Boa confiabilidade e uptime.
+- **Custo:** gratuito permanente (não é trial). Uma VM AMD Micro (1 OCPU, 1 GB RAM) é suficiente; o bot consome menos de 30 MB.
+- VM completa com controle total, processo gerenciado por systemd (reinício automático após crash ou reboot).
+- Sem limites de tempo e sem suspensão por inatividade.
+- Persistência do SQLite em disco local da instância.
+
+O guia completo de deploy (criação da instância, Node.js, systemd, script de atualização) está em [docs/deploy-oracle-cloud.md](docs/deploy-oracle-cloud.md).
 
 ### Alternativas
 
-| Plataforma                 | Custo                     | Observações                                                                                   |
+| Plataforma                 | Custo                     | Observações                                                                                    |
 | -------------------------- | ------------------------- | --------------------------------------------------------------------------------------------- |
-| **Render** (render.com)    | Gratuito (com limitações) | Plano free pode suspender após inatividade — ruim para bots que precisam estar sempre online. |
-| **Fly.io**                 | Gratuito (com limites)    | Bom para bots leves. Requer um pouco mais de configuração.                                    |
-| **Oracle Cloud Free Tier** | Gratuito permanente       | VM completa gratuita. Mais trabalho de setup, mas sem limites de tempo.                       |
-| **VPS própria**            | ~$5/mês                   | DigitalOcean, Hetzner. Controle total.                                                        |
-
-### Setup no Railway
-
-```bash
-# 1. Criar repositório no GitHub com o código do bot
-# 2. Conectar o repositório ao Railway
-# 3. Configurar variáveis de ambiente no dashboard do Railway
-# 4. Deploy automático a cada push
-```
+| **Fly.io**                 | Gratuito (com limites)    | Bom para bots leves; requer um pouco mais de configuração.                                     |
+| **VPS própria**            | ~$5/mês                   | DigitalOcean, Hetzner; controle total, mesma abordagem de Node.js + systemd.                   |
+| **Railway** (railway.app)  | $5/mês de crédito         | Alternativa histórica: foi a hospedagem original do projeto (deploy direto do GitHub, persistent disk). Migrado para Oracle Cloud. |
+| **Render** (render.com)    | Gratuito (com limitações) | Plano free pode suspender após inatividade; ruim para bots que precisam estar sempre online.   |
 
 ---
 
@@ -398,7 +406,7 @@ Esta seção define os requisitos de segurança do cutuCÃO. O bot opera em um s
 **Token do bot:**
 
 - NUNCA commitado no repositório. O `.gitignore` deve incluir `.env`, `*.db`, `data/`, e qualquer arquivo de configuração local.
-- Armazenado exclusivamente via variáveis de ambiente da plataforma de hospedagem (Railway, Fly.io, etc.).
+- Armazenado exclusivamente via variáveis de ambiente da plataforma de hospedagem (no Oracle Cloud, via arquivo `.env` lido pelo systemd; em PaaS como Fly.io, via dashboard).
 - Rotação do token a cada 6 meses ou imediatamente em caso de suspeita de comprometimento (via Discord Developer Portal → Bot → Reset Token).
 - Se o repositório for público, habilitar o GitHub Secret Scanning para detecção automática de tokens expostos.
 
@@ -416,7 +424,7 @@ dist/
 **Variáveis de ambiente no CI/CD:**
 
 - Nunca usar variáveis de ambiente em arquivos de configuração do repositório (ex: `docker-compose.yml` com valores hardcoded).
-- No Railway/Fly.io, configurar via dashboard — nunca via CLI em logs compartilhados.
+- No Oracle Cloud, manter o `.env` com permissões restritas na VM (fora do Git); em PaaS, configurar via dashboard, nunca via CLI em logs compartilhados.
 
 ### 9.3. Princípio do menor privilégio
 
@@ -457,7 +465,7 @@ O bot deve recusar operar em qualquer servidor que não seja o GUILD_ID configur
 
 **Toda entrada do usuário é potencialmente maliciosa.** Isso inclui:
 
-- Parâmetros de slash commands (`/config horarios`, `/resumo @aluno`)
+- Parâmetros de slash commands (`/config horarios`, `/resumo #canal`)
 - Nomes de canais (usados para extrair nível phd/msc/bsc)
 - Nomes de usuário (usados em mensagens de boas-vindas)
 
@@ -557,7 +565,7 @@ db.exec(`SELECT * FROM checkins WHERE canalId = '${canalId}'`);
 
 **Backup:**
 
-- Configurar backup automático semanal do arquivo `.db` (no Railway, usar o persistent disk).
+- Configurar backup automático semanal do arquivo `.db` (no Oracle Cloud, um cron na VM copiando `data/cutucao.db` para outro diretório ou bucket).
 - Se usar Turso, os backups são automáticos.
 - O arquivo de banco NUNCA deve estar no repositório Git.
 
@@ -624,7 +632,7 @@ async function enviarComRateLimit(
 
 ### 9.11. Segurança na hospedagem
 
-**Railway / Fly.io / qualquer PaaS:**
+**Oracle Cloud / Fly.io / qualquer VPS ou PaaS:**
 
 - Habilitar 2FA (autenticação de dois fatores) na conta da plataforma de hospedagem.
 - Habilitar 2FA na conta do Discord Developer Portal.
@@ -679,7 +687,7 @@ Antes de colocar o cutuCÃO em produção, verificar todos os itens:
 - [x] Resumo semanal para o orientador (sexta 18:00) com ephemeral DM
 - [x] Controle de acesso a comandos (seção 9.5)
 - [x] Sanitização de entrada em todos os inputs (seção 9.4)
-- [ ] Deploy no Railway com 2FA habilitado
+- [x] Deploy no Oracle Cloud Free Tier (systemd) com 2FA habilitado
 - [ ] Executar checklist de segurança (seção 9.13)
 
 ### Fase 2 — Complementos

docs/deploy-oracle-cloud.md

@@ -377,6 +377,7 @@ sudo journalctl -u cutucao --since "24 hours ago"
 | Shape | VM.Standard.E2.1.Micro |
 | CPU / RAM | 1 OCPU / 1 GB |
 | OS | Ubuntu 24.04 LTS |
+| Node.js | 20+ (guia instala 20.x) |
 | Custo | Gratuito permanente |
 | Usuário SSH | `ubuntu` |
 | Diretório do bot | `/home/ubuntu/cutucao-bot` |