Web Scraper Produtos Farmacêuticos

# Escopo Técnico — Correção e Evolução do Scraper de Preços Mecofarma e AppySaúde

## 1. Objetivo

Desenvolver, corrigir e estabilizar um sistema de scraping de produtos e preços dos sites Mecofarma e AppySaúde, com foco em:

1. Coletar produtos, preços, disponibilidade, fornecedor/farmácia, categoria, marca e link.
2. Manter o scraper Mecofarma funcional, apenas com ajustes preventivos.
3. Corrigir o scraper AppySaúde, atualmente com erro provável por alteração da API/site.
4. Gerar arquivos Excel/CSV padronizados para comparação de preços, análise de concorrência e sugestão de preços.
5. Criar logs, diagnósticos e mecanismos de contingência para futuras alterações dos sites.

## 2. Situação Atual

### 2.1 Mecofarma

O módulo Mecofarma está funcional e deve ser preservado. A coleta utiliza endpoint AJAX:

`https://www.mecofarma.com/pt/search/ajax/suggest/?q={codigo}`

O scraper deve continuar validando o produto por CNP/SKU, evitando aceitar produtos errados por redirecionamento do Magento.

### 2.2 AppySaúde

O módulo AppySaúde apresenta erro. A causa provável é alteração estrutural no site/API.

O script atual já indica que a API antiga:

`https://www.appysaude.co.ao/v1.0/products/productList`

deixou de funcionar corretamente e foi substituída por:

`https://api.appysaude.co.ao/v2.0/products`

A nova estrutura usa paginação por `pageNumber` e os preços não ficam mais num campo simples `Price`; os preços estão dentro de listas de ofertas, como `offers[]`, cada uma associada a uma farmácia/fornecedor.

Além disso, a AppySaúde parece exigir autenticação via Azure B2C/MSAL, podendo exigir obtenção de token Bearer válido pelo browser com Playwright.

## 3. Requisitos Funcionais

### 3.1 Scraper Mecofarma

Manter as funcionalidades existentes:

* Buscar produto por código/CNP/SKU.
* Extrair:

* data da coleta;
* concorrente;
* código pesquisado;
* nome do produto;
* preço;
* disponibilidade;
* CNP;
* referência;
* categoria;
* marca;
* imagem;
* link do produto;
* método de extração;
* status HTTP;
* erro, se houver.
* Validar se o produto retornado corresponde ao código pesquisado.
* Evitar duplicatas e falsos positivos.
* Manter aba Raw para auditoria.
* Gerar aba apenas com produtos disponíveis para uso na análise de pricing.

### 3.2 Scraper AppySaúde

Corrigir e estabilizar a coleta da AppySaúde.

O programador deve:

1. Validar a API atual usada pelo frontend da AppySaúde.
2. Confirmar endpoint, parâmetros, paginação e necessidade de autenticação.
3. Implementar coleta via API v2.0:

* `pageNumber`;
* `pageSize`;
* `onlyData=true`;
* `expand=all`;
* filtros de produtos aprovados, ativos e com farmácias associadas.
4. Implementar autenticação via Playwright quando necessário:

* abrir o site;
* realizar login;
* obter token via MSAL/acquireTokenSilent ou interceptação de requisições;
* guardar token temporariamente em cache;
* renovar token quando expirar.
5. Extrair corretamente as ofertas por farmácia:

* cada produto pode aparecer em várias farmácias;
* cada oferta deve virar uma linha separada;
* o campo fornecedor deve identificar a farmácia da AppySaúde;
* ignorar preços inválidos como `0`, `1`, vazio ou placeholder.
6. Extrair campos mínimos:

* data;
* concorrente;
* fornecedor/farmácia;
* produto;
* descrição;
* preço Kz;
* disponibilidade;
* categoria;
* marca;
* província;
* ID do produto;
* link;
* método de extração;
* status/erro.
7. Implementar fallback:

* se API direta falhar, tentar chamada da API dentro do browser via Playwright;
* se token falhar, gerar diagnóstico claro;
* salvar screenshots e logs em pasta de debug.

## 4. Requisitos de Saída

O sistema deve gerar arquivos em Excel e CSV.

### 4.1 AppySaúde

Arquivo sugerido:

`appysaude_snapshot_YYYYMMDD_HHMM.xlsx`

Abas:

1. `Raw`

* todos os registros extraídos.
2. `Disponíveis`

* apenas produtos com preço válido e status disponível.
3. `Indisponíveis`

* produtos sem preço ou sem disponibilidade.
4. `Erros`

* páginas, requisições ou produtos com falha.
5. `Resumo`

* total de produtos;
* total de ofertas;
* número de farmácias;
* número de produtos com preço;
* número de produtos sem preço;
* hora inicial/final da coleta.

### 4.2 Mecofarma

Manter padrão atual:

`mecofarma_snapshot_YYYYMMDD_HHMM.xlsx`

Abas:

1. `Mecofarma_Raw`
2. `Disponíveis`
3. `Não Encontrados`
4. `Indisponíveis`
5. `Erros`

### 4.3 Arquivo Consolidado

Gerar também:

`concorrencia_consolidada_YYYYMMDD_HHMM.xlsx`

Com campos padronizados:

* data_coleta;
* origem;
* fornecedor;
* produto_concorrente;
* codigo_concorrente;
* cnp;
* ref;
* marca;
* categoria;
* provincia;
* preco_concorrente_kz;
* status;
* link_produto;
* metodo_extracao;
* erro.

## 5. Integração com Comparação de Preços

