Enciclopédia Kinovo / MyFinanceWeb
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/.
| Parte | Conteúdo |
|---|---|
| A | Produto, para quem, o que não é |
| B | Casa conjunta, convite, plano, carteiras |
| C | Toda UI: topo, home, páginas, 13 abas Ajustes |
| D | Login, sessão, cadeado, admin flag |
| E | KPIs, lançamentos, orçamento, metas (reserva + desafio grupo), cartões… |
| F | Pluggy: sync, saldo, extrato, memória |
| G–N | Deploy, admin, API, SQL, cron, checklist |
| O | KIN: 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á logado | sessao (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 topo | filtroMes recalcula KPIs, gráficos e listas |
| Clica no olho do saldo | Só mascara o card “Saldo em contas”; grava ff_saldo_oculto (padrão oculto) |
| Lança uma despesa | addTransaction; entra no KPI se Concluído no mês |
| Dá baixa / swipe | Status Concluído + data de pagamento |
| Corrige categoria de lançamento do banco | Grava memória OF para próximo extrato |
| Ajustes → Atualizar bancos | sincronizarOpenFinance: saldo Pluggy + extrato 90d + conciliações |
| Dia 1 / cron noturno | Recorrentes, manutenção OF, sync após 17h (1×/dia) |
| Admin publica ZIP | FTP + extrai public/ e src/; backup automático |
| Abre card KIN / Kinovo AI na home | getKinContexto (prefetch) → proativoHome · dismiss kinProativoDismiss_{mes} |
| Pergunta no Kinovo AI | getKinChat 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 simulador | kin_decisoes + avaliação vs kin_evolucao |
| Ajustes → Meta → Lançar desafio ao grupo | saveMetaPatrimonio + enviarDesafio → JSON metasDesafio pendente |
| Parceiro aceita o desafio no popup | responderDesafioMeta → 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 digital | WebAuthn exige UV no dispositivo; servidor valida flags UP+UV |
| Paga fatura do cartão | pagarFatura 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.
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.
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.
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
- 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).
/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
| Fluxo | O que acontece |
|---|---|
| Cadastro sem código | Nova casa “Casa de Fulano”; usuário vira dono; semeia categorias e carteira (Auth::semearConta). |
| Cadastro com código | Entra na casa existente como membro (conta_membros). |
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) eplano_ate; admin altera comadminPlano(sem passar pormp_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 porpayment:{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)
C.2 Topo (header.hero)
| Elemento | ID / classe | Função |
|---|---|---|
| Logo mobile | #logoMark | Ícone Kinovo |
| Logo desktop | .brand-logo-desk | logooficialdesktop.png |
| Busca | #deskSearch | Desktop → extrato filtrado |
| Tema | #btnTheme | ff_theme, html.dark + body.dark |
| Perfil | chip avatar | abrirPerfil() → #perfilOverlay |
| Mês | #perPickBtn | Dropdown período |
C.3 Cadeado
C.4 Home (#pageHome) — ordem vertical
#sumCard— saldo, receitas/despesas mês, poupança %, olho (ff_saldo_oculto)#commitMobiCard— a vencer / a receber / atrasados (mobile).metrics— KPI desktop#foldCharts— donut + barras 12 meses; robô mobile#homeDock— Agenda, Enviar, Atrasados, Extrato#homeExtras— saldo livre, comparativo, pessoas, cartões, meta, orçamento…#homeKinCta— assistente / diagnóstico KIN (proativo “N pontos”, compromissos)#walletsCard,#monthsCard,#recentList
C.5 Nav mobile
| Botão | Ação |
|---|---|
| Início | showPage('home') |
| Contas | showPage('contas') |
| + Lançar | openLaunch() |
| Investimentos | showPage('invest') + invest.js |
| Relatórios | showPage('relatorios') |
C.6 Outras páginas
| Página | ID | Uso |
|---|---|---|
| Atrasados | #pageLate | Vencidos, baixa em lote |
| Agenda | #pageCal | Calendário; bolinhas despesa/receita/misto/atraso + legenda |
| Extrato | #pageList | Filtros + busca |
| Contas | #pageContas | Saldos por carteira |
| Invest | #pageInvest | Módulo invest |
| Relatórios | #pageRelatorios | Exportações |
| KIN diagnóstico | #pageKin | Alertas D01–D09, plano, simulador, compromissos |
| Kinovo AI | #pageKinAi | Chat 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
| Aba | ID | Regra resumida |
|---|---|---|
| Carteiras | cfgWallets | Só manuais suas; OF cria as do banco |
| Cartões | cfgCard | Fatura, pagar fatura |
| Recorrentes | cfgRec | Gera dia 1; custo fixo |
| Categorias | cfgCats | Custom + ícones |
| Orçamento | cfgBud | Teto por categoria pai |
| Investir | cfgInvest | Manual + OF |
| Meta | cfgMeta | Reserva (sliders, plano igual/crescente), desafio grupo, meta mensal KPI |
| Família | cfgFam | Nomes exibidos |
| Grupo | cfgShare | Convite |
| Avisos | cfgTel | Telegram pessoal |
| Acesso | cfgSec | PIN, digital, senha |
| Extrato | cfgImp | MyID + Atualizar bancos |
| Planilha | cfgPlanilha | CSV |
C.9 Perfil · C.10 Assistente · C.11 PWA
- Perfil: avatar, guia (
guia.html), versãoAPP_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
PIN na sessão PHP
| Item | Detalhe |
|---|---|
| PIN da casa | config.pinHash · contaTemPin · usuario.temPin |
| Desbloqueio | $_SESSION['kin_pin_unlock'] · pinDesbloqueadoPara |
| Marca OK | entrar, registrar, entrarDigital, validarPin, validarDigitalDesbloqueio, salvarPin |
| Limpa | aceitarConvite (troca de casa + desvincular membro/OF antigo) |
| Bloqueio API | Finance::dispatch + bloqueioPinFinanceSeNecessario → pinRequired |
sessao | home só se desbloqueado; senão pinRequired: true |
- Registro: senha ≥6, telefone DDD, convite opcional.
- Digital (WebAuthn): credencial por
hostname; optionsuserVerification: required; servidor exige flags UP (0x01) e UV (0x04) emWebAuthnBio::verifyAssertion. - Sessão expirada: JSON
login: true→ redirect login. usuarios.admin = 1→admin.htmle açõesadmin*.Auth::SCHEMA_VER = 15(migração PHP) ≠APP_VER.semver(tela).
E Regras de negócio por módulo
E.1 Período
filtroMes = set/2026 ou todos; KPIs/gráficos usam data_vencimento.
E.2 KPI mês vs abertos
| Métrica | Regra |
|---|---|
| Receitas/despesas do card | Concluído, sem Transfer%, no mês |
| A vencer / A receber / Atrasados | Não concluído; atrasado = venc < hoje |
| Na tela | Pendente + 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)
E.7.1 Meta mensal (KPI)
config.metaPoupanca· APIsaveMetaPoupanca.- 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;metaPatrimonioAtivaIdrecebe aportes. - Pacotes
metaReserva(ativa) emetasPatrimonionogetFinanceData; home com gráfico de progresso. - Aportes: despesas Concluídas categoria contendo “Invest” desde
plano_inicioda meta ativa. - APIs:
previewMetaReserva,saveMetaPatrimonio,setMetaPatrimonioAtiva,deleteMetaPatrimonio.
E.7.3 Desafio em grupo (MetaDesafio.php)
- JSON
config.metasDesafio· popups#metaDesafioOverlay/ aceiteresponderDesafioMeta. - Plano só ativa quando todos os
conta_membrosaceitaram. - 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· dismissff_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);pagarFaturabaixa + 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
F.1 Cadastro MyID
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
| Gatilho | Detalhe |
|---|---|
| Atualizar bancos | sincronizarOpenFinance |
| Cron ≥ 17h | 1×/dia, flag ofSyncDia |
| Admin | adminOpenFinanceSync, SyncTodos |
F.4 Conciliação — cada movimento do extrato
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ário | Valor | Carteira | Quem | Data / série | Texto |
|---|---|---|---|---|---|
| Baixa pendência | Igual | Igual | — | Único: qualquer venc.; vários: FIFO mesma serie_id ou janela −3 / +14 | Texto compatível ou não baixa |
| Cruzar manual | Igual | Igual | Primeiro nome | Pagamento ±3d ou vencimento ±1d | Igual, 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).
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)
- Validar status/valor; descrição
Conta: texto; Inter Tag → pedágio. pluggy_tx_idrepetido → ignora (idempotente).- Baixa pendência (corrente): único / FIFO série / texto — antes do cruzamento.
- Cruzar manual (respeita par rejeitado) → baixa se alvo ainda em aberto; grava
motivo_conciliacao. - 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)
- Inter Tag → pedágio
of_categoria_memoria(você corrigiu antes)- Transferência com prova
- MCC, texto (Uber, mercado…), categoria Pluggy, PIX → Outros · PIX / Renda Extra
- 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 emopenfinance_txs).repararBaixasPendentesVinculadasOpenFinance— desativado (no-op).corrigirPedagiosInterTag,corrigirTransferenciasOpenFinance— cronmanutencaoDia.
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).
Finance.php, Pluggy.php. Fonte única de conciliação: SKILL F.4–F.4.7.G Versionamento, build e deploy
?v= no index.html (ex. 115). Lote ZIP → Admin publica.| Campo | Onde | Significado |
|---|---|---|
APP_VER.semver | public/js/app.js | Mostrado no perfil |
APP_VER.build | idem | ddMMyyyy no tooltip |
Auth::SCHEMA_VER | Auth.php | Migração banco (independente) |
Fluxo deploy
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)
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
Menu lateral → tela
| Item | O que aparece |
|---|---|
| Casa | Grid: Open Finance, Telegram, Brapi + card publicação |
| Usuários | KPIs, busca, cards (plano, bloqueio, MyID por pessoa) |
| Backup e publicação | Portal com configurações Dev/Produção, backups e publicação de ZIP |
| OF / Telegram / Brapi | Só o card da conexão |
| Motor KIN | CRUD 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)
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
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
J API completa
POST /api.php · resposta JSON · success: false + error · login: true → login.
Públicas
Auth (logado)
Finance — leitura
Finance — KIN (Inteligência)
Chat/plano/sim: gate Kin/Acesso.php (Basic+). Contexto único: getKinContexto → kinMontarContexto.
Finance — lançamentos
Carteiras · Recorrentes · Categorias · Orçamento
Invest · Meta · Cartão · PIN · Telegram · OF
getFinanceData inclui metaReserva, desafiosMeta, metaSugestaoKin.
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.
| Grupo | Tabelas |
|---|---|
| Conta | contas, usuarios, conta_membros, config |
| Financeiro | lancamentos, carteiras, recorrentes, cartoes, orcamentos |
| Categorias | categorias, subs, ícones |
| Invest | investimentos |
| OF | usuario_openfinance, openfinance_txs, of_categoria_memoria, of_chaves_familia, pluggy_app |
| Sistema | auditoria, exclusoes_undo, dispositivos_bio, app_config |
| Monetização | mp_assinaturas, mp_eventos (chave UNIQUE — idempotência MP) |
| KIN | kin_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)
| Chave | Conteúdo |
|---|---|
metaPoupanca | Valor KPI meta do mês (string numérica) |
metaReserva | JSON plano reserva / objetivo ativo |
metasDesafio | JSON desafios pendentes/aceitos em grupo |
nomesFamilia | JSON nomes “quem pagou” + inferência de N pessoas no plano |
L Frontend técnico
Boot
loadData
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
| Chave | Uso |
|---|---|
ff_ok | Atalho UX pós-cadeado (session); servidor usa kin_pin_unlock |
ff_saldo_oculto | Saldo mascarado (padrão oculto) |
ff_theme | Claro/escuro |
kin_fin_* | Cache financeiro boot (uid + conta + mês) |
financeData_cache | Legado — invalidar; não usar no boot novo |
kinProativoDismiss_{mes} | Ocultar banner KIN na home (localStorage) |
state.kinContexto | Pacote 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/ .envna raiz MyFinanceWeb (fora do ZIP)- Cron:
cron.php?key=APP_KEY— recorrentes, manutenção, OF 17h saude.phpdiagnóstico
N Checklist desenvolvedor
- Mudou regra? Atualizar SKILL.md + esta página +
MELHORIAS.md - Nova action → api.php + classe +
api()no front - KPI/gráfico → excluir Transfer%, Concluído onde couber
- OF → testar sync, memória categoria, saldo home
- Front → bump
app.css?v/app.js?v - Deploy → semver/build, lote, Admin, sem .env
onclick→ expor emwindow.- Não commitar .env, backups/, BKP/
- Trabalho KIN →
KIN-ROADMAP.md+kin-roadmap.html+ SKILL Parte O + specsKIN-*
O KIN (Inteligência Financeira) + Fase 8
montarPacoteKin, Parte E).O.1 Princípios
- PHP/MySQL calculam; IA interpreta (opcional,
.envKIN_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)
| Fase | Conteúdo | Status |
|---|---|---|
| 2 | Diagnóstico + #pageKin | Feito |
| 3 | Plano + jornada | Feito |
| 4 | Simulador “E se?” | Implementado (histórico kin_simulacoes presente; homologação não certificada) |
| 5–6 | Recuperação, patrimônio, monetização | Feito |
| 7 | Narrativa, chat, saúde, #pageKinAi | Feito |
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.
| # | Entrega | Status | Spec |
|---|---|---|---|
| 8.1 | Pacote JSON getKinContexto | Feito | KIN-CONTEXTO-v1.md |
| 8.2 | Kin/Analysis.php (3m/6m, cartão, reserva) | Feito | KIN-ANALYSIS-v1.md |
| 8.3 | kin_regras + Kin/Rules.php | Feito | KIN-REGRAS-v1.md |
| 8.4 | kin_conhecimento + biblioteca | Feito | KIN-CONHECIMENTO-v1.md |
| 8.5 | kin_memoria + chat confirmado | Feito | KIN-MEMORIA-v1.md |
| 8.6 | kin_decisoes / kin_resultados | Feito | KIN-DECISOES-v1.md |
| 8.7 | Chat 2.0 (chips, 3 caminhos, LLM v2) | Feito | KIN-CHAT-v2.md |
| 8.8 | Home proativa (proativoHome) | Feito | KIN-PROATIVO-v1.md |
| 8.9 | Admin CRUD regras/conhecimento | Feito | KIN-ADMIN-v1.md |
| 8.10 | Histórico kin_simulacoes | Feito | KIN-SIMULACOES-v1.md |
| 8.11 | Evidência agregada anonimizada | Feito | KIN-EVIDENCIA-v1.md |
| 8.12 | Tools contexto (getKinContextoBloco) | Feito | KIN-TOOLS-v1.md |
O.4 Fluxo técnico (Fase 8)
O.5 Campos principais do contexto
| Bloco | Conteúdo |
|---|---|
financeiro | mesAtual, medias3m/6m, tendencia, cartao, parcelas, reserva, problemas |
diagnosticos | Resumo D01–D09 |
saude | Eixos e trajetória (resumo) |
memoria | Contexto confirmado pelo usuário |
decisoesRecentes | Plano/sim + resultado vs evolução |
conhecimento | Até 4 artigos (cartão, reserva, dívida…) |
proativoHome | Título, badge, hash dismiss, compromissos |
chipsChat | Atalhos Kinovo AI dinâmicos |
engineMeta | Specs 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.
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.