Documentação — nectar-charges

Plataforma de Cobrança do IBFT (cobranca-api + cobranca-web): o serviço que centraliza a operação de recuperação de crédito hoje espalhada entre planilha, Kommo, Asaas e Apolo.

O repositório é multi-módulo: modules/frontend (React + Vite + TS) e modules/backend (Rails API). Toda a documentação vive aqui, em .project/docs/.

Por onde começar

Se você quer… Leia
Entender o produto, o faseamento e o glossário features/roadmap.md
Entender o código do front architecture/frontend_layers.md
Entender o código do back architecture/backend_layers.md
Saber as regras de negócio RULES.md
Entender como o reparcelamento roda no Asaas reference/negotiation/repayment_execution.md
Entender a estrutura de módulos modules.md

Arquivos reservados

Arquivo Papel
README.md Este índice
RULES.md Índice das regras de negócio (R-XXX)
modules.md Convenção de módulos do repo multi-módulo

architecture/

Decisões arquiteturais e suas consequências.

Doc Descrição Certainty
frontend_layers.md Camadas do app React: componentes sem lógica, hooks com toda a lógica, e a camada services/ que troca de mock para HTTP sem tocar em mais nada high
backend_layers.md Camadas do app Rails no layout padrão (commons:rails 2.0): controllers, jobs, use cases, models ricos e services só de integração, mais os desvios do código atual high

specs/

Mudanças planejadas ou já executadas.

Doc Descrição Status Certainty
20260720144029_react_port_phase1_foundation.md Port do protótipo dc-runtime para React: fundação, Login, Painel e Lotes done high
20260720172958_react_port_phase2_clientes_pagamentos.md Port fase 2: Clientes, Detalhe do cliente, Negativação, Contratos e Pagamentos, com o primeiro Context compartilhado done high
20260721082709_react_port_phase3_juridico_bots_colaboradores.md Port fase 3: Jurídico, Bots (com motor de simulador puro) e Colaboradores done high
20260721163000_mono_module_structure.md Reorganização da raiz para o layout multi-módulo, antes de o back-end existir done high
20260721190000_compose_makefile_infra_workflows.md Makefile delegador, compose unificado, .infra por módulo e workflows de CI com detected changes in_progress high
20260723085311_rails_backend_scaffold_foundation.md Scaffold da app Rails e implementação concreta das convenções transversais da USER-001 done high
20260723162952_backend_module_skills_standard.md Módulo de back-end no padrão das skills: sem metadado de repo, entrypoints completos, app/ na Arrow Architecture done high
20260727093626_auth_login_jwt.md Login por e-mail/senha com JWT stateless em cookie HttpOnly e proteção das rotas done high
20260924094344_incoming_events_inbox.md IncomingEvent: caixa de entrada dos webhooks do accounts, com dedup por event_id e 3 tentativas no Solid Queue done high
20260928152046_remove_agreement_model.md Remove o model Agreement, suas associações, testes, fixtures e a tabela agreements proposed high
20260928171636_import_overdue_checkout_payments.md Importa os pagamentos atrasados do checkout (desde 01/01/2026) como Debit com parcelas, atendente pelo CSV ou round-robin e ids do provedor done high
20260928232447_import_checkout_products.md Cria os ProductDebit dos débitos importados do checkout (external_id = products.slug) com o progresso do aluno vindo do Apolo; o reimport completa os débitos sem produtos done high
20260929010215_import_overdue_installments_only.md O import passa a exigir ao menos 1 parcela overdue ativa no pagamento, com COALESCE em gateway_deleted no pagamento e na parcela done high
20260929093935_customer_audit_logs.md Tabela audit_logs só de inserção (evento de negócio por cliente, sender user/system/checkout/asaas) e GET /api/v1/customers/:customer_id/audit_logs paginado done low
20260930014047_negotiation_calculator_mockup.md Motor da calculadora IBFT dentro do Negociacao Drawer do mockup, pré-preenchido pelo débito, com gerar/aprovar em dois estágios e sem negativadas proposed high

