# Documento-Mestre — Plataforma de Gestão de Recursos, Eventos, Cotações e Repasses

> **Para implementação no Claude Code.** Este documento é a especificação completa. O protótipo funcional em HTML (`gestao-cultura-festa-do-milho.html`) é a referência viva da Fase 1 e a fonte dos dados-semente (exportáveis em JSON pelo botão *Backup*).

---

## 0. Como ler este documento

- **Seções 1–4:** contexto, princípios, stack e o conceito central (estágios de comprometimento).
- **Seções 5–8:** modelo de dados, regras de negócio, camada de acesso/visões e módulos.
- **Seção 9:** dados-semente reais (fontes, 43 empenhos, pacote da Festa do Milho).
- **Seção 10:** roadmap em fases (o que construir primeiro).
- **Seção 11 + Apêndices:** schema SQL completo e políticas RLS.

O gestor (dono da plataforma) é uma única pessoa que opera vários âmbitos simultâneos: Secretaria de Cultura, empresas de produção (sócio em uma, assessor em outras), associações, paróquia/instituto e a própria gestão pessoal. **Cada interlocutor enxerga apenas o recorte que lhe diz respeito.** Essa segregação é requisito de primeira classe, não enfeite.

---

## 1. Contexto e visão geral

### 1.1 O problema
Gerir, num só lugar e com rastreabilidade total, o ciclo financeiro de eventos culturais e privados: de onde vem o recurso (fontes/cofres), como ele é cotado, comprometido, executado e prestado de contas — e apresentar cada recorte a um público diferente sem vazar o que não é dele.

### 1.2 O ator central e os âmbitos
- **Gestor central (CEO da plataforma):** vê tudo, inclusive relações que os demais desconhecem.
- **Secretaria de Cultura:** camada orçamentária pública (fontes, empenhos, saldo).
- **Empresas de produção** (ex.: RMW, Eternize, Galles): cada uma com seu painel isolado — custos, margem, repasses, sociedade.
- **Associações / Paróquia / Instituto:** recebem visões e relatórios filtrados.
- **Contratantes / agentes políticos:** recebem orçamentos (globais ou discriminados, conforme o caso).

### 1.3 Migração a partir do Notion
O Notion foi usado **apenas como referência** e prototipagem; suas limitações (colunas engessadas, sem preenchimento bidirecional, sem controle de acesso real) são justamente o que esta plataforma supera. As 6 bases originais do Notion viram tabelas relacionais:

| Base no Notion | Vira tabela |
|---|---|
| 🏦 Saldo financeiro — Cofres | `fontes` (cofres) |
| 🧮 Cálculo de Itens por Evento (Real × Processo) | `itens_calculo` |
| 🎭 Eventos Cultura | `eventos` |
| 📑 Itens Cotados da Fonte de Preço | `itens_cotados` |
| 📄 Fontes de Preço (ARP/Proposta/Orçamento) | `fontes_preco` |
| 🏢 Fornecedores | `fornecedores` |

**Cadeia auditável obrigatória (deve sobreviver):**
`Evento → Item (Cálculo) → Preço (Item Cotado / Fonte de Preço) → Fornecedor → Cofre (saldo) → Real executado`

---

## 2. Princípios de produto

1. **Guiado e educativo.** A plataforma conduz o planejamento e a cotação como um formulário inteligente. Campos **obrigatórios travam o avanço**; campos **facultativos** são claramente marcados como "opcional, mas recomendado". Nada fica pela metade por esquecimento.
2. **Preenchimento bidirecional valor↔percentual.** Toda relação valor/percentual é editável pelos dois lados, **célula por célula** (não coluna inteira engessada como no Notion). Digitou o %, calcula o valor; digitou o valor, recalcula o % implícito.
3. **Rastreabilidade total / auditável.** Cada valor responde: qual evento, qual item, qual preço de referência, qual fornecedor (oficial e executante), qual cofre custeou, qual o processo vs. o real.
4. **Saldo como verdade operacional, em camadas.** Ver Seção 4.
5. **Separação processo × real.** Sempre as duas camadas, para justificar diferenças (remanejamentos legítimos dentro das faixas de tolerância).
6. **Visões por audiência.** Mesmo banco, recortes diferentes. Exportações com layout/marca por destinatário.
7. **Acesso restrito por ator.** Login específico; cada um só vê o seu painel.

