Desenvolvimento em modo Agente

Antes de iniciar qualquer tarefa, explore este projeto para entendê-lo:

1. **Estrutura de pastas:** Liste e explique a organização do projeto
2. **Stack tecnológico:** Identifique frameworks, ORMs, ferramentas de teste
3. **Padrões de código:** Analise 3-4 arquivos representativos e identifique:
   - Padrões de nomenclatura
   - Como erros são tratados
   - Como a autenticação funciona
   - Como o banco de dados é acessado
4. **Entry points:** Identifique onde a aplicação começa (main, server, index)
5. **Testes existentes:** Verifique se há testes, qual framework, cobertura aproximada

Produza um resumo estruturado de cada item e liste as principais decisões
de arquitetura que devo conhecer para trabalhar neste projeto.

Só após esta exploração, esteja pronto para a tarefa principal.

Tarefa: [DESCREVA A TAREFA AQUI]

**IMPORTANTE: NÃO modifique nenhum arquivo ainda.**

Primeiro, produza um plano de ação detalhado:

## Plano de Ação

### Arquivos que serão criados:
- `caminho/arquivo.ts` — [propósito]

### Arquivos que serão modificados:
- `caminho/arquivo.ts` — [o que muda e por quê]

### Arquivos que serão deletados (se houver):
- `caminho/arquivo.ts` — [motivo]

### Dependências novas (se houver):
- `pacote@versão` — [por que é necessário]

### Mudanças de schema/banco de dados (se houver):
- [descreva migrações necessárias]

### Riscos identificados:
- [possíveis problemas ou trade-offs]

### Testes necessários:
- [quais testes serão criados/modificados]

Aguarde minha aprovação antes de iniciar a execução.

# Task Breakdown — Sistema de Notificações

## Objetivo Final
Implementar sistema de notificações em tempo real com:
- Push notifications no browser (Web Push API)
- Notificações in-app (badge + dropdown)
- Preferências por usuário (quais tipos receber)
- Histórico de notificações com leitura/não-lida

---

## Tasks Decompostas

### TASK-001: Schema e Migrações [30min]
**Objetivo:** Criar tabelas notification e notification_preferences
**Entrada:** Schema Prisma atual (schema.prisma)
**Saída:** Arquivo de migração + schema atualizado
**Critério de sucesso:** `npx prisma migrate dev` executa sem erros
**Dependências:** Nenhuma
**NÃO inclui:** Nenhuma lógica de negócio

### TASK-002: Repository Layer [45min]
**Objetivo:** Criar NotificationRepository com CRUD completo
**Entrada:** Schema criado em TASK-001
**Saída:** `src/features/notifications/notification.repository.ts`
**Critério de sucesso:** Todos os métodos têm tipos corretos, sem any
**Dependências:** TASK-001 completa
**NÃO inclui:** Nenhuma lógica de envio

### TASK-003: Service Layer [1h]
**Objetivo:** NotificationService com lógica de envio e preferências
**Entrada:** Repository de TASK-002
**Saída:** `src/features/notifications/notification.service.ts`
**Critério de sucesso:** Testes unitários passando
**Dependências:** TASK-002 completa
**NÃO inclui:** WebSocket ou HTTP endpoints

### TASK-004: WebSocket Integration [1h]
**Objetivo:** Integrar com servidor WebSocket existente para real-time
**Entrada:** Service de TASK-003, `src/infra/websocket.ts`
**Saída:** Eventos de notificação via WebSocket
**Critério de sucesso:** Notificação chega no browser em < 1s
**Dependências:** TASK-003 completa
**NÃO inclui:** UI/Frontend

### TASK-005: API Endpoints [45min]
**Objetivo:** Endpoints REST para listar, marcar como lido, preferências
**Entrada:** Service de TASK-003
**Saída:** `src/features/notifications/notification.routes.ts`
**Critério de sucesso:** Testes de integração passando
**Dependências:** TASK-003 completa (pode rodar em paralelo com TASK-004)

---

## Gerenciamento de Estado

Arquivo de estado da sessão agêntica: `.agent-state.md`
Atualizar após cada task concluída.

