Enciclopédia Kinovo / MyFinanceWeb

Para quem não programa: leia as caixas azuis “Em linguagem simples” e os fluxos numerados — explicam o que a família vê e o que o sistema faz por trás.
Para quem desenvolve: tabelas com IDs, action da API, classes PHP e storage do navegador.

Arquivo irmão no Cursor: MyFinance/.cursor/skills/myfinance-Kinovo/SKILL.md (mesmo conteúdo; esta página é para abrir no browser).

Roadmap KIN: kin-roadmap.html · KIN-ROADMAP.md · KIN-2.0-PLAN.md · specs KIN-*-v1.md · KIN-ESPEC-v1.md (D01–D09)

URL: /referencia-tecnica.html · Ignorar pasta BKP/.

ParteConteúdo
AProduto, para quem, o que não é
BCasa conjunta, convite, plano, carteiras
CToda UI: topo, home, páginas, 13 abas Ajustes
DLogin, sessão, cadeado, admin flag
EKPIs, lançamentos, orçamento, metas (reserva + desafio grupo), cartões…
FPluggy: sync, saldo, extrato, memória
G–NDeploy, admin, API, SQL, cron, checklist
OKIN: diagnóstico, plano, sim, chat 2.0, Fase 8 Intelligence Engine

Mapa Quando você faz X, o sistema faz Y

Você (usuário)Sistema
Abre o app já logadosessao (antes do cache) → se PIN bloqueado: #lockScreen sem getFinanceData → senão kin_fin_* → getFinanceHome + getFinanceData
Entra em outra casa (convite)aceitarConvite desvincula casa antiga (membros + OF), limpa PIN → nova sessao → cadeado ou loadData
Escolhe o mês no topofiltroMes recalcula KPIs, gráficos e listas
Clica no olho do saldoSó mascara o card “Saldo em contas”; grava ff_saldo_oculto (padrão oculto)
Lança uma despesaaddTransaction; entra no KPI se Concluído no mês
Dá baixa / swipeStatus Concluído + data de pagamento
Corrige categoria de lançamento do bancoGrava memória OF para próximo extrato
Ajustes → Atualizar bancossincronizarOpenFinance: saldo Pluggy + extrato 90d + conciliações
Dia 1 / cron noturnoRecorrentes, manutenção OF, sync após 17h (1×/dia)
Admin publica ZIPFTP + extrai public/ e src/; backup automático
Abre card KIN / Kinovo AI na homegetKinContexto (prefetch) → proativoHome · dismiss kinProativoDismiss_{mes}
Pergunta no Kinovo AIgetKinChat com pacote contexto (PHP calcula; LLM opcional KIN_IA_*)
Guarda contexto no chat (“Lembre: …”)Proposta → confirma → saveKinMemoria · pode suavizar D04/D09 no diagnóstico
Marca passo do plano / compromisso no simuladorkin_decisoes + avaliação vs kin_evolucao
Ajustes → Meta → Lançar desafio ao gruposaveMetaPatrimonio + enviarDesafio → JSON metasDesafio pendente
Parceiro aceita o desafio no popupresponderDesafioMeta → ativa metaReserva para a casa
Lança aporte (CDB, fundo…)Despesa Concluída categoria Investimentos → soma no progresso da reserva
Confirma assinatura MP de novo (webhook/sync)mp_eventos — mesma chave não estende plano_ate duas vezes
Login com digitalWebAuthn exige UV no dispositivo; servidor valida flags UP+UV
Paga fatura do cartãopagarFatura baixa itens do ciclo; lança despesa Fatura na conta; painel usa max(manual, OF) se ambos > 0
KIN sugere meta (popup)metaSugestaoKin em getFinanceData · #metaKinSugOverlay

Correção local · 06/11/2026 · 1.3.10: mês sem movimentação não recebe fluxo saudável; contas + investimentos são ativos financeiros registrados, sem desconto de dívidas; o assistente rápido não afirma saldo bancário em tempo real. Conferir atualização nas carteiras. Cache v223. Sem alteração SQL; publicação pendente.

Melhoria local · 06/11/2026 · 1.3.11: acesso destacado a Meu plano e Simular uma decisão na home, abaixo do resumo do diagnóstico e acima da mensagem do chat KIN. Componentes responsivos, foco acessível, navegação aguardando carregamento e gate de plano preservado. Assets v224. Sem SQL ou sync. Publicação e homologação no app pendentes.

Ajuste local · 06/11/2026 · 1.3.12: home mobile sem o card de plano para preservar o espaço do gráfico. Botão Relatório passa a Planejar e abre Relatórios, Meu plano financeiro e Simular uma decisão. Card mantido no desktop; atalhos de chat/diagnóstico preservados. Cache v225. Sem SQL ou sync; publicação pendente.

Correção local · 06/11/2026 · 1.3.13: carteiras separam saldo registrado, entradas em aberto, vencidos e contas a vencer até o fim do mês corrente. Saldo projetado parte do saldo registrado e não reconta histórico já pago. Inclui atrasados anteriores; compras de cartão ficam fora, pagamento de fatura precisa estar lançado na conta pagadora. Projeção condicional ao recebimento e à atualização bancária; não fabrica compromissos ausentes. Assets v226, cache financeiro v5. Sem SQL ou sync. Publicação pendente.

Melhoria local · 06/11/2026 · 1.3.14: carteiras distinguem conexão cadastrada de origem Open Finance. Desconectadas não usam histórico como saldo bancário; com pendências ficam sinalizadas, sem pendências saem do painel principal. Arquivar/restaurar preserva histórico, valida dono e confirma pendências; seção Arquivadas em Ajustes. Preferência em config, sem DDL. Reconexão reutilizada restaura visibilidade. Assets v227, cache financeiro v6. Lote inclui a projeção corrigida anterior. Publicação e homologação autenticada pendentes.

Layout local · 06/11/2026 · 1.3.15: página Contas mobile com abas Contas/Cartões, saldo registrado, donos e estados visíveis. Contas expansíveis para compromissos/projeção; cartões compactos com Nova compra/Pagar fatura preservados. Desktop e cálculos sem alteração. Assets v228. Prévia isolada e testes passaram; publicação e homologação autenticada pendentes.

