docs: reescreve CLAUDE.md para refletir a arquitetura Nuxt real
A versao anterior descrevia uma SPA Vue com vue-router/main.js. O projeto e Nuxt 3 de verdade: roteamento por arquivo em src/pages/, autenticacao via padrao Token-Handler/BFF (token nunca chega ao browser, sessao em Redis) em vez do PKCE client-side "pendente" descrito antes, chamadas via $fetch + server/api/proxy (nao existe apiClient/apiClientPublico), variaveis NUXT_* (nao VITE_*). A tabela "O Que Esta Pendente" foi removida: credenciamento, primeiro acesso, certidao, IPTU e avisos ja estao implementados - verificado lendo os services e paginas reais. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
parent
e4c468e61e
commit
fbb765db8d
364
CLAUDE.md
364
CLAUDE.md
@ -1,11 +1,14 @@
|
||||
# portal-modumfiscal-web — Contexto para IA
|
||||
|
||||
> **Revisado por completo em 2026-09-25.** A versão anterior deste arquivo descrevia o projeto como uma SPA Vue com `vue-router`/`main.js` — isso está **errado**: o projeto é um app **Nuxt 3** real (SSR, roteamento por arquivo, BFF de autenticação). Praticamente todo o conteúdo sobre arquitetura, rotas e autenticação foi reescrito após leitura direta do código (`nuxt.config.ts`, `src/pages/`, `server/`, `src/plugins/`, `src/middleware/`). A tabela "O Que Está Pendente" da versão anterior também estava obsoleta — os itens que ela listava como pendentes (PKCE, certidão, IPTU, avisos, credenciamento, primeiro acesso) já estão implementados.
|
||||
|
||||
Portal público de autoatendimento fiscal do contribuinte. SaaS multi-tenant: cada
|
||||
prefeitura cliente tem seu próprio subdomínio (`tutoia.modumfiscal.com.br`) e uma
|
||||
identidade visual distinta (cor primária + foto de fundo + logo).
|
||||
|
||||
Projeto irmão: `core-modumfiscal-web` (backoffice interno da prefeitura, outra repo).
|
||||
Backend compartilhado: API REST Spring Boot em `https://sistema.modumfiscal.com.br`.
|
||||
Projeto irmão: `core-modumfiscal-web` (backoffice interno da prefeitura, outro repo).
|
||||
Backend compartilhado: API REST Spring Boot em `core-modumfiscal-api`, sempre acessada
|
||||
através do próprio servidor Nuxt (nunca direto do browser — ver seção de Autenticação).
|
||||
|
||||
---
|
||||
|
||||
@ -13,54 +16,60 @@ Backend compartilhado: API REST Spring Boot em `https://sistema.modumfiscal.com.
|
||||
|
||||
| Dependência | Versão | Observação |
|
||||
|---|---|---|
|
||||
| Nuxt | 3.14 | `ssr: true`, `srcDir: 'src'`, `serverDir: 'server'` |
|
||||
| Vue | 3.5 | `<script setup>` obrigatório |
|
||||
| Vite | 8 | Plugin `@tailwindcss/vite` (sem PostCSS) |
|
||||
| PrimeVue | 4.5 | Tema Aura, auto-importado via `unplugin-vue-components` |
|
||||
| Vite | 8 (via Nuxt) | Plugin `@tailwindcss/vite` (sem PostCSS) |
|
||||
| PrimeVue | 4.5 | Módulo `@primevue/nuxt-module`, tema Aura, auto-importado |
|
||||
| `@primeuix/themes` | 2 | `updatePreset`, `updateSurfacePalette`, `definePreset` |
|
||||
| TailwindCSS | 4 | `@import "tailwindcss"` no CSS — **sem `tailwind.config.js`** |
|
||||
| Vue Router | 5 | `createWebHistory` |
|
||||
| Pinia | 3 | `pinia-plugin-persistedstate` |
|
||||
| Axios | 1.x | Dois clientes: público e autenticado |
|
||||
| Zod | 4 | Validação de formulários (usar nos wizards) |
|
||||
| Pinia | 3 | Módulos `@pinia/nuxt` + `pinia-plugin-persistedstate/nuxt` |
|
||||
| Axios | não usado | Chamadas HTTP são via `$fetch` nativo do Nuxt (ver Services) |
|
||||
| Zod | 4 | Validação de formulários (wizards) |
|
||||
| `ioredis` | 5 | Sessão + PKCE state (servidor apenas — ver Autenticação) |
|
||||
| `jose` / `jwt-decode` | — | Decodificação de token no servidor |
|
||||
| TypeScript | 5.6 | Usado em `server/` e em parte de `src/` (`.ts`); componentes `.vue` continuam em JS |
|
||||
|
||||
**Não existe roteamento client-side manual** (`vue-router` não é dependência direta do projeto) — o roteamento é **por arquivo**, via `src/pages/` (recurso nativo do Nuxt).
|
||||
|
||||
---
|
||||
|
||||
## Arquitetura Multi-Tenant
|
||||
|
||||
```
|
||||
subdomínio (ex: tutoia.modumfiscal.com.br)
|
||||
└── getTenant() → 'tutoia'
|
||||
└── bootstrapPrefeitura() → GET /api/v1/publico/prefeitura/tutoia
|
||||
└── prefeituraStore.$patch({ nomePrefeitura, template, pathLogo, ... })
|
||||
└── App.vue onMounted → applyTemplate('tutoia')
|
||||
└── PrimeVue recebe cor primária laranja (tutoia)
|
||||
requisição chega no servidor Nuxt (SSR)
|
||||
└── plugins/prefeitura.server.ts (roda em toda request no servidor)
|
||||
└── tenantFromHost(host) → dominio (ex.: 'tutoia')
|
||||
└── GET {coreApiUrl}/api/v1/publico/prefeitura/{dominio}
|
||||
└── prefeituraStore.$patch({ nomePrefeitura, template, pathLogo, pathBackground, ... })
|
||||
|
||||
└── plugins/auth.server.ts (roda em toda request no servidor)
|
||||
└── GET /api/auth/me (usando o cookie de sessão da própria requisição)
|
||||
└── authStore.setUser(...) — hidrata o estado autenticado ANTES do HTML ser enviado
|
||||
|
||||
app.vue (client, onMounted)
|
||||
└── applyTemplate(prefeitura.template) + applySurface('slate')
|
||||
→ PrimeVue já está inicializado neste ponto — pode aplicar o preset dinâmico
|
||||
```
|
||||
|
||||
**Ordem de inicialização em `main.js` (crítica — não alterar):**
|
||||
1. `createPinia()` + `pinia.use(persistedstate)`
|
||||
2. `await bootstrapPrefeitura(pinia)` — busca config da prefeitura antes de montar
|
||||
3. `app.use(router)`
|
||||
4. `app.use(PrimeVue, primeVueConfig)`
|
||||
5. `app.mount('#app')`
|
||||
6. `App.vue onMounted` → `applyTemplate(prefeitura.template)` — aplica cor dinâmica
|
||||
Os dois plugins (`prefeitura.server.ts`, `auth.server.ts`) rodam **no servidor, a cada requisição** — é assim que o SSR já entrega HTML com o tema e o estado de login corretos, sem flash de conteúdo errado. Não existe um `main.js`/bootstrap manual — a ordem de inicialização é controlada pelo próprio Nuxt (plugins → `app.vue` → hidratação client-side).
|
||||
|
||||
> **Por que `applyTemplate` fica no `onMounted` e não no bootstrap?**
|
||||
> `updatePreset()` exige que o PrimeVue já esteja inicializado. No bootstrap,
|
||||
> o `app.use(PrimeVue)` ainda não rodou. Chamá-la antes causa erro silencioso.
|
||||
> **Por que `applyTemplate` fica no `onMounted` de `app.vue` e não num plugin server-side?**
|
||||
> `updatePreset()` do PrimeVue precisa rodar no client, depois que o PrimeVue já foi montado — chamá-la no servidor não tem efeito sobre o CSS enviado ao browser.
|
||||
|
||||
---
|
||||
|
||||
## Detecção de Tenant
|
||||
|
||||
```js
|
||||
// src/utils/tenant.js
|
||||
getTenant() → hostname.split('.')[0]
|
||||
→ localStorage('current_dominio') // fallback
|
||||
→ 'sistema' // último fallback
|
||||
```
|
||||
Existe em **duas cópias equivalentes** (uma para o server, uma para uso client-side), ambas em TypeScript:
|
||||
- `server/utils/tenant.ts` — usado pelos plugins/rotas de servidor (`tenantFromEvent`, a partir do header `Host`)
|
||||
- `src/utils/tenant.ts` — usado no client quando necessário
|
||||
|
||||
`localhost` é inválido propositalmente — em dev, o bootstrap falha graciosamente
|
||||
e o app sobe sem tema personalizado (usa `blue` como padrão).
|
||||
```ts
|
||||
tenantFromHost(host) → primeiro subdomínio, minúsculo
|
||||
→ lista de bloqueio (www, api, admin, test, dev, staging, production, localhost, ...) cai no fallback
|
||||
→ subdomínio inválido (não bate `/^[a-z0-9-]+$/`) cai no fallback
|
||||
→ fallback final: 'sistema'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@ -74,7 +83,7 @@ A superfície é sempre `slate` — não mudar.
|
||||
|
||||
Para adicionar novo município com foto de fundo:
|
||||
1. Colocar a imagem em `src/assets/images/bg-NOME.jpeg`
|
||||
2. Importar em `HomeView.vue` e adicionar ao `heroBgMap`
|
||||
2. Importar em `HomeView`/página correspondente e adicionar ao mapa de fundos
|
||||
3. Cadastrar o `template` correspondente em `theme.config.js` se precisar de cor nova
|
||||
|
||||
---
|
||||
@ -101,18 +110,59 @@ Para adicionar novo município com foto de fundo:
|
||||
|
||||
---
|
||||
|
||||
## Clientes HTTP
|
||||
## Autenticação — padrão Token-Handler (BFF), não PKCE client-side
|
||||
|
||||
```js
|
||||
// src/config/apiClient.js
|
||||
apiClientPublico // sem Authorization — para bootstrap e serviços públicos
|
||||
apiClient // com Bearer token + headers tenant — para /portal/*
|
||||
**O token de acesso nunca chega ao browser.** Toda a troca OAuth2/PKCE com o Keycloak acontece no servidor Nuxt; o cliente só recebe um cookie de sessão **httpOnly** opaco.
|
||||
|
||||
```
|
||||
1. Usuário clica "Entrar" → abre LoginModal.vue (composable useLoginModal)
|
||||
2. POST /api/auth/login { documento?, returnTo? }
|
||||
server/api/auth/login.post.ts:
|
||||
gera PKCE (code_verifier/code_challenge) + state
|
||||
salva o par em Redis (server/utils/pkce.ts, TTL configurável)
|
||||
devolve { authUrl } apontando pro Keycloak
|
||||
3. Browser navega para authUrl (Keycloak)
|
||||
4. Keycloak redireciona pra GET /api/auth/callback?code=...&state=...
|
||||
server/api/auth/callback.get.ts:
|
||||
recupera o PKCE state salvo (consumePkceState)
|
||||
troca o code por tokens (server-side, com client secret)
|
||||
cria sessão em Redis (server/utils/session.ts) com access/refresh/id token
|
||||
seta cookie de sessão httpOnly (setSessionCookie)
|
||||
redireciona pro returnTo original (padrão: /portal/painel)
|
||||
5. Toda página/plugin subsequente:
|
||||
GET /api/auth/me → lê sessão do cookie → devolve só nome/documento/email/roles
|
||||
authStore (Pinia) guarda SÓ esses metadados — nunca o token
|
||||
```
|
||||
|
||||
Interceptors adicionam automaticamente `X-Municipio` e `X-Dominio` em toda requisição.
|
||||
`apiClient` redireciona para `/` em resposta 401.
|
||||
- **Middleware de rota** (`src/middleware/auth.ts`): protege `/portal/**`. Se não autenticado, **abre o modal global de login** (não redireciona pra uma página `/login` — essa página não existe mais como fluxo principal; `pages/entrar.vue` hoje é só um stub que redireciona pra `/` ou `/portal/painel`).
|
||||
- **Refresh de token**: transparente, feito pelo proxy (`server/api/proxy/[...path].ts`) via `getValidAccessToken(sid)` — a página nunca lida com expiração de token diretamente.
|
||||
- **Logout**: `POST /api/auth/logout` — invalida a sessão em Redis e limpa o cookie.
|
||||
|
||||
**Regra:** nunca chamar `apiClient` diretamente em componente — sempre via Service.
|
||||
---
|
||||
|
||||
## Chamada à API — sempre via `/api/proxy/**`
|
||||
|
||||
**Não existe `apiClient.js`/`apiClientPublico`.** Os services usam o `$fetch` global do Nuxt, sempre contra o proxy do próprio servidor:
|
||||
|
||||
```js
|
||||
// src/services/[dominio]Service.js
|
||||
const FETCH_HEADERS = { 'X-Requested-With': 'fetch' }
|
||||
function proxyUrl(path) { return `/api/proxy${path}` }
|
||||
|
||||
export const meuService = {
|
||||
listar(params) {
|
||||
return $fetch(proxyUrl('/contribuinte/algo'), { headers: FETCH_HEADERS, query: params })
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
`server/api/proxy/[...path].ts` é o único ponto que fala com `core-modumfiscal-api`:
|
||||
- Lê a sessão do cookie e busca o access token válido em Redis (refresh automático se expirado)
|
||||
- Resolve o tenant pelo host e busca `codigoMunicipio` (cacheado em Redis)
|
||||
- Encaminha a chamada com `Authorization: Bearer ...` + `X-Municipio` + `X-Dominio` injetados
|
||||
- Rotas sob `/api/v1/publico/**` passam **sem exigir sessão** (`isPublico` no proxy)
|
||||
|
||||
**Regra:** nunca chamar `$fetch` direto pra URL do core-api num componente/página — sempre via service, sempre via `/api/proxy/...`.
|
||||
|
||||
---
|
||||
|
||||
@ -120,115 +170,150 @@ Interceptors adicionam automaticamente `X-Municipio` e `X-Dominio` em toda requi
|
||||
|
||||
```
|
||||
src/
|
||||
├── app.vue ← splash de boot + NuxtLayout/NuxtPage + Toast + LoginModal global
|
||||
├── assets/
|
||||
│ ├── main.css ← Tailwind v4 directives + @variant dark
|
||||
│ ├── layout/layout.scss ← Focus ring, skip link, prefers-reduced-motion, classes a11y
|
||||
│ └── images/ ← Logos e fotos de fundo (importação estática Vite)
|
||||
├── bootstrap/
|
||||
│ └── prefeituraBoot.js ← Busca config da prefeitura antes de montar o app
|
||||
│ ├── main.css Tailwind v4 directives + @variant dark
|
||||
│ ├── layout/layout.scss Focus ring, skip link, prefers-reduced-motion, classes a11y
|
||||
│ └── images/ Logos e fotos de fundo (importação estática Vite)
|
||||
├── components/
|
||||
│ ├── common/
|
||||
│ │ ├── AppHeader.vue ← Header público (logo dinâmica, nav)
|
||||
│ │ ├── AppFooter.vue ← Footer com links institucionais
|
||||
│ │ ├── ServiceCard.vue ← Card reutilizável de serviço (público e autenticado)
|
||||
│ │ └── AccessibilityWidget.vue ← Botão flutuante: fonte, dark, alto contraste
|
||||
│ └── auth/
|
||||
│ └── DocumentoInput.vue ← Input CPF/CNPJ com máscara automática
|
||||
│ ├── common/ AppHeader, AppFooter, ServiceCard, AccessibilityWidget
|
||||
│ └── auth/ DocumentoInput.vue, LoginModal.vue
|
||||
├── composables/
|
||||
│ └── useMotion.js ← prefers-reduced-motion reativo
|
||||
│ ├── useMotion.js prefers-reduced-motion reativo
|
||||
│ ├── useAuth.ts wrapper de authStore + chamadas de login/logout
|
||||
│ └── useLoginModal.ts abre/fecha o LoginModal global, guarda o returnTo
|
||||
├── config/
|
||||
│ ├── apiClient.js ← Axios clients (público + autenticado)
|
||||
│ ├── primevue.config.js ← Aura preset + locale pt-BR
|
||||
│ └── theme.config.js ← Paletas e applyTemplate()
|
||||
│ ├── primevue.config.js Aura preset + locale pt-BR
|
||||
│ └── theme.config.js Paletas e applyTemplate()/applySurface()
|
||||
├── layouts/
|
||||
│ ├── PublicLayout.vue ← Header + Footer + RouterView (rotas públicas)
|
||||
│ └── PortalLayout.vue ← Header autenticado com nav + Sair
|
||||
├── router/index.js ← Rotas + guard requiresAuth
|
||||
├── services/
|
||||
│ ├── prefeituraService.js ← GET /publico/prefeitura/{dominio}
|
||||
│ └── authService.js ← Keycloak PKCE (estrutura pronta, integração pendente)
|
||||
│ ├── default.vue Header + Footer + RouterView (rotas públicas — NÃO se chama PublicLayout)
|
||||
│ └── portal.vue Header autenticado com nav + Sair (NÃO se chama PortalLayout)
|
||||
├── middleware/
|
||||
│ └── auth.ts Guard de `/portal/**` — abre o LoginModal (ver Autenticação)
|
||||
├── pages/ ← ROTEAMENTO POR ARQUIVO (Nuxt) — não existe router/index.js
|
||||
│ ├── index.vue → /
|
||||
│ ├── entrar.vue → /entrar (stub de redirect — login real é via modal)
|
||||
│ ├── credenciamento.vue → /credenciamento (wizard, ~6 etapas)
|
||||
│ ├── primeiro-acesso.vue → /primeiro-acesso (wizard, 3 etapas)
|
||||
│ ├── servicos/
|
||||
│ │ ├── index.vue → /servicos
|
||||
│ │ ├── certidao.vue → /servicos/certidao
|
||||
│ │ └── iptu.vue → /servicos/iptu
|
||||
│ └── portal/
|
||||
│ ├── painel.vue → /portal/painel
|
||||
│ ├── debitos.vue → /portal/debitos
|
||||
│ ├── pagamentos.vue → /portal/pagamentos
|
||||
│ ├── guias.vue → /portal/guias
|
||||
│ ├── certidoes.vue → /portal/certidoes
|
||||
│ ├── dados.vue → /portal/dados
|
||||
│ └── taxas/
|
||||
│ ├── index.vue → /portal/taxas
|
||||
│ └── emitir.vue → /portal/taxas/emitir
|
||||
├── plugins/
|
||||
│ ├── prefeitura.server.ts Bootstrap do tenant — roda a cada request no servidor
|
||||
│ └── auth.server.ts Hidrata authStore via /api/auth/me — roda a cada request no servidor
|
||||
├── services/ avisoService, certidaoService, credenciamentoService,
|
||||
│ iptuService, portalService, primeiroAcessoService — todos via $fetch + /api/proxy
|
||||
├── stores/
|
||||
│ ├── prefeituraStore.js ← Config da prefeitura (persiste localStorage)
|
||||
│ └── authStore.js ← Token + userInfo (persiste localStorage)
|
||||
├── utils/
|
||||
│ └── tenant.js ← getTenant / setTenant / clearTenant
|
||||
└── views/
|
||||
├── public/ ← Home, Login, PrimeiroAcesso, Credenciamento
|
||||
├── servicos/ ← ServicosHub, Certidao, Iptu
|
||||
└── portal/ ← Painel, Debitos, Certidoes, Alvaras, Pagamentos, Dados
|
||||
│ ├── prefeituraStore.js Config da prefeitura (persiste localStorage; Options API por legado)
|
||||
│ └── authStore.js SÓ metadados do usuário — token nunca fica aqui nem no cliente
|
||||
└── utils/
|
||||
└── tenant.ts Espelho client-side de server/utils/tenant.ts
|
||||
|
||||
server/
|
||||
├── api/
|
||||
│ ├── auth/ login.post.ts, callback.get.ts, me.get.ts, refresh.post.ts, logout.post.ts
|
||||
│ └── proxy/[...path].ts Único gateway para o core-api (ver seção acima)
|
||||
├── middleware/
|
||||
│ └── csrf.ts
|
||||
└── utils/
|
||||
├── keycloak.ts buildAuthUrl, exchangeCodeForTokens, userInfoFromAccessToken
|
||||
├── pkce.ts generatePkce, savePkceState, consumePkceState (Redis)
|
||||
├── session.ts createSession, getValidAccessToken, setSessionCookie, etc. (Redis)
|
||||
├── redis.ts cliente ioredis compartilhado
|
||||
├── prefeitura.ts fetchPrefeituraInfo (cacheado em Redis)
|
||||
└── tenant.ts tenantFromHost / tenantFromEvent
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rotas
|
||||
|
||||
| Path | Nome | Layout | Auth |
|
||||
|---|---|---|---|
|
||||
| `/` | `home` | Public | ✗ |
|
||||
| `/login` | `login` | Public | ✗ |
|
||||
| `/primeiro-acesso` | `primeiro-acesso` | Public | ✗ |
|
||||
| `/credenciamento` | `credenciamento` | Public | ✗ |
|
||||
| `/servicos` | `servicos` | Public | ✗ |
|
||||
| `/servicos/certidao` | `certidao` | Public | ✗ |
|
||||
| `/servicos/iptu` | `iptu` | Public | ✗ |
|
||||
| `/portal/painel` | `painel` | Portal | ✓ |
|
||||
| `/portal/debitos` | `debitos` | Portal | ✓ |
|
||||
| `/portal/certidoes` | `certidoes-portal` | Portal | ✓ |
|
||||
| `/portal/alvaras` | `alvaras` | Portal | ✓ |
|
||||
| `/portal/pagamentos` | `pagamentos` | Portal | ✓ |
|
||||
| `/portal/dados` | `dados` | Portal | ✓ |
|
||||
Roteamento **por arquivo** — criar um `.vue` em `src/pages/` já cria a rota, sem passo de registro manual.
|
||||
|
||||
Guard no router: rotas `requiresAuth: true` redirecionam para `home` se não autenticado.
|
||||
| Path | Arquivo | Layout | Auth |
|
||||
|---|---|---|---|
|
||||
| `/` | `pages/index.vue` | `default` | ✗ |
|
||||
| `/entrar` | `pages/entrar.vue` | — | stub de redirect |
|
||||
| `/credenciamento` | `pages/credenciamento.vue` | `default` | ✗ |
|
||||
| `/primeiro-acesso` | `pages/primeiro-acesso.vue` | `default` | ✗ |
|
||||
| `/servicos` | `pages/servicos/index.vue` | `default` | ✗ |
|
||||
| `/servicos/certidao` | `pages/servicos/certidao.vue` | `default` | ✗ |
|
||||
| `/servicos/iptu` | `pages/servicos/iptu.vue` | `default` | ✗ |
|
||||
| `/portal/painel` | `pages/portal/painel.vue` | `portal` | ✓ (`middleware/auth.ts`) |
|
||||
| `/portal/debitos` | `pages/portal/debitos.vue` | `portal` | ✓ |
|
||||
| `/portal/pagamentos` | `pages/portal/pagamentos.vue` | `portal` | ✓ |
|
||||
| `/portal/guias` | `pages/portal/guias.vue` | `portal` | ✓ |
|
||||
| `/portal/certidoes` | `pages/portal/certidoes.vue` | `portal` | ✓ |
|
||||
| `/portal/dados` | `pages/portal/dados.vue` | `portal` | ✓ |
|
||||
| `/portal/taxas` | `pages/portal/taxas/index.vue` | `portal` | ✓ |
|
||||
| `/portal/taxas/emitir` | `pages/portal/taxas/emitir.vue` | `portal` | ✓ |
|
||||
|
||||
> Não existe mais `/portal/alvaras` — o módulo de Alvará foi removido do produto (consolidado em Taxas), consistente com o `core-modumfiscal-api`.
|
||||
|
||||
---
|
||||
|
||||
## Fluxo de Login (2 etapas)
|
||||
## Fluxo de Login (modal, não página)
|
||||
|
||||
```
|
||||
Home (captura CPF/CNPJ)
|
||||
└── router.push({ name: 'login', query: { doc: documento } })
|
||||
└── LoginView.vue exibe o doc mascarado + campo senha
|
||||
└── entrar() → Keycloak PKCE (a implementar em authService.js)
|
||||
└── authStore.setSession(token, userInfo)
|
||||
└── router.push({ name: 'painel' })
|
||||
Qualquer página → clique em "Entrar" ou navegação bloqueada por middleware/auth.ts
|
||||
└── useLoginModal().open(returnTo) → abre LoginModal.vue (renderizado globalmente em app.vue)
|
||||
└── LoginModal chama POST /api/auth/login → recebe { authUrl } → window.location = authUrl
|
||||
└── Keycloak autentica → GET /api/auth/callback → sessão criada → redirect pro returnTo
|
||||
```
|
||||
|
||||
O documento trafega como query param (`?doc=01234567890`) — apenas os dígitos,
|
||||
sem formatação. `LoginView` faz a máscara localmente.
|
||||
Não existe mais uma página `LoginView.vue` com captura de CPF/CNPJ em duas etapas — isso foi substituído pelo modal global. `pages/entrar.vue` existe só como redirecionamento de compatibilidade.
|
||||
|
||||
---
|
||||
|
||||
## Variáveis de Ambiente
|
||||
|
||||
Nuxt usa `runtimeConfig` (não `VITE_*`). Chaves reais, definidas em `nuxt.config.ts` e sobrescritas via `.env` local ou secret manager em produção:
|
||||
|
||||
```bash
|
||||
# .env.development.local (GIT IGNORADO — crie localmente)
|
||||
VITE_API_URL=https://sistema.modumfiscal.com.br
|
||||
VITE_KEYCLOAK_URL=https://keycloakprod.modumfiscal.com.br
|
||||
VITE_KEYCLOAK_REALM=modumfiscal-dev
|
||||
VITE_KEYCLOAK_CLIENT_ID=portal-modumfiscal-web
|
||||
# .env (GIT IGNORADO — copiar de .env.example e preencher)
|
||||
NUXT_CORE_API_URL=... # URL do core-modumfiscal-api, usada só no servidor
|
||||
NUXT_KEYCLOAK_URL=...
|
||||
NUXT_KEYCLOAK_REALM=...
|
||||
NUXT_KEYCLOAK_CLIENT_ID=...
|
||||
NUXT_KEYCLOAK_CLIENT_SECRET=... # client confidential — nunca vai pro bundle client-side
|
||||
NUXT_REDIS_URL=... # sessão + PKCE state
|
||||
NUXT_COOKIE_SECRET=... # assina o cookie de sessão — rotacionar em incidente
|
||||
NUXT_SESSION_TTL_SECONDS=... # default 8h
|
||||
NUXT_PKCE_TTL_SECONDS=... # default 5min
|
||||
```
|
||||
|
||||
Os arquivos `.env.development` e `.env.production` estão no repo mas vazios —
|
||||
servem de template. Os valores reais ficam apenas nos arquivos `.local`.
|
||||
Todas essas chaves são `runtimeConfig` **server-only** (não expostas ao client) — só `runtimeConfig.public.appName` é pública. `.env.production` no repo está vazio (template); valores reais só em `.env` local ou no secret manager do orquestrador.
|
||||
|
||||
---
|
||||
|
||||
## Regras Críticas de Código
|
||||
|
||||
- **`<script setup>` obrigatório** — Options API proibida (exceto `prefeituraStore` que usa Options API por compatibilidade com o padrão do core)
|
||||
- **`<script setup>` obrigatório** — Options API proibida (exceto `prefeituraStore.js`, que usa Options API por compatibilidade com o padrão do core)
|
||||
- **PrimeVue auto-importado** — não adicionar `import Button from 'primevue/button'` manualmente
|
||||
- **CSS:** TailwindCSS inline no template — `@apply` proibido — SCSS só em `assets/layout/`
|
||||
- **`dark:` em toda view nova** — ver tabela acima
|
||||
- **Máximo 300 linhas por componente** — extrair subcomponentes se ultrapassar
|
||||
- **Nunca `apiClient` direto em componente** — sempre via Service
|
||||
- **`router.push({ name: 'home' })` para "voltar"** — nunca `router.back()` em fluxos críticos (histórico inesperado)
|
||||
- **Componentes PrimeVue com `dark:` manual nos wrappers** — PrimeVue já adapta seus internos, mas divs externas precisam de dark: Tailwind
|
||||
- **Máximo 300 linhas por página/componente** — extrair subcomponentes se ultrapassar
|
||||
- **Nunca `$fetch` direto num componente/página apontando pro core-api** — sempre via service, sempre via `/api/proxy/...`
|
||||
- **Nunca guardar token no client** (localStorage, cookie não-httpOnly, store) — o padrão é Token-Handler/BFF; se uma feature nova parecer exigir isso, é sinal de que deveria virar mais uma rota em `server/api/`
|
||||
- **`router.push({ name: 'index' })` (ou `navigateTo('/')`) para "voltar"** — nunca `router.back()` em fluxos críticos
|
||||
- **Componentes PrimeVue com `dark:` manual nos wrappers** — PrimeVue já adapta seus internos, mas divs externas precisam de `dark:` Tailwind
|
||||
|
||||
---
|
||||
|
||||
## Acessibilidade
|
||||
|
||||
Widget flutuante (`AccessibilityWidget.vue`) disponível em todas as telas via `App.vue`.
|
||||
Widget flutuante (`AccessibilityWidget.vue`) disponível em todas as telas via `app.vue`.
|
||||
Persiste preferências no `localStorage` (chaves: `a11y-fonte`, `a11y-contraste`, `a11y-escuro`).
|
||||
|
||||
Classes aplicadas no `<html>`:
|
||||
@ -244,43 +329,30 @@ ARIA implementada: skip link, `aria-label`, `aria-current`, `role="alert"`, `ari
|
||||
|
||||
## Como Adicionar Nova Tela Pública
|
||||
|
||||
1. Criar `src/views/servicos/MinhaView.vue`
|
||||
2. Adicionar rota em `src/router/index.js` dentro do bloco `PublicLayout`
|
||||
3. Incluir botão voltar (`router.push({ name: 'home' })`) no topo
|
||||
1. Criar `src/pages/servicos/minha-tela.vue` (o arquivo **já é a rota** — nada para registrar)
|
||||
2. Definir o layout se não for o `default` (`definePageMeta({ layout: '...' })`)
|
||||
3. Incluir botão voltar (`navigateTo('/')`) no topo
|
||||
4. Adicionar `dark:` em todos os utilitários Tailwind
|
||||
5. (Opcional) Adicionar no `servicosPublicos` de `HomeView.vue`
|
||||
|
||||
---
|
||||
5. Criar/usar um service em `src/services/` que chame `$fetch` via `/api/proxy/...`
|
||||
6. (Opcional) Adicionar no hub de serviços (`pages/servicos/index.vue`)
|
||||
|
||||
## Como Adicionar Nova Tela Autenticada
|
||||
|
||||
1. Criar `src/views/portal/MinhaView.vue`
|
||||
2. Adicionar rota em `src/router/index.js` dentro do bloco `PortalLayout` com `meta: { requiresAuth: true }` já herdado do pai
|
||||
3. Criar serviço em `src/services/` que use `apiClient` (nunca `apiClientPublico`)
|
||||
4. Adicionar no `navItems` de `PortalLayout.vue` se entrar na navegação principal
|
||||
1. Criar `src/pages/portal/minha-tela.vue`
|
||||
2. `definePageMeta({ layout: 'portal' })` — o `middleware/auth.ts` protege tudo sob `/portal/**` automaticamente (confirmar se o middleware está registrado globalmente para o prefixo ou se precisa ser declarado por página antes de assumir)
|
||||
3. Criar serviço em `src/services/` usando `$fetch` + `/api/proxy/...` (nunca rota pública)
|
||||
4. Adicionar na navegação do `layouts/portal.vue` se entrar no menu principal
|
||||
5. Adicionar `dark:` em todos os utilitários Tailwind
|
||||
|
||||
---
|
||||
|
||||
## O Que Está Pendente
|
||||
|
||||
| Feature | Arquivos envolvidos | Observações |
|
||||
|---|---|---|
|
||||
| Keycloak PKCE real | `authService.js`, `LoginView.vue` | Estrutura pronta, falta integrar `pkce-challenge` |
|
||||
| Wizard Credenciamento | `CredenciamentoView.vue` | 6 etapas: dados pessoais, endereço, documentos, representante, confirmação |
|
||||
| Wizard Primeiro Acesso | `PrimeiroAcessoView.vue` | 4 etapas: identificação, código, nova senha, confirmação |
|
||||
| Certidão (implementação real) | `CertidaoView.vue` | Input CPF/CNPJ → POST API → download PDF |
|
||||
| IPTU (implementação real) | `IptuView.vue` | Input inscrição imobiliária → GET débitos → carnê PDF |
|
||||
| Endpoint avisos carousel | `HomeView.vue` | `GET /api/v1/publico/avisos/{dominio}` (dados mockados atualmente) |
|
||||
| Campo `pathBackground` na API | `prefeituraBoot.js` | Backend ainda não retorna — mapeamento estático por `template` como POC |
|
||||
|
||||
---
|
||||
|
||||
## Comandos
|
||||
|
||||
```bash
|
||||
npm run dev # dev server (http://localhost:5173)
|
||||
npm run build # build produção
|
||||
npm run dev # nuxt dev — http://localhost:3000 (ou porta configurada)
|
||||
npm run build # nuxt build
|
||||
npm run generate # nuxt generate
|
||||
npm run preview # nuxt preview
|
||||
npm run lint # ESLint + fix
|
||||
```
|
||||
|
||||
@ -290,10 +362,20 @@ npm run lint # ESLint + fix
|
||||
|
||||
| Erro | Correto |
|
||||
|---|---|
|
||||
| `applyTemplate()` no bootstrap | Chamar no `App.vue onMounted` — PrimeVue precisa estar inicializado |
|
||||
| `router.back()` no botão voltar | `router.push({ name: 'home' })` — back usa histórico do browser |
|
||||
| Assumir SPA com `vue-router`/`main.js` | É Nuxt 3 — roteamento por arquivo em `src/pages/`, bootstrap via `plugins/*.server.ts` |
|
||||
| `applyTemplate()` fora do `onMounted` de `app.vue` | PrimeVue precisa estar inicializado no client primeiro |
|
||||
| Redirecionar pra uma página `/login` | Login é o `LoginModal.vue` global, via `useLoginModal()` |
|
||||
| Guardar token de acesso no client | Padrão é Token-Handler — token fica só em Redis, servidor injeta via proxy |
|
||||
| `import Button from 'primevue/button'` | Não importar — PrimeVue é auto-importado |
|
||||
| `@apply` no template | TailwindCSS inline — `@apply` só em `layout.scss` e nunca |
|
||||
| Utilitário Tailwind sem `dark:` | Sempre adicionar par dark: para qualquer bg/text/border |
|
||||
| `apiClient` direto na view | Criar Service e chamar pela view |
|
||||
| Path relativo de logo/foto da API | `resolverUrl()` em `prefeituraBoot.js` converte para URL absoluta |
|
||||
| `@apply` no template | TailwindCSS inline — `@apply` só em `layout.scss` |
|
||||
| Utilitário Tailwind sem `dark:` | Sempre adicionar par `dark:` para qualquer bg/text/border |
|
||||
| `$fetch` direto pra URL do core-api | Sempre via service, sempre via `/api/proxy/...` |
|
||||
| Variável de ambiente `VITE_*` | Nuxt usa `runtimeConfig`, variáveis reais são `NUXT_*` |
|
||||
| Path relativo de logo/foto da API | `resolverUrl()` em `plugins/prefeitura.server.ts` converte para URL absoluta |
|
||||
|
||||
---
|
||||
|
||||
## Pontos não totalmente confirmados nesta revisão
|
||||
|
||||
- Se `pathBackground` já é populado de fato pelo `core-modumfiscal-api` (o código do plugin já lê o campo da resposta, mas não confirmei o DTO do backend).
|
||||
- Mecanismo exato de como `middleware/auth.ts` é aplicado a todas as rotas `/portal/**` (globalmente vs. por página) — confirmar em `nuxt.config.ts`/cada página antes de assumir ao criar uma tela nova.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user