---

## 3. Stack técnica

Confirmada pelo gestor (já habituado): **Supabase + Cloudflare + SQL**.

### 3.1 Componentes
- **Supabase**
  - **Postgres** — banco relacional principal.
  - **Auth** — login por usuário, com associação a um ou mais âmbitos (empresa/secretaria/etc.).
  - **Storage** — anexos da prestação de contas (relatório fotográfico, documentos, espelhos de emenda).
  - **RLS (Row Level Security)** — o coração da camada de visões: a empresa A só lê linhas da empresa A. Ver Apêndice B.
- **Cloudflare**
  - **Pages** — hospedagem do front-end.
  - **Workers / Functions** — geração de PDF/Excel por marca, exportações, automações (ex.: parsing de empenhos).
- **Front-end** — framework à escolha do implementador (sugestão: Next.js/React ou SvelteKit). O protótipo atual é HTML/JS vanilla e serve de base visual.

### 3.2 Migração do protótipo
O HTML da Fase 1 persiste em `localStorage` e exporta **JSON**. Esse JSON é o **seed inicial**: o Claude Code deve criar um importador que lê o JSON e popula `fontes`, `empenhos` e `itens_festa`. A partir daí o Supabase vira a fonte de verdade.

---

## 4. Conceito central — Estágios de Comprometimento do Saldo

Este é o conceito mais importante da plataforma. O saldo **não é um número único**: ele é consumido em **camadas reversíveis** até virar definitivo. Cada despesa/item carrega o seu **estágio atual** e migra de camada conforme avança.

### 4.1 A escada de estágios

| Chave interna | Rótulo (fonte **pública**) | Rótulo (contexto **empresarial**) | Significado | Reversível? |
|---|---|---|---|---|
| `pre_reserva` | Pré-reserva | Pré-reserva | Intenção de gasto, sem cotação ("separa R$200 mil pra festa") | Sim, livre |
| `reserva` | Reserva / Cotação | Reserva / Cotação | Já cotado, valor de referência definido | Sim |
| `comprometido` | Empenhado | Contratado (firme) | Comprometimento formal; valor definitivo que sai da fonte | Só por anulação/remanejamento |
| `devido` | **Liquidado** | **A pagar (devido)** | Serviço entregue/atestado; obrigação reconhecida | Não |
| `pago` | Pago | Pago | Desembolso efetivo; encerra o ciclo | Não |

> **Terminologia adaptativa:** o estágio `devido` exibe **"Liquidado"** quando a fonte tem `contexto = 'publico'` e **"A pagar (devido)"** quando `contexto = 'empresarial'`. A chave interna é sempre a mesma — só o rótulo na tela troca. O mesmo vale para `comprometido` (Empenhado ↔ Contratado).

> **Observação do gestor:** pelo caminho da prefeitura, o **empenho** é o valor definitivo; por fora (empresa), a **cotação** já cumpre esse papel de "firmar" o valor. O sistema aceita os dois fluxos: em contexto empresarial, a transição `reserva → comprometido` pode ser automática ao fechar a cotação.

### 4.2 Os dois saldos (leituras simultâneas)

```
Saldo da fonte (cofre)
 ├─ Teto (dotação / disponibilidade)
 ├─ (−) Σ pré-reservas        → "comprometido provisório"
 ├─ (−) Σ reservas/cotações   → "comprometido em cotação"
 ├─ (−) Σ comprometido (empenho/contrato firme)
 ├─ (−) Σ devido (liquidado/a pagar)
 └─ (−) Σ pago

SALDO LIVRE       = Teto − (pré-reservas + reservas + comprometido + devido + pago não coberto)
                    → "quanto eu ainda posso planejar/prometer?"
SALDO DISPONÍVEL  = Teto − comprometido_firme_ou_acima
                    → "quanto oficialmente sobrou na fonte?" (visão Secretário)
```

> **Importante:** os estágios são cumulativos por hierarquia — um item em `pago` já passou por `comprometido`. Para não contar em dobro, o cálculo soma cada item **uma vez, pelo seu estágio mais avançado**. O "saldo disponível oficial" considera tudo que está em `comprometido` ou acima; o "saldo livre" considera também pré-reservas e reservas.