Correção local · 06/11/2026 · 1.3.16: seletor de período no desktop fica acima dos cards de receitas/despesas, sem recorte. Camadas elevadas somente durante abertura, com fechamento e seleção preservados. Assets v229. Sem cálculo/SQL/sync. Prévia isolada aprovada; publicação pendente.

Melhoria local · 06/11/2026 · 1.3.17: assistente da home consulta getKinChat, com acesso/PIN, erro e proteção contra retornos de outro mês/casa. Orientação inicial para déficit, sobra, reserva, viagem, investimento e compra de bem, com valores do contexto e perguntas sobre objetivo/custo/prazo/reserva. Sem comparação quantitativa nova, memória conversacional ou decisão automática. Definições e simulador existentes preservados. Motor IA 1.9.4; assets v230. QA local passou; publicação e smoke autenticado pendentes. Sem SQL/.env/sync.

Aprendizado responsável: já existem trajetória mensal, memória confirmada e ciclo recomendou/escolheu/mediu. Isso não comprova leitura integral do histórico nem perfil de pontualidade/juros. Prompt orienta não julgar caráter, não presumir juros por atraso nem confundir movimento OF com vencimento original. Perfil histórico de pagamentos com cobertura e evidências ainda pendente; conformidade do LLM precisa avaliação real.

Correção local · 06/11/2026 · 1.3.18: dúvida sobre pagar contas e continuar no vermelho recebe explicação curta da fórmula receitas − pagas − em aberto = saldo livre, sem relatório ou playbook não pedido. Como estou inicia curto; detalhe solicitado preserva caminho existente. Saudação e orientação de objetivos reduzidas. Respostas locais com valores reprovados agora são substituídas por aviso curto, sem expor a recomendação divergente; causa específica do relatório remoto ainda depende de evidência do servidor. IA 1.9.5, assets v231. QA local passou; publicação e smoke autenticado pendentes. Sem SQL/.env/sync.

Estado atual do projeto · 05/11/2026

Consolidação: base MyFinanceWeb incorporada em Kincorp/Kinovo, com documentos, geradores e Telegram interativo. Preservados redesenho do Admin e correções locais. Iniciar lote-ui.cmd nesta pasta: 127.0.0.1:18767; a ferramenta mostra a origem. O filtro usa a última geração de ZIP, não comprova publicação. Specs recuperados ficam em Doc/. Ver INICIAR-AQUI.md. Não houve deploy.

Base exclusiva: arquivos de Kinovo baixados do HostGator e atualizados pelo usuário. Ignorar Kinovo-dev e backups. Este espelho acompanha SKILL.md; não certifica testes ou publicação em outro ambiente.

Versão e fontes disponíveis

APP_VER 1.3.9 · build 30092026-meio-ico · index: app.js/app.css v222 · CACHE_FINANCE_VER=4 · SCHEMA_VER=15 · Portal DEPLOY_BUILD=20261005-local2. Não confundir esses identificadores. SKILL.md fica na raiz Kinovo; caminhos MyFinanceWeb são nomes históricos. Specs, README, gerador de lote e outros documentos citados que não estejam nesta pasta não devem ser considerados disponíveis.

Admin · autenticação vigente e integração pendente

O fluxo atual é Totp.php + Auth::adminTotpDispatch, campos admin_totp_secret/admin_totp_habilitado. Tela: adminTotpStatus/Iniciar/Confirmar/Verificar/Desativar; sessão: adminTotpHabilitado/adminTotpOk; bloqueio: adminTotpRequired. O segundo fator é exigido quando habilitado. Cadastro pendente expira em 900 segundos. Não há recuperação de uso único nem duração MFA de 30 minutos nesse fluxo.

Correção local de 05/11/2026: Admin::dispatch encaminha a lista explícita de ações TOTP para Auth, que exige administrador; demais ações preservam o gate. Estado TOTP com erro bloqueia a ação. Confirmação/desativação respeitam bloqueio de tentativas. Cadastro por chave manual, sem QR externo; respostas no-store. Homologação de sessão/MySQL ainda pendente. Recuperação e prevenção de reutilização de código continuam no backlog.

AdminMfa.php e Doc/ADMIN-MFA-DEPLOY.md são implementação alternativa não ligada ao fluxo ativo. Não publicar a alternativa nem misturar seus contratos sem integração explícita.

Admin · usuários

Cards de resumo com status, plano, identidade, casa e bancos. Gerenciar abre userDrawer; Open Finance abre diretamente essa aba. Contato, Open Finance, Plano e Acesso ficam no editor do usuário selecionado. Busca inclui banco e MyID. Plano pertence à casa. Remover conexão preserva lançamentos anteriores. Helpers antigos de expansão existem, mas não são a navegação principal.

Publicação · destino efetivo

Dev/Homolog publica na raiz da aplicação aberta, inclusive se ela estiver em Produção. Esse ramo faz backup de banco ou aplicação. Produção resolve a raiz própria no host kinovo.kincorp.com.br, ou portal_prod_raiz/pasta irmã fora dele. Se não achar, aborta. O ramo Prod recusa mudaBanco e não executa o backup do ramo Dev. Multipart: pacote, ambiente e mudaBanco. Checkbox não executa SQL.

FTP possui configuração/teste Dev e Prod, mas não é requisito de Portal::deploy atual: o ZIP é aplicado no disco local. Não usar FTP ok como prova do destino. A gravação do pacote pode ser parcial; backup da aplicação não substitui cópia de storage/comprovantes.

Conciliação · novo MyID

Remover registra openfinance_item_removido e apaga vínculo ativo usuario_openfinance, preservando lançamentos e histórico. Remoção na Pluggy é separada. Novo item pode usar histórico de sucessão; reconexão e gemelo exigem item antecessor e pluggy_account_id não vazio e igual. Fingerprint é metadado. NOT EXISTS/JOIN restringem o pareamento 1:1. Sem identidade suficiente, pode haver novo_extrato para revisão.

Comportamento atual: aceita PENDING/POSTED e cria Concluído; tx ID já vinculado a lançamento existente é ignorado, sem re-baixa automática nem atualização remota. Isso não equivale a garantia de que todo pendente foi efetivado.

