# 🔐 Sistema de Credenciais Dinâmicas
## Gerenciamento Centralizado de Credenciais de Afiliados

> **📌 Documentação Oficial do Sistema de Credenciais**
> 
> Sistema centralizado para gerenciar credenciais de Amazon, Mercado Livre, Shopee e outros através da interface administrativa.

---

## 📋 Visão Geral

O sistema de credenciais dinâmicas permite gerenciar todas as credenciais de plataformas de afiliados através da interface administrativa, sem necessidade de editar arquivos `.env` ou código.

### ✨ Principais Recursos

- ✅ **Gerenciamento Visual**: Configure via interface web
- ✅ **Multi-Plataforma**: Suporte para Amazon, Mercado Livre, Shopee
- ✅ **Fallback Automático**: Mantém compatibilidade com `.env`
- ✅ **Segurança**: Credenciais armazenadas de forma segura no banco
- ✅ **Fácil Atualização**: Altere credenciais sem restartar o sistema
- ✅ **Escalável**: Adicione novas plataformas facilmente

---

## 🎯 Como Funciona

### Fluxo de Busca de Credenciais

```
1. Sistema tenta buscar credenciais no BANCO DE DADOS
   ↓
2. Se encontrar → Usa as credenciais do banco
   ↓
3. Se NÃO encontrar → Usa as credenciais do .env (fallback)
   ↓
4. Se NÃO encontrar em nenhum lugar → Retorna erro
```

### Prioridade de Carregamento

1. **Primeiro**: Configurações do banco de dados (tabela `settings`)
2. **Segundo**: Variáveis de ambiente (arquivo `.env`)
3. **Terceiro**: Valores padrão (se configurado)

---

## 🛠️ Plataformas Suportadas

### 1. Amazon PA-API 5.0 (✅ Implementado)

**Credenciais Necessárias:**
- `affiliates.amazon_access_key` - Access Key da PA-API
- `affiliates.amazon_secret_key` - Secret Key da PA-API
- `affiliates.amazon_partner_tag` - Store ID / Partner Tag
- `affiliates.amazon_host` - Host da API (ex: webservices.amazon.com.br)
- `affiliates.amazon_region` - Região AWS (sempre us-east-1)

**Como Configurar:**
```
1. Acesse: /admin/settings/affiliates
2. Preencha os campos da seção Amazon
3. Clique em Salvar
```

### 2. Mercado Livre (🚧 Em Preparação)

**Credenciais Necessárias:**
- `affiliates.mercadolivre_client_id` - Client ID da aplicação
- `affiliates.mercadolivre_client_secret` - Client Secret
- `affiliates.mercadolivre_access_token` - Access Token
- `affiliates.mercadolivre_refresh_token` - Refresh Token

**Status**: Campos criados, aguardando implementação do serviço

### 3. Shopee (🚧 Em Preparação)

**Credenciais Necessárias:**
- `affiliates.shopee_partner_id` - Partner ID
- `affiliates.shopee_partner_key` - Partner Key
- `affiliates.shopee_shop_id` - Shop ID

**Status**: Campos criados, aguardando implementação do serviço

---

## 📍 Acesso às Configurações

### Via Interface Web

**URL**: `/admin/settings/affiliates`

**Caminho Completo**:
```
Admin → Configurações → Credenciais de Afiliados
```

**Permissões Necessárias**:
- `settings.view` - Para visualizar
- `settings.edit` - Para editar (em desenvolvimento)

---

## 💾 Estrutura no Banco de Dados

### Tabela: `settings`

```sql
+-------------+------------------+
| Coluna      | Tipo             |
+-------------+------------------+
| id          | bigint unsigned  |
| key         | varchar(255)     |
| value       | text             |
| type        | varchar(50)      |
| description | text             |
| created_at  | timestamp        |
| updated_at  | timestamp        |
+-------------+------------------+
```

### Exemplo de Registros

```sql
-- Amazon
INSERT INTO settings (key, value, type, description) VALUES
('affiliates.amazon_access_key', 'AKPAPKZHOM...', 'password', 'Amazon PA-API 5.0 - Access Key'),
('affiliates.amazon_secret_key', 'kTeept1aja...', 'password', 'Amazon PA-API 5.0 - Secret Key'),
('affiliates.amazon_partner_tag', 'promogbbrasil-20', 'text', 'Amazon Associates - Store ID'),
('affiliates.amazon_host', 'webservices.amazon.com.br', 'text', 'Amazon PA-API - Host'),
('affiliates.amazon_region', 'us-east-1', 'text', 'Amazon PA-API - Região AWS');
```

---

## 🔧 Implementação Técnica

### 1. Modelo `Setting.php`

```php
// Buscar uma configuração
$accessKey = Setting::get('affiliates.amazon_access_key');

// Definir uma configuração
Setting::set('affiliates.amazon_access_key', 'NOVA_KEY');

// Buscar todas as configurações de um grupo
$affiliates = Setting::getByGroup('affiliates');
```

### 2. Service `AmazonAffiliateService.php`

```php
// Busca com fallback automático
$accessKey = Setting::get('affiliates.amazon_access_key') 
    ?: env('AMAZON_ACCESS_KEY');
```

### 3. Controller `SettingController.php`

Gerencia a interface de configurações e salva os dados no banco.

---

## 📝 Migrando do `.env` para o Banco

### Passo 1: Executar o Seeder

O seeder já migra automaticamente as credenciais do `.env` para o banco:

