# Controlus Faturas (faturas.controlus.com.br)

Sistema novo, criado em 01/10/2026 a pedido de Mardhell Garcia. Objetivo: um
painel **único e standalone** (sem acoplamento a nenhum outro módulo/sistema
Controlus) pra gerenciar cobrança de TODOS os tenants de TODOS os sistemas
hospedados pela Controlus — sem precisar entrar sistema por sistema pra
marcar fatura como paga, ver quem deve, etc.

## Requisitos explícitos do usuário (não reabrir essa discussão sem motivo)

- **Não vinculado a outros módulos.** Não é mais um módulo dentro de
  app.controlus.com.br/gov.controlus.com.br — é uma aplicação própria, auth
  própria (simples, só pra equipe interna da Controlus, não multi-tenant
  Stancl como os outros sistemas).
- Cadastro mínimo por linha de cobrança: **tenant, de qual sistema ele é,
  valor mensal, se emite nota fiscal ou não**, status de pagamento.
- Suporta tanto cobrança recorrente mensal quanto **faturas avulsas**
  (cobranças pontuais, não recorrentes).
- **Importar tudo que já existe**, de todos os sistemas, **sem duplicar**.
- Depois (fase futura, não agora): importar os dados daqui pro
  `financas.controlus.com.br` (Pulse Contábil/Controlus Finanças — sistema
  financeiro pessoal/PJ do Mardhell, ver `/home/controlus/financas.controlus.com.br`).
  **Não confundir os dois** — financas.controlus.com.br é outra coisa
  (gestão financeira pessoal, não cobrança de clientes hospedados).
- Dentro de cada sistema de origem (App, Gov, etc.), a ideia é **desabilitar**
  a futura gestão de fatura própria deles — este sistema novo vira a fonte
  única de gestão. (Avaliar se isso é viável de imediato ou se tem que
  conviver um tempo com o Institucional, que ainda está gerando fatura de
  verdade — ver seção de dedup abaixo.)

## Infra já pronta (feita pela sessão "VPS Visual Prime")

- Subdomínio `faturas.controlus.com.br` criado via `uapi SubDomain
  addsubdomain`, docroot corrigido pra `/home/controlus/faturas.controlus.com.br`
  (fora do `public_html` que é symlink do app.controlus.com.br — bug
  conhecido deste servidor, já documentado/corrigido nos userdata e SSL).
  DNS A record autocriado pelo wizard, certificado wildcard `*.controlus.com.br`
  já cobre. Testado: `https://faturas.controlus.com.br` responde 200.
- Esta sessão Claude Code (`controlus-faturas`) está rodando via
  `screen -S claude-faturas` com watchdog cron (`/home/controlus/claude-rc-faturas.sh`,
  `@reboot` + `*/5 * * * *`) — mesmo padrão dos outros sistemas Controlus
  nesta VPS (ver `/home/controlus/claude-rc-*.sh` como referência se precisar
  mexer no watchdog).
- MySQL: usuário `controlus_mardhel` / senha `SpeakerPass` tem acesso de
  leitura a todos os bancos `controlus_*` neste servidor (confirmado
  funcionando nesta sessão de setup). Vai precisar disso pra importar de
  cada sistema de origem.

## Levantamento de dados pra importar (feito em 01/10/2026)

Fonte: sondagem completa de todos os sistemas multi-tenant hospedados pela
Controlus nesta VPS. Dados abaixo são o estado encontrado — confirmar que
ainda bate antes de importar de fato (pode ter mudado).

### Sistemas COM dado de cobrança

**Institucional** (`controlus_institucional`, sistema ANTIGO, tenants sendo
migrados pro App) — tabela `tenants` (slug, name, active, monthly_fee) +
tabela `invoices` (tenant_id, customer_id, amount, status, due_date, paid_at,
nf_path, apply_tax, payment_method, pix_code, integration_id). 19 tenants
ativos, TODOS já existem também no App por nome (migração de cadastro parece
100% completa) — mas o Institucional **ainda está gerando fatura de verdade**
(tem fatura com vencimento em 2027), então pelo menos parte da cobrança real
ainda roda por aqui, não só no App. Ver tabela de cruzamento mais abaixo.

