Bot do Telegram para Controle de Estoque

Este bot permite gerenciar o estoque através do Telegram.

Configuração

Criar um bot no Telegram:
- Converse com @BotFather no Telegram
- Use o comando /newbot
- Escolha um nome e username para seu bot
- Copie o token fornecido
Configurar variáveis de ambiente:

Edite o arquivo .env e adicione seu token do bot:
```
TELEGRAM_BOT_TOKEN=seu_token_aqui
```
Instalar dependências:
```
pip install -r requirements.txt
```

Iniciar os serviços de banco (PostgreSQL e Redis):

# No Linux
make docker-up

# No Windows
docker-compose up -d

Executar o bot:

# No Linux
make telegram

# No Windows
python bot_main.py

Comandos Disponíveis

🔐 Identificação (Obrigatório)

/start - Inicia o bot e mostra instruções
/identificar <seller_id> - Se identifica como seller (ex: /identificar luizaLabs)
/help - Mostra lista de comandos

📦 Gestão de Estoque (Após identificação)

/adicionar <sku> <quantidade> - Adiciona/incrementa produto no seu estoque
/consultar <sku> - Consulta quantidade de um produto seu
/atualizar <sku> <quantidade> - Define quantidade exata do produto
/remover <sku> - Remove produto do seu estoque

📊 Relatórios (Apenas seus produtos)

/estoque_baixo - Lista seus produtos com estoque baixo (≤ 15 unidades)
/listar - Lista todos os seus produtos no estoque
/config - Mostra configurações do sistema (limite de estoque baixo, versão, etc.)

⚠️ Importante: Após se identificar, todas as operações são feitas apenas no seu estoque. Você não pode ver ou modificar produtos de outros sellers.

Exemplos de Uso

🔐 Primeiro acesso

/start
/identificar luizaLabs

📦 Gerenciando estoque

/adicionar PRODUTO123 50
/consultar PRODUTO123
/atualizar PRODUTO123 100
/remover PRODUTO123

📊 Relatórios

/listar
/estoque_baixo
/config

Funcionalidades

🔐 Sistema de Identificação: Cada usuário se identifica com seu seller_id único
🛡️ Isolamento por Seller: Cada seller só pode ver e modificar seus próprios produtos
📦 Gestão Completa: Adicionar, consultar, atualizar e remover produtos
📊 Relatórios Personalizados: Estoque baixo e listagem apenas dos seus produtos
✅ Validações: Verifica parâmetros e permissões antes de executar operações
🔧 Diagnóstico: Comando para verificar se o sistema está funcionando
💾 Persistência: Dados salvos em PostgreSQL com histórico de movimentações

⚙️ Configurações do Sistema

Estoque Baixo

Limite padrão: 15 unidades ou menos
Configurável: Pode ser alterado no arquivo app/settings/app.py
Campo: low_stock_threshold
Verificação: Use /config para ver o valor atual

Como alterar o limite:

Edite app/settings/app.py
Altere a linha: low_stock_threshold: int = Field(default=15, ...)
Reinicie o bot

🔒 Segurança e Isolamento

Proteção por Seller

✅ Identificação obrigatória antes de usar qualquer comando
✅ Isolamento total - sellers só veem seus próprios produtos
✅ Validação automática - sistema impede acesso cruzado
✅ Sessão por chat - cada conversa tem sua própria identificação

Como funciona:

Primeiro acesso: Usuario deve usar /identificar seller_id
Comandos protegidos: Todos os comandos de estoque verificam autenticação
Filtragem automática: Sistema filtra apenas produtos do seller logado
Sessão persistente: Identificação mantida durante toda a conversa

Estruturação dos Arquivos do BOT

bot_main.py - Arquivo principal recomendado para executar o bot
app/integrations/bots/telegram_bot.py - Comandos e lógica do bot

Solução de Problemas

Erro "Could not parse SQLAlchemy URL"

✅ Solução: Certifique-se de que PostgreSQL está rodando (start_services.bat)

Erro "Field required [type=missing, input_value=...]"

✅ Solução: Corrigido na versão atual do bot

Bot não responde

✅ Verifique se o TELEGRAM_BOT_TOKEN está correto no .env
✅ Verifique se os serviços estão rodando: docker ps

Como verificar se os serviços estão rodando

# Verificar containers Docker
docker ps

# Deve mostrar:
# - pc-postgres (PostgreSQL)
# - redis

FilesExpand file tree

TELEGRAM_BOT_README.md

Latest commit

History