```bash
php artisan db:seed --class=SettingsSeeder
```

### Passo 2: Verificar no Admin

Acesse `/admin/settings/affiliates` e verifique se as credenciais foram importadas.

### Passo 3: Teste

Teste a funcionalidade Amazon Affiliate em `/admin/amazon-affiliate` para confirmar que está funcionando.

### Passo 4: (Opcional) Remover do `.env`

Depois de confirmar que está tudo funcionando, você pode opcionalmente remover as credenciais do `.env` (mantenha como backup se preferir).

---

## 🔒 Segurança

### Proteção de Credenciais

1. **Tipo `password`**: Campos sensíveis são marcados com tipo `password`
2. **Acesso Restrito**: Apenas administradores podem visualizar
3. **Nunca Commitar**: `.env` está no `.gitignore`
4. **Logs Seguros**: Credenciais não aparecem em logs
5. **HTTPS Recomendado**: Use sempre HTTPS em produção

### Boas Práticas

- ✅ Altere as credenciais periodicamente
- ✅ Não compartilhe credenciais entre ambientes
- ✅ Use credenciais diferentes para desenvolvimento/produção
- ✅ Revogue credenciais antigas após rotação
- ✅ Monitore uso de API para detectar anomalias

---

## 🚀 Adicionando Novas Plataformas

### Exemplo: Adicionar Credenciais da AliExpress

**1. Adicionar no modelo `Setting.php`:**

```php
// Credenciais de Afiliados - AliExpress
'affiliates.aliexpress_app_key' => [
    'type' => 'password', 
    'description' => 'AliExpress - App Key'
],
'affiliates.aliexpress_app_secret' => [
    'type' => 'password', 
    'description' => 'AliExpress - App Secret'
],
'affiliates.aliexpress_tracking_id' => [
    'type' => 'text', 
    'description' => 'AliExpress - Tracking ID'
],
```

**2. Usar no Service:**

```php
use App\Models\Setting;

class AliExpressAffiliateService
{
    public function __construct()
    {
        $this->appKey = Setting::get('affiliates.aliexpress_app_key') 
            ?: env('ALIEXPRESS_APP_KEY');
        $this->appSecret = Setting::get('affiliates.aliexpress_app_secret') 
            ?: env('ALIEXPRESS_APP_SECRET');
        $this->trackingId = Setting::get('affiliates.aliexpress_tracking_id') 
            ?: env('ALIEXPRESS_TRACKING_ID');
    }
}
```

**3. Pronto!** A interface será atualizada automaticamente.

---

## 🧪 Testes

### Testar Carregamento de Credenciais

```php
// No Tinker ou em um Controller de teste
php artisan tinker

>>> Setting::get('affiliates.amazon_access_key')
=> "AKPAPKZHOM1760125907"

>>> Setting::get('affiliates.amazon_partner_tag')
=> "promogbbrasil-20"
```

### Testar Fallback para .env

```php
// Se não houver no banco, deve retornar do .env
>>> Setting::get('affiliates.amazon_access_key') ?: env('AMAZON_ACCESS_KEY')
```

---

## 📊 Monitoramento

### Verificar Credenciais Configuradas

```sql
SELECT key, type, description, 
       CASE 
           WHEN value IS NOT NULL AND value != '' THEN '✅ Configurado'
           ELSE '❌ Não Configurado'
       END as status
FROM settings
WHERE key LIKE 'affiliates.%'
ORDER BY key;
```

### Auditoria de Alterações

As tabelas `settings` têm `created_at` e `updated_at` para rastrear quando foram alteradas.

---

## ❓ Perguntas Frequentes

### 1. Preciso remover as credenciais do `.env`?

Não é obrigatório. O sistema funciona com ambos. Recomendamos manter no `.env` como backup durante a transição.

### 2. Como adicionar uma nova plataforma?

Adicione as chaves no array `DEFAULTS` do modelo `Setting.php` e use `Setting::get()` no seu service.

### 3. As credenciais são criptografadas no banco?

Atualmente são armazenadas em texto. Para adicionar criptografia, você pode usar os mutators do Laravel no modelo Setting.

### 4. Posso ter credenciais diferentes por ambiente?

Sim! Cada ambiente (dev/prod) tem seu próprio banco de dados com suas próprias configurações.

### 5. O que acontece se eu alterar uma credencial?

A mudança é instantânea. Na próxima requisição, o sistema usará a nova credencial.

---

## 🔄 Roadmap

### Versão Atual (v1.0)
- ✅ Suporte a Amazon PA-API
- ✅ Interface administrativa
- ✅ Fallback para .env
- ✅ Preparação para Mercado Livre
- ✅ Preparação para Shopee

### Próximas Versões
- 🚧 v1.1: Implementar serviço Mercado Livre
- 🚧 v1.2: Implementar serviço Shopee
- 🚧 v1.3: Criptografia de credenciais no banco
- 🚧 v1.4: Histórico de alterações com auditoria
- 🚧 v1.5: Testes de conexão das credenciais
- 🚧 v1.6: Alertas de credenciais expiradas

---

## 📞 Suporte

Para dúvidas ou problemas:
1. Consulte a documentação em `docs/`
2. Verifique os logs em `storage/logs/laravel.log`
3. Execute `php artisan config:clear` se houver cache

---

**Versão**: 1.0  
**Data**: Outubro 2025  
**Status**: ✅ Funcional e em Produção