---
name: planilha-ao-app
description: Transforma planilhas (Excel/Sheets/CSV) e documentos de processos em aplicativos web no ar, guiando uma pessoa leiga de ponta a ponta pelo framework "Da Planilha ao App" em 7 fases com checkpoint em cada uma — Entrada, Processo, Regras, Usuários & Permissões, Automações, Interface, Banco & Deploy. Mapeia a lógica embutida (cadastros, condicionais, fluxo), extrai regras (PROCV/VLOOKUP, SE/IF, listas suspensas, dependências, formatação condicional), define usuários/permissões, sugere automações que a pessoa nem imaginou (e-mail, WhatsApp via Evolution, alertas, relatórios), aplica design bonito (21st + Painel da Tata) e sobe na VPS (Hostinger por padrão). Use quando pedir "transformar planilha em app", "virar app essa planilha", "app a partir do meu Excel", "da planilha ao app", "transformar planilha de orçamento/cálculo/cadastro em sistema", "criar sistema a partir da planilha", "automatizar minha planilha", "transformar documento de processos em app", ou mandar um .xlsx/.csv/.ods pra virar sistema.
---

# Da Planilha ao App

Pega uma planilha (ou documento de processos) de uma pessoa **leiga em programação** e a transforma, passo a passo, em um **aplicativo web no ar**. A planilha já contém um sistema escondido — cadastros, regras, fluxo de trabalho. Esta skill desenterra esse sistema e o reconstrói como software de verdade, com banco de dados, login, automações e interface bonita.

## Princípios desta skill

1. **A pessoa é leiga.** Nunca jogue jargão técnico sem traduzir. Explique cada decisão com analogia ("o login é a portaria do prédio", "o banco de dados é o arquivo morto que nunca se perde"). Decida o lado técnico por ela, mas mostre o porquê.
2. **A planilha é a fonte da verdade.** Tudo que o app faz tem origem em algo que já existe na planilha. Não invente funcionalidade que contradiga a lógica dela sem avisar.
3. **Uma fase por vez, com checkpoint.** NUNCA pule para a fase seguinte sem fechar a atual com a pessoa. Cada fase termina com um resumo do que foi entendido + pergunta de aprovação. Isso evita construir o app errado.
4. **Reuse o ecossistema, não reinvente.** Deploy → `skill-deploy-vps`. Build autônomo longo → `/construtor-imperatriz`. Design → 21st + design system Painel da Tata. Arquitetura de porte maior → `/arquitetura-imperatriz`.
5. **Stack padrão Imperatriz** (a menos que a pessoa peça outra): Node + TypeScript, PostgreSQL, Next.js/React, design Painel da Tata, deploy em VPS Hostinger. Veja `references/06-banco-arquitetura.md`.

## Visão geral do framework (7 fases)

```
[Planilha/Documento]
   │
 1. ENTRADA          → localizar e abrir o arquivo
 2. PROCESSO         → mapear de A a Z a lógica (cadastros, fluxo, condicionais)
 3. REGRAS           → extrair fórmulas e dependências → regras de aplicação
 4. USUÁRIOS/PERMISSÕES → quem usa, como, com que poderes
 5. AUTOMAÇÕES       → estudar o domínio e sugerir o que ela não imaginou
 6. INTERFACE        → design system + telas
 7. BANCO + DEPLOY   → schema, build e subir na VPS
   │
[Aplicativo no ar]
```

Trabalhe as fases **em ordem**. Cada fase tem um arquivo de referência com a metodologia detalhada — leia o arquivo da fase ANTES de executá-la.

## Protocolo de checkpoint (obrigatório em toda fase)

Ao fim de cada fase, produza um bloco assim e **pare** até a pessoa responder:

```
✅ FASE [N] — [NOME] — o que eu entendi:
[resumo em linguagem simples, com bullets]

❓ Confirma que está certo? Quer ajustar algo antes de eu seguir?
```

Mantenha um arquivo vivo `BLUEPRINT.md` na pasta do projeto, acrescentando o resultado aprovado de cada fase. Ele é a memória do projeto e o contrato do que será construído.

---

## Fase 1 — Entrada

**Objetivo:** localizar e abrir o arquivo.

1. Pergunte onde está o arquivo no computador (caminho) ou peça pra anexar. Aceita `.xlsx`, `.xlsm`, `.csv`. Para `.ods`/`.xls`, peça pra converter pra `.xlsx` (ou converta via `soffice --headless --convert-to xlsx`).
2. Para **documentos de processos** (`.docx`/`.pdf` com muitos processos), use a skill `docx` / `pdf` pra extrair o texto — o framework é o mesmo, mas a Fase 2 mapeia processos descritos em texto em vez de células.
3. Pergunte em uma frase: **"O que essa planilha faz hoje no seu dia a dia?"** — a resposta orienta toda a leitura.