### 4.3 Máquina de estados
Transições permitidas:
```
pre_reserva → reserva → comprometido → devido → pago
            ↘ (cancelar) volta para estágio anterior ou remove (apenas até 'comprometido')
comprometido → (anulação/remanejamento) → realoca para outra rubrica/fonte
```
Regras:
- Antes de `comprometido`: transições e cancelamentos livres.
- A partir de `comprometido`: só sai via **anulação** ou **remanejamento** registrado (ver Seção 6.4), preservando o histórico.
- `devido` e `pago` são irreversíveis (apenas estorno explícito e auditado).

---

## 5. Modelo de dados (entidades)

Resumo das entidades. O schema SQL completo está no **Apêndice A**.

### 5.1 Núcleo financeiro/eventos (herdado do Notion)
- **`ambitos`** — Secretaria, Empresa RMW, Empresa Eternize, Galles, Associação X, Paróquia/Instituto, Pessoal. Define o "dono" de cada registro e a base da RLS.
- **`fontes`** (cofres) — `codigo`, `nome`, `contexto` (publico/empresarial), `teto`, `vigencia`, `tipo` (emenda, licitação, fonte orçamentária 100/117/181/234/281, convênio, receita própria, aporte), `nota_interna`, `protocolo_id`, `ambito_id`, `limite_remanejamento_pct`.
- **`eventos`** — `nome`, `contexto`, `periodo_inicio`, `periodo_fim`, `local`, `responsavel`, `status`, `ambito_id`. (Ex.: Festa do Milho, Festa Junina, Corpus Christi.)
- **`fornecedores`** — `nome`, `cnpj_cpf`, `tipo` (oficial / executante-sub), `contato`, `ambito_id`.
- **`fontes_preco`** — documento de referência (ARP, proposta, orçamento): `tipo`, `numero`, `vigencia`, `anexo_url`.
- **`itens_cotados`** — quebra do documento em itens unitários: `descricao`, `unidade`, `vu`, `fornecedor_oficial_id`, `fonte_preco_id`.
- **`itens_calculo`** (livro-razão) — amarra tudo: `evento_id`, `fonte_id` (cofre), `item_cotado_id`, `fornecedor_executante_id`, `dias`, `qtd_por_dia`, `qtd_total`, `vu_referencia`, `valor_total_processo`, `vu_efetivo`, `qtd_real`, `total_real`, `estagio` (Seção 4), `agenda_entrega`, `agenda_instalacao`, `conferente`, `observacoes`, `motivo_diferenca`.

### 5.2 Módulos novos
- **`cotacoes`** — `item_id`, `fornecedor_id`, `valor`, `forma_pagamento`, `data`, `selecionada` (bool). Suporta variações de preço por forma de pagamento.
- **`movimentos`** — tabela unificada de **transformações sobre valor-base** (margem e remanejamento usam a mesma mecânica). Campos: `tipo` (`margem` | `remanejamento`), `origem_ref`, `destino_ref`, `valor_base`, `modo` (`percentual` | `absoluto`), `percentual`, `valor_movimento`, `data`, `observacao`. Ver Seções 6.2 e 6.4.
- **`prestacao_contas`** — `evento_id`, `fonte_id`, `etapa` (planejado/contratado/executado/documentado/prestado), `status`, e anexos via `anexos`.
- **`anexos`** — `tipo` (relatorio_fotografico/documento/espelho_emenda), `url` (Supabase Storage), `vinculo_tipo` (evento/item/prestacao/fonte), `vinculo_id`.
- **`custos_fixos`** — catálogo recorrente (gasolina, mão de obra, deslocamento) aplicável a todo evento, só editando o valor.
- **`atores_visoes`** — define, por ator, o que esconder e o nível de detalhe. Ver Seção 7.
- **Societária:** `socios`, `aportes`, `pagamentos_aporte`, `distribuicao_lucros`. Ver Seção 6.5.
- **`inventario`** — ativos próprios (cadeiras, tendas, som, gerador): `item`, `quantidade`, `valor_unitario_repasse`, `gera_custeio` (bool, subsídio cruzado). Ver Seção 6.6.
- **`protocolos`** — repositório de "como resolver X": `titulo`, `categoria` (emenda/dado/burocracia), `passos`, `orgao`, `departamento`, `contato`, `meio` (ofício/pessoa). Reutilizável; fontes podem linkar para um protocolo.

