Casa das Artes — Documentação

Requisição inicial do projeto: sistema modular e completo de gestão e precificação para pequenos negócios criativos e produtivos (artesanato, confeitaria, costura, cosméticos etc.).

O coração do sistema é uma calculadora de precificação universal e avançada. Ao redor desse núcleo, o app se expande para um ERP leve e automatizado, cobrindo suprimentos, produção, vendas, financeiro e planejamento.

Módulos pedidos no PRD: Dashboard, Engenharia e Precificação (produtos, fichas técnicas, kits), Suprimentos e Compras (materiais, compras com rateio de frete), Operação (pedidos em Kanban e CRM de clientes), Financeiro e Planner.

Banco de dados: PostgreSQL via Supabase (projeto casadasartes). Controle de versão: GitHub (carinavalladares).

2.1 Preço por dentro (fórmula obrigatória)

Toda precificação usa markup divisor, nunca markup multiplicador:

Preço = Custo Total / (1 - Lucro% - Comissão/Taxas%)

Implementada em src/lib/pricing.ts e usada na Calculadora e na ficha técnica de Produtos.

2.2 Custo-hora e custos globais

Cada produto define rendimento, tempo de produção (min), custo de mão de obra/hora, custos indiretos (%), margem de lucro (%) e taxas (%). O custo de materiais vem da ficha técnica (composição).

2.3 Inteligência de suprimentos

Compras registram itens com quantidade, custo unitário e frete rateado (o frete da compra é diluído proporcionalmente ao valor de cada item). Ao salvar, o estoque e o custo médio ponderado dos materiais são atualizados.

• Frontend: React 19 + TanStack Start v1 (SSR) + TanStack Router (rotas em arquivos em src/routes/) + TanStack Query.
• Estilo: Tailwind CSS v4 com tokens semânticos em src/styles.css + componentes shadcn/ui.
• Backend: Supabase (Postgres, Auth, RLS) conectado ao projeto egycztqsemevusgadxig. Lógica de servidor em createServerFn (TanStack), nunca em Edge Functions novas.
• Autenticação: e-mail/senha; rotas protegidas sob o layout src/routes/_authenticated/ com redirecionamento para /auth.
• Idioma/moeda: pt-BR; valores monetários em BRL via Intl.NumberFormat.

Padrão de dados: loaders de rota usam context.queryClient.ensureQueryData(queryOptions) e componentes leem com useSuspenseQuery. Funções autenticadas usam o middleware requireSupabaseAuth (RLS aplicado como o usuário logado).

• profiles — perfil do usuário (nome, nome do negócio); id referencia auth.users.
• user_roles — papéis (admin, user) por usuário; consulta via função has_role(user_id, role).
• convites — tokens de convite (uso único, validade de 7 dias, revogáveis).
• materiais — insumos: unidade, custo por unidade, estoque atual.
• compras + compra_itens — entradas de suprimentos com fornecedor, frete e rateio por item.
• produtos + produto_materiais — ficha técnica: composição de materiais, rendimento, tempo, custos, margens, preço sugerido e final.
• kits + kit_itens — combos de produtos com desconto percentual e preço final.
• clientes — CRM: contato, endereço, observações.
• pedidos + pedido_itens — vendas com status (novo → em produção → pronto → concluído), itens com preço fechado (snapshot).
• financeiro — contas a pagar/receber (tipo, categoria, vencimento, status), vinculável a pedido.
• planner — tarefas de produção/agenda, vinculáveis a pedido.

Segurança: todas as tabelas têm RLS habilitado com políticas auth.uid() = user_id (cada usuário só vê os próprios dados). Toda tabela possui GRANT explícito para authenticated e service_role, e trigger update_updated_at_column.

5.1 Automação de pedido concluído (trigger)

Quando um pedido muda para status concluido, a função pedido_concluido_automation() cria automaticamente:

• Uma receita no financeiro (categoria "Vendas", valor total do pedido), se ainda não existir para aquele pedido;
• Uma tarefa de produção no planner, se ainda não existir.

5.2 Rateio de frete

Na compra, o frete é distribuído proporcionalmente ao valor de cada item (frete_rateado), compondo o custo_total do item e o custo médio do material.

5.3 Snapshot de preços

Itens de pedido guardam preco_fechado e subtotal no momento da venda — mudanças posteriores no produto não alteram pedidos antigos.

• Cadastro público desabilitado: a tela /auth só tem login. Novos usuários entram exclusivamente por convite.
• Admin fundador: buu.592@gmail.com (papel admin em user_roles). Papéis nunca ficam na tabela de perfil — sempre em tabela separada.
• Gestão de convites: página /convites (somente admin, link "Convites" na sidebar). Gera link /convite/<token> válido por 7 dias e de uso único; pode ser revogado.
• Aceite de convite: rota pública /convite/$token — o convidado define nome, e-mail e senha; a conta é criada via cliente admin no servidor (registrarComConvite em src/lib/convites.functions.ts).
• Verificação de papel: função SQL has_role (security definer) — padrão oficial Supabase; o aviso do linter sobre ela é intencional e documentado na memória de segurança.

• /dashboard — visão geral: receitas/despesas do mês, pedidos ativos, tarefas do dia.
• /pedidos — Kanban de produção (novo, em produção, pronto, concluído).
• /produtos e /produtos/$produtoId — catálogo e ficha técnica com cálculo de preço sugerido.
• /kits — combos com desconto percentual.
• /materiais — estoque e custo de insumos.
• /compras — entradas com rateio de frete e atualização de custo médio.
• /clientes — CRM.
• /financeiro — contas a pagar/receber.
• /planner — agenda/tarefas vinculadas a pedidos.
• /calculadora — calculadora de precificação avulsa (preço por dentro).
• /convites — administração de convites (somente admin).
• /docs — esta documentação (rota pública).

Tema artesanal definido em src/styles.css com tokens semânticos (background, foreground, primary, card, muted etc.) e fontes display/sans. Regra do projeto: nunca hardcodar cores nos componentes (text-white, bg-[#...]) — sempre usar tokens, para não quebrar o tema.

Como rodar

• Variáveis de ambiente já configuradas: VITE_SUPABASE_URL, VITE_SUPABASE_PUBLISHABLE_KEY (cliente) e SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, SUPABASE_SERVICE_ROLE_KEY (servidor — nunca expor ao browser).
• O dev server roda com Vite; o roteador gera src/routeTree.gen.ts automaticamente — nunca edite esse arquivo.

Regras de ouro do projeto

• Nova rota protegida → criar dentro de src/routes/_authenticated/.
• Lógica de servidor → createServerFn em src/lib/*.functions.ts; dados do usuário sempre com requireSupabaseAuth. Não criar Supabase Edge Functions.
• Mudança de schema → sempre via ferramenta de migração SQL (com GRANTs e RLS na mesma migração). Nunca editar src/integrations/supabase/types.ts (é gerado).
• Toda precificação nova deve usar a fórmula de preço por dentro (seção 2.1).
• Papéis/permissões sempre via user_roles + has_role, nunca no cliente.

Pendências conhecidas / roadmap sugerido

• Ativar a proteção contra senhas vazadas no Supabase Dashboard (Authentication → Providers).
• Baixa automática de estoque de materiais ao concluir pedido.
• Relatórios/exportação (CSV/PDF) no financeiro.
• Anexos/fotos de produtos via Supabase Storage.