---
description: Workflow completo para criar nova feature
---

# Workflow: Criar Nova Feature

Processo completo para desenvolver uma nova funcionalidade seguindo padrões do projeto.

---

## Pré-requisitos

1. Identificar o **ambiente** (rh, financeiro-v2, prafrota, etc)
2. Definir nome da feature
3. Listar componentes/hooks/services necessários

---

## Etapas

### 1. Análise de Reutilização

**Antes de criar qualquer código**, verificar o que já existe:

```bash
# Buscar componentes similares
node .agent/scripts/check-reuse.js [termo-relacionado]
```

**Pergunte**:
- Posso reutilizar componentes existentes?
- Posso estender hooks atuais?
- Services similares já existem?

---

### 2. Criar Service (se necessário)

```bash
node .agent/scripts/create-service.js [nomeService] [ambiente]
```

**Ajustar**:
1. Endpoints da API
2. Mapeamento de dados (adapters)
3. Tratamento de erros

---

### 3. Criar Hook (se necessário)

```bash
node .agent/scripts/create-hook.js use[NomeHook] [ambiente]
```

**Implementar**:
1. Lógica de negócio
2. Integração com service
3. Estados (loading, error, data)

---

### 4. Criar Componentes

```bash
# Para cada componente necessário
node .agent/scripts/create-component.js [NomeComponente] [ambiente]
```

**Ordem recomendada**:
1. Componentes básicos (Cards, Forms)
2. Componentes compostos (que usam os básicos)
3. View principal

---

### 5. Testar no Playground

**OBRIGATÓRIO antes de usar em produção**:

1. Cadastrar componentes em `PlaygroundView.jsx`
2. Adicionar variantes Dev com controles
3. Testar estados: loading, error, success
4. Validar responsividade

---

### 6. Criar View

**Estrutura**:
```
src/features/[ambiente]/views/
└── [FeatureName]View.jsx
```

**Implementar**:
1. Importar componentes do Playground
2. Usar hooks criados
3. Layout e estrutura
4. Validar isolamento (não importar de outros ambientes)

---

### 7. Validação

// turbo-all

```bash
# Build sem erros
npm run dev

# Verificar console (sem warnings)
# Abrir no navegador: http://localhost:5173

# Testar fluxos:
# - Happy path (uso normal)
# - Error path (API offline, campos vazios)
```

---

### 8. Documentação

Atualizar documentação relevante:
- README do ambiente (se houver)
- Comentários JSDoc nos arquivos
- Adicionar exemplos no Playground

---

## Checklist Final

- [ ] Reutilização verificada com `check-reuse.js`
- [ ] Service criado e testado
- [ ] Hook implementado com error handling
- [ ] Componentes < 150 linhas cada
- [ ] Todos os componentes testados no Playground
- [ ] View usando apenas componentes validados
- [ ] Build roda sem erros
- [ ] Sem warnings no console
- [ ] Responsividade validada
- [ ] Documentação atualizada

---

## Exemplo Completo: Feature "Folha de Pagamento"

```bash
# 1. Verificar reutilização
node .agent/scripts/check-reuse.js payroll

# 2. Criar service
node .agent/scripts/create-service.js payrollService rh

# 3. Criar hook
node .agent/scripts/create-hook.js usePayroll rh

# 4. Criar componentes
node .agent/scripts/create-component.js PayrollCard rh
node .agent/scripts/create-component.js PayrollForm rh
node .agent/scripts/create-component.js PayrollTable rh

# 5. Cadastrar no Playground e testar

# 6. Criar view: src/features/rh/views/PayrollView.jsx

# 7. Validar
npm run dev
```

---

**IMPORTANTE**: Nunca pular a etapa de Playground! Todo componente deve ser validado antes de usar em produção.