Agents para Estrutura do Módulo Financeiro

Este documento define instruções detalhadas para o Codex (ou outro agente de geração de código) garantir que o módulo Financeiro do aplicativo siga rigorosamente a estrutura padronizada de Controllers, Services e Routes, assegurando completude, consistência e qualidade no código gerado.

1. Controllers (

src/controllers/financeiro/

)

Arquivo	Funções Esperadas
metaFinanceiroController.ts	criarMetaFinanceiro listarMetasFinanceiro buscarMetaFinanceiroPorId atualizarMetaFinanceiro deletarMetaFinanceiro regenerarOcorrenciasParaMetaRecorrente
pagamentoController.ts	criarPagamento listarPagamentos buscarPagamentoPorId atualizarPagamento deletarPagamento quitarPagamentoPorId
recebimentoController.ts	criarRecebimento listarRecebimentos buscarRecebimentoPorId atualizarRecebimento deletarRecebimento quitarRecebimentoPorId
tarefaFinanceiroController.ts	criarTarefaFinanceiro listarTarefasFinanceiro buscarTarefaFinanceiroPorId atualizarTarefaFinanceiro deletarTarefaFinanceiro gerarOcorrenciasTarefaFinanceiro
painelAtividadesFinanceiroController.ts	obterPainelAtividadesFinanceiro listarAtividadesFinanceiro
dashboardFinanceiroController.ts	obterDashboardFinanceiro
ocorrenciasFinanceiroController.ts	listarOcorrenciasFinanceiro buscarOcorrenciaFinanceiroPorId iniciarOcorrenciaFinanceiroPorId concluirOcorrenciaFinanceiroPorId resetarOcorrenciaFinanceiroPorId
categoriaFinanceiroController.ts	criarCategoriaFinanceiro listarCategoriasFinanceiro buscarCategoriaFinanceiroPorId atualizarCategoriaFinanceiro deletarCategoriaFinanceiro
contaFinanceiroController.ts	criarContaFinanceira listarContasFinanceiras buscarContaFinanceiraPorId atualizarContaFinanceira deletarContaFinanceira getSaldoConta
transferenciaFinanceiroController.ts	criarTransferencia listarTransferencias buscarTransferenciaPorId atualizarTransferencia deletarTransferencia executarTransferencia
relatorioFinanceiroController.ts	gerarFluxoCaixa gerarResumoMensal gerarComparativoFinanceiro listarRelatoriosFinanceiros buscarRelatorioFinanceiroPorId
configuracaoFinanceiroController.ts	obterConfiguracaoFinanceiro atualizarConfiguracaoFinanceiro
exportacaoFinanceiroController.ts	exportarCSVFinanceiro exportarXLSXFinanceiro importarCSVFinanceiro importarXLSXFinanceiro
integracaoFinanceiroController.ts	conectarGatewayFinanceiro sincronizarTransacoesFinanceiras receberWebhookFinanceiro testarConexaoFinanceira

2. Services (

src/services/financeiro/

)

Arquivo	Métodos Esperados
metaFinanceiroService.ts	criarMetaFinanceiro listarMetasFinanceiro buscarPorId atualizarMetaFinanceiro deletarMetaFinanceiro regenerarOcorrenciasParaMetaRecorrente
pagamentoService.ts	criarPagamento listarPagamentos buscarPagamentoPorId atualizarPagamento deletarPagamento quitarPagamento
recebimentoService.ts	criarRecebimento listarRecebimentos buscarRecebimentoPorId atualizarRecebimento deletarRecebimento quitarRecebimento
tarefaFinanceiroService.ts	criarTarefaFinanceiro listarTarefasFinanceiro buscarPorId atualizarTarefaFinanceiro deletarTarefaFinanceiro gerarOcorrenciasTarefa
painelAtividadesFinanceiroService.ts	obterPainelAtividadesFinanceiro listarAtividadesFinanceiro
dashboardFinanceiroService.ts	obterDashboardFinanceiro
ocorrenciasFinanceiroService.ts	listarOcorrenciasFinanceiro buscarPorId iniciarOcorrencia(id: string) concluirOcorrencia(id: string) resetarOcorrencia(id: string)
categoriaFinanceiroService.ts	criarCategoriaFinanceiro listarCategoriasFinanceiro buscarPorId atualizarCategoriaFinanceiro deletarCategoriaFinanceiro
contaFinanceiroService.ts	criarContaFinanceira listarContasFinanceiras buscarPorId atualizarContaFinanceira deletarContaFinanceira getSaldoConta
transferenciaFinanceiroService.ts	criarTransferencia listarTransferencias buscarPorId atualizarTransferencia deletarTransferencia executarTransferencia
relatorioFinanceiroService.ts	gerarFluxoCaixa gerarResumoMensal gerarComparativoFinanceiro listarRelatorios buscarPorId
configuracaoFinanceiroService.ts	obterConfiguracaoFinanceiro atualizarConfiguracaoFinanceiro
exportacaoFinanceiroService.ts	exportarCSVFinanceiro exportarXLSXFinanceiro importarCSVFinanceiro importarXLSXFinanceiro
integracaoFinanceiroService.ts	conectarGatewayFinanceiro sincronizarTransacoesFinanceiras receberWebhookFinanceiro testarConexaoFinanceira

