Gerencia

Ultima atualizacao: 19 de Outubro 2025

Visao Geral do Projeto

Termo de Abertura

Titulo do projeto: Pro-Mata

Semestre: 2025/2 - 2a-feira e 4a-feira - 17:30-19:00 (2JK4JK)

Justificativa: A plataforma digital de hotelaria para o Centro de Pesquisas e Protecao da Natureza (CPPN) Pro-Mata justifica-se pela necessidade de oferecer um canal eficiente, acessivel e integrado que facilite a gestao e o acesso aos diversos servicos disponibilizados pelo centro. Especificamente, busca criar uma ferramenta online que permita ampliar o publico, facilitar o processo de reservas, agendamento e planejamento, alem de promover maior transparencia e comodidade para os usuarios.

Objetivos: Desenvolver uma plataforma digital Web de hotelaria para o Centro de Pesquisas e Protecao da Natureza (CPPN) Pro-Mata, visando oferecer um sistema eficiente, acessivel e integrado para a gestao das reservas e servicos do centro.

Descricao em Alto Nivel

No escopo:

• Identificacao do usuario externo: alunos e professores da PUCRS, alunos e professores de outras universidades e publico geral
• Modulo administrativo: atualizacao de informacoes da plataforma, elaboracao de relatorios de multiplas reservas e emissao de confirmacoes
• Modulo de reservas de hospedagem, atividades e demais servicos: usuarios externos e administrativos podem consultar disponibilidade de quartos (individuais e coletivos), laboratorios, salas multiuso e auditorio
• Agendamento de atividades: trilhas interpretativas, visitas turisticas, retiros espirituais, cursos e eventos academicos
• Acesso a diversas formas de pagamento com anexacao de comprovantes

Nao esta no escopo:

• Integracao com portais de pagamento (gateways)

Tecnologia: Web (React 19 + NestJS)

Stakeholder e Orientacao

• Stakeholder: Prof.Dr. Augusto Mussi Alvim
• Professor Orientador: Prof.Dr. Edson Moreno

Equipe e Estrutura Organizacional

AGES IV (Gerenciamento de Projeto de Software)

• Andre Sacilotto Santos
• Arthur Pizzolatti Igansi
• Eduarda Lodi Bertiz
• Lucas Ulsenheimer Lantieri

Responsabilidades: Planejamento estrategico, monitoramento de sprints, facilitacao de cerimonias Scrum, gestao de riscos, documentacao (Wiki GitLab), comunicacao com stakeholder

Entregas: Wiki atualizada, atas de reunioes, retrospectivas documentadas, metricas de sprint, relatorios de progresso

AGES III (Arquitetura de Software)

• Joao Henrique Pires Bergallo
• Kayky BalleBoni Casagrande

Responsabilidades: Definicao de arquitetura, setup CI/CD, code review, aprovacao de PRs, definicao de padroes tecnicos, gestao de infraestrutura

Entregas: Documentacao de arquitetura, pipelines CI/CD funcionais, aprovacoes de PRs, padroes de codigo definidos

AGES II (Analise e Projeto de BD)

• Guilherme Dentzien
• Henrique Pinho Valente Schultz
• Jayme Eduardo Fortes
• Rafaela do Nascimento Mello
• Samuel Ribeiro Bitdinger

Responsabilidades: Modelagem de banco de dados, analise de requisitos, criacao de migrations, otimizacao de queries, validacao de regras de negocio

Entregas: Modelo ER, schema Prisma, migrations, documentacao de BD, validacao de user stories

AGES I (Desenvolvimento de Software)

• Felipe Prunes Rambor
• Matias Stockey Pereira
• Pedro Costa Widholzer

Responsabilidades: Implementacao de funcionalidades, testes unitarios e de integracao, correcao de bugs, desenvolvimento frontend e backend

Entregas: Codigo funcional, testes com cobertura ≥70%, correcoes de bugs, implementacao de user stories

Matriz de Responsabilidade (RACI)

Legenda:

• R (Responsavel): Executa a atividade
• A (Aprovador): Autoridade final de aprovacao
• C (Consultado): Fornece input especializado
• I (Informado): Recebe atualizacoes
• P (Participa): Colabora ativamente