Motor e KIN IA · implementação presente

EstadoCasa integra cinco fases (vermelho, estabilizar, reserva, objetivos, patrimonio), flags sobrepostas, restrições e proteção de conquista. DecisaoComparada reutiliza o simulador. DadosQualidade, CalendarioCaixa, Snapshot, BacktestForecast, Playbooks, LLM/LlmTools, ciclo de recomendação e decisões existem no código. EstadoCasa/DecisaoComparada integram getKinContexto. Presença não significa eficácia comprovada.

Reserva ainda compara caixa + investimentos brutos com três vezes despesas mensais, sem elegibilidade por liquidez. Calendário 1.1.1 distingue confirmado/estimado, trata faturas e lê dataISO/parcelas no formato Finance. Recorrência é coberta 1:1 por série ou correspondência legada de descrição/carteira/valor/data; vencimentos 29–31 ajustam ao fim do mês. Correção local testada; validar em homologação.

Backtest e qualidade · correções locais e limites

Snapshots imutáveis por INSERT IGNORE; coleta ao consultar getKinContexto do mês atual. Backtest compara previsão em T com saldos diários em 30/60/90, exigindo cobertura. Não há prova de coleta agendada; snapshots não são audit trail intradiário. Prontidão não mede acurácia.

Correção local: Snapshot 1.2.1 / BacktestForecast 2.1.1 removem variável inexistente e preservam nulos. Horizontes disponíveis são avaliados individualmente; prontidão 90 exige forecast/cobertura e cinco amostras 90 retornadas. amostras90Retornadas e amostrasCalendario tornam a cobertura explícita. MAE e detecção não diluem métricas com previsões ausentes. Antecedência média considera alertas previstos com aperto observado. Histórico antigo não é corrigido retroativamente.

EvalRunner considera falha RAG na triagem. Correção local: EvalNumerico exige todos os valores monetários reconhecidos; pergunta financeira sem valores não demonstra fidelidade. Não valida automaticamente associação ao campo/período. No caminho LLM, valores reprovados são substituídos por resposta de verificação; caminhos locais mantêm aviso para revisão de cálculos derivados. Bateria aprovada não garante fidelidade financeira. Ações: getKinBacktest, getKinMotorSnapshots, getKinContextoTool, adminKinEvalExecutar/Retestar/RetestarMotor.

Motor PHP calcula antes do LLM opcional. provider=local indica fallback/caminho PHP; não comprova um modelo de linguagem local instalado. Decisões e aprendizado precisam de resultados reais para demonstrar benefício.

Testes locais: 30 verificações PHP 8.2.26 (snapshots, métricas, calendário e TOTP com doubles de banco), teste temporal e lint dos PHP alterados. Sessão/MySQL reais e publicação ainda pendentes. Recuperação TOTP/replay, Telegram, sync, fidelidade numérica e operação continuam no backlog.

A O que é o Kinovo

Em linguagem simples: app web de finanças da família. Cada um entra com seu e-mail, mas todos da mesma casa veem o mesmo dinheiro e lançamentos. Junta planilha, lançamento manual, contas a pagar, cartão, investimentos e extrato bancário (Open Finance).
  • Cada membro: login próprio; mesma casa (conta_id).
  • Carteiras podem ser “de cada um” (ex.: Santander · Reginaldo) e MyID Open Finance individual.
  • Fontes: manual, recorrente, CSV, Pluggy (OF), cartões, Brapi (cotações).
Não é: contabilidade formal, conciliação certificada ou substituto do app do banco — é controle doméstico com automação.
URLs (rewrite): /login, /index, /admin, /inicio (landing Kinovo KIN · tagline institucional).

B Modelo familiar (conta conjunta)

B.1 Criar casa vs entrar na casa de alguém

FluxoO que acontece
Cadastro sem códigoNova casa “Casa de Fulano”; usuário vira dono; semeia categorias e carteira (Auth::semearConta).
Cadastro com códigoEntra na casa existente como membro (conta_membros).
Convite: logado → gerar código (API gerarConvite) → outra pessoa usa no registro ou aceitarConvite

Trocar de casa: aceitarConvite chama desvincularUsuarioDaConta — remove conta_membros (incl. dono) e usuario_openfinance da casa antiga; limpa PIN na sessão. garantirTabelaOpenFinance() roda antes de beginTransaction() (sem DDL dentro da transação). Conta antiga e lançamentos históricos permanecem no banco.

B.2 Plano, Mercado Pago e bloqueio

  • contas.plano (ex. free) e plano_ate; admin altera com adminPlano (sem passar por mp_eventos).
  • Assinatura MP: preapproval → status + busca pagamentos pela ext; **só pagamento aprovado** estende plano (payment:{id}).
  • Recuperação: search MP paginada (limit=100, até ~5 000 cobranças/ext); operação normal = webhook por payment:{id}.
  • usuarios.bloqueado — admin não bloqueia outro admin.

B.3 Campo “Quem”

Primeiro nome de quem pagou/recebeu (lancamentos.quem) — relatórios por pessoa e conciliação OF.

B.4 Carteiras

  • OF: nome Banco · Pessoa; selo OF; saldo na home vem do banco quando possível.
  • Várias contas Pluggy no mesmo item somam saldo (exc. crédito, empréstimo, investimento).

C Jornada na tela (do ícone ao rodapé)

C.1 Camadas do index.html (de baixo para cima)

1. #lockScreen (cadeado) 2. aside.desk-side — menu desktop ≥1100px 3. header.hero — barra em todas as páginas 4. main.wrap — #pageHome, #pageLate, … 5. nav fixo inferior — mobile 6. Overlays: #configOverlay, #launchOverlay, modais, #guiaOverlay, assistente…

C.2 Topo (header.hero)

ElementoID / classeFunção
Logo mobile#logoMarkÍcone Kinovo
Logo desktop.brand-logo-desklogooficialdesktop.png
Busca#deskSearchDesktop → extrato filtrado
Tema#btnThemeff_theme, html.dark + body.dark
Perfilchip avatarabrirPerfil() → #perfilOverlay
Mês#perPickBtnDropdown período