3. Routes (

src/routes/financeiro/

)

Arquivo	Endpoints / Métodos
financeiroRouter.ts	monta sub-routers: metasFinanceirasRoutes, pagamentosRoutes, recebimentosRoutes, tarefasFinanceirasRoutes, painelAtividadesFinanceiroRoutes, dashboardFinanceiroRoutes, ocorrenciasFinanceiroRoutes, categoriasFinanceiroRoutes, contasFinanceiroRoutes, transferenciasFinanceiroRoutes, relatoriosFinanceiroRoutes, configuracaoFinanceiroRoutes, exportacaoFinanceiroRoutes, integracaoFinanceiroRoutes
metasFinanceirasRoutes.ts	POST `/metas` GET `/metas` GET `/metas/:id` PUT `/metas/:id` DELETE `/metas/:id` POST `/metas/:id/ocorrencias`
pagamentosRoutes.ts	POST `/pagamentos` GET `/pagamentos` GET `/pagamentos/:id` PUT `/pagamentos/:id` DELETE `/pagamentos/:id` POST `/pagamentos/:id/quitar`
recebimentosRoutes.ts	POST `/recebimentos` GET `/recebimentos` GET `/recebimentos/:id` PUT `/recebimentos/:id` DELETE `/recebimentos/:id` POST `/recebimentos/:id/quitar`
tarefasFinanceirasRoutes.ts	POST `/tarefas` GET `/tarefas` GET `/tarefas/:id` PUT `/tarefas/:id` DELETE `/tarefas/:id` POST `/tarefas/:id/ocorrencias`
painelAtividadesFinanceiroRoutes.ts	GET `/painel-atividades`
dashboardFinanceiroRoutes.ts	GET `/dashboard`
ocorrenciasFinanceiroRoutes.ts	GET `/ocorrencias` GET `/ocorrencias/:id` POST `/ocorrencias/:id/iniciar` POST `/ocorrencias/:id/concluir` POST `/ocorrencias/:id/resetar`
categoriasFinanceiroRoutes.ts	POST `/categorias` GET `/categorias` GET `/categorias/:id` PUT `/categorias/:id` DELETE `/categorias/:id`
contasFinanceiroRoutes.ts	POST `/contas` GET `/contas` GET `/contas/:id` PUT `/contas/:id` DELETE `/contas/:id`
transferenciasFinanceiroRoutes.ts	POST `/transferencias` GET `/transferencias` GET `/transferencias/:id` PUT `/transferencias/:id` DELETE `/transferencias/:id` POST `/transferencias/:id/executar`
relatoriosFinanceiroRoutes.ts	GET `/relatorios/fluxo-caixa` GET `/relatorios/resumo-mensal` GET `/relatorios/comparativo` GET `/relatorios` GET `/relatorios/:id`
configuracaoFinanceiroRoutes.ts	GET `/configuracao` PUT `/configuracao`
exportacaoFinanceiroRoutes.ts	GET `/exportacao/csv` GET `/exportacao/xlsx` POST `/importacao/csv` POST `/importacao/xlsx`
integracaoFinanceiroRoutes.ts	POST `/integracoes/connect` POST `/integracoes/sync` POST `/integracoes/webhook` GET `/integracoes/test-connection`

🔧 Como usar

Substitua Financeiro nos nomes de arquivos pelo seu padrão de nomenclatura se necessário.
Gere ou atualize cada Controller/Service/Route conforme a lista acima.
Crie stubs nos arquivos novos, ajuste os existentes e remova qualquer elemento não listado.
Padronize convenções (arquivos em kebab-case, classes/controllers em PascalCase, métodos em camelCase), tratamento de erros, validação e logging.

Com este inventário ampliado, o módulo Financeiro cobre todas as funcionalidades planejadas (Metas, Pagamentos, Recebimentos, Tarefas, Ocorrências, Painel, Dashboard, Categorias, Contas, Transferências, Relatórios, Configurações, Export/Import e Integrações), pronto para build, testes e manutenção.

Critérios adicionais de qualidade

Remover funções e métodos não listados explicitamente neste documento.
Garantir coerência entre Controllers, Services e Routes, não permitindo endpoints ou métodos não documentados.
Aplicar tratamento padronizado de erros e validação de dados em todas as funções e métodos implementados.
Usar consistentemente nomes em camelCase para métodos e funções, e PascalCase para classes e tipos.
Garantir uso adequado dos tipos definidos pelos Models correspondentes para DTOs e respostas das funções.
Implementar logs claros e sucintos para operações críticas (ex: criação, atualização, exclusão).

