# Especificação — Módulo Cofre (Saldo Financeiro por Fonte) > **O que é este documento.** Especificação detalhada do **primeiro módulo** a construir — o que o Bruno chama de *cofre*. Nasceu da conversa de refinamento sobre o `DOCUMENTO-MESTRE-plataforma-gestao.md`; é o recorte enxuto e prioritário, escrito pra ser **lido e corrigido** antes de virar código. Onde divergir do documento-mestre, vale este (é mais novo e mais focado). > > **Princípio que organiza tudo:** uma base de dados só, **recortes diferentes conforme o contexto**. (É o modelo do Notion que o Bruno usa — uma base, vários papéis/visões referenciando ela — mas resolvendo as duas dores que o Notion não resolve: ver §6 e §7.) --- ## 1. Para que serve Bruno atua **interseccionalmente**: assessora a Secretaria de Cultura (lado público) e produções/empresas (lado privado), sentado no meio. Esta é a **central pessoal dele** — não é "do governo" nem "da empresa". Centraliza o acompanhamento financeiro de recursos que custeiam eventos, vindos de fontes diferentes (uma fonte orçamentária, uma emenda parlamentar, um recurso trazido politicamente…), e permite **apresentar a cada interlocutor só o recorte que lhe cabe**. Foco imediato (esta entrega): **o cofre** — quanto há disponível em cada fonte, quanto está comprometido, liquidado, pago ou ainda só planejado. Em última análise, responder ao Secretário de Economia: *o que já empenhamos e o que pretendemos empenhar.* > **Ética da intersecção (regra de produto, não opcional):** estando no meio de tudo, Bruno **não pode** expor numa visão dados de uma relação interna que não dizem respeito àquele interlocutor. A exposição é sempre um **recorte deliberado** (ver §7), nunca o todo. --- ## 2. Conceito central — o Cofre **Cofre** = um saldo financeiro disponível, de uma fonte específica, para aplicar (tipicamente em eventos). > **Nomenclatura.** Interno: **"cofre"** (claro, todo mundo entende). Para fora / documentos: **"Saldo Financeiro por Fonte"** (evita confundir com as *fontes orçamentárias* 100/117/234/281, que são um tipo de origem, não o conceito todo). Cada cofre tem: | Campo | Descrição | |---|---| | **Nome** | ex.: "Emenda Dep. Fulano 2026", "Fonte 100 — Ordinários", "Recurso padrinho — Festa do Milho" | | **Origem / tipo** | fonte orçamentária, emenda parlamentar, recurso político, convênio, receita própria… | | **Teto** | valor total disponível | | **Vigência** | **opcional** — ver §3 | | **Contexto** | público ou privado (decide rótulos e o que pode ser exposto) | | **Despesas** | a lista de aplicações desse cofre, cada uma num estágio (ver §4) | **Saldo** não é um número — é `teto − despesas`, lido em **duas camadas** (ver §5). > **Despesa pertence ao cofre E a uma finalidade.** A despesa nunca fica "solta" — ela sempre aponta para *alguma* finalidade. O **evento não é a regra nem a exceção: é um TIPO de finalidade.** Generalizando, a finalidade é um **projeto**, e cabe a distinção que a própria administração pública usa (PPA — projeto × atividade): > > - **Projeto** — finalidade **temporária**, com começo e fim → *Festa do Milho, campeonato de quadrilha*. (Um evento é um projeto.) > - **Atividade** — finalidade **contínua**, do dia a dia → *manutenção de serviços administrativos, sistema de cadastro municipal.* > > A régua prática (exemplo do crachá): crachá **para o evento** → vinculado àquele projeto; crachá **para o dia a dia** → vinculado à atividade "serviços administrativos". Mesma despesa, finalidades diferentes. > > Modelo: **Cofre** → tem despesas · **Despesa** → pertence a um cofre **e** a uma **finalidade** · **Finalidade** → é um *projeto* (temporário) ou uma *atividade* (contínua). O remanejamento entre itens (§6) e o escopo de itens por contexto (§7) valem para **qualquer finalidade**, não só evento. > > **Finalidade provisória (antecipação).** A finalidade tem o mesmo direito de ser provisória que o valor tem de ser pré-reserva. Caso real: *"sei que vou precisar de crachás para eventos, mas ainda não sei quais."* Não é "despesa sem finalidade" — é **finalidade ainda em aberto**: provisiona-se agora contra uma finalidade **genérica** ("crachás para eventos do ano") e, quando o evento concreto aparece, a antecipação **se ancora** nele (ou se reparte entre vários) — usando a mesma mecânica de origem preservada do §6 (a bolsa genérica vira X e Y sem apagar de onde nasceu). Isso costuma andar junto com o estágio **pré-reserva** (§4): valor separado, destino a definir. --- ## 3. Vigência (opcional, três casos) Nem todo recurso tem prazo. A vigência é **opcional** e assume um de três modos, sempre explícito (nunca um campo em branco ambíguo): 1. **Com prazo** — vale de uma data a outra (ex.: emenda que vence no fim do exercício). 2. **Atrelada ao evento** — vale enquanto o evento existir. 3. **Indefinida** — "enquanto houver saldo disponível, pode usar". > Decisão registrada: a dimensão temporal relevante aqui **não é o ano-exercício** (isso é forte só no setor público). O que serve aos dois lados é **cada cofre ter sua própria validade**. --- ## 4. Estágios da despesa (a escada) Toda despesa de um cofre anda numa escada de comprometimento. **Não são livros diferentes** (não existe "livro de empenhos" separado de "livro de planejamento") — é **a mesma despesa vista em degraus diferentes**: ``` pré-reserva → reserva/cotação → empenhado → liquidado → pago (intenção) (já cotado) (firme) (serviço (saiu da conta) prestado) ``` - **pré-reserva** — "separo R$ X pra isso", ainda sem cotação. Reversível à vontade. - **reserva/cotação** — já cotado, valor de referência definido. Reversível. - **empenhado** — comprometimento formal; valor firme que sai da fonte. Daqui pra frente só sai por anulação/remanejamento registrado. - **liquidado** — serviço prestado/atestado; obrigação reconhecida. *Na prática: "já tem que pagar."* - **pago** — desembolso efetivo. Encerra o ciclo. **Pago/não-pago é simples** — na pior das hipóteses, um checklist no fim da escada. Não precisa de mais que isso agora. > **Rótulo adaptativo:** em cofre **público**, o degrau firme chama "Empenhado" e o reconhecido chama "Liquidado". Em **privado**, "Contratado" e "A pagar". A chave interna é a mesma; muda só a palavra na tela. --- ## 5. Os dois saldos Da mesma base, duas leituras simultâneas: - **Saldo firme** (`teto − despesas empenhadas ou acima`) → *"quanto oficialmente já saiu da fonte"*. **É a visão do Secretário de Economia.** - **Saldo livre** (`teto − todas as despesas, inclusive intenções`) → *"quanto eu ainda posso planejar/prometer"*. **É a visão de quem opera.** > Cada despesa é contada **uma vez, pelo seu degrau mais avançado** (uma despesa "paga" já passou por "empenhada" — não conta duas vezes). --- ## 6. Remanejamento — o coração do módulo Bruno tem liberdade para **remanejar saldo entre itens** sem perder o vínculo com a destinação inicial. Ex.: planejou som, mas decide aplicar em artista; ou tira um pouco do som e reforça as tendas — **seleciona o item de origem e "puxa" o valor pro item de destino.** **Regra estrutural:** remanejar **não é editar a célula** — é **registrar um movimento por cima**. Assim coexistem, sempre: - **a proposição inicial** — "esse recurso veio para estes itens" (imutável; é a determinação de origem); - **o estado vigente** — "depois dos remanejamentos, hoje está assim" (= original + movimentos aplicados). A cadeia nunca quebra: dá sempre pra responder *"de onde isso veio e o que aconteceu desde então."* **Escopo:** o remanejamento que importa primeiro é **entre itens de um mesmo evento** (não entre cofres distintos). Origem e destino são itens; o valor migra de um pro outro. **Linhagem → duas leituras escolhíveis na exposição (ver §7):** - **Versão Original** ("o que foi determinado") — para quem aprovou a destinação inicial (ex.: o padrinho/autoridade). - **Versão Vigente** ("como está hoje") — para quem opera. Ninguém edita nada para alternar — é a mesma base lida de dois jeitos. > **Distinção que estava confusa antes e fica clara aqui:** existem DUAS coisas separadas. (a) O **registro do remanejamento com origem preservada** = estrutural, é isto. (b) O **semáforo de tolerância** ("remanejei 14% de um limite de 20%") = só um aviso lateral, informativo, **não bloqueia nada**. Não confundir uma com a outra. --- ## 7. Itens com escopo por evento (a dor nº 1 do Notion) **Problema no Notion:** ao relacionar uma base, o popup de opções oferece **o banco inteiro** — não dá para dizer "neste evento, só me ofereça estes itens". É a maior limitação que o Bruno não consegue contornar lá. **Solução aqui (comportamento padrão):** a base de itens/fornecedores continua **única e grande** por trás, mas **cada evento tem seu próprio conjunto de itens** (os que foram cotados/planejados para ele). Quando se abre o popup *dentro daquele evento*, ele lista **só os itens daquele evento** — não o universo. Vale nos dois lugares: - no **remanejamento**, o destino só oferece itens **daquele evento** (não itens de outra festa); - na **exposição**, a mesma base aparece **filtrada conforme a visão** — nem todo item em toda tela. > É o mesmo princípio de tudo: **uma base só, oferta na tela recortada pelo contexto.** --- ## 8. Exposição / compartilhamento Dois públicos, dois mecanismos: 1. **Pessoas de confiança que assessoram um segmento** → recebem uma **visão específica, sempre atualizada** (uma visualização ligada à base; ao editar, eles passam a ver a versão mais recente daquela visão). Recorte controlado: só o segmento delas, escolhendo inclusive **Original × Vigente** (§6). 2. **Secretário / autoridade** → basta **exportar**: no mínimo CSV/planilha; idealmente um **PDF caprichado** (transmite profissionalismo). Aqui o foco é o painel de saldo por fonte. > A **filtragem da exportação** segue o mesmo motor de recorte: exporta-se só o que aquele destinatário pode ver. (Detalhar o layout de exportação depois — não é o foco da primeira entrega.) --- ## 9. Relação com o Notion O Notion **continua sendo uma das centrais** do Bruno (já integrado a muita coisa; sistema de tarefas próprio fica para um talvez-futuro). Esta plataforma **não substitui** o Notion agora — resolve o que o Notion não faz: **filtro de opções por contexto** (§7) e **linhagem original↔vigente no remanejamento** (§6). Eventual integração por base de dados pode existir depois; não é requisito desta entrega. --- ## 10. O que entra nesta primeira entrega (e o que não entra) **Entra:** - Cadastro de **cofres** (nome, origem, teto, vigência opcional, contexto). - **Despesas por cofre/evento**, com **estágio** (a escada) e marcação pago/não-pago. - **Dois saldos** (firme e livre) calculados ao vivo. - **Remanejamento entre itens do evento**, com origem preservada e leitura Original × Vigente. - **Itens com escopo por evento** no popup de seleção. - **Painel do Secretário** + **exportação** (CSV agora; PDF caprichado em seguida). **Fica para depois (módulos que só *reusam* estas bases):** margem/repasse, societária (prêmio decrescente), inventário/subsídio cruzado, protocolos, prestação de contas com anexos. Não precisam existir para o cofre funcionar. **Decisão de stack para já:** o **protótipo HTML basta** para a apresentação (mesmo sem salvar — serve para mostrar a interação). Backend (Supabase) só quando precisar de multi-dispositivo ou das visões publicadas que se atualizam sozinhas. Não antes. --- ## 11. Pontos que ainda quero confirmar com o Bruno 1. ~~Despesa sempre pertence a um evento?~~ **RESPONDIDO:** despesa pertence ao **cofre + uma finalidade**. Finalidade = **projeto** (temporário, ex.: evento) ou **atividade** (contínua, ex.: serviços administrativos). Evento é um *tipo* de projeto, não um campo opcional solto. Ver §2. 2. **O recurso do "padrinho político"** entra *dentro* de uma fonte já existente, ou é um **cofre à parte** (fora do relatório oficial) que o Bruno controla por fora? → decide se há cofres que não vêm do relatório oficial. 3. **Remanejamento entre cofres** (não só entre itens) — é necessário em algum momento, ou nunca? (Hoje: só entre itens do evento.)