---

## 6. Regras de negócio

### 6.1 Saldo da fonte
```
empenhado_liquido(fonte)  = Σ (vl_empenho − vl_anulado) dos empenhos da fonte
saldo_disponivel(fonte)   = teto − Σ(itens em estágio ≥ comprometido)
saldo_livre(fonte)        = teto − Σ(itens em qualquer estágio, contados uma vez pelo mais avançado)
status                    = disponivel | no_limite (<5% do teto) | zerado | estourado (saldo<0)
```

### 6.2 Motor bidirecional valor↔percentual (margem/repasse)
Aplicável a `movimentos.tipo = 'margem'` e a qualquer distribuição:
```
SE modo = 'percentual':  valor_movimento = valor_base × (percentual/100)
                         preco_repassado = valor_base + valor_movimento
SE modo = 'absoluto':    valor_movimento = valor_informado
                         percentual = (valor_movimento / valor_base) × 100   // recalculado e exibido
```
- **Margem por item** (como na planilha Corpus Christi: custo → +25% → preço) **e por contrato** (margem global sobre o pacote). Ambos suportados.
- **Margem fixa** (itens próprios): percentual estável.
- **Margem variável/travada:** o subcontratado encareceu (ex.: tenda R$350→R$450), mas o preço repassado acordado se mantém — registrar `vu_efetivo` (custo real) separado de `vu_referencia` (preço acordado); a margem é recalculada e pode ficar negativa/reduzida sem alterar o preço ao contratante.
- **Variações por forma de pagamento:** múltiplas linhas em `cotacoes` com `forma_pagamento` distinta (à vista, parcelado).

### 6.3 Confidencialidade de margem (assessoria/intermediação)
O contratante final vê **apenas o preço cobrado** (global ou discriminado, conforme acordado com a empresa). Custo, margem e identidade do subcontratado são **internos da empresa** e nunca aparecem na visão do contratante. Isso é configuração de visão (Seção 7), não cálculo.

### 6.4 Remanejamento (mesma mecânica do movimento)
`movimentos.tipo = 'remanejamento'`: saldo sai de uma rubrica/fonte de origem e entra em outra de destino. **Registro próprio, nunca edição de célula** — preserva o "antes" (planejamento original) e o "depois" (readequação).
```
saldo_efetivo(rubrica) = planejado − executado
                         − Σ(remanejamentos saindo) + Σ(remanejamentos entrando)
```
- **Indicador de tolerância (informativo):** cada fonte tem `limite_remanejamento_pct`. O app mostra um semáforo: "remanejado 14% do teto de 20%". **Apenas informativo** — não bloqueia, não julga. A decisão de pedir autorização prévia ou comunicar depois é do gestor e está fora do escopo do sistema.

### 6.5 Gestão societária — aporte com prêmio decrescente
Modelo confirmado com o gestor. Separar **dois fluxos**:

**(a) A dívida (amortização do aporte):**
```
saldo_devedor = aporte_total − Σ pagamentos_aporte
// Ex.: 170.000 − 115.000 = 55.000 em aberto
```

**(b) O prêmio de lucro (remuneração do capital em risco):**
Numa divisão igualitária, cada sócio vale **1 cota**. O sócio investidor recebe **1 base + 1 cota de prêmio** (= 2× no início). O prêmio **decai proporcionalmente ao saldo devedor**:
```
fator_premio   = saldo_devedor / aporte_total           // 55/170 = 0,324
cota_premio    = premio_inicial × fator_premio          // 1 × 0,324 = 0,324
multiplicador  = 1 + cota_premio                         // hoje ≈ 1,32×
```
Marcos: 0% pago → 2,00× · 50% pago → 1,50× · 75% pago → 1,25× · 100% pago → 1,00× (todos iguais).
- O app calcula **dois cenários lado a lado** (acordo original fixo "17,5 p.p. a mais até o fim" × prêmio decrescente proporcional) para a negociação entre sócios.
- **Remuneração operacional opcional:** um sócio que executa função específica (ex.: técnico de som) pode receber pelo operacional **além** da divisão de lucros — campo opcional, hoje desativado por decisão do grupo, mas previsto no modelo.
- **Distribuição de lucros não igualitária:** suportar percentuais arbitrários por sócio/colaborador (ex.: 10% / 15% / 15%).

