# Módulo Gestor-Y - Documentação Técnica

## Instalação

### 1. Instalação Básica (cURL)

O módulo funciona por padrão com cURL, sem dependências adicionais.

### 2. Instalação Puppeteer (Recomendado para JavaScript dinâmico)

```bash
cd scripts
npm install
```

**Requisitos:**
- Node.js 16+ instalado
- NPM ou Yarn

### 3. Instalação Selenium (Alternativa)

```bash
pip3 install selenium
```

**Requisitos:**
- Python 3.7+
- ChromeDriver instalado e no PATH

### 4. Configuração do Cron

Adicione ao crontab:

```bash
# Executar a cada 6 horas
0 */6 * * * /usr/bin/php /caminho/para/scripts/gestory-cron.php >> /var/log/gestory-cron.log 2>&1
```

## Estrutura de Arquivos

```
modules/GestorY/
├── Module.php                          # Registro do módulo
├── Controllers/
│   ├── GestorYController.php         # API endpoints
│   └── GestorYViewsController.php    # Views HTML
├── Services/
│   ├── YamahaScraperService.php       # Scraping com cURL
│   ├── BrowserScraperService.php      # Scraping com Puppeteer/Selenium
│   ├── ProdutoIntegrationService.php # Integração com produtos
│   ├── UpdateSchedulerService.php    # Atualização automática
│   ├── NotificationService.php       # Sistema de notificações
│   └── ApiMigrationService.php        # Migração para API oficial
├── migrations/
│   ├── initial.sql                    # Tabelas principais
│   ├── 001_permissions_mysql.sql     # Permissões RBAC
│   └── 002_notificacoes_mysql.sql    # Notificações e campos avançados
└── views/gestory/
    ├── index.php                      # Dashboard
    ├── pesquisa.php                   # Pesquisa de peças
    ├── config.php                     # Configurações
    └── logs.php                       # Logs

scripts/
├── gestory-cron.php                   # Script para cron job
├── puppeteer-scraper.js              # Script Puppeteer
├── selenium-scraper.py               # Script Selenium
└── package.json                       # Dependências Node.js
```

## API Endpoints

### Pesquisa
- `GET /api/gestor-y/pesquisar?termo=X&modelo=Y&ano=Z` - Pesquisa peças
- `GET /api/gestor-y/peca/{codigo}` - Detalhes de uma peça

### Importação
- `POST /api/gestor-y/importar` - Importa uma peça
- `POST /api/gestor-y/importar-lote` - Importa múltiplas peças

### Configuração
- `GET /api/gestor-y/config` - Obtém configuração
- `PUT /api/gestor-y/config` - Atualiza configuração

### Atualização
- `POST /api/gestor-y/atualizar` - Executa atualização manual

### Notificações
- `GET /api/gestor-y/notificacoes` - Lista notificações
- `POST /api/gestor-y/notificacoes/{id}/ler` - Marca como lida

### API Oficial
- `POST /api/gestor-y/api/config` - Configura API oficial
- `POST /api/gestor-y/api/migrar` - Migra para API oficial

### Logs
- `GET /api/gestor-y/logs` - Lista logs

### Estatísticas
- `GET /api/gestor-y/stats` - Estatísticas do módulo

## Fluxo de Funcionamento

1. **Pesquisa:**
   - Usuário pesquisa peça
   - Sistema verifica cache
   - Se não em cache, faz scraping (cURL/Puppeteer/Selenium)
   - Retorna resultados
   - Salva no cache

2. **Importação:**
   - Usuário seleciona peça para importar
   - Sistema salva peça em `gestory_pecas`
   - Cria produto no ERP
   - Vincula peça ao produto

3. **Atualização Automática:**
   - Cron executa script
   - Verifica se precisa atualizar
   - Pesquisa modelos configurados
   - Atualiza peças existentes
   - Cria novas peças
   - Notifica sobre conclusão

## Troubleshooting

### Erro: "Node.js não está disponível"
- Instale Node.js: `apt-get install nodejs` (Linux) ou baixe de nodejs.org
- Verifique caminho em configurações

### Erro: "Puppeteer não encontrado"
- Execute: `cd scripts && npm install`

### Erro: "ChromeDriver não encontrado"
- Instale ChromeDriver: `apt-get install chromium-chromedriver`
- Ou baixe de: https://chromedriver.chromium.org/

### Nenhum resultado na pesquisa
- Verifique se o site Yamaha mudou estrutura
- Tente usar Puppeteer em vez de cURL
- Verifique logs em `/gestor-y/logs`

## Segurança

- Respeite limites de requisições
- Use User-Agent apropriado
- Implemente delays entre requisições
- Monitore logs para detectar problemas

## Licença e Uso

⚠️ **AVISO LEGAL:** Este módulo utiliza web scraping. Certifique-se de:
- Respeitar termos de uso do site Yamaha
- Usar de forma ética e responsável
- Preferir APIs oficiais quando disponíveis
- O uso é de responsabilidade do usuário