Não há checkpoint formal aqui; siga direto pra Fase 2 assim que tiver o arquivo.

## Fase 2 — Processo

**Objetivo:** mapear de A a Z a lógica embutida.

Rode o analisador (ele faz a radiografia estrutural):

```bash
scripts/analyze_spreadsheet.py CAMINHO.xlsx --out /tmp/analise.json --sample 8
```

Depois leia `references/01-mapear-processo.md` e siga a metodologia: identificar abas de catálogo vs. abas de trabalho, áreas de cadastro, entidades, e o fluxo do processo (o que entra, o que é calculado, o que sai). **Checkpoint ao fim.**

## Fase 3 — Regras

**Objetivo:** traduzir cada fórmula/dependência em regra de aplicação.

Leia `references/02-extrair-regras.md`. Use o JSON da Fase 2 (campos `formulas`, `validacoes_dados`, `formatacao_condicional`) pra catalogar: lookups (PROCV → relacionamento entre tabelas), condicionais (SE → regra de negócio), validações (lista suspensa → campo de seleção), cálculos (área = largura × altura → campo computado), formatação condicional (→ estados/badges visuais). **Checkpoint ao fim.**

## Fase 4 — Usuários & Permissões

**Objetivo:** definir quem usa o app e com que poderes.

Leia `references/03-usuarios-permissoes.md`. Descubra: é uso pessoal (1 pessoa), banco de dados compartilhado, ou empresa multi-usuário com papéis? Defina autenticação e o modelo de permissões (RBAC) na medida certa — sem complicar o que é simples. **Checkpoint ao fim.**

## Fase 5 — Automações

**Objetivo:** sugerir proativamente automações que a pessoa não pediu.

**Esta é a fase onde a skill agrega mais valor.** Estude o domínio do app (o que ele faz, pra quem) e leia `references/04-automacoes.md` — catálogo de automações por tipo de negócio (e-mail, WhatsApp via Evolution, alertas, relatórios agendados, lembretes, integrações). Apresente 3–6 sugestões priorizadas com o ganho de cada uma. **Checkpoint ao fim.**

## Fase 6 — Interface

**Objetivo:** definir o visual e as telas.

Leia `references/05-interface.md`. Pergunte se já existe identidade visual/preferência. Por padrão aplique o design system **Painel da Tata** e use **21st** (Magic MCP / `/ui-designer` / `/design-page-builder`) pra componentes bonitos. Liste as telas derivadas das entidades (lista, cadastro, detalhe, dashboard). **Checkpoint ao fim.**

## Fase 7 — Banco de Dados & Deploy

**Objetivo:** construir e colocar no ar.

Leia `references/06-banco-arquitetura.md` (derivar o schema a partir da planilha + stack) e depois `references/07-build-deploy.md` (build + deploy).

1. Modele o schema do banco a partir das entidades (cada aba de catálogo/trabalho → tabela).
2. Scaffold do app na stack Imperatriz padrão.
3. Para builds longos e autônomos, considere acionar `/construtor-imperatriz` com o `BLUEPRINT.md` como escopo.
4. Deploy via **`skill-deploy-vps`** (Hostinger por padrão; respeite outro provedor se a pessoa usar). Confirme domínio/subdomínio antes.
5. **Checkpoint final:** entregue a URL no ar + um guia de uso de 1 página pra pessoa leiga.

---

## Arquivos de referência

- `references/01-mapear-processo.md` — como ler a planilha e extrair entidades + fluxo
- `references/02-extrair-regras.md` — taxonomia de fórmulas → regras de app (PROCV, SE, validações...)
- `references/03-usuarios-permissoes.md` — modelos de usuário e permissões por porte
- `references/04-automacoes.md` — catálogo de automações por domínio (e-mail, WhatsApp/Evolution...)
- `references/05-interface.md` — design system Painel da Tata + 21st + telas
- `references/06-banco-arquitetura.md` — schema a partir da planilha + stack padrão
- `references/07-build-deploy.md` — build e deploy (integra com skill-deploy-vps)

## Script

- `scripts/analyze_spreadsheet.py` — radiografia estrutural do `.xlsx`/`.csv` em JSON (abas, cabeçalhos, amostra, fórmulas classificadas, validações, formatação condicional, intervalos nomeados). Roda via `uv` (Python do brew quebrado nesta máquina). Use sempre na Fase 2.