> *Nota: regras de sociedade dependem de acordo entre os sócios e do contrato social; o sistema executa a matemática, não a decisão jurídica.*

### 6.6 Subsídio cruzado ("item como ativo de custeio")
Itens marcados `gera_custeio = true` (ex.: cadeiras) operam com margem ~zero, mas sua **receita bruta é destinada a um pool de custeio** (mão de obra, logística). Permite uma simulação:
```
receita_item = quantidade × valor_unitario_repasse
// Ex.: 400 cadeiras × R$2 = R$800 → banca N ajudantes
```
Útil para a proposta à empresa: demonstrar que a cadeira gera capital de custeio em vez de lucro.

---

## 7. Camada de acesso e visões (RLS)

### 7.1 Atores e o que cada um vê

| Ator | Vê | NÃO vê |
|---|---|---|
| **Gestor central** | Tudo, todos os âmbitos, todas as relações | — |
| **Secretário de Economia** | Fontes, empenhos, saldo orçamentário, planejamento da festa por cofre | Margem, custo, empresa, sociedade |
| **Empresa (sócio)** | Painel da sua empresa: custos, margem, repasses, sociedade, inventário | Outras empresas, camada secretaria, relações do gestor |
| **Associação / Paróquia** | Relatórios filtrados do que lhe diz respeito | Margem, outras fontes/eventos |
| **Contratante / político** | Orçamento (global ou discriminado) com preço cobrado | Custo, margem, subcontratado |

### 7.2 Implementação
- Cada linha tem `ambito_id`. RLS no Postgres garante que o usuário só lê linhas dos âmbitos a que pertence (`ator_ambitos`).
- **Campos sensíveis** (custo, margem) ficam em colunas/tabelas com policy adicional: só o âmbito dono e o gestor leem.
- **Visões de exportação** (`atores_visoes`): definem nível de detalhe (global × discriminado) e quais campos suprimir por destinatário.

### 7.3 Exportações por marca
Botões de exportação geram **PDF/Excel com layout por destinatário**:
- Orçamento da empresa → logo/marca da empresa.
- Orçamento via instituto (assessoria) → marca do instituto.
- Orçamento genérico → sem marca.
- Painel Secretário → cabeçalho institucional da Secretaria.

Cada template é uma função no Cloudflare Worker que recebe a visão filtrada e renderiza.

---

## 8. Módulos (resumo funcional)

1. **Eventos** — cadastro, período, status; agrupa o pacote. Modular/replicável (clonar Festa do Milho → Festa Junina).
2. **Cofres / Fontes** — tetos editáveis, saldo em camadas, nota interna, link a protocolo.
3. **Cálculo / Itens** (livro-razão) — processo × real, estágios de comprometimento.
4. **Cotações** — múltiplos fornecedores, formas de pagamento, seleção.
5. **Repasses & Margem** — motor bidirecional, por item e por contrato.
6. **Remanejamentos** — registro com histórico, indicador de tolerância.
7. **Prestação de Contas & Anexos** — etapas + upload (foto, documentos).
8. **Custos fixos** — catálogo recorrente.
9. **Societária** — sócios, aportes, prêmio decrescente, distribuição.
10. **Inventário** — ativos próprios + subsídio cruzado.
11. **Protocolos** — base de resolução de problemas recorrentes.
12. **Visões & Exportações** — filtros por ator, PDF/Excel por marca.

---

## 9. Dados-semente (reais)

> Fonte canônica: o JSON exportado pelo HTML da Fase 1. Abaixo, a referência tabulada.

