# Etapa 1 - Leitura bruta de canais/grupos Telegram

## Status

- Situacao: **Concluido**
- Objetivo da etapa: capturar URLs brutas de grupos/canais Telegram para validacao operacional.
- Escopo atual: cadastro de fontes, leitura de mensagens, extracao de URLs, classificacao basica por plataforma e exibicao em tela.

---

## Objetivo

Permitir que o usuario informe canais/grupos do Telegram para monitoramento e capturar URLs publicadas nas mensagens, sem processamento avancado de afiliado nesta etapa.

---

## Escopo da Etapa 1

Inclui:

1. Cadastro de fontes Telegram (canais/grupos).
2. Leitura de novas mensagens dessas fontes.
3. Extracao de URLs de cada mensagem.
4. Classificacao inicial de plataforma por dominio (Mercado Livre, Amazon, Shopee, outros).
5. Exibicao em tela para validacao operacional.

Nao inclui (fases futuras):

- Conversao para link de afiliado.
- Scraping avancado por plataforma (exceto testes pontuais).
- Deduplicacao final por produto.
- Repost automatico.

---

## Regras de negocio

- O sistema monitora somente fontes Telegram cadastradas e ativas.
- Cada mensagem lida pode gerar zero, uma ou varias URLs.
- Cada URL capturada deve manter vinculo com:
  - fonte (canal/grupo),
  - mensagem original,
  - data/hora de captura.
- A classificacao por plataforma nesta etapa e apenas por dominio da URL:
  - `mercadolivre.com` / `mercadolibre.com` -> `mercadolivre`
  - `amazon.` / `amzn.to` / `a.co` -> `amazon`
  - `shopee.` -> `shopee`
  - demais -> `outros`

---

## Dados minimos a registrar

### Fonte Telegram

- Nome da fonte
- Link/identificador da fonte
- Status (ativo/inativo)
- Ultimo checkpoint de leitura (ex.: `last_message_id`)

### URL capturada

- URL original
- Plataforma detectada
- Fonte de origem
- `chat_id`
- `message_id`
- Data/hora da mensagem
- Data/hora da captura
- Texto original (opcional, util para auditoria)

---

## Fluxo funcional

1. Usuario cadastra canais/grupos Telegram.
2. Leitor Telegram busca novas mensagens a partir do checkpoint.
3. Sistema extrai URLs da mensagem.
4. Sistema classifica cada URL por dominio.
5. Sistema salva os registros capturados.
6. Tela de monitoramento exibe os itens para validacao manual.

---

## Tela de validacao (monitor)

A tela deve mostrar, no minimo:

- Horario
- Fonte (grupo/canal)
- URL original
- Plataforma detectada
- Status (capturado)

Filtros recomendados:

- Periodo
- Fonte
- Plataforma
- Texto livre por URL

---

## Criterios de aceite da Etapa 1

- E possivel cadastrar/ativar/desativar fontes Telegram.
- O sistema le mensagens novas sem reler mensagens antigas ja processadas.
- URLs sao extraidas e exibidas em tela com os metadados minimos.
- A classificacao basica de plataforma funciona para ML, Amazon e Shopee.
- Logs permitem rastrear falhas por fonte.

---

## Riscos e observacoes

- Bot API nao atende leitura ampla de canais por link; leitura deve usar API de cliente (MTProto).
- Erros de rede ou limitacao temporaria devem gerar retry com backoff.
- Esta etapa ainda nao elimina duplicados de produto; foco e captura e visibilidade do pipeline.

---

## Checklist tecnico inicial

- [x] Comando `telegram:test-login` criado e validado.
- [x] Autenticacao via numero de telefone + 2FA funcionando.
- [x] Sessao persistida em `storage/app/telegram/session.madeline`.
- [x] Comando `telegram:read-links` criado e validado.
- [x] Modo avulso para testes: `--channel=` sem banco.
- [x] Modo normal: le todas as fontes ativas do banco com checkpoint.
- [x] Extracao de URLs via entities Telegram (UTF-16 corrigido).
- [x] Extracao de URLs de legendas de midia (caption).
- [x] Extracao de URLs de botoes inline (reply_markup).
- [x] Classificacao por plataforma: Mercado Livre, Amazon, Shopee, Outros.
- [x] `meli.la` reconhecido como encurtador oficial do Mercado Livre.
- [x] Logs da biblioteca redirecionados para `storage/logs/madeline.log`.
- [x] Terminal limpo com saida apenas dos dados relevantes.
- [x] Checkpoint por fonte (`last_message_id`) no banco — so le mensagens pendentes.
- [x] Cadastro de fontes via `telegram:source-add`.
- [x] Limpeza automatica por quantidade via `telegram:prune`.
- [x] Schedule configurado no Kernel (leitura + prune diario).

## Estrutura de banco criada

- `telegram_sources` — fontes monitoradas com checkpoint e limite configuravel
- `captured_urls` — log de URLs brutas capturadas por mensagem
- `processed_offers` — deduplicacao por MLB/produto (chave SHA1 unica)

## Variaveis de ambiente

| Variavel | Padrao | Descricao |
|---|---|---|
| `TELEGRAM_READ_LIMIT` | 100 | Mensagens por leitura por canal |
| `TELEGRAM_CRON_FREQUENCY` | `*/15 * * * *` | Frequencia do Cron |
| `TELEGRAM_PRUNE_KEEP_URLS` | 500 | Registros mantidos em captured_urls |
| `TELEGRAM_PRUNE_KEEP_OFFERS` | 500 | Registros mantidos em processed_offers |

## Comandos disponiveis

| Comando | Descricao |
|---|---|
| `telegram:test-login` | Testa autenticacao da sessao |
| `telegram:source-add {channel} {name}` | Cadastra nova fonte |
| `telegram:read-links` | Le mensagens pendentes de todas as fontes |
| `telegram:read-links --channel=URL` | Teste avulso sem banco |
| `telegram:prune` | Limpeza de registros antigos |
| `telegram:prune --dry-run` | Simula limpeza sem apagar |
| `telegram:resolve-ml {url}` | Resolve URL ML e extrai MLB |
| `telegram:process-ml {url}` | Processa ML completo e gera texto formatado |
| `telegram:process-pending` | Processa todas as URLs pendentes do banco (scraping + texto) |
| `telegram:scrape-debug {url}` | Diagnostica extracao de preco de uma URL ML |

---

## Execucao inicial da etapa

Implementacao inicial concluida para iniciar a integracao Telegram:

- Arquivo de configuracao criado: `config/telegram.php`
- Comando de teste de autenticacao criado: `php artisan telegram:test-login`
- Variaveis adicionadas no `.env.example`:
  - `TELEGRAM_API_ID`
  - `TELEGRAM_API_HASH`
  - `TELEGRAM_PHONE`
  - `TELEGRAM_SESSION_PATH`
  - `TELEGRAM_SUPPRESS_WINDOWS_PERFORMANCE_WARNING`

Objetivo deste comando: validar credenciais e criar/reutilizar a sessao local antes da leitura de links dos grupos.

---

## Proxima etapa (Etapa 2)

Para URLs Mercado Livre de perfil social (`/social/{nome}`):

1. Resolver/scrapar a pagina.
2. Encontrar URL do produto (ex.: botao "Ir para produto").
3. Extrair `MLB`.
4. Exibir resultado intermediario para validacao.