O sistema deve permitir integração com as seguintes bases:

1. Lista AppySaúde.
2. Lista Mecofarma.
3. Relatório de inventário das Farmácias de Coimbra.
4. Tabela de comparação de códigos.
5. Lista de menor preço de fornecedores.
6. Lista de pedido/necessidades de compra.

A planilha final deverá permitir comparar:

* nosso preço de venda;
* nosso preço de custo;
* preço Mecofarma;
* menor preço AppySaúde;
* preço médio AppySaúde;
* menor preço de fornecedores;
* desvio percentual para menor preço;
* desvio percentual para preço médio;
* sugestão de preço;
* alerta de margem.

## 6. Regras de Pricing

Criar aba `Parâmetros` para permitir alteração sem mexer no código.

Parâmetros iniciais:

* margem mínima: 25%;
* margem alvo: 38%;
* alerta de preço caro: acima de 10% ou 12%;
* alerta de preço barato: abaixo de 10%;
* regra de posicionamento: quando possível, ficar até 5% abaixo da Mecofarma;
* regra de comparação AppySaúde: usar média e menor preço das farmácias disponíveis;
* alerta de compra: se preço de compra + 50% for superior à média AppySaúde ou ao menor preço Mecofarma.

## 7. Requisitos Técnicos

### 7.1 Linguagem e bibliotecas

* Python 3.10 ou superior.
* pandas.
* openpyxl.
* requests.
* beautifulsoup4.
* lxml.
* playwright.
* rapidfuzz, se houver matching textual.
* python-dotenv ou leitura manual segura de `.env`.

### 7.2 Execução

O sistema deve permitir:

```bash
python main.py --rodar mecofarma
python main.py --rodar appysaude
python main.py --rodar tudo
python main.py --rodar appysaude --limite 50
python main.py --rodar appysaude --sem-cache
python main.py --limpar-cache
python main.py --diagnostico
```

### 7.3 Logs

Criar logs detalhados em:

`logs/`

Mínimo esperado:

* início e fim da execução;
* endpoint usado;
* status HTTP;
* páginas coletadas;
* produtos extraídos;
* ofertas extraídas;
* erros de token;
* erros de login;
* erros de parsing;
* tempo total;
* arquivo gerado.

### 7.4 Cache

Implementar cache controlado:

* cache de token AppySaúde com expiração;
* cache JSON de respostas por tempo limitado;
* opção `--sem-cache`;
* opção `--limpar-cache`;
* não deixar cache crescer indefinidamente.

## 8. Diagnóstico Obrigatório da AppySaúde

Antes de corrigir, o programador deve executar um diagnóstico e entregar:

1. Endpoint atual confirmado.
2. Exemplo real de JSON retornado pela API.
3. Campos onde estão:

* nome do produto;
* preço;
* farmácia;
* disponibilidade;
* ID do produto;
* categoria;
* marca.
4. Confirmação se precisa login.
5. Confirmação se precisa token Bearer.
6. Método usado para obter o token.
7. Print ou log da primeira página coletada.
8. Total de páginas/produtos/ofertas encontrados.
9. Motivo exato do erro atual.

## 9. Critérios de Aceitação

A entrega será considerada aprovada se:

1. Mecofarma continuar funcionando.
2. AppySaúde coletar pelo menos 50 produtos em modo teste.
3. AppySaúde coletar base completa sem interrupção.
4. Cada oferta da AppySaúde aparecer em linha separada por farmácia.
5. Preços inválidos como `0`, `1`, vazio ou placeholder forem ignorados.
6. Arquivos Excel forem gerados corretamente.
7. Logs indicarem claramente páginas, produtos e erros.
8. O sistema funcionar em Windows.
9. O sistema puder rodar com `.bat`.
10. O código não expuser senhas, tokens ou credenciais em logs ou arquivos enviados.

## 10. Entregáveis

1. Código-fonte corrigido.
2. `requirements.txt` atualizado.
3. Arquivo `.bat` para execução da AppySaúde.
4. Arquivo `.bat` para execução completa.
5. Manual curto de instalação.
6. Manual curto de execução.
7. Relatório técnico explicando a correção da AppySaúde.
8. Exemplo de saída Excel da Mecofarma.
9. Exemplo de saída Excel da AppySaúde.
10. Arquivo consolidado de concorrência.
11. Logs de teste.
12. Lista de limitações conhecidas.

## 11. Observações de Segurança

Credenciais, tokens e sessões não devem ser enviados ao GitHub nem partilhados em arquivos de entrega.

O `.env` deve conter apenas variáveis locais e deve estar no `.gitignore`.

Tokens de Telegram, AppySaúde, Azure B2C ou qualquer outra credencial devem ser tratados como sensíveis.

## 12. Prioridade de Desenvolvimento

### Fase 1 — Correção urgente

* Diagnosticar erro AppySaúde.
* Corrigir endpoint/API.
* Corrigir token/autenticação.
* Gerar Excel AppySaúde funcional.

### Fase 2 — Estabilização

* Melhorar logs.
* Melhorar cache.
* Criar fallback Playwright.
* Criar screenshots de diagnóstico.
* Padronizar saídas.

### Fase 3 — Inteligência de pricing

* Consolidar Mecofarma + AppySaúde.
* Cruzar com inventário.
* Aplicar fatores de conversão.
* Gerar sugestão de preço.
* Gerar alertas de compra e margem.

### Fase 4 — Automação

* Agendamento periódico.
* Relatório automático.
* Dashboard histórico de preços.
* Alertas por Telegram ou e-mail.