Dados fake (Faker)

O template pode rodar sem nenhum backend, com dados gerados por @faker-js/faker — é assim que este site (/docs, /changelog e o app em si) fica navegável publicado numa Vercel sem servidor próprio. Duas flags controlam tudo, em um único arquivo central:

// src/config/demo.config.ts
export const DEMO_CONFIG = {
  mockApi: readBooleanFlag(process.env.NEXT_PUBLIC_ENABLE_MOCK_API),
  disableAuth: readBooleanFlag(process.env.NEXT_PUBLIC_DISABLE_AUTH),
};

NEXT_PUBLIC_ENABLE_MOCK_API

Troca o adapter do axios por um adapter fake (src/lib/mock/adapter.ts), sem tocar em nenhum hook ou componente acima dessa camada — useFetch/useCreate/useUpdate/useDelete continuam chamando api.get/api.post/... normalmente, sem saber que a resposta não veio de rede.

De propósito essa troca não mora dentro de src/lib/axios-instance.ts (o arquivo em si fica limpo, sem saber que o modo demo existe) — mora em src/lib/mock/bootstrap.ts, importado uma única vez (só pelo efeito colateral) em src/providers/root-providers.tsx:

// src/lib/mock/bootstrap.ts
if (DEMO_CONFIG.mockApi) {
  api.defaults.adapter = async (config) => {
    const { mockAdapter } = await import("./adapter"); // code-split
    return mockAdapter(config);
  };
}

Isso importa: src/lib/axios-instance.ts é parte do kernel compartilhado (@kso/base no registry) — um projeto cliente que instala @kso/lojas não deve ganhar @faker-js/faker de brinde. Mantendo a ligação fora dele, src/lib/mock/ inteiro fica de fora do que é publicado.

O adapter é um CRUD genérico: qualquer rota registrada em ROUTE_TO_COLLECTION (src/lib/mock/db.ts) vira GET/GET :id/POST/ PUT/DELETE completos contra uma coleção fake. As 22 entidades do sistema (todos os módulos de cadastro + usuários/papéis/permissões/sistemas) são seedadas uma vez, respeitando referência entre entidades de verdade (ex: colaborador.gerencia aponta para uma gerência que existe de fato na coleção gerencias), e persistidas em localStorage para sobreviver a um refresh — cada visitante do demo tem seu próprio "banco".

NEXT_PUBLIC_DISABLE_AUTH

Pula o fluxo de login inteiro:

• src/middleware.ts para de checar sessão/redirecionar para /login.
• useAuthUser (src/lib/auth/hooks/use-auth-user.ts) retorna um usuário sintético (isAdmin: true) sem chamar /auth/me.

AuthGuard e Can não mudam nada — eles continuam checando user e isAdmin do jeito que sempre checaram; só a fonte desses dados muda.

Estendendo para um módulo novo

// src/lib/mock/factories/<dominio>.ts
export function createMeuModulo(index: number): IMeuModulo {
  return { _id: fakeId(), nome: faker.commerce.productName(), ...fakeTimestamps() };
}

Registre a coleção em ROUTE_TO_COLLECTION e chame a factory em seedDatabase() (src/lib/mock/db.ts), na ordem certa se o módulo referenciar outro (ex: um módulo que referencia lojas deve ser seedado depois de lojas).

Removendo o mock e voltando a um backend real

1. Apague a pasta src/lib/mock/ (adapter, banco fake e todas as factories).
2. Remova a linha import "@/lib/mock/bootstrap"; de src/providers/root-providers.tsx.
3. Reverta o trecho equivalente em src/lib/auth/hooks/use-auth-user.ts e em src/middleware.ts (ambos guardados por if (DEMO_CONFIG.disableAuth)).
4. Apague src/config/demo.config.ts e as duas variáveis do .env.
5. npm uninstall @faker-js/faker.

Como cada mudança está isolada atrás de uma checagem de flag (nunca no meio da lógica de negócio), remover é apagar um arquivo/import por vez — não precisa desfazer nada no restante do código, e src/lib/axios-instance.ts nunca precisa ser tocado.