Onboarding — Dev¶

Setup do ambiente local para trabalhar nos projetos Vanguru.

Status: draft

Este documento será expandido na Fase F8. Por ora, lista o essencial.

Pré-requisitos¶

Ferramenta	Versão mínima	Por quê
Git	2.40+	Controle de versão
GitHub CLI (`gh`)	2.40+	Auth + operações repo
Node.js	20 LTS	Scripts `public-docs`, `content-docs`, blog-poster
Flutter SDK	3.22+	App `vanguru_mobile`, `vanguru_connect_mobile`
Java JDK	21	Backends Spring Boot
Python	3.12+	MkDocs (`internal-docs`)
Firebase CLI	13+	Deploy Cloud Functions, emulators
`gcloud` CLI	460+	GCP / Cloud Run
Docker	25+	Backend local (Postgres + Keycloak via `backend-environment/`)

Clonar repos essenciais¶

mkdir -p ~/project/vanguru && cd ~/project/vanguru

# Docs (clone esses primeiro — Claude/LLM vai apontar aqui)
gh repo clone rotaescolarappbr/internal-docs
gh repo clone rotaescolarappbr/public-docs
gh repo clone rotaescolarappbr/content-docs

# Apps mobile
gh repo clone rotaescolarappbr/vanguru_mobile

# Backends que você vai mexer (lista conforme necessidade)
# gh repo clone rotaescolarappbr/payments-api
# gh repo clone rotaescolarappbr/secure-functions
# ...

Autenticação¶

GitHub¶

gh auth login    # escolher GitHub.com → HTTPS → browser
gh auth status

GCP¶

Service accounts (legacy + Vanguru) ficam em ~/project/vanguru/*.json:

rota-escolar-app-185ef-e1cb20526b87.json — prd backend (linen-badge-396722)
vanguru-fire-dev-84c25ba33a14.json — dev Firebase

Nunca commitar.

Para usar em scripts locais:

export GOOGLE_APPLICATION_CREDENTIALS=~/project/vanguru/vanguru-fire-dev-84c25ba33a14.json

Firebase¶

firebase login
firebase use --add    # selecionar vanguru-fire-dev ou vanguru-fire-prd

Trabalhando em cada projeto¶

Projeto	Comando inicial	Documentação
`vanguru_mobile`	`flutter pub get && flutter run -t lib/main_dev.dart --flavor dev`	projects/vanguru-mobile
`payments-api`	`./gradlew bootRun`	projects/payments-api
`*-functions/`	`npm install && firebase emulators:start --only functions`	api/functions
`public-docs`	`npm install && npm run validate`	README do repo
`content-docs`	idem	README do repo
`internal-docs`	`pip install -r requirements.txt && mkdocs serve`	este repo

Convenções¶

Identifiers de negócio em pt-br (pontoDeEmbarque, iniciarExecucao).
Identifiers técnicos em inglês.
PII (CPF, RG, nome completo, telefone, data nasc.) nunca raw em Firestore — usar secure-functions.
LGPD: ver security/lgpd.

Próximos passos sugeridos¶

Ler architecture/overview para topologia geral.
Ler architecture/firestore se for tocar mobile/Functions.
Ler CLAUDE.md de cada projeto antes de fazer mudanças (instruções para LLMs e padrões locais).