status	canonical
owner	engineering
last_verified_commit	9f2b8f177e7531f1c19242099f403c55b3820d08

PROTEA-R Hub

Plataforma de cursos da PROTEA-R: catálogo e aprendizagem para Alunas, autoria e operação para Admin/Suporte, comércio Asaas em preparação para o corte de produção, vídeo via JMVStream, mídia via Cloudflare R2, e-mail via Resend e Postgres/Neon.

Antes de começar

Pré-requisitos:

• Bun 1.3.11, versão fixada em package.json;
• acesso a um banco Postgres já compatível com o schema atual;
• credenciais das integrações necessárias à funcionalidade que será testada.

O topo da cadeia local, a quantidade de migrations e a quantidade de tabelas exportadas têm uma única autoridade: o runbook de banco, validado contra o journal e o schema por bun run docs:check. O catálogo efetivamente implantado em cada ambiente permanece no Estado de release. Para um banco local descartável, use os comandos de reset, seed e smoke somente conforme o runbook: eles recusam host remoto e exigem confirmação quando destrutivos.

O estado de deployment, verificação e documentação é mantido separadamente em Estado de release. Um commit verificado localmente não é tratado como implantado até passar o workflow e o smoke test do ambiente.

Desenvolvimento local com banco existente

1. Instale dependências:

   bun install

2. Copie .env.example para .env.local e preencha somente os serviços necessários. A matriz completa está em Ambiente local.

3. Garanta no mínimo DATABASE_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL e NEXT_PUBLIC_APP_URL.

4. Inicie:

   bun run dev

5. Abra http://localhost:3000. Cadastro público fica fechado por padrão. Em ambiente não produtivo, o bootstrap de Admin exige INTERNAL_BOOTSTRAP_SECRET; veja getBootstrapAdminDecision em src/lib/auth-policy.ts.

Comandos seguros

bun run dev
bun run verify:quick
bun run verify

verify:quick executa os gates rápidos durante o desenvolvimento. verify executa a verificação completa exigida antes de um Pull Request. Os dois comandos param no primeiro erro. bun run check é somente leitura. Para correções automáticas deliberadas, use bun run fix e revise o diff.

Mapa arquitetural

• src/app: rotas Next.js App Router, layouts, handlers HTTP e Server Actions.
• src/features: regras e serviços por capacidade (payments, enrollments, courses, certificates, privacy, jmvstream, storage).
• src/lib: autenticação, autorização, ambiente e utilidades transversais.
• src/db: schema, conexão e migrations.
• scripts: operações manuais; algumas estão bloqueadas para onboarding.
• docs: documentação canônica, decisões e runbooks.

O mapa completo, inclusive fluxos ponta a ponta, está em Arquitetura.

Ordem de leitura para quem chegou agora

1. Produto
2. Glossário
3. Índice da documentação
4. Arquitetura
5. Guia de domínio da primeira tarefa
6. ADR e runbook relacionados

Estado de verificação

Production está ativa em https://app.neurocapacitar.com.br, na Vercel Pro, com Next.js nativo, Functions Node.js 24 em gru1, Neon pooled em São Paulo e Cloudflare R2. Push e merge não publicam Production automaticamente: a promoção usa um workflow manual que aplica migrations pendentes, testa um deployment sem domínio e só então o promove.

A auditoria de Production Readiness de 23 de agosto de 2026 registrou NO-GO para uma nova decisão de release até o encerramento dos dez findings e dos gates de recuperação/Sentry. Esse veredito não afirma que o deployment existente esteja indisponível; impede tratá-lo como evidência suficiente para a próxima promoção.

Para publicar qualquer mudança, siga o tutorial de alteração até Production. O status Vercel-first é registro histórico da migração concluída, não o procedimento diário.

A jornada E2E completa de conclusão, emissão, renderização, e-mail absorvido, download privado e validação pública está implementada no repositório. A execução da CI para este commit permanece pendente; não é evidência de promoção ou deploy.