C.3 Cadeado

Conta com PIN e sessão PHP sem desbloqueio → pinRequired na sessao → #lockScreen (validarPin ou validarDigitalDesbloqueio grava kin_pin_unlock) → loadData ff_ok no sessionStorage = atalho UX; servidor manda (Auth.php + Finance::dispatch)

C.4 Home (#pageHome) — ordem vertical

  1. #sumCard — saldo, receitas/despesas mês, poupança %, olho (ff_saldo_oculto)
  2. #commitMobiCard — a vencer / a receber / atrasados (mobile)
  3. .metrics — KPI desktop
  4. #foldCharts — donut + barras 12 meses; robô mobile
  5. #homeDock — Agenda, Enviar, Atrasados, Extrato
  6. #homeExtras — saldo livre, comparativo, pessoas, cartões, meta, orçamento…
  7. #homeKinCta — assistente / diagnóstico KIN (proativo “N pontos”, compromissos)
  8. #walletsCard, #monthsCard, #recentList

C.5 Nav mobile

BotãoAção
InícioshowPage('home')
ContasshowPage('contas')
+ LançaropenLaunch()
InvestimentosshowPage('invest') + invest.js
RelatóriosshowPage('relatorios')

C.6 Outras páginas

PáginaIDUso
Atrasados#pageLateVencidos, baixa em lote
Agenda#pageCalCalendário; bolinhas despesa/receita/misto/atraso + legenda
Extrato#pageListFiltros + busca
Contas#pageContasSaldos por carteira
Invest#pageInvestMódulo invest
Relatórios#pageRelatoriosExportações
KIN diagnóstico#pageKinAlertas D01–D09, plano, simulador, compromissos
Kinovo AI#pageKinAiChat KIN · abertura proativa · chips dinâmicos

C.7 Lançamento

#launchOverlay → composer: tipo, categoria, conta, data, valor, parcelas, quem, meio, comprovante → addTransaction / updateTransaction / transferir.

C.8 Ajustes — 13 abas

AbaIDRegra resumida
CarteirascfgWalletsSó manuais suas; OF cria as do banco
CartõescfgCardFatura, pagar fatura
RecorrentescfgRecGera dia 1; custo fixo
CategoriascfgCatsCustom + ícones
OrçamentocfgBudTeto por categoria pai
InvestircfgInvestManual + OF
MetacfgMetaReserva (sliders, plano igual/crescente), desafio grupo, meta mensal KPI
FamíliacfgFamNomes exibidos
GrupocfgShareConvite
AvisoscfgTelTelegram pessoal
AcessocfgSecPIN, digital, senha
ExtratocfgImpMyID + Atualizar bancos
PlanilhacfgPlanilhaCSV

C.9 Perfil · C.10 Assistente · C.11 PWA

  • Perfil: avatar, guia (guia.html), versão APP_VER, sair.
  • #assistFab — dicas (não altera regras OF).
  • manifest.json, ícones 192/512/180; sw.js — push; não cacheia JS/CSS (use ?v=).

D Acesso, segurança e sessão

Fluxo: primeiro acesso do dia

login.html → api entrar → cookie ff_sess → index bootApp → api sessao (pinDesbloqueado / pinRequired) → lockScreen OU pintarComCache + loadData

PIN na sessão PHP

ItemDetalhe
PIN da casaconfig.pinHash · contaTemPin · usuario.temPin
Desbloqueio$_SESSION['kin_pin_unlock'] · pinDesbloqueadoPara
Marca OKentrar, registrar, entrarDigital, validarPin, validarDigitalDesbloqueio, salvarPin
LimpaaceitarConvite (troca de casa + desvincular membro/OF antigo)
Bloqueio APIFinance::dispatch + bloqueioPinFinanceSeNecessario → pinRequired
sessaohome só se desbloqueado; senão pinRequired: true
  • Registro: senha ≥6, telefone DDD, convite opcional.
  • Digital (WebAuthn): credencial por hostname; options userVerification: required; servidor exige flags UP (0x01) e UV (0x04) em WebAuthnBio::verifyAssertion.
  • Sessão expirada: JSON login: true → redirect login.
  • usuarios.admin = 1 → admin.html e ações admin*.
  • Auth::SCHEMA_VER = 15 (migração PHP) ≠ APP_VER.semver (tela).

E Regras de negócio por módulo

Em linguagem simples: o mês que você escolhe no topo filtra gráficos e totais do card azul. Contas a pagar “atrasadas” são pendentes com data passada. Transferência entre suas contas não conta como despesa/receita do mês.

E.1 Período

filtroMes = set/2026 ou todos; KPIs/gráficos usam data_vencimento.

E.2 KPI mês vs abertos

MétricaRegra
Receitas/despesas do cardConcluído, sem Transfer%, no mês
A vencer / A receber / AtrasadosNão concluído; atrasado = venc < hoje
Na telaPendente + venc passado → label Atrasado

E.3 Saldo vs poupança % · compras no cartão

  • netCashFlow — saldo em contas (OF = Pluggy).
  • savingsRate — margem do mês; não é saldo bancário.
  • Compras no cartão Concluídas não saem do caixa nos KPIs/saldos: sqlExcluirDespesaCompraCartaoConcluida() (saída real = lançamento Fatura … na conta).

E.4 Lançamentos

Receita/Despesa · Pendente/Concluído · baixa manual, swipe ou OF · parcelas · transferência (par_id, fora KPI) · comprovante max 3 MB — ordem: grava arquivo → UPDATE → apaga anterior.

E.5 Gráficos

Donut e barras 12 meses; concluídos; sem Transfer%.

E.6 Orçamento

Teto por categoria pai vs gasto; card #budgetCard.

E.7 Metas (mensal · reserva · grupo · KIN)

Em linguagem simples: a família pode ter um objetivo patrimonial (começando pela reserva de emergência). Um propõe, o outro aceita no app. Cada aporte para poupança/CDB entra como despesa em Investimentos e o Kinovo mostra o progresso. O KIN também pode sugerir uma meta quando a saúde financeira permitir.

E.7.1 Meta mensal (KPI)

  • config.metaPoupanca · API saveMetaPoupanca.
  • Barra metaProgresso = margem do mês (saldoRaw), não saldo em contas (netCashFlow).

E.7.2 Metas patrimoniais (metas_patrimonio + MetaReserva.php)

  • Tabela metas_patrimonio: nome, valor_alvo, prazo_meses, plano igual/crescente, status (ativa/rascunho/arquivada). Várias metas; metaPatrimonioAtivaId recebe aportes.
  • Pacotes metaReserva (ativa) e metasPatrimonio no getFinanceData; home com gráfico de progresso.
  • Aportes: despesas Concluídas categoria contendo “Invest” desde plano_inicio da meta ativa.
  • APIs: previewMetaReserva, saveMetaPatrimonio, setMetaPatrimonioAtiva, deleteMetaPatrimonio.

E.7.3 Desafio em grupo (MetaDesafio.php)

  • JSON config.metasDesafio · popups #metaDesafioOverlay / aceite responderDesafioMeta.
  • Plano só ativa quando todos os conta_membros aceitaram.
  • Tipos: reserva, objetivo custom, troca de carro, terreno, viagem (catálogo; forms avançados = roadmap).

E.7.4 Sugestão KIN (Kin/MetaSugestao.php)

  • Campo metaSugestaoKin · popup #metaKinSugOverlay · dismiss ff_meta_kin_{hash} (session).

E.8–E.16 (demais módulos)

  • Saldo livre / comparativo / pessoas / destino: cards home.
  • Cartões: manual ou OF; painel montarCartoes — se manual e OF > 0 no ciclo, max(manual, OF) (não soma); pagarFatura baixa + lança Fatura na conta de caixa.
  • Invest: Brapi + posições OF (carteira ≠ motor de meta; calculadora local no invest.js).
  • Recorrentes: cron dia 1 → Pendente.
  • Telegram, planilha, relatório, auditoria, desfazer exclusão.

F Open Finance (Pluggy) — processo completo

Em linguagem simples: você cola o código do banco (MyID) em Ajustes → Extrato. “Atualizar bancos” puxa saldo real e movimentos dos últimos ~90 dias, tenta bater com contas que você já lançou, dá baixa em pendências iguais e cria lançamentos novos já pagos. Se você mudar a categoria de um lançamento do banco, o app lembra para a próxima vez.

F.1 Cadastro MyID

Admin: Client ID + Secret Pluggy (pluggy_app / .env) Usuário: cola item_id em Ajustes → Extrato → salvarOpenFinance → usuario_openfinance + carteira "Banco · Nome"

F.2 Saldo na home

  • Sync grava snapshot: soma corrente/poupança Pluggy.
  • Ignora crédito, LOAN, INVESTMENT, BROKERAGE.
  • Carteira OF usa saldoBanco; manual = soma lançamentos concluídos.

F.3 Sync — gatilhos e pipeline

GatilhoDetalhe
Atualizar bancossincronizarOpenFinance
Cron ≥ 17h1×/dia, flag ofSyncDia
AdminadminOpenFinanceSync, SyncTodos
POR ITEM Pluggy do usuário: (1) Buscar item + accounts (paginado) (2) Snapshot saldo → gravar para home (3) POR CONTA (exc. investimento): transactions últimos 90 dias (API v2 paginada) → importarTxOpenFinance para cada movimento (ver F.4) (4) migrarTransferenciasOfSemProva (try/catch) (5) cruzarDuplicatasOpenFinance (6) repararBaixasPendentesVinculadasOpenFinance (7) Resposta JSON: novos, baixas, pulados, lidosPluggy, contasExtrato[], erros[], lista openFinance atualizada

F.4 Conciliação — cada movimento do extrato

Em linguagem simples: para cada PIX/débito do banco, o app decide: ignorar (já processado), quitar uma conta em aberto sua, ligar a um lançamento que você já tinha feito, ou criar um lançamento novo. A ordem importa — pendência é quitada antes de só vincular sem baixar.

Fluxo de decisão (diagrama)

flowchart TD
  A[Movimento Pluggy] --> B{Válido POSTED/PENDING e valor?}
  B -->|não| Z[Ignorar]
  B -->|sim| C[Montar tipo, valor, carteira OF, data]
  C --> D{Inter Tag?}
  D -->|sim| P[Pedágio]
  D -->|não| E{pluggy_tx_id já existe?}
  E -->|sim| Z
  E -->|não| H{Conta corrente?}
  H -->|sim| I{Pendência: único / FIFO série / texto?}
  I -->|sim| J[Baixa automática]
  I -->|não| K{Manual compatível sem OF?}
  H -->|cartão crédito| K
  K -->|sim| L{Vincula; se aberto → baixa}
  K -->|não| R{Reconexão elegível e account ID igual?}
  R -->|sim| V[Vincula histórico 1:1]
  R -->|não| M[Cria Concluído + openfinance_txs]
  P --> K
          

Fim do sync (por casa)

flowchart LR
  S[sincronizarOpenFinance] --> C[cruzarDuplicatasOpenFinance]
  C --> J[JSON: novos · baixas · pulados]
          

Tabela de critérios (espelho SKILL F.4.1)

CenárioValorCarteiraQuemData / sérieTexto
Baixa pendênciaIgualIgual—Único: qualquer venc.; vários: FIFO mesma serie_id ou janela −3 / +14Texto compatível ou não baixa
Cruzar manualIgualIgualPrimeiro nomePagamento ±3d ou vencimento ±1dIgual, tokens, merchant/PIX, ou ENVIO PIX genérico
Cartão crédito OF————Sem baixa de pendência; cruza ou cria novo

Contadores na mensagem do sync

  • novos — criou lançamento do extrato.
  • baixas — quitou em aberto (pendência ou cruzamento com baixa).
  • pulados / já existiam — cruzou manual já Concluído (só vínculo OF, sem mudar status).
Código: importarTxOpenFinance, conciliarPendenciaOpenFinance, escolherLancamentoBaixaPendenciaOpenFinance, candidatosCruzamentoOpenFinance, garantirBaixaLancamentoOpenFinance, liberarVinculoOpenFinanceLancamento, cruzarDuplicatasOpenFinance em Finance.php. Regras completas (manual, incidentes, roadmap): SKILL Parte F.4–F.4.7 (.cursor/skills/myfinance-kinpay/SKILL.md).

F.4 passos numerados (SKILL)

  1. Validar status/valor; descrição Conta: texto; Inter Tag → pedágio.
  2. pluggy_tx_id repetido → ignora (idempotente).
  3. Baixa pendência (corrente): único / FIFO série / texto — antes do cruzamento.
  4. Cruzar manual (respeita par rejeitado) → baixa se alvo ainda em aberto; grava motivo_conciliacao.
  5. Senão criar Concluído + openfinance_txs.

Detalhes: lançamentos manuais (F.4.2), incidentes (F.4.3), desafios D1–D8 (F.4.4), cenários GD (F.4.5) — só no SKILL.

F.5 Categorias (ordem de prioridade)

  1. Inter Tag → pedágio
  2. of_categoria_memoria (você corrigiu antes)
  3. Transferência com prova
  4. MCC, texto (Uber, mercado…), categoria Pluggy, PIX → Outros · PIX / Renda Extra
  5. Fallback Outros / Renda Extra

Memória: ao editar categoria de lançamento OF → chaves cnpj: / loja:. Não memoriza Outros genérico nem Transferência.

F.6 Manutenção automática

  • cruzarDuplicatasOpenFinance — fim sync + cron; remove duplicata OF quando acha manual equivalente (merchant/recebedor em openfinance_txs).
  • repararBaixasPendentesVinculadasOpenFinance — desativado (no-op).
  • corrigirPedagiosInterTag, corrigirTransferenciasOpenFinance — cron manutencaoDia.

F.7 Limites (o que OF não faz)

  • Não renomeia PIX genérico sem lançamento seu para cruzar.
  • Vários boletos iguais na mesma série → FIFO; ambíguos → não baixa automático (fila P2).
Código: Finance.php, Pluggy.php. Fonte única de conciliação: SKILL F.4–F.4.7.

G Versionamento, build e deploy

Em linguagem simples: a versão no perfil (ex. 1.3.0) é informativa. Depois de mudar telas ou JS, aumente ?v= no index.html (ex. 115). Lote ZIP → Admin publica.
CampoOndeSignificado
APP_VER.semverpublic/js/app.jsMostrado no perfil
APP_VER.buildidemddMMyyyy no tooltip
Auth::SCHEMA_VERAuth.phpMigração banco (independente)

Fluxo deploy

1. Alterar código + MELHORIAS.md 2. Bump APP_VER e ?v= no index.html (app.css / app.js) 3. Preparar ZIP com arquivos tocados (gerar-lote.cmd disponível; UI em lote-ui.cmd, porta 18767; novos ZIPs salvos em deploy/, pasta criada automaticamente) → lote-AAAAMMDD-HHMM.zip (public, src, .htaccess — SEM .env) 4. Admin → Backup e publicação → conferir ambiente e pasta → enviar ZIP → cópia local no HostGator → backup automático apenas no ramo Dev; SQL não é executado pelo checkbox 5. Senha FTP só no banco (portal_ftp_pass), nunca no ZIP

VERSIONAMENTO.md é uma referência histórica ausente nesta cópia. Confira o destino efetivo descrito no estado atual antes de publicar qualquer lote.

H Painel Admin (admin.html)

Em linguagem simples: área só para admin=1 — gerir usuários, Pluggy, Brapi, FTP e publicar versões. Não é o menu Ajustes da família.

Detalhe completo: SKILL.md Partes H.0–H.11. Arquivo: public/admin.html (CSS/JS inline).

Acesso

sessao → admin? → adminUsuarios Não admin → index · Não logado → login

Menu lateral → tela

ItemO que aparece
CasaGrid: Open Finance, Telegram, Brapi + card publicação
UsuáriosKPIs, busca, cards (plano, bloqueio, MyID por pessoa)
Backup e publicaçãoPortal com configurações Dev/Produção, backups e publicação de ZIP
OF / Telegram / BrapiSó o card da conexão
Motor KINCRUD kin_regras + kin_conhecimento (JSON, sem redeploy)

Tema: kinovo-admin-tema (claro/escuro). Versão no rodapé: lida de app.js no servidor.

Publicação (3 passos na UI)

1. Conferir ambiente e pasta efetiva (Dev/Homolog = aplicação aberta) 2. Garantir backup: ramo Dev faz banco/app; ramo Prod não chama esse backup 3. Enviar ZIP public/src; SQL é separado e mudaBanco é recusado em Prod

Chaves banco: portal_ftp_*, teste em portal_ftp_test. Deploy: Portal.php.

Usuários

  • Conectado: último acesso ≤ 15 min.
  • Plano: Gratuito/Inteligente/Patrimônio por contaId.
  • OF: atalho Open Finance ou Gerenciar abre o painel lateral; sync individual ou global.
  • Bloquear: não aplica a admin nem a si.

API admin

adminUsuariosadminBloquearadminPlano adminPluggyCredenciaisadminBrapiSalvar adminOpenFinanceSalvaradminOpenFinanceSyncadminOpenFinanceSyncTodos adminPortalFtpSalvaradminPortalFtpTestar adminPortalBackupDbadminPortalBackupAppadminPortalDeploy adminKinMotoradminKinRegraSalvaradminKinConhecimentoSalvar

Deploy usa multipart (pacote + mudaBanco), não JSON.

I Arquitetura técnica

MyFinanceWeb/
├── .env                 # NUNCA commitar
├── .htaccess → public/
├── public/
│   ├── api.php          # roteador JSON POST
│   ├── index, login, admin, inicio, guia, referencia-tecnica.html
│   ├── js/app.js, css/app.css, invest/
│   ├── cron.php, telegram.php, saude.php, avatar.php, sw.js
│   └── icones/, bancos/, img/, uploads/
├── src/ Config, Database, Http, Auth, Finance, Admin, Pluggy, Brapi, Portal…
│   ├── MetaReserva.php, MetaDesafio.php
│   └── Kin/  Diagnostico, PlanoAcao, Simulador, Saude, MetaSugestao, MetaAdaptativa,
│             Patrimonio, IaChat, Brain, Orchestrator, Acesso…
└── sql/schema.sql, migrate-*.sql

Erro fatal → JSON 500 + log prefixo Kinovo.

Fluxo HTTP

POST api.php { action, payload } → Config → Auth::start() → públicas OU Auth::requireUser() → Admin (admin*) OU Finance::dispatch → MySQL PDO

J API completa

POST /api.php · resposta JSON · success: false + error · login: true → login.

Públicas

registrarentrarsessaosairentrarDigital

Auth (logado)

gerarConviteaceitarConvitecontaInfoalterarSenhasalvarDigitaldesligarDigitalsalvarOpenFinanceapagarOpenFinance

Finance — leitura

getFinanceDatagetFinanceHomegetFinanceExtras

Finance — KIN (Inteligência)

getKinDiagnosticogetKinPlanotoggleKinPlanoItem getKinSimulacaogetKinSimulacoesgetKinAcessogetKinChat getKinContextogetKinContextoBlocogetKinEvidencia getKinMemoriasaveKinMemoriadeleteKinMemoria getKinDecisoessaveKinDecisao getKinRegrasgetKinConhecimento

Chat/plano/sim: gate Kin/Acesso.php (Basic+). Contexto único: getKinContexto → kinMontarContexto.

Finance — lançamentos

addTransactionupdateTransactiondeleteTransactiondesfazerExclusaodarBaixadarBaixaVariaspagarFaturatransferireditarTransferenciabuscarParTransferencia

Carteiras · Recorrentes · Categorias · Orçamento

saveWalletsaddCarteiradeleteCarteirarenameCarteirasaveRecorrentedeleteRecorrentesaveCategoriarenameCategoriadeleteCategoriasaveSubcategoriasaveOrcamentodeleteOrcamento

Invest · Meta · Cartão · PIN · Telegram · OF

saveInvestimentoatualizarCotacoesradarInvestimentossaveMetaPoupancasaveMetaPatrimoniopreviewMetaReservacriarDesafioMetaresponderDesafioMetasaveCartaovalidarPinsaveTelegramsincronizarOpenFinanceimportarPlanilhauploadComprovante

getFinanceData inclui metaReserva, desafiosMeta, metaSugestaoKin.

Só no JS (sem PHP hoje): previewExtrato, importarExtrato, backupPlanilha.

Cliente: api(name, payload, ok, fail) → fetch('api.php').

K Banco de dados

schema.sql + migrate-*.sql (rodar uma vez). Produção: não rodar seed.sql cegamente.

GrupoTabelas
Contacontas, usuarios, conta_membros, config
Financeirolancamentos, carteiras, recorrentes, cartoes, orcamentos
Categoriascategorias, subs, ícones
Investinvestimentos
OFusuario_openfinance, openfinance_txs, of_categoria_memoria, of_chaves_familia, pluggy_app
Sistemaauditoria, exclusoes_undo, dispositivos_bio, app_config
Monetizaçãomp_assinaturas, mp_eventos (chave UNIQUE — idempotência MP)
KINkin_planos, kin_evolucao, kin_memoria, kin_decisoes, kin_resultados, kin_regras, kin_conhecimento, kin_simulacoes (DDL em Finance.php)

lancamentos: vencimento, pagamento, tipo, categoria, carteira, valor, status, quem, meio, parcelas, par_id…

Chaves config (metas)

ChaveConteúdo
metaPoupancaValor KPI meta do mês (string numérica)
metaReservaJSON plano reserva / objetivo ativo
metasDesafioJSON desafios pendentes/aceitos em grupo
nomesFamiliaJSON nomes “quem pagou” + inferência de N pessoas no plano

L Frontend técnico

Boot

bootApp mountChrome() api('sessao') — ANTES do cache tratarPinPosSessao → lockScreen OU ff_ok + pintarComCache + loadData aceitarConvite → nova sessao antes de loadData fim do arquivo: else { bootApp(); } — obrigatório (node --check)

loadData

getFinanceHome → UI parcial getFinanceData → pacote completo → gravarCacheFinanceiro pinRequired em api() → cadeado (exc. sessao, temPin, validarPin, validarDigitalDesbloqueio)

Cache kin_fin_*

Chave kin_fin_{ver}_{uid}_{contaId}_{filtroMes} · CACHE_FINANCE_VER · invalidar ao sair / trocar casa / convite. Legado financeData_cache removido no boot.

Storage

ChaveUso
ff_okAtalho UX pós-cadeado (session); servidor usa kin_pin_unlock
ff_saldo_ocultoSaldo mascarado (padrão oculto)
ff_themeClaro/escuro
kin_fin_*Cache financeiro boot (uid + conta + mês)
financeData_cacheLegado — invalidar; não usar no boot novo
kinProativoDismiss_{mes}Ocultar banner KIN na home (localStorage)
state.kinContextoPacote de getKinContexto para home AI
ff_meta_kin_{hash}Dispensar popup sugestão meta KIN (session)
ff_bio_*WebAuthn

Mobile: breakpoint 767px; menu lateral 1100px; evitar display: contents no Safari em home.

M Operação HostGator

  • PHP 8.1+, pdo_mysql, mod_rewrite, docroot public/
  • .env na raiz MyFinanceWeb (fora do ZIP)
  • Cron: cron.php?key=APP_KEY — recorrentes, manutenção, OF 17h
  • saude.php diagnóstico

N Checklist desenvolvedor

  1. Mudou regra? Atualizar SKILL.md + esta página + MELHORIAS.md
  2. Nova action → api.php + classe + api() no front
  3. KPI/gráfico → excluir Transfer%, Concluído onde couber
  4. OF → testar sync, memória categoria, saldo home
  5. Front → bump app.css?v / app.js?v
  6. Deploy → semver/build, lote, Admin, sem .env
  7. onclick → expor em window.
  8. Não commitar .env, backups/, BKP/
  9. Trabalho KIN → KIN-ROADMAP.md + kin-roadmap.html + SKILL Parte O + specs KIN-*

O KIN (Inteligência Financeira) + Fase 8

Em linguagem simples: o KIN explica o mês (por que vermelho, cartão, atrasos), sugere plano e simula “e se?”. O Kinovo AI conversa sobre seus números — deve manter fidelidade aos valores; a validação atual ainda é limitada. Memória e compromissos só entram se você confirmar.
Regra de ouro: KIN não altera KPIs, OF nem fórmulas da home — lê o mesmo pacote (montarPacoteKin, Parte E).

O.1 Princípios

  • PHP/MySQL calculam; IA interpreta (opcional, .env KIN_IA_*).
  • Separar fato · interpretação · sugestão; projeção linear ≠ garantia.
  • Spec: Doc/KIN-ESPEC-v1.md (recuperado da base de desenvolvimento) (D01–D09).

O.2 Fases 0–7 (resumo)

FaseConteúdoStatus
2Diagnóstico + #pageKinFeito
3Plano + jornadaFeito
4Simulador “E se?”Implementado (histórico kin_simulacoes presente; homologação não certificada)
5–6Recuperação, patrimônio, monetizaçãoFeito
7Narrativa, chat, saúde, #pageKinAiFeito

O.3 KIN 2.0 — Fase 8 (core + admin 8.9 · app 1.3.2)

Plano: KIN-2.0-PLAN.md. Acompanhamento: kin-roadmap.html.

#EntregaStatusSpec
8.1Pacote JSON getKinContextoFeitoKIN-CONTEXTO-v1.md
8.2Kin/Analysis.php (3m/6m, cartão, reserva)FeitoKIN-ANALYSIS-v1.md
8.3kin_regras + Kin/Rules.phpFeitoKIN-REGRAS-v1.md
8.4kin_conhecimento + bibliotecaFeitoKIN-CONHECIMENTO-v1.md
8.5kin_memoria + chat confirmadoFeitoKIN-MEMORIA-v1.md
8.6kin_decisoes / kin_resultadosFeitoKIN-DECISOES-v1.md
8.7Chat 2.0 (chips, 3 caminhos, LLM v2)FeitoKIN-CHAT-v2.md
8.8Home proativa (proativoHome)FeitoKIN-PROATIVO-v1.md
8.9Admin CRUD regras/conhecimentoFeitoKIN-ADMIN-v1.md
8.10Histórico kin_simulacoesFeitoKIN-SIMULACOES-v1.md
8.11Evidência agregada anonimizadaFeitoKIN-EVIDENCIA-v1.md
8.12Tools contexto (getKinContextoBloco)FeitoKIN-TOOLS-v1.md

O.4 Fluxo técnico (Fase 8)

montarPacoteKin → getKinDiagnostico (KinRules + KinMemory suaviza D04/D09) → KinAnalysis::analisar (série 6m, kin_evolucao, problemas[]) → kinMontarContexto (memória, decisões, KinConhecimento) → contexto JSON (sem extrato bruto) → getKinChat / prefetch home / LLM opcional

O.5 Campos principais do contexto

BlocoConteúdo
financeiromesAtual, medias3m/6m, tendencia, cartao, parcelas, reserva, problemas
diagnosticosResumo D01–D09
saudeEixos e trajetória (resumo)
memoriaContexto confirmado pelo usuário
decisoesRecentesPlano/sim + resultado vs evolução
conhecimentoAté 4 artigos (cartão, reserva, dívida…)
proativoHomeTítulo, badge, hash dismiss, compromissos
chipsChatAtalhos Kinovo AI dinâmicos
engineMetaSpecs KIN-* referenciadas

O.6 Planos comerciais (KIN)

Matriz: KIN-MONETIZACAO-v1.md · Kin/Acesso.php.

  • Free: controle + diagnóstico KIN.
  • Basic (Inteligente): plano, simulador, evolução, chat KIN.
  • Premium (Patrimônio): trilhas patrimoniais + gates premium.

Versão referência (out/2026): espelho SKILL F.4 conciliação + fluxos Mermaid · deploy: alinhar com APP_VER e ?v= do index.html.

Kinovo · espelho alinhado ao SKILL.md Partes A–O (conciliação OF F.4.1 out/2026) · Guia: guia.html

Telegram · segurança local em 05/11/2026

Telefone só vincula quando o contato pertence ao próprio remetente no chat privado. Contatos de terceiros, identidade ausente, cadastros bloqueados e correspondências ambíguas não vinculam. Use o link em Ajustes → Avisos nesses casos. Uso do bot e vínculo /start também filtram usuários bloqueados.

Confirmações exigem remetente do chat privado e pendência da mesma pessoa e casa atual. Onze verificações isoladas passaram e foram adicionadas ao QA, sem mensagens externas ou banco real. Homologação de uso, replay do link e concorrência de callbacks continuam pendentes.

Conferência HostGator: oito arquivos principais de Produção comparados, api.php idêntico e sete diferenças compatíveis com correções/consolidação locais. Não é comparação integral nem confirmação de deploy. Nenhuma publicação realizada; .env permanece de Produção e fora do lote.

Homologação KIN em Dev · 05/11/2026

Admin/Authenticator confirmado pelo usuário. Contexto, snapshots e backtest executaram em Dev; snapshot existente preservado. Conta avaliada tem 10 dias coletados em janela maior, com lacunas: histórico insuficiente é esperado. Calendário de 60 dias tem 61 pontos, mas zero eventos futuros nessa amostra; cálculos básicos conferem. Auditoria não encontrou vínculos OF órfãos nem reutilizados no mesmo item. Nenhum sync ou pagamento foi executado.

Correções locais novas: Finance preserva confiança calculada, BacktestForecast 2.1.2 mantém amostras dos três horizontes; EvalNumerico/RespostaValidador 1.1.0 verificam todos os valores reconhecidos, sinais e zero, distinguindo falta de evidência. IaChat 1.9.3 não entrega valores LLM reprovados. Associação entre valor, campo e período ainda exige evolução.

QA: teste temporal, 36 verificações gerais, 16 monetárias e 11 de identidade OF passaram. Novas correções não foram publicadas: preset Melhorias para Dev agora possui 19 arquivos. Telegram permanece fora da prioridade. Não confundir auditoria/testes isolados com homologação completa de manual pago e sync real.