Skip to content

GitLab

Repositorios · Changes

Page history
feat: add comprehensive project repository documentation for Pró-Mata authored by Saccilotto's avatar Saccilotto
Hide whitespace changes
Inline Side-by-side
Repositorios.md 0 → 100644
View page @ 72d9dd7f
# Repositórios do Projeto
| [Home](Home) | [Escopo](Escopo) | [Processo](Processo) | [Sprints](Sprints) | [Design](Design) | [Arquitetura](Arquitetura) | [**Repositorios**](Repositorios) | [Gerencia](Gerencia) | [Banco de Dados](Banco-de-Dados) |
| :----------: | :-------------------------------: | :------------------: | :--------------: | :--------------------: | :--------------------------: | :------------------------: | :---------------: | :--------------: |
> Última atualização: 19 de Outubro 2025
## Estrutura de Repositórios
O projeto Pró-Mata utiliza uma estrutura **híbrida GitLab (oficial) + GitHub (desenvolvimento)**:
- **GitLab**: Repositórios oficiais (requisito institucional AGES)
- **GitHub**: Desenvolvimento ativo (familiaridade da equipe, ferramentas)
- **Sincronização**: Automática GitHub → GitLab
---
## Repositórios Oficiais (GitLab)
### Frontend
**URL**: <https://tools.ages.pucrs.br/pro-mata/frontend>
**Descrição**: Interface Web do usuário (React 19 + TypeScript)
**Tecnologias Principais**:
- React 19
- Vite 6
- TanStack Router (file-based routing)
- TanStack Query (server state)
- Tailwind CSS 4
- Shadcn/UI + Radix UI
- Vitest (unit/integration) + Playwright (E2E)
**Estrutura**:
```plain
src/
├── components/ui/ # Shadcn/UI components
├── features/ # Feature modules
├── lib/ # Utilities
├── routes/ # TanStack Router (file-based)
├── styles/ # Tailwind + tokens
└── main.tsx # App bootstrap
```
**Scripts Principais**:
- `npm run dev`: Dev server (hot reload)
- `npm run build`: Build produção
- `npm run test`: Testes unitários (Vitest)
- `npm run test:e2e`: Testes E2E (Playwright)
**Deploy**: AWS S3 static hosting (via GitHub Actions)
### Backend
**URL**: <https://tools.ages.pucrs.br/pro-mata/backend>
**Descrição**: API REST (NestJS + Node.js 22)
**Tecnologias Principais**:
- NestJS (framework)
- Node.js 22
- TypeScript (strict mode)
- Prisma ORM + PostgreSQL 15
- JWT (autenticação)
- Zod (validação)
- Swagger (documentação API)
- Jest (testes)
**Estrutura**:
```plain
src/
├── analytics/ # Umami integration
├── auth/ # JWT auth + roles
├── database/ # Prisma client
├── user/ # User management
├── experience/ # Experiences CRUD
└── main.ts # App bootstrap
prisma/
├── schema.prisma # Database schema
└── migrations/ # Database migrations
```
**Scripts Principais**:
- `npm run dev`: Dev server (hot reload)
- `npm run build`: Build produção
- `npm run test`: Testes unitários (Jest)
- `npm run prisma:migrate`: Rodar migrations
- `npm run prisma:generate`: Gerar Prisma Client
**Deploy**: AWS EC2 (Docker container via GitHub Actions)
**Documentação API**: <https://api.pro-mata.exemplo.com/api> (Swagger)
### Infraestrutura
**URL**: <https://tools.ages.pucrs.br/pro-mata/infrastructure>
**Descrição**: Configuração de infraestrutura (scripts, configs)
**Conteúdo**:
- Scripts de deploy
- Configurações AWS
- Docker Compose files
- Documentação de infraestrutura
**Nota**: Infraestrutura atual simplificada (AWS S3 + EC2). Ver repositório de backup para stack completa.
---
## Repositórios Desenvolvimento (GitHub)
### Frontend (GitHub)
**URL**: <https://github.com/AGES-Pro-Mata/frontend>
**Status**: Desenvolvimento ativo (mirror → GitLab)
**Acesso**: Privado (membros org AGES-Pro-Mata)
**CI/CD**:
- **Trigger**: Push em `main`
- **Pipeline**: Lint → Test → Build → Deploy S3
- **Ferramentas**: GitHub Actions
### Backend (GitHub)
**URL**: <https://github.com/AGES-Pro-Mata/backend>
**Status**: Desenvolvimento ativo (mirror → GitLab)
**Acesso**: Privado (membros org AGES-Pro-Mata)
**CI/CD**:
- **Trigger**: Push em `main`
- **Pipeline**: Lint → Test → Build → Docker → Deploy EC2
- **Registry**: Docker Hub (imagens públicas)
### Issues e Projects
**GitHub Projects**: <https://github.com/orgs/AGES-Pro-Mata/projects/1>
**Acesso**: Privado (apenas membros org AGES-Pro-Mata)
**Kanban**: Backlog → To Do → In Progress → Review → Done
**Sincronização Issues**: GitHub Issues → GitLab Issues (automatizada, simplificada)
**Observação**: O board kanban é gerenciado no GitHub Projects privado. Milestones são usados para tracking de Sprints:
- Sprint 4 Backend: 40% (3 issues abertas, 2 fechadas)
- Sprint 4 Frontend: 47% (10 issues abertas, 9 fechadas)
- Prazo Sprint 4: 17/11/2025 (entrega), 19/11/2025 (apresentação)
**CI/CD de Sincronização**: GitHub → GitLab (automatizado via GitHub Actions)
- **Código**: Mirror completo em tempo real (branches, commits, tags)
- **Issues**: Sincronização automatizada para documentação e histórico
- **Kanban/Projects**: Não sincronizado (GitHub Projects privado é fonte única)
- **Wiki**: Atualização manual no GitLab (documentação oficial)
- **Propósito**: Manter histórico completo no GitLab para fins institucionais AGES, enquanto desenvolvimento ativo ocorre no GitHub
---
## Repositório de Backup (Infraestrutura Multi-Cloud)
### Infra Multi-Cloud (Azure + AWS)
**URL**: <https://github.com/Saccilotto/pro-mata-infra>
**Owner**: André Sacilotto Santos (AGES IV - pessoal)
**Status**: Standby (não utilizado em produção atual)
**Descrição**: Infraestrutura completa multi-cloud com Terraform + Ansible + Docker Swarm
**Stack**:
- **IaC**: Terraform (Azure VMs / AWS EC2)
- **CaC**: Ansible (Docker Swarm config)
- **Orquestração**: Docker Swarm
- **Proxy/LB**: Traefik v3
- **Observabilidade**: Prometheus + Grafana
- **CDN/WAF**: Cloudflare
- **Domínio**: registro.br
**Estrutura**:
```plain
iac/ # Terraform (Infrastructure as Code)
cac/ # Ansible (Configuration as Code)
docker/ # Dockerfiles e Compose
envs/ # Environment configs
scripts/ # Deployment scripts
docs/ # Documentation
```
**Propósito**: Redundância geográfica, backup, tolerância a falhas (RTO < 4h)
---
## Sincronização Automatizada
### Visão Geral do CI/CD de Sincronização
O projeto utiliza **pipelines automatizados de CI/CD** (GitHub Actions) para manter o GitLab como repositório oficial de documentação e histórico, enquanto o desenvolvimento ativo ocorre no GitHub.
**Motivação**:
- **GitLab**: Repositório oficial institucional AGES (requisito, auditoria, transparência)
- **GitHub**: Plataforma de desenvolvimento (familiaridade da equipe, ferramentas, Projects privado)
- **Sincronização automática**: Garante conformidade institucional sem duplicar trabalho manual
### GitHub → GitLab (Código)
**Ferramenta**: GitHub Actions (mirror workflow)
**Trigger**: Push em `main`, `develop` ou `feature/*`
**Frequência**: Tempo real (a cada push)
**Pipeline**:
```plaintext
1. Push no GitHub (qualquer branch)
↓
2. GitHub Actions detecta evento
↓
3. Workflow de mirror executa
↓
4. Git push --mirror para GitLab
↓
5. GitLab atualizado (branches, commits, tags)
```
**Conteúdo Sincronizado**:
- ✅ Código-fonte (todos os arquivos)
- ✅ Branches (`main`, `develop`, `feature/*`)
- ✅ Commits (histórico completo com mensagens)
- ✅ Tags (releases e versões)
- ✅ Histórico de merge/rebase
**Latência**: < 2 minutos
**Logs**: Disponíveis em GitHub Actions (repositório → Actions → Mirror Workflow)
### GitHub Issues → GitLab Issues
**Ferramenta**: GitHub Actions (custom script Python)
**Trigger**: Criação, atualização ou fechamento de issue
**Frequência**: Tempo real (webhook-based)
**Pipeline**:
```plaintext
1. Issue criada/atualizada no GitHub
↓
2. Webhook dispara GitHub Actions
↓
3. Script Python processa issue
↓
4. GitLab API cria/atualiza issue espelhada
↓
5. Link bidirecional adicionado (GitHub ↔ GitLab)
```
**Conteúdo Sincronizado**:
- ✅ Título e descrição
- ✅ Labels (mapeamento automático)
- ✅ Status (aberta/fechada)
- ✅ Milestones (Sprint 1, 2, 3, 4)
- ⚠️ Comentários (resumo simplificado)
- ❌ Assignees (não sincronizado)
- ❌ GitHub Projects (board privado, não exportado)
**Mapeamento de Labels**:
| GitHub | GitLab |
|--------|--------|
| `bug` | `bug` |
| `feature` | `enhancement` |
| `frontend` | `frontend` |
| `backend` | `backend` |
| `documentation` | `documentation` |
**Nota**: Sincronização simplificada para fins de **documentação e histórico institucional**. Para gestão de tarefas ativa, usar GitHub Issues/Projects.
### GitHub Projects → GitLab (Não Sincronizado)
**Status**: ❌ Não sincronizado automaticamente
**Motivo**:
- GitHub Projects é privado (apenas membros org AGES-Pro-Mata)
- GitLab não possui ferramenta equivalente configurada
- Kanban é fonte única no GitHub
**Alternativa para Documentação**:
- Milestones sincronizados (Sprint 1, 2, 3, 4) servem como tracking no GitLab
- Wiki GitLab documenta progresso das sprints manualmente
- Métricas consolidadas em [Sprints](Sprints)
### Diagrama de Fluxo CI/CD de Sincronização
```plaintext
┌─────────────────────────────────────────────────────────────┐
│ DESENVOLVIMENTO ATIVO (GitHub) │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Código │ │ Issues │ │ Projects │ │
│ │ (repos dev) │ │ (tracking) │ │ (kanban) │ │
│ │ │ │ │
│ │ push │ webhook │ (privado) │
│ ↓ ↓ ↓ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ GitHub Actions (CI/CD Workflows) │ │
│ │ • mirror-workflow.yml (código) │ │
│ │ • sync-issues.yml (issues) │ │
│ └─────────────┬───────────────┬───────────────────────┘ │
│ │ │ │
└────────────────┼───────────────┼────────────────────────────┘
│ │
git push │ │ GitLab API
--mirror │ │ (create/update)
↓ ↓
┌─────────────────────────────────────────────────────────────┐
│ DOCUMENTAÇÃO E HISTÓRICO OFICIAL (GitLab AGES) │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Código │ │ Issues │ │ Wiki │ │
│ │ (mirror) │ │ (espelho) │ │ (manual) │ │
│ │ ✅ sync │ │ ✅ sync │ │ (manual) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ Propósito: Auditoria, Transparência, Requisito AGES │
└─────────────────────────────────────────────────────────────┘
```
**Fluxo Resumido**:
1. **Desenvolvedor**: Push código ou cria issue no GitHub
2. **GitHub Actions**: Detecta evento e executa workflow automático
3. **Sincronização**: Mirror de código e espelhamento de issues para GitLab
4. **GitLab**: Mantém histórico completo para fins institucionais
5. **Wiki**: Atualização manual semanal com métricas consolidadas
**Ferramentas de Monitoramento**:
- GitHub Actions logs: `github.com/AGES-Pro-Mata/{repo}/actions`
- GitLab mirror status: `tools.ages.pucrs.br/pro-mata/{repo}`
- Webhook delivery: GitHub Settings → Webhooks
---
## Workflow de Desenvolvimento
### 1. Desenvolvimento (GitHub)
```bash
# 1. Criar branch feature
git checkout -b feature/42-login-jwt
# 2. Desenvolver + commits semânticos
git commit -m "feat: adiciona autenticação JWT"
# 3. Push para GitHub
git push origin feature/42-login-jwt
# 4. Abrir Pull Request (GitHub)
# - Target: develop
# - Reviewers: AGES III/IV (mín. 2)
# 5. CI/CD valida automaticamente
# - Lint (ESLint + Prettier)
# - Test (Vitest/Jest)
# - Build (TypeScript)
# 6. Merge após aprovação
# - GitHub: merge PR
# - GitLab: mirror automático
```
### 2. Deploy (Automático)
```bash
# Após merge em main (GitHub):
# 1. CI/CD build produção
# 2. Frontend → AWS S3
# 3. Backend → Docker Hub → AWS EC2
# 4. Mirror → GitLab
```
---
## Convenções
### Branches
**Nomenclatura**: `feature/[numero-issue]-[descricao]`
**Exemplos**:
- `feature/42-login-jwt`
- `feature/15-reservas-crud`
- `feature/8-admin-dashboard`
### Commits
**Padrão**: Conventional Commits
**Formato**: `tipo: descrição`
**Tipos**:
- `feat`: Nova funcionalidade
- `fix`: Correção de bug
- `docs`: Documentação
- `style`: Formatação (sem lógica)
- `refactor`: Refatoração
- `test`: Testes
- `chore`: Manutenção (deps, config)
**Exemplos**:
```bash
git commit -m "feat: adiciona autenticação JWT no backend"
git commit -m "fix: corrige validação de datas em reservas (#15)"
git commit -m "docs: atualiza README com instruções de setup"
```
### Pull Requests
**Template**:
```markdown
## Descrição
[O que foi implementado]
## Issue Relacionada
Closes #42
## Tipo de Mudança
- [ ] Nova funcionalidade
- [ ] Correção de bug
- [ ] Breaking change
- [ ] Documentação
## Checklist
- [ ] Testes passando
- [ ] Code review feito
- [ ] Documentação atualizada
```
---
## Acesso aos Repositórios
### GitLab (Oficial)
**Acesso**: Público (leitura) / Privado (escrita - membros AGES)
**Login**: Credenciais institucional PUCRS
**URL Base**: <https://tools.ages.pucrs.br>
### GitHub (Desenvolvimento)
**Acesso**: Privado (apenas membros org AGES-Pro-Mata)
**Convite**: Solicitar a AGES IV
**URL Base**: <https://github.com/AGES-Pro-Mata>
### Backup (Pessoal)
**Acesso**: Público (leitura)
**Owner**: André Sacilotto Santos
**URL**: <https://github.com/Saccilotto/pro-mata-infra>
---
## Links Rápidos
### Repositórios
- **Frontend GitLab**: <https://tools.ages.pucrs.br/pro-mata/frontend>
- **Backend GitLab**: <https://tools.ages.pucrs.br/pro-mata/backend>
- **Infraestrutura GitLab**: <https://tools.ages.pucrs.br/pro-mata/infrastructure>
- **Frontend GitHub**: <https://github.com/AGES-Pro-Mata/frontend> (privado)
- **Backend GitHub**: <https://github.com/AGES-Pro-Mata/backend> (privado)
- **Backup Infra**: <https://github.com/Saccilotto/pro-mata-infra>
### Gestão
- **GitHub Projects**: <https://github.com/orgs/AGES-Pro-Mata/projects/1> (privado)
- **GitLab Issues**: <https://tools.ages.pucrs.br/groups/pro-mata/-/issues>
- **Wiki**: <https://tools.ages.pucrs.br/pro-mata/wiki/-/wikis/home>
### Documentação
- **Swagger API**: TODO (adicionar URL de produção)
- **Figma Design**: [Link Figma](https://www.figma.com/design/JWCBFx52pKQVs4FmzDjEXW/Pr%C3%B3-mata-Main-Design?node-id=0-1&t=yFXQcgjDZCbv9gtF-1)
- **Processo**: [Processo](Processo)
- **Arquitetura**: [Arquitetura](Arquitetura)
---
## Troubleshooting
### Problemas Comuns
#### 1. Erro ao clonar repositório GitLab
```bash
# Solução: Verificar credenciais PUCRS
git config --global credential.helper store
git clone https://tools.ages.pucrs.br/pro-mata/frontend.git
```
#### 2. CI/CD falhando
- Verificar linter: `npm run lint`
- Verificar testes: `npm run test`
- Verificar build: `npm run build`
#### 3. Docker build falhando (backend)
```bash
# Rebuild containers
docker-compose down
docker-compose build --no-cache
docker-compose up
```
#### 4. Prisma migrations out of sync
```bash
# Backend: sincronizar schema
npm run prisma:migrate deploy
npm run prisma:generate
```
---
**Última Revisão**: 15 de Novembro 2025
**Responsável**: AGES III (Arquitetura) + AGES IV (Gerência)