### 9.1 Fontes (cofres) — Cultura
| Código | Nome | Contexto | Teto | Empenhado líquido 2026 |
|---|---|---|---|---|
| 100 | Recursos Ordinários | publico | *(a definir)* | R$ 319.059,23 |
| 117 | Fonte 117 — Vinculada | publico | *(a definir)* | R$ 2.475.185,00 |
| 234 | Fonte 234 | publico | *(a definir)* | R$ 78.316,33 |
| 281 | Fonte 281 — Investimento | publico | *(a definir)* | R$ 64.712,00 |
| 181 | Fonte 181 | publico | *(a cadastrar quando houver)* | — |

**Total empenhado líquido (validado contra o relatório):** R$ 2.937.272,56 · Pago: R$ 2.034.571,15 · Saldo a liquidar: R$ 165.193,54.

### 9.2 Empenhos — Fundo Municipal de Cultura (01/01 a 31/05/2026)
43 lançamentos, ordenados por fonte. Empenhado líquido = `vl_empenho − vl_anulado`. (Lista completa no JSON; resumo por natureza/fornecedor abaixo.)

- **Fonte 100 — anulados (folha/obrigações):** Vencimentos (8.489,48 + 11.000), INSS 2.424,48, Indenizações 6.222,23, RPPS 648,50, Auxílio-Alimentação 1.100, Auxílio-Transporte 583,20 — **todos integralmente anulados (líquido 0)**.
- **Fonte 100 — material de consumo:** Alfa Papelaria 83,02 · LBM 407,40 · Notável 256 · SL Comércio 976,66.
- **Fonte 100 — serviços PF (Osvaldo Marques):** 8.000 (pago) + 12.000 (pago 2.000, a liquidar 10.000).
- **Fonte 100 — serviços PJ (produção de eventos):** C.L.A dos Santos (4 emp., 33.659,98) · **Galles Assessoria, Produção e Eventos (6 emp., 161.046,50)** · Inove Produção (4 emp., 59.632,30) · Roberto Sá (3 emp., 13.038,72) · Star Locação (4 emp., 13.780,00).
- **Fonte 100 — Elétrica Radiante emp. 210: R$ 1.235.287,87 INTEGRALMENTE ANULADO** (recomposto na Fonte 117).
- **Fonte 100 — outros:** ECAD 12.178,65 · Osvaldo (exerc. anterior) 4.000.
- **Fonte 117 — Elétrica Radiante:** emp. 265 = 1.239.897,13 (pago) · emp. 23469 = 1.235.287,87 (liquidado; pago no período 500.000).
- **Fonte 234 — Alessandra Moura (advocacia):** 78.316,33 (pago).
- **Fonte 281 — Double Soluções (equip. permanente):** 17.456,48 + 17.303,52 + 29.952 = 64.712 (a liquidar, não pago).

### 9.3 Festa do Milho 2026 — pacote (26 a 28/06)

**Estrutura & infraestrutura (23 itens):**
Palco duas águas 14×12 (alt. 2m) · Laterais p/ LED 4×3 · Painel LED palco 5×3 · Som P.A. 32 · Iluminação palco e camarote · Geradores (04) · Fechamento cego placas 2m · Alambrado/parapeito · Balcões, praça de alimentação e bar · Pórtico de entrada, banheiro e praça · Banheiros químicos (60) · Camarins octanorm c/ ar-condicionado (06) · Camarote 30×10 elevado 1,5m · Tendas 10×10 (10) · Tendas 6×6 (10) · Extintores c/ comunicação · Ornamentação camarote e camarins · Comunicação visual · Pontos de luz/tomadas praça · Pontos de luz camarote · Pontos de luz tendas · Apoio polícia/bombeiros/SAMU · Rádios de comunicação.

**Grade de artistas (14 atrações):**
- **26/06:** César e Alessandro · Gustavo Moura e Rafael · George Henrique e Rodrigo · DJ WAM Baster
- **27/06:** Renato Vilela · Gabriel Gava · Muriel Alves · Duda Martins · Mc Jacaré · Dj Breno Paixão
- **28/06:** DJ Performance · Jennifer · Benzadeus · Jiraya Uai

Cada item: `fonte`, `cotacao`, `valor_contratado`, `estagio` (pré-reserva → … → pago).

---

## 10. Roadmap em fases

### Fase 1 — Festa do Milho + Painel Secretário *(protótipo HTML pronto)*
- Cofres editáveis, empenhos carregados, pacote da festa, painel orçamentário, exportação PDF/Excel.
- **Entrega imediata** (apresentação ao Secretário de Economia).
- Persistência local + JSON.