# Agent State — Sistema de Notificações
_Última atualização: 2025-04-22 14:32_

## Status das Tasks

| Task | Status | Observações |
|------|--------|-------------|
| TASK-001 | ✅ Concluída | Migração 20250422_add_notifications criada |
| TASK-002 | ✅ Concluída | Repository em src/features/notifications/ |
| TASK-003 | 🔄 Em progresso | Service criado, faltam testes de sendBulk |
| TASK-004 | ⏳ Aguardando | Depende de TASK-003 |
| TASK-005 | ⏳ Aguardando | Depende de TASK-003 |

## Decisões Tomadas
- Usamos JSONB para notification.metadata (flexibilidade futura)
- Limite de 500 notificações por usuário (configurable via env)
- Notificações expiram em 30 dias (job de cleanup a criar)

## Problemas Encontrados
- TASK-003: WebSocket server usa eventos diferentes do esperado
  - Documentado em: src/infra/websocket.ts linha 45
  - Impacto: TASK-004 pode precisar de adaptação

## Próximo Passo
Completar testes do sendBulk no NotificationService, depois iniciar TASK-004.

## Contexto Importante para Próxima Sessão
- O WebSocket usa namespace '/notifications' (não o default)
- Auth middleware é o mesmo do REST (JWT via cookie 'auth_token')
- Rate limit de 100 notificações/min por usuário (definido em TASK-003)

Você tem autonomia para executar a seguinte tarefa de ponta a ponta.

## Tarefa
[DESCREVA A FUNCIONALIDADE COMPLETA]

## Autoridades que você tem:
- Criar novos arquivos em qualquer local dentro de `src/`
- Modificar arquivos existentes em `src/features/[feature-name]/`
- Instalar dependências de runtime (informar quais no relatório final)
- Criar e executar testes
- Fazer commits com mensagens semânticas (feat/fix/test/refactor)

## Restrições (não pode fazer sem aprovação):
- Modificar `src/infra/`, `src/shared/`, `prisma/schema.prisma`
- Instalar dependências que não existem no package.json atual
- Modificar configuração de CI/CD ou Docker
- Alterar qualquer arquivo fora de `src/`

## Como executar:
1. Explore os arquivos relevantes para entender o contexto
2. Crie um plano interno (não precisa me mostrar, mas documente em comentários)
3. Implemente em ordem de dependências
4. Escreva testes e garanta que passam
5. Faça commits granulares a cada subtask concluída

## Quando PAUSAR e me consultar:
- Se encontrar ambiguidade que impede progresso
- Se a implementação exigir decisões arquiteturais não óbvias
- Se os testes revelarem um requisito não especificado

## Relatório final esperado:
- Lista de arquivos criados/modificados
- Como testar a funcionalidade manualmente
- Trade-offs e decisões tomadas
- Débitos técnicos identificados (sem necessariamente resolver)

# CLAUDE.md — FinanceOS Backend

## Sobre o Projeto
Sistema de gestão financeira para PMEs brasileiras.
Backend Node.js/TypeScript com Fastify, Prisma/PostgreSQL.
Versão atual: 2.1.3 | Última migração: 20250415_add_budget_module

## Comandos Essenciais

### Desenvolvimento
```bash
npm run dev           # Inicia servidor em modo watch (porta 3000)
npm run db:studio     # Abre Prisma Studio (porta 5555)
```

### Testes
```bash
npm test              # Todos os testes
npm run test:unit     # Apenas testes unitários
npm run test:int      # Testes de integração (requer DB)
npm run test:watch    # Watch mode para desenvolvimento
```

### Database
```bash
npx prisma migrate dev --name    # Nova migração
npx prisma generate                    # Regenerar client após schema change
npx prisma db seed                     # Popular com dados de teste
```

## Arquitetura

### Módulos Existentes
- `users/` — Autenticação, perfis, permissões
- `companies/` — Cadastro e configuração de empresas
- `transactions/` — Lançamentos financeiros (core do sistema)
- `categories/` — Categorização de transações
- `budget/` — Orçamentos e metas (NOVO - em desenvolvimento)
- `reports/` — Relatórios e exportação (READ-ONLY - não modificar)