Metodologia Scrum

Framework: Scrum com sprints de ~3 semanas (varia conforme calendario academico)

Cerimônias

Daily - 3 Perguntas

1. O que fiz desde a ultima daily?
2. O que farei ate a proxima?
3. Ha impedimentos?

Observacao:

• Dailys presenciais ocorrem em aulas (2a e 4a-feira, 17:30)
• Dailys de sabado via Discord por texto (organizadas via eventos Discord em canal especifico)
• Nao sao diarias como em Scrum tradicional, adaptacao ao calendario academico

Calendario e Sprints

Calendario Academico 2025/2

O projeto segue o calendario academico da PUCRS com sprints de aproximadamente 3 semanas:

Observacoes:

• Sprint 0 e preparatoria (4 semanas)
• Sprints 1-4 seguem duracao de ~3 semanas
• Datas podem variar conforme feriados e calendario academico
• Code Freeze: 2 dias antes de cada Sprint Review
• Ver Sprints para detalhamento de cada sprint

Marcos (Milestones)

Estrutura Analitica do Projeto (EAP)

1. Pro-Mata
   1.1 Gestao
       1.1.1 Planejamento
       1.1.2 Documentacao (Wiki GitLab)
       1.1.3 Monitoramento (GitLab Issues/GitHub Projects)

   1.2 Arquitetura
       1.2.1 Definicao
       1.2.2 Setup CI/CD (GitHub Actions)
       1.2.3 Deploy AWS (S3 + EC2)
       1.2.4 Infraestrutura Backup (Azure/Terraform - repositorio pessoal)

   1.3 Backend (API REST)
       1.3.1 Autenticacao JWT
       1.3.2 Gestao Reservas
       1.3.3 Gestao Experiencias (Quartos/Espacos/Atividades)
       1.3.4 Gestao Usuarios (PUCRS/Externa)
       1.3.5 Gestao Comprovantes
       1.3.6 Relatorios Administrativos
       1.3.7 Notificacoes
       1.3.8 Analytics (Umami)

   1.4 Frontend (Web)
       1.4.1 Login/Registro
           1.4.1.1 Usuarios PUCRS
           1.4.1.2 Usuarios Externos
       1.4.2 Dashboard Usuario
       1.4.3 Sistema Reservas
           1.4.3.1 Hospedagem (Quartos)
           1.4.3.2 Espacos (Lab, Auditorio, Salas)
           1.4.3.3 Atividades (Trilhas, Eventos)
       1.4.4 Upload Comprovantes
       1.4.5 Painel Administrativo
           1.4.5.1 Gestao Reservas
           1.4.5.2 Relatorios
           1.4.5.3 Confirmacoes
       1.4.6 Responsividade

   1.5 Banco de Dados
       1.5.1 Modelagem
       1.5.2 Migrations (Prisma)
       1.5.3 Seeds (dados teste)

   1.6 Testes
       1.6.1 Unitarios (70%+ cobertura)
       1.6.2 Integracao (Vitest + MSW)
       1.6.3 E2E (Playwright)

   1.7 Documentacao
       1.7.1 Wiki GitLab (manual)
       1.7.2 README repos GitLab/GitHub
       1.7.3 API Docs (Swagger)
       1.7.4 Manual Usuario

Gestao de Tarefas

Workflow: GitLab como Oficial, GitHub como Desenvolvimento

O projeto utiliza GitLab como plataforma oficial (requisito institucional AGES):

GitLab (Oficial - tools.ages.pucrs.br):

• Repositorios: Codigo-fonte oficial (mirror sincronizado)
• Wiki: Documentacao centralizada
• Issues: Mirror automatico das issues do GitHub (sincronizacao simplificada)
• Requisito: Padrao institucional AGES

GitHub (Desenvolvimento - AGES-Pro-Mata):

• Repositorios: Desenvolvimento ativo
• Projects: Kanban privado (restrito a membros da org)
• Issues: Gestao de tarefas principal
• CI/CD: GitHub Actions (pipelines de deploy)
• Code Review: Pull Requests