### Fase 2 — Backend e núcleo relacional (Supabase)
- Migrar JSON → Postgres. Implementar `fontes`, `empenhos`, `eventos`, `itens_calculo`, `cotacoes`, `movimentos`.
- Estágios de comprometimento completos (a escada da Seção 4).
- Motor bidirecional valor↔percentual.
- Auth + RLS básica (gestor vê tudo; secretário vê camada pública).

### Fase 3 — Empresa, margem, sociedade, visões
- Repasses/margem (item e contrato), confidencialidade.
- Societária (aportes, prêmio decrescente, distribuição).
- Inventário + subsídio cruzado.
- Visões por ator + exportações por marca (Cloudflare Workers).
- Protocolos, prestação de contas + anexos (Storage).

### Fase 4 — Refinos
- Remanejamento com semáforo de tolerância.
- Dashboards/gráficos.
- Logins por colaborador do grupo com campos obrigatórios guiados.

---

## 11. Instruções para o Claude Code

1. **Importador de seed:** ler o JSON do HTML e popular `fontes`, `empenhos`, `itens_festa`.
2. **Schema:** aplicar o SQL do Apêndice A.
3. **RLS:** aplicar políticas do Apêndice B antes de expor qualquer dado.
4. **Estágios:** implementar a máquina de estados (Seção 4.3) e os dois saldos (4.2).
5. **Terminologia adaptativa:** rótulos de estágio conforme `fonte.contexto`.
6. **Deploy:** front em Cloudflare Pages; exportações em Workers; banco/auth/storage em Supabase.
7. Manter a **cadeia auditável** (Seção 1.3) intacta em todas as telas.

---

## Apêndice A — Schema SQL (esqueleto)