plans/

Passo a passo de implementação de uma spec.

Doc Spec Certainty
20260723174510_backend_module_skills_standard.md Módulo de back-end no padrão das skills — 5 fases de refactor estrutural com a suíte como rede de segurança high
20260924100043_incoming_events_inbox.md IncomingEvent — caixa de entrada de eventos do accounts — 6 tasks, da tabela ao endpoint high
20260928152900_remove_agreement_model.md Remover o model Agreement — remove o código e depois dropa a tabela agreements high
20260928181435_import_overdue_checkout_payments.md Importação dos pagamentos atrasados do checkout — conexão readonly, colunas provider_*, checkout_import_runs, assigner, use case paginado e job high
20260928233421_import_checkout_products.md Importação dos produtos do checkout — service Apolo, Checkout::Product.for_payments, contadores do run e o use case high
20260929030500_debit_repayment_use_case.md Use case Debits::Repayment — PaymentProviderAccount, colunas do Negotiation, status do Debit, módulo Asaas e o use case high
20260930014514_negotiation_calculator_mockup.md Negociação no mockup — 15 tasks: motor testado em tasks/mockup/, inlinado no bundle, e o drawer em duas colunas high

features/

User stories e critérios de aceite. O faseamento, o grafo de dependências, as decisões de arquitetura travadas e o glossário de domínio estão em features/roadmap.md — é lá que se entende em que ordem as features se encaixam e por quê; aqui embaixo estão as 29 individuais.

Fase 0 — Fundação transversal

ID Doc Descrição
USER-001 backend_service_foundation Convenções transversais: versionamento, contrato de erro, paginação, datas, dinheiro, observabilidade, idempotência
USER-002 backend_auth_jwt Login por e-mail/senha com JWT stateless em cookie HttpOnly
USER-003 auth_session_integration Substituir o login mockado do front pela autenticação real
USER-004 backend_domain_model_audit Modelo de domínio central e trilha de auditoria — o status do caso vira estado do sistema
USER-005 backend_asaas_adapter Adapter Asaas: extração de inadimplentes, emissão e negativação; ibft-api só como consulta
USER-006 backend_apolo_adapter Adapter Apolo: progresso, cursos, certificado e escrita de notas
USER-007 backend_kommo_adapter Adapter Kommo: upsert dedup, Salesbot por API, notas e webhooks
USER-008 backend_slack_adapter Adapter Slack: notificações operacionais assíncronas

Fase 1 — Estancar as duplicatas

ID Doc Descrição
USER-009 backend_batch_import Lotes e importação em 5 passos observáveis, com dedup e round-robin
USER-010 batch_import_integration Tela de Lotes acompanhando o job real por polling

Fase 2 — Sincronizar pagamentos e status

ID Doc Descrição
USER-011 backend_webhooks_status_sync Webhooks de Asaas e Kommo e o checklist de pós-pagamento
USER-012 live_state_integration Estado ao vivo no front: badges e status refletindo eventos sem refresh

Fase 3 — Unificar o atendimento

ID Doc Descrição
USER-013 backend_unified_customer_record Ficha unificada: Asaas, Apolo e Kommo numa única resposta
USER-014 customer_detail_integration Lista de clientes e as cinco abas da ficha com dados reais
USER-015 backend_negotiation_engine Motor de negociação: simulador, emissão tipada e todas as regras validadas
USER-016 payments_integration Pagamentos e avulso com mutação otimista reconciliada pelo servidor
USER-017 backend_message_cadence Régua de 4 disparos, janela de 24h do WhatsApp e agendamentos
USER-018 backend_credit_bureau_listing Negativação: fila por regra, execução do gestor e reconciliação pós-pagamento
USER-019 credit_bureau_listing_integration Tela de Negativação com execução real e badge vivo