Sincronizacao Automatica GitHub → GitLab:

• Codigo: Mirror completo (branches, commits, tags)
• Issues: Sincronizacao simplificada das issues privadas do GitHub
• Frequencia: A cada commit/issue criada ou atualizada
• Link GitLab Issues: https://tools.ages.pucrs.br/groups/pro-mata/-/issues

Motivacao da estrutura hibrida:

• Equipe utiliza GitHub para desenvolvimento diario (familiaridade, ferramentas, Projects privado)
• GitLab atende requisitos institucionais AGES (padrao, auditoria, transparencia)
• Sincronizacao automatica garante conformidade sem duplicar trabalho manual

Board Kanban

Ferramenta: GitHub Projects (privado - https://github.com/orgs/AGES-Pro-Mata/projects/1)

Colunas do Board

Backlog → To Do → In Progress → Review → Done

Observacao: Board visivel apenas para membros da organizacao AGES-Pro-Mata no GitHub.

Git Flow e Processos

Estrutura de Branches

main (producao)
  ↑
develop (integracao)
  ↑
feature/[id]-[descricao]

Nao usamos: hotfix/* (ajustes vao na proxima sprint)

Workflow de Desenvolvimento

1. Criar branch (GitHub): git checkout -b feature/t42-login-jwt
2. Desenvolver com commits semanticos
3. Push: git push origin feature/t42-login-jwt
4. Abrir PR (GitHub) para develop
5. Code Review: Minimo 2 aprovacoes (AGES III/IV)
6. CI passa: GitHub Actions valida testes
7. Merge e delete da branch
8. Sincronizacao: GitHub → GitLab (automatica via GitHub Actions)

Commits Semanticos (Conventional Commits)

feat: nova funcionalidade
fix: correcao de bug
docs: documentacao
style: formatacao (sem mudanca logica)
refactor: refatoracao de codigo
test: adicao/correcao de testes
chore: manutencao (deps, config)

Exemplos:

• feat: adiciona autenticacao JWT no backend
• fix: corrige validacao de datas em reservas
• docs: atualiza README com instrucoes de setup

Code Review - Checklist

Revisores devem verificar:

• Codigo limpo e legivel
• Testes adequados (cobertura mantida/aumentada)
• Documentacao necessaria (README, comentarios complexos)
• Segue padroes do projeto (ESLint, Prettier)
• Tratamento de erros adequado
• Validacoes de entrada
• Concordancia com criterios de aceitacao/padroes de desenvolvimento
• Documentacao Swagger atualizada (endpoints de API)
• Acessibilidade verificada (frontend)

SLA: PRs abertos ate 2 dias antes da entrega serao revisados a tempo.

CI/CD - GitHub Actions

Pipeline de CI

Trigger: Push em qualquer branch, PR para develop ou main

Jobs:

1. Lint: ESLint + Prettier
2. Test:
   • Backend: Jest (unit + integration)
   • Frontend: Vitest (unit + integration com MSW)
3. Build: Compilacao TypeScript

Requisito: Pipeline deve passar (green) para merge.

Pipeline de CD

Trigger: Merge em main

Deploy Atual (AWS Simplificado):

• Frontend: AWS S3 static hosting (TanStack Router file-based routing)
• Backend: AWS EC2 (Docker container)
• Database: PostgreSQL (container na EC2)
• Outros Servicos: Umami, Metabase (containers na EC2)
• Publicacao: Imagens Docker publicadas no Docker Hub a cada deploy

Motivacao da transicao:

• Simplificacao operacional (reducao de complexidade de manutencao)
• Vantagens do S3 para aplicacoes SPA (React + TanStack Router)
• Descentralizacao de conhecimento (infraestrutura anterior concentrada em AGES IV)
• Facilidade de manutencao para equipe

Infraestrutura de Backup (Azure/AWS Multi-Cloud)

Repositorio: https://github.com/Saccilotto/pro-mata-infra (pessoal - André Sacilotto)

Stack:

• IaC: Terraform (provisionamento VMs/EC2)
• CaC: Ansible (configuracao Docker Swarm)
• Orquestracao: Docker Swarm (multi-cloud)
• Proxy/LB: Traefik v3 (reverse proxy + SSL)
• Observabilidade: Prometheus + Grafana
• Dominio: Cloudflare + registro.br
• Multi-Cloud: Azure VMs (Terraform state em Blob Storage) + AWS EC2 (state em S3)

Status:

• Standby: Backup funcional, nao utilizado em producao atual
• Ativacao: Configuracao de variaveis apontando para Azure ou AWS
• Sincronizacao: Consome imagens Docker Hub atualizadas pelo CI/CD principal
• Tolerancia a Falhas: Redundancia geografica multi-cloud disponivel se necessario

Observacao sobre Gestao de Riscos:

• Risco Mitigado: Falha critica em infraestrutura AWS (baixa probabilidade, alto impacto)
• Estrategia: Infraestrutura backup pronta para ativacao (Recovery Time Objective < 4h)
• Trade-off: Decisao de simplificar operacao atual vs. manter redundancia ativa
• Aprendizado: Importancia de descentralizar conhecimento critico (bus factor)

Sincronizacao GitHub → GitLab

Automatica via GitHub Actions:

• Trigger: Push em main ou develop
• Action: Mirror para GitLab (tools.ages.pucrs.br/pro-mata)
• Frequencia: A cada commit

Comunicacao

Plano de Comunicacao

Canais de Comunicacao

• GitHub Issues/PR: Comunicacao tecnica assincrona
• Discord: Chat rapido, duvidas, avisos, dailys de sabado (eventos + canal texto)
• WhatsApp: Comunicacao urgente
• Email: Comunicacao formal com stakeholder/orientador
• GitLab Wiki: Documentacao centralizada

Reunioes com Stakeholder

• Frequencia: Sprint Review (fim de cada sprint) + ad-hoc quando necessario
• Formato: Demo ao vivo + Q&A + Validacao proximo ciclo
• Duracao: 1h (Review), 30min-1h (ad-hoc)
• Presenca: Prof. Augusto Mussi Alvim

Riscos e Mitigacoes

Matriz de Riscos

Escala:

• Probabilidade: 0 (improvavel) - 10 (certo)
• Impacto: 0 (insignificante) - 10 (catastrofico)
• Exposicao: Probabilidade × Impacto
• Atencao: Exposicao ≥40 requer monitoramento ativo

Plano de Respostas a Riscos

R1 - Mudancas de Escopo (Exposicao: 48)

Estrategia: Mitigar

• Backlog bem definido e priorizado com stakeholder
• Validacao constante em Sprint Reviews
• Change control: mudancas significativas requerem aprovacao formal
• Responsavel: AGES IV

R3 - Indisponibilidade de Membros (Provas/Trabalhos Academicos) (Exposicao: 48)

Estrategia: Aceitar + Mitigar

• Calendario academico compartilhado (provas G1/G2, entregas outras disciplinas)
• Distribuicao de tarefas criticas entre multiplos membros
• Documentacao de decisoes tecnicas na Wiki
• Pareamento para disseminar conhecimento
• Planejamento considerando periodos de sobrecarga academica
• Responsavel: AGES IV

R4 - Atraso em Entregas (Exposicao: 48)

Estrategia: Mitigar

• Monitoramento diario de progresso (burndown)
• Sprints de 3 semanas permitem ajustes mid-sprint
• Buffer de 2-3 dias em marcos criticos
• Priorização rigorosa de backlog
• Responsavel: AGES IV

R9 - Concentracao de Conhecimento (Exposicao: 49)

Estrategia: Mitigar

• Documentacao detalhada de arquitetura e decisoes tecnicas
• Code review obrigatorio (2 aprovacoes) para disseminar conhecimento
• Pareamento em tarefas criticas
• Rotacao de responsabilidades quando possivel
• Nota: Infraestrutura backup criada para mitigar dependencia de unico membro (Andre Sacilotto)
• Responsavel: AGES IV

Metricas e Monitoramento

Metricas de Sprint

Velocity (Story Points por Sprint):

• Meta: Estabilizar apos 2-3 sprints
• Medicao: Total de story points completados por sprint
• Uso: Planejamento de capacidade futura

Burndown Chart:

• Medicao: Story points restantes por dia de sprint
• Uso: Identificar desvios early, ajustar scope mid-sprint

Lead Time de Issues:

• Definicao: Tempo de "To Do" → "Done"
• Meta: ≤ 7 dias para issues de tamanho medio
• Uso: Identificar gargalos no fluxo

Metricas de Qualidade

Cobertura de Testes:

• Meta: ≥70% linhas/funcoes, ≥60% branches
• Medicao: Vitest (frontend), Jest (backend)
• Bloqueio: PR nao pode diminuir cobertura

Taxa de Aprovacao em Code Review:

• Meta: ≥90% PRs aprovados na primeira revisao
• Medicao: PRs aprovados / PRs totais
• Uso: Avaliar qualidade do codigo antes de PR

Tempo de Code Review:

• Meta: ≤2 dias uteis
• SLA: PRs abertos ate 2 dias antes de entrega
• Medicao: Tempo entre abertura e merge de PR

Metricas de Deploy

Frequencia de Deploy:

• Medicao: Merges em main por semana
• Meta: 1-2 deploys por sprint (entregas incrementais)

Taxa de Sucesso de Deploy:

• Meta: ≥95% deploys sem rollback
• Medicao: Deploys bem-sucedidos / total deploys

Tempo de Recovery (MTTR):

• Meta: ≤4h (infraestrutura backup disponivel)
• Medicao: Tempo entre falha detectada e restauracao do servico

Satisfacao

Stakeholder:

• Medicao: Feedback qualitativo apos cada Sprint Review
• Acao: Ajustes de backlog baseados em feedback

Equipe:

• Medicao: Retrospectiva com acoes documentadas
• Acao: Implementacao de melhorias de processo

Review Metricas: A cada retrospectiva (fim de sprint)

Stack Tecnologico

Frontend

• Framework: React 19
• Linguagem: TypeScript (strict mode)
• Build Tool: Vite 6
• Roteamento: TanStack Router (file-based routing)
• Estado:
  • Server State: TanStack Query
  • UI State: Zustand
• Estilizacao: Tailwind CSS 4
• Componentes UI: Shadcn/UI + Radix UI
• Formularios: React Hook Form + Zod
• HTTP Client: Axios (interceptor JWT)
• Testes:
  • Unit/Integration: Vitest
  • Mocking: MSW (Mock Service Worker)
  • E2E: Playwright
• Lint/Format: ESLint + Prettier
• Analytics: Umami (privacy-respecting)

Backend

• Runtime: Node.js 22+
• Framework: NestJS
• Linguagem: TypeScript (strict mode)
• ORM: Prisma (PostgreSQL)
• Autenticacao: JWT (@nestjs/jwt)
• Hashing: argon2 (argon2id)
• Validacao: Zod + nestjs-zod
• Documentacao API: Swagger (@nestjs/swagger)
• Testes: Jest + ts-jest + supertest
• Lint/Format: ESLint + Prettier
• Analytics: @umami/node

Banco de Dados

• SGBD: PostgreSQL 15
• ORM: Prisma
• Migrations: Prisma Migrate
• Modelagem: Ver Banco de Dados

Infraestrutura (Producao Atual)

• Hospedagem Frontend: AWS S3 static hosting
• Hospedagem Backend: AWS EC2 (Ohio - us-east-2)
• Containerizacao: Docker
• Banco de Dados: PostgreSQL (container EC2)
• Servicos Adicionais:
  • Umami Analytics (container EC2)
  • Metabase BI (container EC2)
• CI/CD: GitHub Actions
• Registry: Docker Hub (imagens publicas)
• Repositorios Desenvolvimento: GitHub (AGES-Pro-Mata)
• Repositorios Oficiais: GitLab (tools.ages.pucrs.br/pro-mata)
• Documentacao: GitLab Wiki

Infraestrutura de Backup (Standby)

• IaC: Terraform (Azure Blob Storage / AWS S3 state)
• CaC: Ansible
• Orquestracao: Docker Swarm
• Proxy/LB: Traefik v3 (reverse proxy + SSL Let's Encrypt)
• Observabilidade: Prometheus + Grafana
• Multi-Cloud: Azure VMs + AWS EC2
• CDN/WAF: Cloudflare
• Dominio: registro.br
• Repositorio: https://github.com/Saccilotto/pro-mata-infra (pessoal)

Ferramentas de Gestao

• Board: GitHub Projects (privado - AGES-Pro-Mata org)
• Issues: GitHub Issues (desenvolvimento)
• Wiki: GitLab Wiki (oficial)
• Chat: Discord (dailys sabado, code review) + WhatsApp (urgencias)
• Reunioes: Discord Voice + Presencial
• Email: Comunicacao formal stakeholder/orientador

Links Rapidos

Repositorios Oficiais (GitLab - tools.ages.pucrs.br)

• Frontend: https://tools.ages.pucrs.br/pro-mata/frontend
• Backend: https://tools.ages.pucrs.br/pro-mata/backend
• Infraestrutura: https://tools.ages.pucrs.br/pro-mata/infrastructure
• Wiki: https://tools.ages.pucrs.br/pro-mata/wiki/-/wikis/home

Repositorios Desenvolvimento (GitHub - AGES-Pro-Mata)

• Frontend: https://github.com/AGES-Pro-Mata/frontend
• Backend: https://github.com/AGES-Pro-Mata/backend
• Projects: https://github.com/orgs/AGES-Pro-Mata/projects/1 (privado)

Infraestrutura Backup

• Infra Multi-Cloud: https://github.com/Saccilotto/pro-mata-infra (pessoal - Andre Sacilotto)

Wiki (GitLab)

• Home
• Escopo
• Processo
• Sprints
• Design
• Arquitetura
• Repositorios
• Banco de Dados

Links Externos

• Site AGES
• CPPN Pro-Mata
• Projeto Pro-Mata AGES

Convencoes e Padroes

Nomenclatura

Branches:

• feature/[numero-issue]-[descricao-curta]
• Exemplo: feature/42-login-jwt

Commits:

• Seguir Conventional Commits
• Mensagens em ingles
• Imperativo (add, fix, update)

Issues:

• Titulo claro e objetivo
• Labels apropriadas
• Criterios de aceitacao definidos

Qualidade de Codigo

• Linting: ESLint (erros = bloqueio)
• Formatacao: Prettier (automatico)
• TypeScript: Strict mode habilitado
• Documentacao: JSDoc para funcoes complexas
• Cobertura Testes: ≥70% linhas/funcoes, ≥60% branches

Definicao de Pronto (DoD)

Uma task so esta DONE quando:

• Codigo implementado e funcional
• Testes unitarios/integracao escritos e passando
• Cobertura de testes mantida ou aumentada (≥70%)
• Code review aprovado (minimo 2 aprovacoes)
• CI pipeline passando (green)
• Documentacao Swagger atualizada (endpoints de API)
• Merge realizado em develop
• Issue/PR fechada no GitHub
• Sincronizacao confirmada no GitLab (mirror)

Proximos Passos

Imediatos (Concluidos)

• Estruturar repositorios GitLab/GitHub
• Configurar GitHub Projects (Kanban)
• Setup CI/CD (GitHub Actions)
• Criar pagina de gerencia (Wiki GitLab)
• Definir horarios fixos das cerimonias
• Criar template de issues/PRs
• Popular backlog inicial

Sprint 0 (Concluidos)

• Levantamento detalhado de requisitos
• Definir arquitetura tecnica
• Setup ambiente desenvolvimento
• Criar mockups iniciais (Figma)
• Modelagem banco de dados

Sprint 1 (To Do)

Pendencias e Melhorias

• Criar EAP visual (diagrama - Miro/Lucidchart)
• Formalizar Termo de Abertura em PDF
• Adicionar metricas de velocity ao monitoramento
• Documentar retrospectivas de cada sprint
• Revisar e atualizar matriz de riscos a cada sprint