MVP 1 - Web - Foundation Layer¶

Atualizado: 2026-03-27

Objetivo¶

Estabelecer uma camada de infraestrutura reutilizável no auraxis-web antes de codificar as regras de negócio dos módulos. O princípio central é: cada módulo não deve reinventar HTTP handling, toast, paginação, validação ou componentes genéricos — esses insumos ficam prontos na base para consumo imediato.

Motivação¶

O auraxis-web possui seis módulos com integração API pendente (goals, portfolio, alerts, simulations, shared-entries, subscription). Sem uma base comum, cada módulo acumularia boilerplate idêntico, pontos de falha independentes e comportamento inconsistente ao usuário. Qualquer mudança global (ex: formato de toast de erro) exigiria edição em N arquivos.

Escopo¶

WF — Foundation Layer¶

Task	Entregável	Caminho
WF1	Interceptors HTTP globais + `ApiResponse<T>`, `PaginatedResponse<T>`	`app/core/api/`
WF2	`createApiQuery` + `createApiMutation` (factories sobre Vue Query)	`app/core/query/`
WF3	Utils globais: `date`, `number`, `string`, `validators` (CPF, CNPJ, telefone)	`app/utils/`
WF4	Zod schemas reutilizáveis: CPF, CNPJ, telefone, moeda, data, paginação	`app/core/validation/schemas/`
WF5	Stores Pinia: `useUiStore` (sidebar, theme, modal stack) + `useFiltersStore`	`app/stores/`
WF6	Composables: `useToast`, `usePagination`, `useFilters`, `useConfirm`, `useErrorBoundary`	`app/composables/`
WF7	Shared UI Kit: `UiConfirmDialog`, `UiFilterBar`, `UiPagination`, `UiStatusBadge`, `UiCurrencyDisplay`	`app/shared/components/`

WI — Integração mock → API real¶

Task	Página	Endpoints
WI1	`goals.vue`	`GET /goals`
WI2	`portfolio.vue`	`GET /wallet`
WI3	`alerts.vue`	`GET /alerts`, `PATCH /alerts/:id/read`, `DELETE /alerts/:id`
WI4	`simulations.vue`	`GET /simulations`, `DELETE /simulations/:id`
WI5	`shared-entries.vue`	`GET /shared-entries?direction=sent/received`, `DELETE /shared-entries/:id`
WI6	`subscription.vue`	`GET /subscriptions/me`, `GET /subscriptions/plans`, `POST /subscriptions/checkout`

WB — Bug Fixes e Completude¶

Task	Problema	Solução
WB1	`plans.vue` com referência quebrada ao `PlanCard` antigo; `tools.vue` com placeholder `<h1>`	Remover/redirecionar `plans.vue`; implementar `tools.vue` como hub NaiveUI

Arquitetura da Foundation Layer¶

`app/core/api/` — HTTP¶

http-client.ts       (existente — createHttpClient + X-API-Contract: v2)
interceptors.ts      (novo — 401 logout, 403 toast, 5xx toast)
types.ts             (novo — ApiResponse<T>, PaginatedResponse<T>, ApiError)

O interceptors.ts é registrado no createHttpClient via axios.interceptors.response.use. Nenhum módulo precisa tratar esses erros individualmente.

`app/core/query/` — Vue Query factories¶

use-api-query.ts     (createApiQuery — wrapper sobre useQuery)
use-api-mutation.ts  (createApiMutation — wrapper sobre useMutation)

Contrato de uso:

// Módulo de goals
const { data, isLoading } = createApiQuery(['goals'], goalsApi.getGoals);

// Módulo de alerts (com mutation)
const deleteMutation = createApiMutation(
  alertsApi.deleteAlert,
  { invalidates: [['alerts']], successMessage: 'Alerta removido' }
);

O factory encapsula: queryKey, staleTime padrão (5 min), retry em 500, normalização de erro via useErrorBoundary.

`app/core/validation/schemas/` — Zod¶

common.ts     — cpfSchema, cnpjSchema, phoneSchema, currencySchema, dateSchema
pagination.ts — paginationParamsSchema

Schemas importados diretamente em formulários VeeValidate via toTypedSchema().

`app/utils/` — Utilitários puros¶

currency.ts    (existente — formatCurrency)
date.ts        (novo — formatDate, formatRelativeTime, formatDateRange)
number.ts      (novo — formatPercentage, formatDecimal, clamp)
string.ts      (novo — truncate, capitalize)
validators.ts  (novo — isCPF, isCNPJ, isPhone)

`app/stores/` — Pinia¶

session.ts    (existente — token/cookie)
user.ts       (existente — profile, isProfileComplete)
ui.ts         (novo — sidebarCollapsed, activeTheme, modalStack)
filters.ts    (novo — filtros globais reativos, debounce, syncWithQueryString)

`app/composables/` — Composables¶

useToast.ts          (novo — wrapper NaiveUI $message com API padronizada)
usePagination.ts     (novo — page/limit/total reativos + métodos)
useFilters.ts        (novo — estado + debounce + sync query string)
useConfirm.ts        (novo — dialog de confirmação via $dialog NaiveUI)
useErrorBoundary.ts  (novo — normaliza ApiError → mensagem pt-BR amigável)

`app/shared/components/` — UI Kit¶

UiListPanel/         (existente)
UiSurfaceCard/       (existente)
UiEmptyState/        (existente)
UiSegmentedControl/  (existente)
UiConfirmDialog/     (novo — NModal de confirmação reutilizável)
UiFilterBar/         (novo — NInput + NSelect + NDatePicker combinados)
UiPagination/        (novo — NPagination configurado)
UiStatusBadge/       (novo — NTag semântico por status string)
UiCurrencyDisplay/   (novo — formatCurrency + cor condicional)

Sequência de execução recomendada¶

Fase 1 — Core (desbloqueador)
  WF1 → WF2 → WF3 → WF4 → WF5

Fase 2 — Composables + UI Kit
  WF6 → WF7

Fase 3 — Integração (paralelo após WF1 + WF2)
  WB1 (sem dependência)
  WI1, WI2, WI4 (sem mutations complexas)
  WI3, WI5 (com mutations + optimistic update)
  WI6 (checkout — maior risco)

Critérios de qualidade¶

Cobertura ≥ 85% em todos os arquivos novos (lines/functions/statements/branches)
Zero elementos HTML puros em páginas (apenas componentes NaiveUI ou Shared UI Kit)
Todos os componentes novos com stories Storybook (mínimo 3 variações)
pnpm quality-check passando no branch antes de abrir PR
Responsive validado em 375px, 768px e 1280px

Referências¶

app/core/http/http-client.ts — client HTTP existente
app/composables/useAuth/ — exemplo de API adapter existente
app/shared/components/UiListPanel/ — exemplo de componente shared existente
.context/61_design_source_of_truth.md — contrato canônico de design para bootstrap de agentes
docs/wiki/MVP-1-Web-Rebrand-Total-2026-04.md — direção oficial do rebrand web
docs/wiki/MVP-1-Web-Design-System-v3-Market-Pulse.md — tokens/componentes/estados oficiais do web
TASKS.md — status de execução das tasks WF/WI/WB