Fase 4 — Medir e gerir

ID Doc Descrição
USER-020 backend_dashboard_kpis Painel de KPIs calculados, comissões e reincidência contínua
USER-021 dashboard_integration Painel respondendo aos filtros, com o cálculo migrado para o back
USER-022 backend_renegotiation_contracts Contrato do 2º reparcelamento: acordo travado, assinatura e esteira
USER-023 contracts_integration Esteira de contratos com transições reais no servidor
USER-024 backend_legal_cases Jurídico: máquina de estados, timeline, alerta de prazo e export
USER-025 legal_cases_integration Tela do Jurídico com transições autoritativas no servidor
USER-026 backend_bots_salesbot Config dos bots e round-robin real da distribuição
USER-027 bots_integration Simulador de bots parametrizado pela config do servidor
USER-028 backend_users_management Colaboradores: convites, perfis, ativação e desativação
USER-029 users_management_integration Tela de Colaboradores com mutações reais

Todas as 29 features têm certainty: high.

features/assets/prototype/

Arquivos do protótipo dc-runtime original, preservados como material de consulta. Não fazem parte do build.

Asset O que é
product_architecture.dc.html O blueprint de produto — “IBFT · Arquitetura de Produto, Plataforma de Cobrança, v1.0”; fonte da verdade citada como §N pelas features
collection_system.dc.html Protótipo das 14 telas do sistema de cobrança; origem do port para React
unified_record.dc.html Protótipo da Ficha Unificada, ainda não portada; contém o bug de vencBase
support.js Motor genérico do formato dc-runtime (sc-if/sc-for/{{ }}), sem lógica de negócio
ibft_guide.txt Guia de referência do IBFT que acompanhava o protótipo

rules/

Regras de negócio em Given/When/Then. Índice completo em RULES.md.

ID Doc Scope
R-001 installment_renegotiation negotiation
R-002 debt_settlement negotiation
R-003 credit_bureau_listing collections
R-004 access_extension enrollment
R-005 enrollment_cancellation enrollment
R-006 case_status_marking collections
R-007 manager_only_customer_actions access-control
R-010 incoming_event_processing events
R-011 customer_audit_log audit

reference/

Como o sistema é ou funciona: fluxos, contratos e modelos de dados.

Doc Descrição Scope Certainty
repayment_execution.md Máquina de estados do provider_status: como Debits::Repayment cria o parcelamento no Asaas, apaga as cobranças antigas e retoma de onde parou depois de uma falha negotiation high

learnings/

Aprendizados retrospectivos.

Doc Descrição Certainty
prototype_dc_quirks.md Sete comportamentos do protótipo replicados por fidelidade que não são regra de negócio — mock, simplificação ou bug. Protótipo não é spec high
backend_ruby4_default_gems.md Ruby 4.0 tirou ostruct dos defaults e uma dependência transitiva de u-case parou de bootar high
checkout_ignores_negotiation_payments.md O checkout-api ignora as cobranças do acordo criadas pelo nectar-charges e ninguém devolve o acesso do aluno quando ele paga o acordo medium

Convenções desta documentação

  • O primeiro nível de .project/docs/ é um conjunto fechado: specs/, plans/, features/, learnings/, architecture/, guides/, reference/<scope>/ e rules/<scope>/, mais os três arquivos reservados. Nenhuma outra pasta.
  • Nome de arquivo e de pasta em inglês, snake_case, sem acento nem espaço. Título, corpo, headings e tabelas em português. Termo técnico e identificador de código não se traduzem.
  • Todo doc tem certainty no frontmatter: high (veio do documento original ou de código verificado), medium (parcialmente reconstruído a partir do código), low (majoritariamente inferido; precisa de revisão humana).
  • Todo doc entra neste índice.

guides/ e reference/<scope>/ ainda não existem neste repo — serão criados quando houver conteúdo que a tabela de roteamento mande para lá.