From d8bc126c17732b709c154c9f740ddbe460292358 Mon Sep 17 00:00:00 2001 From: Erick Nunes Date: Wed, 15 Jul 2026 18:17:58 -0300 Subject: [PATCH] =?UTF-8?q?Adiciona=20quality=20gate=20de=20revis=C3=A3o?= =?UTF-8?q?=20de=20PR=20via=20Claude=20Code=20Action?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Revisão automática (informativa) em PRs que alteram docs de arquitetura ou specs Bruno, verificando consistência entre HLD/LLD/ARCHITECTURE_CONTEXT e as specs de API. --- .github/claude-review-guidelines.md | 45 ++++++++++++++++++++++++++++ .github/workflows/claude-review.yml | 46 +++++++++++++++++++++++++++++ CLAUDE.md | 22 ++++++++++++++ 3 files changed, 113 insertions(+) create mode 100644 .github/claude-review-guidelines.md create mode 100644 .github/workflows/claude-review.yml create mode 100644 CLAUDE.md diff --git a/.github/claude-review-guidelines.md b/.github/claude-review-guidelines.md new file mode 100644 index 0000000..1cc4446 --- /dev/null +++ b/.github/claude-review-guidelines.md @@ -0,0 +1,45 @@ +# Critérios de revisão automática de PR + +Aplicado pelo workflow `.github/workflows/claude-review.yml` a cada Pull Request. Leia `CLAUDE.md` antes de revisar para ter o contexto da arquitetura. + +## 1. Consistência entre os documentos de arquitetura + +`architecture/ARCHITECTURE_CONTEXT.md`, `HLD.md` e `LLD.md` devem usar os mesmos nomes para: + +- Serviços: Core API, Processor, Notification. +- Filas/tópicos: SQS `process-video`, SNS `videos-events`, SQS `update-status`, SQS `notificate-status`. +- Buckets S3 (vídeos enviados, ZIP de frames). +- Bancos/cache: PostgreSQL, Redis. +- Estados do vídeo: `PENDING_UPLOAD`, `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`. + +Aponte qualquer nome divergente entre os três arquivos, ou um documento descrevendo um fluxo que os outros não mencionam. + +## 2. Specs Bruno como reflexo da arquitetura + +Para cada `.bru` alterado ou novo em `auth/`, `health/`, `monitoring/`, `videos/`: + +- O verbo HTTP e o path fazem sentido com o que a arquitetura descreve para aquele endpoint. +- `auth: bearer` é usado quando o endpoint exige autenticação; `auth: none` quando não exige. +- Variáveis referenciadas (ex. `{{api_url}}`, `{{token}}`, `{{video_id}}`) estão de fato definidas em `environments/local.bru` e/ou `environments/aws.bru`. +- Os status codes tratados em `script:post-response` são coerentes com o fluxo assíncrono (ex. `202` para uma operação que dispara processamento em background). + +## 3. Convenções entre pastas + +- `meta.name` e `meta.seq` consistentes e sequenciais dentro de cada pasta. +- Nomenclatura de arquivos alinhada com o padrão já usado na pasta. +- O nome da coleção em `bruno.json` é coerente com o nome do projeto usado nos documentos de arquitetura. + +## 4. Clareza de redação + +- Termos usados de forma inconsistente (ex. "vídeo" vs "video" dentro do mesmo documento). +- Markdown ou diagramas Mermaid quebrados (sintaxe inválida, referências a nós inexistentes). + +## Formato da resposta + +Poste um único comentário na PR (atualize o comentário existente em pushes seguintes, não crie um novo) com: + +- Um resumo de 1-2 frases. +- Os achados agrupados em **Possíveis inconsistências** (algo que parece objetivamente errado ou divergente) e **Sugestões** (estilo, clareza, convenção). +- Se não houver nada relevante, diga isso explicitamente em vez de forçar um comentário. + +Esta é uma revisão **informativa** — não é necessário nem esperado emitir um veredito de aprovação/reprovação; o objetivo é ajudar quem for revisar o PR, não bloquear o merge. diff --git a/.github/workflows/claude-review.yml b/.github/workflows/claude-review.yml new file mode 100644 index 0000000..c522684 --- /dev/null +++ b/.github/workflows/claude-review.yml @@ -0,0 +1,46 @@ +name: Claude PR Review + +on: + pull_request: + types: [opened, synchronize, reopened] + paths: + - "architecture/**" + - "**/*.bru" + - "bruno.json" + +concurrency: + group: claude-review-${{ github.event.pull_request.number }} + cancel-in-progress: true + +permissions: + contents: read + pull-requests: write + id-token: write + +jobs: + review: + if: github.event.pull_request.draft == false + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Run Claude review + uses: anthropics/claude-code-action@v1 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + use_sticky_comment: true + prompt: | + Leia CLAUDE.md e .github/claude-review-guidelines.md e aplique os + critérios de revisão ali definidos a este Pull Request + (#${{ github.event.pull_request.number }}). + + Poste um único comentário resumindo os achados, usando comentários + inline nos arquivos específicos quando fizer sentido. Esta é uma + revisão informativa: não bloqueia o merge, apenas ajuda quem for + revisar o PR. + claude_args: | + --model claude-sonnet-5 + --max-turns 8 + --allowedTools "Bash(gh pr diff:*),Bash(gh pr comment:*)" diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..405f218 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,22 @@ +# media-processor-docs + +Repositório de documentação do projeto de pós-graduação FIAP X (grupo 13SOAT) — **não contém código de aplicação**. O código do sistema (Core API, Processor, Notification) vive em outros repositórios; aqui ficam apenas a documentação de arquitetura e as specs de API usadas para exercitá-la. + +## O sistema documentado + +Sistema de processamento de vídeos: usuário autenticado envia um vídeo e recebe um `.zip` com os frames extraídos (um frame por segundo). Arquitetura de microsserviços em AWS ECS Fargate, comunicação assíncrona via SNS/SQS: + +- **Core API** (Go, Gin, JWT) — autenticação, upload/download via URL assinada no S3, publica trabalhos. +- **Processor** (Go, ffmpeg) — consome a fila `process-video`, extrai frames, gera o ZIP, publica em `videos-events` (SNS). +- **Notification** (Go, AWS SES) — consome `notificate-status` e notifica o usuário por e-mail. +- Fan-out via SNS `videos-events` → SQS `update-status` (volta pra API) e SQS `notificate-status` (Notification). +- Estados do vídeo: `PENDING_UPLOAD` → `PENDING` → `PROCESSING` → `PROCESSED` | `FAILED`. + +## Estrutura do repositório + +- `architecture/` — `ARCHITECTURE_CONTEXT.md`, `HLD.md`, `LLD.md`: os três documentos devem descrever a mesma arquitetura de forma consistente (mesmos nomes de serviços, filas, buckets, estados). +- `auth/`, `health/`, `monitoring/`, `videos/` — coleção Bruno (ferramenta de teste de API tipo Postman) com specs `.bru` por domínio. Cada spec deve refletir o que a arquitetura descreve (endpoint, autenticação, status codes). +- `environments/` — `local.bru` e `aws.bru` definem as variáveis (`{{api_url}}`, `{{token}}`, etc.) usadas pelas specs. +- `bruno.json` — configuração da coleção Bruno na raiz. + +Não há build, testes automatizados ou lint configurados neste repositório — é conteúdo de documentação e specs, revisado por leitura.