Skip to content

GitLab

Gerencia · Changes

Page history
feat: add full project documentation layout and structure for Pró-Mata Wiki until AGES' end authored by Saccilotto's avatar Saccilotto
Hide whitespace changes
Inline Side-by-side
Gerencia.md 0 → 100644
View page @ 181e3600
# Gerencia
| [Home](Home) | [Escopo](Escopo) | [Processo](Processo) | [Sprints](Sprints) | [Design](Design) | [Arquitetura](Arquitetura) | [Repositorios](Repositorios) | [**Gerencia**](Gerencia) | [Banco de Dados](Banco-de-Dados) |
| :----------: | :-------------------------------: | :------------------: | :--------------: | :--------------------: | :--------------------------: | :------------------------: | :---------------: | :--------------: |
> 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)
| Atividade | AGES I | AGES II | AGES III | AGES IV |
|-----------|--------|---------|----------|---------|
| Documentacao Wiki | I | I | C | **R/A** |
| Planejamento Sprint | C | C | C | **R/A** |
| Analise Requisitos | I | **R** | C | A |
| Modelagem BD | I | **R/A** | C | I |
| Arquitetura Sistema | I | C | **R/A** | I |
| Desenvolvimento Backend | **R** | C | C | I |
| Desenvolvimento Frontend | **R** | C | C | I |
| Code Review | P | P | **R/A** | C |
| Testes Unitarios | **R** | C | C | I |
| Testes Integracao | **R** | C | **A** | I |
| CI/CD Setup | I | I | **R/A** | C |
| Deploy Producao | I | I | **R** | **A** |
| Gestao Riscos | C | C | C | **R/A** |
| Comunicacao Stakeholder | I | I | C | **R/A** |
| Retrospectiva | P | P | P | **R** |
**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
| Cerimonia | Quando | Duracao | Horario | Participantes | Responsavel |
|-----------|--------|---------|---------|---------------|-------------|
| **Planning** | Inicio da sprint | 2h | 17:30 | Toda equipe | AGES IV |
| **Daily** | 2a, 4a e sab | ~10min | 17:40 (2a/4a presencial) | Equipe dev | AGES IV |
| **Review** | Fim da sprint | 1h | 17:30 | Equipe + Stakeholder | AGES IV |
| **Retrospective** | Apos Review | 1h | Apos Review | Toda equipe | AGES IV |
| **Code Review Meeting** | Sexta pre-entrega | 1-1.5h | A definir | AGES I/II/III | AGES III |
### 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:
| Sprint | Periodo | Duracao | Foco |
|--------|---------|---------|------|
| **Sprint 0** | 30/7 - 20/8 | 4 semanas | Planejamento de User Stories e Mockups |
| **Sprint 1** | 6/8 - 27/8 | 3 semanas | Validacao User Stories e Planejamento/Efetivacao de Arquitetura e Ambientes Dev |
| **Sprint 2** | 27/8 - 17/9 | 3 semanas | Melhoria de Processos e Artefatos de Entrega e Proposta de novas User Stories |
| **Sprint 3** | 17/9 - 8/10 | 3 semanas | Melhoria de Processos e Artefatos da ultima entrega e proposta de novas User Stories |
| **Sprint 4** | 8/10 - 29/10 | 3 semanas | Finalizacao do MVP e Retrospectiva de Aprendizados |
**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](Sprints) para detalhamento de cada sprint
### Marcos (Milestones)
| Marco | Sprint | Semana | Descricao |
|-------|--------|--------|-----------|
| **M1** | 0 | ~4 | Arquitetura aprovada + ambiente configurado |
| **M2** | 1 | ~6 | Autenticacao + CRUD experiencias funcionais |
| **M3** | 2 | ~9 | Fluxo reserva completo (MVP) |
| **M4** | 3 | ~13 | Sistema completo com notificacoes |
| **M5** | 4 | ~18 | Deploy producao + documentacao |
---
## Estrutura Analitica do Projeto (EAP)
```plain
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
```plain
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
```plain
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)
```plain
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
| Evento | Responsavel | Envolvidos | Frequencia | Duracao | Plataforma |
|--------|-------------|------------|------------|---------|------------|
| **Kickoff Projeto** | AGES IV | Todos + Stakeholder | Inicio semestre | 2h | Presencial |
| **Daily (2a/4a)** | AGES IV | Equipe dev | 2x semana | 15min | Presencial (aula) |
| **Daily (Sab)** | AGES IV | Equipe dev | Semanal | 15min | Discord (texto) |
| **Sprint Planning** | AGES IV | Toda equipe | Inicio sprint | 2h | Presencial/Meet |
| **Sprint Review** | AGES IV | Todos + Stakeholder | Fim sprint | 1h | Discord Discord/Meet |
| **Retrospectiva** | AGES IV | Toda equipe | Fim sprint | 1h | Discord/Meet |
| **Code Review Meeting** | AGES III | AGES I/II/III | Sexta pre-entrega | 1-1.5h | Discord |
| **Reuniao Stakeholder** | AGES IV | AGES IV + Stakeholder | Ad-hoc | 30min-1h | Email/Meet |
### 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
| # | Risco | Prob. (0-10) | Impacto (0-10) | Exposicao | Responsavel | Mitigacao |
|---|-------|--------------|----------------|-----------|-------------|-----------|
| R1 | Mudancas de escopo | 6 | 8 | **48** | AGES IV | Backlog bem definido, validacao constante com stakeholder, revisao em Review |
| R2 | Dificuldades tecnicas | 6 | 6 | **36** | AGES III | Pareamento (pair programming), suporte AGES III/IV, documentacao detalhada |
| R3 | Indisponibilidade membros (provas/trabalhos academicos) | 8 | 6 | **48** | AGES IV | Calendario academico compartilhado, tarefas distribuidas, documentacao codigo |
| R4 | Atraso entregas | 6 | 8 | **48** | AGES IV | Monitoramento daily, sprints 3 semanas permitem ajustes, buffer em marcos |
| R5 | Bugs producao | 4 | 9 | **36** | AGES III | Testes automatizados (70%+), code review obrigatorio (2 aprovacoes) |
| R6 | Integracao PUCRS falhar | 3 | 6 | **18** | AGES III | Mock de dados, testes sem dependencias externas, validacao early |
| R7 | Calendario academico | 8 | 5 | **40** | AGES IV | Sprints flexiveis (3 semanas), buffer em marcos, adaptacao cerimônias |
| R8 | Falha infraestrutura AWS | 2 | 9 | **18** | AGES III | Backup multi-cloud (Azure) standby, monitoramento (Prometheus/Grafana) |
| R9 | Concentracao conhecimento | 7 | 7 | **49** | AGES IV | Documentacao detalhada, code review disseminando conhecimento, pareamento |
| R10 | Comunicacao stakeholder | 4 | 7 | **28** | AGES IV | Reviews regulares, comunicacao proativa, validacao incremental |
**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](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](Home)
- [Escopo](Escopo)
- [Processo](Processo)
- [Sprints](Sprints)
- [Design](Design)
- [Arquitetura](Arquitetura)
- [Repositorios](Repositorios)
- [Banco de Dados](Banco-de-Dados)
### Links Externos
- [Site AGES](https://www.ages.pucrs.br)
- [CPPN Pro-Mata](https://www.pucrs.br/ima/pro-mata/)
- [Projeto Pro-Mata AGES](https://www.ages.pucrs.br/projetos/)
---
## 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)
- [x] Estruturar repositorios GitLab/GitHub
- [x] Configurar GitHub Projects (Kanban)
- [x] Setup CI/CD (GitHub Actions)
- [x] Criar pagina de gerencia (Wiki GitLab)
- [x] Definir horarios fixos das cerimonias
- [x] Criar template de issues/PRs
- [x] Popular backlog inicial
### Sprint 0 (Concluidos)
- [x] Levantamento detalhado de requisitos
- [x] Definir arquitetura tecnica
- [x] Setup ambiente desenvolvimento
- [x] Criar mockups iniciais (Figma)
- [x] 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
---