VitePress docs.olp.digital — Resumo de Implementação

Status das Entregas

#	Entrega	Status	Arquivos
1	Instalação e config base	✅	docs/.vitepress/config.ts, docs/index.md, package.json
2	Tema custom CSS (paleta OLP)	✅	docs/.vitepress/theme/custom.css, docs/.vitepress/theme/index.ts
3	4 componentes Vue	✅	docs/.vitepress/theme/components/*.vue
4	Sidebar completa	✅	Incluída na Entrega 1 (config.ts)
5	Auth Worker	✅	workers/docs-auth/src/index.ts, wrangler.toml, README.md
6	CI deploy-docs	✅	.github/workflows/deploy-docs.yml
7	.gitignore	⚠️ Manual	Arquivo read-only no Lovable
8	Landing page index.md	✅	Incluída na Entrega 1

---

Ações Manuais Necessárias

1. .gitignore (obrigatório antes do primeiro commit)

Adicionar ao .gitignore:

docs/.vitepress/cache
docs/.vitepress/dist

2. Cloudflare Pages — Criar projeto olp-docs

1. Cloudflare Dashboard → Pages → Create a project → Direct Upload (o deploy será via CI, não conectado ao Git)
2. Nome do projeto: olp-docs
3. Não precisa configurar build — o CI faz o build e faz upload via wrangler pages deploy

3. GitHub Secrets (obrigatório para o CI funcionar)

Adicionar em Settings → Secrets and variables → Actions:

Secret	Valor	Onde obter
CLOUDFLARE_API_TOKEN	API Token com permissão Pages + Workers	Cloudflare Dashboard → My Profile → API Tokens → Create Token → "Edit Cloudflare Workers" template
CLOUDFLARE_ACCOUNT_ID	ID da conta Cloudflare	Cloudflare Dashboard → página inicial → coluna direita

4. Auth Worker — Deploy e configuração

4.1 Deploy do Worker

cd workers/docs-auth
npx wrangler deploy

Ou via Dashboard: Workers & Pages → Create → Upload src/index.ts

4.2 Configurar Secrets do Worker

# Secret de validação JWT (mesmo valor da produção Supabase)
npx wrangler secret put OLP_JWT_SECRET
# → Colar o valor de OLP_JWT_SECRET da produção

IMPORTANTE: DOCS_PAGES_HOST é definido como variável não-secreta em wrangler.toml. NÃO use wrangler secret put DOCS_PAGES_HOST — isso sobrescreveria o valor versionado. O valor correto (olp-anp290q1f9.pages.dev) já está no arquivo.

4.3 Custom Domain

Dashboard → Workers & Pages → olp-docs-auth → Settings → Domains & Routes → Add Custom Domain → docs.olp.digital

O Cloudflare criará o registro DNS automaticamente (o DNS já é gerenciado pelo Cloudflare).

5. Primeiro deploy manual (para validar tudo)

Após os passos 2-4, rodar localmente para validar:

bun install
bun run docs:build
npx wrangler pages deploy docs/.vitepress/dist --project-name=olp-docs

Acessar https://docs.olp.digital — deve redirecionar para login. Após login como administrador, deve exibir a documentação.

---

Ordem de Execução das Ações Manuais

1. .gitignore                    ← Antes de qualquer push
2. Cloudflare Pages (olp-docs)   ← Criar projeto vazio
3. GitHub Secrets                ← CLOUDFLARE_API_TOKEN + ACCOUNT_ID
4. Auth Worker deploy            ← wrangler deploy + secrets + domain
5. Primeiro deploy manual        ← Validar fluxo completo
6. Push em main com change em docs/ ← CI roda automaticamente

---

Fluxo de Funcionamento Pós-Setup

Developer edita docs/*.md
        │
        ▼
Push em main (com changes em docs/**)
        │
        ▼
GitHub Actions: deploy-docs.yml
  ├── bun install
  ├── bun run docs:build (VitePress)
  └── wrangler pages deploy → olp-anp290q1f9.pages.dev
        │
        ▼
Usuário acessa docs.olp.digital
        │
        ▼
Worker olp-docs-auth intercepta
  ├── Extrai cookie olp_auth
  ├── Verifica JWT HS256 com OLP_JWT_SECRET
  ├── Valida principal_role === "administrador"
  │
  ├─ ✅ OK → Proxy para olp-anp290q1f9.pages.dev
  └─ ❌ Falha → Redirect para olp.digital/?redirect=...&redirect_error=<reason>

---

Componentes Vue Disponíveis

Uso direto em qualquer arquivo .md:

<BenchmarkChart
  :data="[
    { label: '64MB t=2', value: 189, status: 'ok' },
    { label: '128MB t=2', value: 378, status: 'marginal' },
    { label: '256MB t=2', value: 756, status: 'inviavel' }
  ]"
  unit="ms"
  title="CPU Time por Configuração"
/>

<DecisionTable
  :headers="['Opção', 'Custo', 'Latência']"
  :rows="[['Redis', '+$25/mês', '<1ms'], ['Postgres', '$0', '~5ms']]"
  :chosen-index="1"
  :justifications="['Mais rápido mas custo adicional', 'Zero custo, latência aceitável para o volume atual']"
/>

<Roadmap
  :items="[
    { titulo: 'Cache Redis', condicao: 'Volume > 5k req/min', status: 'pendente' },
    { titulo: 'Rate limit por IP', condicao: 'Após incidente', status: 'concluido' }
  ]"
/>

<ContingencyBox
  title="Argon2 OOM em Edge Function"
  :signals="['Timeout > 2s em verify-password', 'HTTP 500 intermitente']"
  cause="Parâmetro m (memória) excede limite do isolate Deno"
  :actions="['Reduzir m para 64MB no _shared/password-helper.ts', 'Monitorar via Edge Function logs', 'Considerar offload para Worker dedicado']"
/>

---

Ambientes de Preview e Cookies

IMPORTANTE: Ambientes de preview (*.workers.dev, *.lovable.app, *.lovableproject.com) não são ambientes válidos para testar o acesso autenticado a docs.olp.digital.

O cookie olp_auth é emitido com Domain=.olp.digital pelo Gateway e não é propagado para outros domínios. Nesses ambientes:

• O Worker retorna 401 diagnóstico HTML em vez de redirect (evita loops infinitos)
• O botão "Documentação Técnica" no perfil exibe um toast informativo em vez de abrir o link
• Para diagnóstico, use ?__debug_auth=1 para obter resposta JSON

Testando a documentação corretamente

1. Acesse olp.digital (produção)
2. Faça login como administrador
3. Clique em "Documentação Técnica" no perfil

---

Manutenção Contínua

Cenário	Ação
Novo arquivo .md em docs/	Adicionar entrada na sidebar em config.ts
Rotação de OLP_JWT_SECRET	Atualizar também no Worker: wrangler secret put OLP_JWT_SECRET
Link interno quebrado	Build falha no CI (dead links enforcement)
Novo papel com acesso à docs	Editar guard no Worker (principal_role check)
Adicionar novo componente Vue	Criar em theme/components/, registrar em theme/index.ts
Loop de redirect em preview	Verificar X-Docs-Auth-Reason headers ou usar ?__debug_auth=1