Desenvolvimento de Software com IA

# Arquitetura do Projeto

## Stack Tecnológico
- Runtime: Node.js 20 LTS + TypeScript 5.x
- Framework: Fastify v4 (NÃO Express — já decidido e documentado em ADR-001)
- ORM: Prisma com PostgreSQL 15
- Cache: Redis 7 via ioredis
- Fila: BullMQ para jobs assíncronos
- Testes: Vitest + Supertest

## Padrões de Código
- Arquitetura: Feature-based modules (não layers)
- Nomenclatura: camelCase para variáveis, PascalCase para tipos/classes
- Erro handling: Result pattern (never throw, return { data, error })
- Logs: Pino com structured logging, sempre incluir requestId

## Estrutura de Pastas
src/
├── features/          # Módulos por domínio de negócio
│   ├── users/
│   │   ├── users.service.ts
│   │   ├── users.repository.ts
│   │   ├── users.routes.ts
│   │   └── users.schema.ts
├── shared/            # Utilitários compartilhados
├── infra/             # Config, DB, cache, queues
└── types/             # Types globais

## Restrições Importantes
- NUNCA usar `any` em TypeScript
- Toda query ao banco deve passar pelo repository
- Autenticação via JWT — tokens de 15min + refresh 7d
- Rate limiting obrigatório em endpoints públicos

# Cursor Rules — Sistema de Gestão Financeira (FinanceOS)

## Identidade
Você é um desenvolvedor TypeScript senior especializado em sistemas financeiros.
Seu código é seguro, tipado, testável e segue os padrões estabelecidos.

## Stack Tecnológico
- TypeScript 5.4 (strict mode SEMPRE ativado)
- Node.js 20 LTS + Fastify v4
- Prisma 5 + PostgreSQL 15
- Vitest para testes unitários e de integração
- Zod para validação de schemas

## Padrões de Código Obrigatórios

### Nomenclatura
- Funções: camelCase, verbos descritivos (getUserById, calculateTax)
- Interfaces: PascalCase, prefixo 'I' NÃO usado (User, não IUser)
- Types: PascalCase (UserCreateInput, not CreateUserDTO)
- Enums: PascalCase com valores SCREAMING_SNAKE (UserRole.ADMIN)
- Arquivos: kebab-case (user-service.ts, not userService.ts)

### Error Handling (CRÍTICO)
NUNCA use try-catch direto. Use o Result pattern:

```typescript
type Result = { data: T; error: null } | { data: null; error: E };

// Correto:
async function getUser(id: string): Promise> {
  try {
    const user = await prisma.user.findUnique({ where: { id } });
    if (!user) return { data: null, error: new Error('User not found') };
    return { data: user, error: null };
  } catch (err) {
    return { data: null, error: err as Error };
  }
}
```

### Validação de Input
Sempre use Zod para validação. Nunca confie em dados externos:

```typescript
const CreateUserSchema = z.object({
  name: z.string().min(2).max(100),
  email: z.string().email(),
  role: z.nativeEnum(UserRole).default(UserRole.USER),
});
```

### Logging
Use structured logging com Pino. Sempre inclua requestId:

```typescript
logger.info({ requestId, userId, action: 'user.created' }, 'User created successfully');
```

## Regras de Comportamento

### O que fazer:
- Sempre inferir tipos explicitamente quando não é óbvio
- Incluir comentários JSDoc para funções públicas
- Criar testes para toda lógica de negócio
- Seguir o padrão Repository para acesso a dados

### O que NÃO fazer:
- NUNCA usar `any` — use `unknown` se necessário
- NUNCA fazer refactoring de código não relacionado à tarefa
- NUNCA adicionar dependências novas sem perguntar
- NUNCA expor dados sensíveis (senha, token) em logs ou respostas
- NUNCA usar `console.log` — use o logger Pino

## Contexto do Negócio
FinanceOS é um sistema de gestão financeira para PMEs brasileiras.
Opera com entidades: Company, User, Transaction, Account, Category.
Compliance: LGPD (dados pessoais devem ser tratados com cuidado).
Moeda padrão: BRL. Fuso horário: America/Sao_Paulo.

Gere testes unitários completos para a seguinte função/classe usando Vitest.

**Código a testar:**
```typescript
[COLE O CÓDIGO AQUI]
```

**Requisitos para os testes:**

1. **Happy path:** Teste todos os fluxos de sucesso com dados válidos realistas.

2. **Edge cases obrigatórios:**
   - Valores null e undefined para cada parâmetro
   - Strings vazias e strings com apenas espaços
   - Arrays/objetos vazios
   - Valores nos limites (0, -1, MAX_INT para números)
   - Caracteres especiais e Unicode em strings

3. **Error cases:**
   - Cada condição de erro documentada no código
   - Erros de rede/IO mockados (se aplicável)
   - Timeout e comportamento assíncrono

4. **Estrutura dos testes:**
   - Use describe/it aninhados para organização
   - Nomes descritivos: "should return null when user not found"
   - Setup com beforeEach para dados compartilhados
   - Mocks isolados por teste (vi.clearAllMocks no afterEach)

5. **Cobertura esperada:** >= 90% de branches e statements