Este documento é o guia mestre definitivo para automatizar com precisão a geração e padronização do código do módulo Financeiro, garantindo uniformidade, clareza e facilidade de manutenção futura.

Objetivo 2

📘 Boas Práticas por Camada 🧱 1. MODELS (Mongoose) Nomeie o arquivo como NomeDoRecursoModel.ts

Exporte o Model, o Schema, e o tipo do documento (RecursoDoc)

Use timestamps: true no Schema

Sempre use .lean() nos services, nunca diretamente no model

Mantenha os tipos explícitos para garantir type-safety

✅ Exemplo de nome de arquivo: ReceitaModel.ts ✅ Tipo: export type ReceitaDoc = Receita & Document

⚙️ 2. SERVICES Nomeie o arquivo como nomeDoRecursoService.ts

Use classe com métodos estáticos

Nunca inclua lógica de HTTP (sem req, res)

Foque em retorno de dados, lógica de negócio e chamadas ao Model

Trate exceções lógicas aqui (ex: verificação se algo existe)

✅ Exemplo de nome de arquivo: receitaService.ts ✅ Método típico: static async listar(): Promise<ReceitaDoc[]>

🌐 3. ROUTES Use express.Router() para cada recurso

Não coloque lógica nas rotas, só chamadas ao controller

Prefira agrupar rotas por domínio/módulo

Centraliza o uso de todos os routers (use('/api/...') por módulo

Usar nome dos módulos como prefixos (/api/alimentacao, /api/financeiro, etc.)

Evitar hardcode: ideal usar nomes consistentes nos arquivos 📁 Exemplo: ts Copiar Editar // src/routes/index.ts import { Router } from "express";

import receitaRoutes from "./alimentacao/receitaRoutes"; import estoqueRoutes from "./alimentacao/estoqueRoutes"; import tarefasProfissionaisRoutes from "./profissional/tarefaRoutes";

const router = Router();

router.use("/alimentacao/receitas", receitaRoutes); router.use("/alimentacao/estoque", estoqueRoutes); router.use("/profissional/tarefas", tarefasProfissionaisRoutes);

export default router;

Crie um index.ts por módulo se tiver várias rotas

✅ Exemplo: routes/alimentacao/receitaRoutes.ts ✅ Sempre faça:

ts Copiar Editar router.get("/", ReceitaController.listar); 🧭 4. INDEX PRINCIPAL DE ROTAS Centralize todas as rotas no routes/index.ts

Use prefixos claros por módulo: /api/alimentacao, /api/financeiro, etc.

Mantenha os imports organizados por grupo/modulo

Evite hardcodes: mantenha nomes consistentes entre pastas e paths

✅ Exemplo:

ts Copiar Editar router.use("/alimentacao/receitas", receitaRoutes); 🧠 Extra: Convenções Gerais Use nomes semânticos e coerentes com o domínio (ex: MetaAlimentacao, TarefaFinanceiro, etc.)

Nunca misture lógica de camadas (Controller ≠ Service ≠ Model)

Prefira classes para controller e service (ótimo para modularização e automação)

Use sempre tipos e interfaces explícitas no TypeScript

Obs:

✅ Como evitar esse erro de vez: 🔹 1. Garanta que res está corretamente tipado Certifique-se de que a função tem a assinatura completa com Request e Response do Express:

ts Copiar Editar import { Request, Response } from "express";

export async function deletarItem(req: Request, res: Response): Promise { try { // ... res.status(204).end(); } catch (error) { res.status(500).json({ error: "Erro ao deletar." }); } } 🔹 2. Não use .end() se não for necessário Se não precisar realmente da semântica "sem conteúdo", troque por algo mais amigável:

ts Copiar Editar res.status(200).json({ mensagem: "Item deletado com sucesso." }); 🔹 3. Evite o uso de res fora do escopo principal Não declare ou reatribua res dentro da função. Exemplo ruim que pode causar esse erro:

ts Copiar Editar const res = await algumaFuncao(); // ERRADO: sobrescreveu o res do Express! res.status(204).end(); // 💥 Aqui o TS surta 🔹 4. Use o tsconfig.json a seu favor Você pode desabilitar esse erro específico em ambientes de dev, mas não é recomendado em produção. De qualquer forma, para fins didáticos:

json Copiar Editar { "compilerOptions": { "strict": true, "noImplicitAny": true, "strictNullChecks": true, // isso está ativando esse aviso } } Se você está usando strictNullChecks: true (que é uma boa prática!), então o TypeScript está apenas te protegendo.

🔧 Solução alternativa rápida: Adicione uma checagem simples:

ts Copiar Editar if (res && typeof res.status === "function") { res.status(204).end(); } Mas sinceramente: se res estiver bem tipado, você não deveria precisar disso.