**App** (`controlus_app`, app.controlus.com.br) — `tenants` central, 34
ativos, `monthly_fee`/`billing_email`/`document` quase todos NULL exceto
`aabbslmb` (R$200) e `baruque` (R$50). Tabela `invoices` própria, 12 linhas,
todas do tenant `baruque` (R$50/mês recorrente, "Servidor de Hospedagem de
Emails Institucionais", 11 pendentes + 1 paga), campos `public_token`,
`pix_code`, `nf_path` existem mas não usados ainda.

**Gov** (`controlus_gov`, gov.controlus.com.br) — 6 tenants ativos, 4 com
`monthly_fee`: CISO II R$1.500, Prefeitura de São Luís de Montes Belos
R$4.950, SEMMA/Meio Ambiente SLMB R$2.000, Obras SLMB sem valor. Tabela
`invoices` existe mas **0 linhas** (nunca usada).

**Esportes** (`controlus_esportes`, esporte.controlus.com.br) — 1 tenant
(Secretaria de Esportes SLMB), CNPJ `53.260.647/0001-19` — **reparar: é o
mesmo CNPJ da Prefeitura/CISO II**, confirmar com o usuário se é a mesma
entidade jurídica (prefeitura) cobrada por secretaria/produto diferente, o
que é normal, ou erro de cadastro. `valor_mensal` R$750, status de pagamento
direto no campo do tenant (não tem tabela de fatura separada).

**Publicações** (`controlus_publicacoes`, publicacoes.controlus.com.br) — 4
tenants, mesmo padrão "estado atual" (sem tabela de fatura): Prefeitura SLMB
R$750/mês, "CISO II" (2 linhas — id=2 inativa, id=3 ativa, **parece
duplicata literal**, mesmo CNPJ `53.560.647/0001-19` — ATENÇÃO: esse CNPJ
tem um dígito diferente do CNPJ usado em Esportes acima, `53.260.647` vs
`53.560.647` — pode ser erro de digitação em algum dos dois cadastros,
**perguntar ao usuário antes de tratar como a mesma empresa**), CIGIRS
R$1.500/mês — CIGIRS tem o MESMO CNPJ que a linha "CISO II" ativa aqui
também, o que é suspeito (duas empresas diferentes não deveriam ter o mesmo
CNPJ) — **não assumir, perguntar**.

**Stream** (`controlus_stream_app`, stream.controlus.com.br) — 1 tenant: JD
Solidária (a rádio ligada à associação APRCHD — ver módulo Carteirinhas em
app.controlus.com.br se precisar de contexto). 1 fatura: R$200, status
**paga**, paid_at 2026-08-30, "mensalidade de servidor de streaming + mídias".

**Run** (`controlus_run_app`, run.controlus.com.br) — 1 tenant (MG Gym), sem
valor cadastrado, tabela `invoices` existe mas 0 linhas.

**Agro** (`controlus_agro`, agro.controlus.com.br) — 1 tenant (WMG Agro), sem
valor, sem tabela de fatura.

### Cruzamento (mesmo cliente, sistemas diferentes — NÃO são duplicata simples)

- **CISO II**: cobrado em Gov (R$1.500) E em Publicações (R$1.500) — são
  DOIS produtos/linhas de cobrança legítimas pro mesmo cliente, não
  deduplicar como se fosse um só.
- **Prefeitura de São Luís de Montes Belos**: cobrada em Gov (R$4.950) E em
  Publicações (R$750) E em Esportes (R$750, possivelmente, a confirmar CNPJ)
  — mesmo padrão, linhas de cobrança legítimas separadas por
  produto/secretaria.
- **Sine SLMB**: tem valor só no Institucional (R$449, sistema antigo) — não
  tem valor recadastrado nem no App nem no Gov, onde o tenant já existe. Esse
  é exatamente o tipo de buraco de migração que motivou este sistema novo —
  sinalizar isso bem visível na importação, não só silenciar.

### Fora do escopo (sem conceito de mensalidade, confirmado na sondagem)

Atendimento (CRM interno, 3 tenants sem campo de valor), Agenda (uso pessoal
do Mardhell), Licitações (clientes de **licitação pública**, não hospedagem —
modelo de negócio totalmente diferente, confirmar com o usuário se ele quer
isso aqui ou não antes de incluir), Roteiros (ferramenta de geração de
vídeo/roteiro, não multi-tenant), Musical Easy, Vistorias, OCR (lê do Gov,
não é fonte própria — ignorar pra não contar duas vezes).

## Próximos passos sugeridos (não fazer sem alinhar com o usuário antes)

1. Resolver as duas dúvidas de CNPJ acima com o usuário ANTES de importar
   (Esportes vs Publicações/CISO II, e CIGIRS vs CISO II) — importar errado
   e descobrir depois é pior que perguntar agora.
2. Confirmar se Licitações entra no escopo ou não.
3. Desenhar o modelo de dados (sugestão inicial: tabela `tenants` com
   `source_system` enum/string, `name`, `document` (CNPJ/CPF), `monthly_fee`,
   `emite_nota` bool, `active`; tabela `invoices` com `tenant_id`, `type`
   (recorrente/avulsa), `amount`, `due_date`, `paid_at`, `status`,
   `source_system` + `source_invoice_id` pra rastrear de onde veio cada
   fatura importada e evitar reimportar duplicado numa segunda rodada).
4. Scaffold Laravel (ou stack que preferir — mas considerar consistência com
   os outros sistemas da Controlus, que são majoritariamente Laravel) com
   auth simples de equipe (não Stancl tenancy).
5. Escrever scripts de importação por sistema de origem, idempotentes
   (rodar de novo não duplica — usar `source_system` + `source_invoice_id`
   ou `source_tenant_id` como chave de dedup).
6. Construir a UI: lista de tenants com sistema de origem, valor, nota
   fiscal sim/não, lista de faturas com marcar-como-pago, filtro por
   sistema/status.
7. Só depois disso, nas próximas fases: (a) decidir com o usuário como
   desabilitar a gestão de fatura dentro de cada sistema de origem, (b)
   importar pro financas.controlus.com.br.

## Como pedir ajuda de volta

Se precisar de algo que só a sessão "VPS Visual Prime" já investigou ou tem
acesso mais direto (ex: mexer em outro sistema específico, feature de outro
projeto), pode mandar mensagem pra ela — procure por "VPS Visual Prime" nos
peers (`ListAgents`).