**Framework:** Vitest + @testing-library (se UI) ou supertest (se API)
**Evite:** Testes que testam implementação interna; teste comportamento externo.

import { describe, it, expect, beforeEach, vi } from 'vitest';
import { calculateDiscount } from './pricing.service';

describe('calculateDiscount', () => {
  describe('Happy path', () => {
    it('should apply percentage discount correctly', () => {
      expect(calculateDiscount(100, { type: 'percentage', value: 10 })).toBe(90);
    });

    it('should apply fixed discount correctly', () => {
      expect(calculateDiscount(100, { type: 'fixed', value: 15 })).toBe(85);
    });

    it('should handle decimal prices', () => {
      expect(calculateDiscount(99.99, { type: 'percentage', value: 5 }))
        .toBeCloseTo(94.99, 2);
    });
  });

  describe('Edge cases', () => {
    it('should return 0 when discount >= price (fixed)', () => {
      expect(calculateDiscount(50, { type: 'fixed', value: 50 })).toBe(0);
      expect(calculateDiscount(50, { type: 'fixed', value: 100 })).toBe(0);
    });

    it('should return 0 when 100% percentage discount', () => {
      expect(calculateDiscount(200, { type: 'percentage', value: 100 })).toBe(0);
    });

    it('should not allow negative result', () => {
      const result = calculateDiscount(10, { type: 'fixed', value: 999 });
      expect(result).toBeGreaterThanOrEqual(0);
    });
  });

  describe('Error cases', () => {
    it('should throw for negative price', () => {
      expect(() => calculateDiscount(-10, { type: 'fixed', value: 5 }))
        .toThrow('Price must be positive');
    });

    it('should throw for negative discount value', () => {
      expect(() => calculateDiscount(100, { type: 'percentage', value: -10 }))
        .toThrow('Discount value must be positive');
    });

    it('should throw for percentage > 100', () => {
      expect(() => calculateDiscount(100, { type: 'percentage', value: 101 }))
        .toThrow('Percentage discount cannot exceed 100%');
    });

    it('should throw for unknown discount type', () => {
      expect(() => calculateDiscount(100, { type: 'unknown' as any, value: 10 }))
        .toThrow('Unknown discount type');
    });
  });
});

name: CI/CD Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

env:
  NODE_VERSION: '20'
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  quality:
    name: Code Quality
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - name: TypeScript Check
        run: npx tsc --noEmit
      - name: Lint
        run: npm run lint
      - name: Format Check
        run: npm run format:check

  test:
    name: Tests
    runs-on: ubuntu-latest
    needs: quality
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: test
          POSTGRES_DB: testdb
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - name: Run Database Migrations
        run: npx prisma migrate deploy
        env:
          DATABASE_URL: postgresql://postgres:test@localhost:5432/testdb
      - name: Run Tests with Coverage
        run: npm run test:coverage
        env:
          DATABASE_URL: postgresql://postgres:test@localhost:5432/testdb
      - name: Upload Coverage
        uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          fail_ci_if_error: true

  security:
    name: Security Scan
    runs-on: ubuntu-latest
    needs: quality
    steps:
      - uses: actions/checkout@v4
      - run: npm audit --audit-level=high
      - name: SAST Scan
        uses: github/codeql-action/analyze@v3
        with:
          languages: javascript-typescript

  deploy:
    name: Deploy to Production
    runs-on: ubuntu-latest
    needs: [test, security]
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    steps:
      - uses: actions/checkout@v4
      - name: Build and Push Docker Image
        uses: docker/build-push-action@v5
        with:
          push: true
          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest

{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--network", "host",
        "mcp/postgres",
        "postgresql://localhost:5432/mydb"
      ]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y", "@modelcontextprotocol/server-filesystem",
        "/Users/dev/projects/my-app/src"
      ]
    },
    "github": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "mcp/github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Realize uma revisão de segurança do seguinte código com foco nas vulnerabilidades do OWASP Top 10.

**Código:**
```
[COLE O CÓDIGO]
```

**Contexto:**
- Stack: [Node.js/Python/etc.]
- Tipo: [API REST / Web App / CLI / etc.]
- Dados sensíveis processados: [descreva]
- Autenticação: [JWT / OAuth / Session / etc.]

**Checklist de verificação:**

1. **A01 - Broken Access Control**
   - Verificação de autorização em cada endpoint
   - Prevenção de escalação de privilégios
   - Referências diretas a objetos (IDOR)

2. **A02 - Cryptographic Failures**
   - Dados sensíveis em trânsito (HTTPS)
   - Armazenamento seguro de senhas (bcrypt/argon2)
   - Chaves/secrets hardcoded

3. **A03 - Injection**
   - SQL injection (queries parametrizadas?)
   - Command injection (exec, eval?)
   - XSS (sanitização de output?)

4. **A05 - Security Misconfiguration**
   - Headers de segurança (CORS, CSP, HSTS)
   - Error messages que expõem detalhes internos
   - Dependências desatualizadas

5. **A07 - Authentication Failures**
   - Rate limiting em login
   - Validação de tokens JWT
   - Timeout de sessão

Para cada vulnerabilidade encontrada:
- Localização exata no código
- CVSS Score estimado
- Prova de conceito de exploração
- Remediação com código corrigido