# Fase 7 (parte 1) — Banco de Dados & Arquitetura

Objetivo: transformar as entidades/relações da planilha em um schema de banco de dados real e escolher a stack. A planilha vira tabelas; as relações (PROCV) viram chaves estrangeiras.

## Sumário
- Stack padrão Imperatriz
- Da planilha ao schema (regras de modelagem)
- Tipos de coluna
- Campos calculados (não armazenar o que se calcula)
- Migração dos dados existentes
- Saída desta fase

## Stack padrão Imperatriz

A menos que a pessoa peça outra coisa:

| Camada | Padrão |
|---|---|
| Linguagem | Node + TypeScript |
| Banco | PostgreSQL (para multi-usuário/produção). SQLite (WAL) só pra app pessoal de 1 usuário |
| Backend | Express/Fastify |
| Frontend | Next.js / React |
| Design | Painel da Tata + 21st (Fase 6) |
| Deploy | VPS Hostinger via `skill-deploy-vps` (ou provedor da pessoa) |

Escolha de banco: **se há mais de 1 usuário ou qualquer chance de crescer, use Postgres.** SQLite não aguenta concorrência. (Vários apps do ecossistema nasceram em SQLite e viraram gargalo — não repetir.)

## Da planilha ao schema

1. **Cada entidade (Fase 2) → uma tabela.** Cabeçalhos → colunas.
2. **Toda tabela ganha:** `id` (PK), `created_at`, `updated_at`. Se multi-usuário: `created_by`. Se multi-tenant: `organization_id` em todas.
3. **Relações (PROCV/lookup da Fase 3) → chave estrangeira.** Ex.: `orcamentos.material_id` → `materiais.id`. Não duplique o nome/preço do material na tabela de orçamento; referencie por id (o preço "congelado" no momento da venda é exceção — ver abaixo).
4. **Listas suspensas fixas → enum** (ou tabela de domínio se a lista muda com frequência).
5. **Normalize com bom senso:** evite repetir dados, mas não exagere a ponto de complicar. Catálogos viram tabelas próprias.

### Valores "congelados" (snapshot)
Quando a planilha calcula um total com o preço **do momento**, armazene o valor calculado **e** a referência. Ex.: orçamento guarda `preco_unitario_no_momento` além de `material_id` — assim, mudar o preço do catálogo no futuro não altera orçamentos antigos. Confirme isso com a pessoa (é uma decisão de negócio).

## Tipos de coluna

| Da planilha | Postgres |
|---|---|
| Texto | `text` / `varchar` |
| Número | `integer` / `numeric` |
| Moeda | `numeric(12,2)` (nunca float pra dinheiro) |
| Data | `date` / `timestamptz` |
| Sim/Não | `boolean` |
| Seleção fixa | `enum` ou FK pra tabela de domínio |
| Foto/arquivo | guardar o **caminho/URL**; arquivo em disco/objeto, não no banco |

## Campos calculados

**Não armazene o que é derivado** (ex.: `area = largura × altura`, `total = area × preço`). Calcule no backend a cada leitura/escrita. Exceção: snapshots (acima) e agregações pesadas que valem cache.

## Migração dos dados existentes

A planilha já tem dados reais. Ofereça importá-los:
1. Use o `scripts/analyze_spreadsheet.py` (ou leitura direta) pra ler as linhas das abas de trabalho/catálogo.
2. Mapeie cada linha pros campos da tabela; resolva relações por nome → id.
3. Importe primeiro os catálogos, depois as transações (respeitando as FKs).
4. Mostre um resumo ("X materiais e Y orçamentos importados") e valide com a pessoa.

## Saída desta fase (para o BLUEPRINT.md)

```
## Fase 7 — Banco & Arquitetura
**Stack:** [confirmada]
**Banco:** [Postgres/SQLite] — motivo
**Tabelas:** nome — colunas (tipo) — FKs
**Campos calculados:** [lista]
**Snapshots:** [lista]
**Migração de dados:** [sim/não] — volume estimado
```

Depois siga para `07-build-deploy.md`.