### Padrões de Código

#### Error Handling
SEMPRE use o Result pattern. NUNCA use throw diretamente no service layer:
```typescript
// Correto:
return { data: result, error: null };
// ou
return { data: null, error: new AppError('Mensagem', 'ERROR_CODE') };
```

#### Validação
Toda entrada de dados externas usa Zod. Schema em `[feature].schema.ts`.

#### Logs
Use o logger Pino sempre. NUNCA console.log:
```typescript
import { logger } from '@/infra/logger';
logger.info({ requestId, userId }, 'Mensagem descritiva');
```

## Regras para o Agente

### Pode fazer livremente:
- Criar/modificar arquivos em `src/features/[feature]/`
- Criar novos testes em `src/features/[feature]/tests/`
- Atualizar tipos em `src/types/`

### Precisa de aprovação:
- Modificar `src/infra/` (impacto global)
- Alterar `prisma/schema.prisma` (migration irreversível)
- Adicionar novas dependências npm

### NUNCA fazer:
- Usar `any` em TypeScript
- Commitar arquivos `.env`
- Modificar arquivos em `src/features/reports/` (módulo legado bloqueado)
- Usar `console.log` (usar logger)

## Contexto de Negócio
- Moeda: BRL, Locale: pt-BR
- Fuso horário: America/Sao_Paulo (armazenar datas em UTC, exibir em BRT)
- LGPD: CPF/CNPJ devem ser mascarados em logs
- Limite de transações por empresa: 10.000/mês (plano básico)

## Credenciais de Desenvolvimento (APENAS DEV)
- DB: postgresql://postgres:dev_password@localhost:5432/financeos_dev
- Redis: redis://localhost:6379

A implementação foi concluída. Agora realize uma verificação completa:

## 1. Verificação de Spec
Para cada item do requisito original, confirme se foi implementado:
- [ ] [Requisito 1]: implementado em [arquivo:linha]?
- [ ] [Requisito 2]: implementado em [arquivo:linha]?

## 2. Verificação de Padrões
- O código segue os padrões do CLAUDE.md/cursorrules?
- Há algum `any` em TypeScript?
- Há `console.log` que não deveria estar lá?
- Todos os inputs externos são validados com Zod?

## 3. Verificação de Segurança
- Há dados sensíveis expostos em logs?
- Há endpoints sem verificação de autenticação?
- Há queries SQL construídas por concatenação de string?

## 4. Verificação de Testes
- Quais funções/métodos NÃO têm teste ainda?
- Os testes cobrem os edge cases mais críticos?

## 5. Identificação de TODOs
Liste qualquer TODO, FIXME ou comentário de "completar depois"
que ficou no código durante a implementação.

Para cada discrepância encontrada, corrija-a agora.

Execute o seguinte workflow de testes de forma autônoma:

## Fase 1: Análise de Cobertura
1. Execute `npm run test:coverage`
2. Identifique os 5 arquivos com menor cobertura de branches
3. Para cada arquivo, liste as funções sem cobertura adequada

## Fase 2: Geração de Testes
Para cada função identificada na Fase 1:
1. Analise o código da função e seus tipos
2. Gere testes que cubram:
   - Happy path com dados realistas
   - Todos os branches de if/switch
   - Error cases (null, undefined, valores inválidos)
   - Casos de borda numéricos
3. Salve os testes em `[arquivo].test.ts` seguindo o padrão do projeto

## Fase 3: Execução e Correção
1. Execute os testes gerados: `npm run test:watch -- --run`
2. Para cada teste que falhar:
   a. Analise o erro (problema no teste ou no código?)
   b. Se for bug no código: corrija o código E documente a correção
   c. Se for teste incorreto: corrija o teste
3. Itere até 100% dos testes passarem

## Fase 4: Relatório
Produza:
- Cobertura antes vs depois (%)
- Bugs encontrados pelos testes gerados (lista com arquivo:linha)
- Testes criados (quantidade e arquivos)
- Tempo estimado de execução do CI adicionado