```sql
-- ÂMBITOS E ACESSO
create table ambitos (
  id uuid primary key default gen_random_uuid(),
  nome text not null,
  tipo text not null  -- secretaria | empresa | associacao | paroquia | instituto | pessoal
);

create table ator_ambitos (
  user_id uuid references auth.users(id),
  ambito_id uuid references ambitos(id),
  papel text not null,  -- gestor | membro | leitor
  primary key (user_id, ambito_id)
);

-- FONTES / COFRES
create table fontes (
  id uuid primary key default gen_random_uuid(),
  ambito_id uuid references ambitos(id),
  codigo text,
  nome text not null,
  contexto text not null default 'publico',   -- publico | empresarial
  tipo text,                                   -- emenda | licitacao | orcamentaria | convenio | receita_propria | aporte
  teto numeric default 0,
  vigencia daterange,
  limite_remanejamento_pct numeric,
  nota_interna text,
  protocolo_id uuid
);

-- EMPENHOS
create table empenhos (
  id uuid primary key default gen_random_uuid(),
  fonte_codigo text,
  fornecedor text,
  natureza text,
  num_empenho text,
  data date,
  vl_empenho numeric default 0,
  vl_anulado numeric default 0,
  liquidado numeric default 0,
  pago numeric default 0,
  saldo_liquidar numeric default 0
  -- empenhado_liquido = vl_empenho - vl_anulado  (coluna gerada ou view)
);

-- EVENTOS
create table eventos (
  id uuid primary key default gen_random_uuid(),
  ambito_id uuid references ambitos(id),
  nome text not null,
  contexto text default 'publico',
  periodo_inicio date, periodo_fim date,
  local text, responsavel text, status text
);

-- FORNECEDORES / PREÇOS / ITENS COTADOS
create table fornecedores (
  id uuid primary key default gen_random_uuid(),
  ambito_id uuid references ambitos(id),
  nome text not null, cnpj_cpf text, tipo text, contato text
);
create table fontes_preco (
  id uuid primary key default gen_random_uuid(),
  tipo text, numero text, vigencia daterange, anexo_url text
);
create table itens_cotados (
  id uuid primary key default gen_random_uuid(),
  fonte_preco_id uuid references fontes_preco(id),
  descricao text, unidade text, vu numeric,
  fornecedor_oficial_id uuid references fornecedores(id)
);

-- LIVRO-RAZÃO (CÁLCULO REAL x PROCESSO)
create table itens_calculo (
  id uuid primary key default gen_random_uuid(),
  evento_id uuid references eventos(id) not null,
  fonte_id uuid references fontes(id) not null,
  item_cotado_id uuid references itens_cotados(id),
  fornecedor_executante_id uuid references fornecedores(id),
  dias int default 1, qtd_por_dia numeric default 1,
  qtd_total numeric, vu_referencia numeric, valor_total_processo numeric,
  vu_efetivo numeric, qtd_real numeric, total_real numeric,
  estagio text not null default 'pre_reserva',  -- pre_reserva|reserva|comprometido|devido|pago
  agenda_entrega date, agenda_instalacao date,
  conferente text, observacoes text, motivo_diferenca text
);

-- COTAÇÕES
create table cotacoes (
  id uuid primary key default gen_random_uuid(),
  item_id uuid references itens_calculo(id),
  fornecedor_id uuid references fornecedores(id),
  valor numeric, forma_pagamento text, data date, selecionada boolean default false
);

-- MOVIMENTOS (margem + remanejamento, mesma mecânica)
create table movimentos (
  id uuid primary key default gen_random_uuid(),
  tipo text not null,            -- margem | remanejamento
  origem_ref text, destino_ref text,
  valor_base numeric, modo text, -- percentual | absoluto
  percentual numeric, valor_movimento numeric,
  data date default now(), observacao text
);

-- PRESTAÇÃO DE CONTAS / ANEXOS
create table prestacao_contas (
  id uuid primary key default gen_random_uuid(),
  evento_id uuid references eventos(id),
  fonte_id uuid references fontes(id),
  etapa text, status text
);
create table anexos (
  id uuid primary key default gen_random_uuid(),
  tipo text, url text, vinculo_tipo text, vinculo_id uuid
);

-- CUSTOS FIXOS / INVENTÁRIO / PROTOCOLOS
create table custos_fixos (
  id uuid primary key default gen_random_uuid(),
  ambito_id uuid references ambitos(id),
  descricao text, valor_padrao numeric
);
create table inventario (
  id uuid primary key default gen_random_uuid(),
  ambito_id uuid references ambitos(id),
  item text, quantidade numeric, valor_unitario_repasse numeric,
  gera_custeio boolean default false
);
create table protocolos (
  id uuid primary key default gen_random_uuid(),
  titulo text, categoria text, passos text,
  orgao text, departamento text, contato text, meio text
);

-- SOCIETÁRIA
create table socios (
  id uuid primary key default gen_random_uuid(),
  ambito_id uuid references ambitos(id),
  nome text, cota_percentual numeric, remuneracao_operacional numeric default 0
);
create table aportes (
  id uuid primary key default gen_random_uuid(),
  ambito_id uuid references ambitos(id),
  socio_id uuid references socios(id),
  valor_total numeric, premio_inicial numeric default 1  -- 1 = recebe o dobro no início
);
create table pagamentos_aporte (
  id uuid primary key default gen_random_uuid(),
  aporte_id uuid references aportes(id),
  valor numeric, data date default now()
);
create table distribuicao_lucros (
  id uuid primary key default gen_random_uuid(),
  ambito_id uuid references ambitos(id),
  periodo text, socio_id uuid references socios(id), percentual numeric, valor numeric
);
```

## Apêndice B — RLS (padrão)

```sql
alter table fontes enable row level security;

-- Gestor (papel 'gestor' em qualquer âmbito) vê tudo
create policy gestor_total on fontes for all
using (exists (select 1 from ator_ambitos a
               where a.user_id = auth.uid() and a.papel = 'gestor'));

-- Demais veem apenas linhas dos seus âmbitos
create policy ambito_proprio on fontes for select
using (ambito_id in (select ambito_id from ator_ambitos
                     where user_id = auth.uid()));
```
Replicar o padrão para `eventos`, `itens_calculo`, `fornecedores`, `inventario`, `socios`, etc. Campos sensíveis (custo/margem) protegidos por policy adicional restrita ao âmbito-dono e ao gestor.

---

*Fim do documento-mestre. Referência viva: protótipo `gestao-cultura-festa-do-milho.html`.*