care-api/.cursor/README.md

# 🏗️ Cursor AI Integration - StackWorkflow v2.2

Sistema completo de auditoria de qualidade de código integrado com Cursor AI.

## 📁 Estrutura Criada

```
.cursor/
├── CURSOR.md           # Contexto persistente + regras de qualidade
├── .cursor-context     # Ficheiros/pastas excluídos da análise
├── keymap.json        # Comandos personalizados com atalhos
└── README.md          # Este ficheiro de instruções
```

## 🚀 Como Usar

### 1. Configuração Inicial (Automática via `/iniciar`)

A estrutura é criada automaticamente quando usar o comando `/iniciar` do StackWorkflow.

### 2. Importar Comandos Personalizados

**Opção A: Manual**
1. Abrir Cursor
2. `Ctrl+Shift+P` → "Open Keyboard Shortcuts (JSON)"
3. Copiar conteúdo de `keymap.json` para o seu ficheiro pessoal

**Opção B: Merge Automático** (Recomendado)
```bash
# Fazer backup do keymap existente
cp ~/.config/Cursor/User/keybindings.json ~/.config/Cursor/User/keybindings.backup.json

# Merge dos comandos (preserva configurações existentes)
jq -s '.[0] + .[1]' ~/.config/Cursor/User/keybindings.json .cursor/keymap.json > temp.json
mv temp.json ~/.config/Cursor/User/keybindings.json
```

### 3. Comandos Disponíveis

| Atalho | Comando | Descrição |
|--------|---------|-----------|
| `Ctrl+Alt+A` | **Auditoria Completa** | Análise sistemática do projeto completo |
| `Ctrl+Alt+R` | **Refactoring** | Refactoring do código selecionado |
| `Ctrl+Alt+D` | **Documentação** | Gerar documentação automática |
| `Ctrl+Alt+T` | **Testes** | Criar testes para código selecionado |
| `Ctrl+Alt+P` | **Performance** | Análise de performance e otimizações |
| `Ctrl+Alt+S` | **Code Review** | Review detalhado do código |

## 📋 Workflow Recomendado

### Auditoria Completa de Projeto
```bash
1. Abrir projeto no Cursor
2. Pressionar Ctrl+Alt+A
3. Aguardar análise automática
4. Relatório salvo em reports/cursor-audit-[timestamp].md
5. Implementar top 5 melhorias sugeridas
```

### Refactoring Incremental
```bash
1. Selecionar função/classe problemática
2. Pressionar Ctrl+Alt+R
3. Review da sugestão de refactoring
4. Aplicar mudanças se apropriadas
5. Executar testes para validar
```

### Documentação Automática
```bash
1. Selecionar função não documentada
2. Pressionar Ctrl+Alt+D
3. JSDoc/PHPDoc gerado automaticamente
4. Review e ajustes se necessário
```

## 🎯 Contexto Persistente (CURSOR.md)

O ficheiro `CURSOR.md` é **automaticamente carregado** pelo Cursor em todas as interações. Define:

- **Regras de qualidade** específicas do projeto
- **Padrões de código** a seguir
- **Métricas de avaliação**
- **Permissões automáticas** para análise
- **Formato de relatórios**

## 🔐 Controlo de Acesso (.cursor-context)

O ficheiro `.cursor-context` **exclui automaticamente**:
- `node_modules/`, `vendor/`, `.git/`
- Ficheiros de configuração sensíveis
- Logs e temporários
- Builds e caches
- **reports/** (evita recursão)

## 📊 Sistema de Scoring

### Métricas Tracked
- **Complexidade Ciclomática**: ≤ 10 por função
- **Tamanho de Funções**: ≤ 50 linhas
- **Duplicação de Código**: ≤ 3%
- **Cobertura de Testes**: ≥ 70%
- **Documentação**: ≥ 80% funções públicas

### Score Final
- **🟢 90-100**: Excelente qualidade
- **🟡 70-89**: Boa qualidade
- **🟠 50-69**: Precisa melhorias
- **🔴 0-49**: Refactoring crítico necessário

## 🔄 Integração com StackWorkflow

### Fluxo Completo
```mermaid
graph TD
    A[/iniciar] --> B[Estrutura .cursor/ criada]
    B --> C[Desenvolvimento no Cursor]
    C --> D[Ctrl+Alt+A - Auditoria]
    D --> E[reports/cursor-audit-*.md]
    E --> F[/avaliar StackWorkflow]
    F --> G[Master Orchestrator lê relatórios]
    G --> H[Implementa correções automaticamente]
    H --> I[Código melhorado]
    I --> C
```

### Comandos StackWorkflow
- **`/avaliar`**: Lê relatórios do Cursor e implementa correções
- **`/plan`**: Integra qualidade de código no planeamento
- **`/tasks`**: Cria tarefas baseadas em code smells identificados

## ⚡ Tips de Produtividade

### Para Máxima Eficiência
1. **Use `@folder:src`** para análise completa de pastas
2. **Combine comandos**: Auditoria → Refactoring → Testes → Documentação
3. **Review relatórios**: Sempre verificar `reports/` antes de commits
4. **Iterativo**: Pequenas melhorias constantes > refactoring massivo

### Debugging de Comandos
```bash
# Se comandos não funcionarem:
1. Verificar se keymap.json foi importado corretamente
2. Reiniciar Cursor após importar comandos
3. Verificar se CURSOR.md existe no diretório raiz
4. Confirmar que .cursor-context não está excluindo ficheiros necessários
```

## 🎯 Objetivos do Sistema

1. **Qualidade Automatizada**: Zero intervention code quality
2. **Performance Otimizada**: Automatic bottleneck detection
3. **Maintainability**: Self-documenting, testable code
4. **Developer Experience**: Seamless workflow integration
5. **Continuous Improvement**: Metrics-driven development

---
**Powered by**: Cursor AI + StackWorkflow v2.2 Adversarial System
**Suporte**: Documentação completa em `reports/README.md`