🛍️ Telegram Shop Bot

A production-ready Telegram shop bot with advanced security features, transactional integrity, comprehensive admin tools, real-time monitoring, and disaster recovery capabilities.

Language: English | 简体中文

---

🌐 Community & Links

• Telegram交流频道: https://t.me/+6dcMgO8XsN41NWNl
• 友情链接: linux.do
• 欢迎提交 Issues 和 Pull Requests，贡献说明见 .github/CONTRIBUTING.md。
• 如果这个项目对你有帮助，可以通过 GitHub Star 或 README 顶部的 Sponsor/Support 入口支持项目。

---

🖼️ Current Screenshots

The screenshots below are generated from the current local admin/client UI with sanitized demo data.

📋 Table of Contents

• Features
• Community & Links
• Current Screenshots
• Security
• Architecture
• Tech Stack
• Environment Variables
• Installation
• Admin Panel & Metrics
• Usage
• API Documentation
• Testing
• Contributing
• License

✨ Features

Core Shop Functionality

• Product Management: Categories, goods, stock tracking, JSON delivery files, and promo codes in one admin page
• Transactional Purchases: ACID-compliant purchase process
• Digital Delivery: Single JSON purchase is delivered as .json; multiple JSON purchases are delivered as .zip
• Points Economy: Daily check-in points, streak rewards, product redemption by points, and per-redemption quantity limits
• Group Invite Rewards: Per-user group invite links, reward after invited user check-in, and tiered reward rules
• Lottery Module: Product prize pool, prize levels, per-level winner count, and automatic/manual draw support
• Multiple Payment Methods:
  • 💎 CryptoPay (TON, USDT, BTC, ETH)
  • ⭐ Telegram Stars
  • 💳 Telegram Payments provider token (for supported Stripe/card checkout scenarios)
• Shopping Cart: Add multiple items, apply promo codes per item, atomic multi-item checkout with receipt
• Promo Codes: Percent/fixed/balance discount types, category/item binding, usage limits, expiration
• Product Reviews: 1–5 star ratings with optional text, one review per user per item
• Referral System: Configurable commission rates
• Multi-language Support: Russian, English, and Chinese localization

Admin Features

• Role-Based Access Control (RBAC):
  • Built-in roles: USER, ADMIN, OWNER
  • 10 granular permission bits: USE, BROADCAST, SETTINGS, USERS, CATALOG, ADMINS, OWNER, STATS, BALANCE, PROMOS
  • Custom roles: Create roles with any combination of permissions via admin panel
  • Role management: Create, edit, delete roles; assign roles to users
  • Permission-safe: Bitwise subset validation — cannot create/assign roles exceeding own permissions
  • Permission-aware UI: Admin panel shows only buttons matching user's actual permissions
• Comprehensive Admin Panel:
  • Real-time statistics dashboard
  • User management with balance control
  • Role management: create custom roles, assign roles to users
  • Product/category/stock/promo management in the unified Product Operations page
  • Broadcast messaging system
  • Promo code management (create, toggle, delete, view usage stats)
  • CSV data export (users, purchases, payments, operations) with date filtering
  • Dual-write audit logging (rotating file + database table with web UI)

User Experience

• Shopping Cart: Add items, apply promo codes, batch checkout with formatted receipt
• Purchase Receipts: Formatted order receipt with item details, order ID, timestamp, and quick-view buttons
• Product Reviews: Rate and review purchased items (1–5 stars with optional text)
• Lazy Loading Pagination: Efficient data loading for large catalogs
• Purchase History: Complete transaction records
• Referral Dashboard: Track earnings and referrals
• Channel Integration: Optional news channel with subscription checks

Performance & Reliability

• Fully Async Database Layer: Native async PostgreSQL via asyncpg + async SQLAlchemy
  • Zero thread-pool overhead — all DB operations run natively on the event loop
  • Async connection pooling with automatic recycling and timeout handling
  • Graceful handling of high-load scenarios
• Optional Redis Caching: Multi-layer caching system for optimal performance (enable with REDIS_ENABLED=1)
  • User role caching (15-minute TTL)
  • Product catalog caching (5-minute TTL)
  • Statistics caching (1-minute TTL)
  • Smart cache invalidation on data updates (purchases, admin item adds, stock changes)
  • Cache warm-up on startup (categories, user/admin counts)
  • Cache scheduler: hourly stats refresh, daily cleanup at 3:00 AM
  • When disabled: bot uses in-memory FSM storage and queries the database directly
• Performance Optimizations: Up to 60% reduction in database queries for read operations (with Redis enabled)
• Optimized Queries: JOIN-based queries instead of N+1 patterns, SQL-level sorting for paginated results

Web Admin Panel & Monitoring

• SQLAdmin Web Interface:
  • Full database admin panel with authentication
  • Browse, search, filter, and edit all tables
  • Read-only views for purchases, payments, operations, and audit logs
  • All CRUD operations via web panel are audit-logged automatically
  • CSV data export endpoints (/export/users, /export/purchases, /export/operations, /export/payments) with optional date filtering
• Real-Time Metrics Collection:
  • Event tracking (purchases, payments, user actions)
  • Performance metrics (response times, query durations)
  • Error tracking and categorization
  • Conversion funnel analysis
• Prometheus-Compatible Metrics:
  • Export endpoint at /metrics/prometheus
  • Ready for integration with Grafana
  • Custom metrics for business KPIs
• Health Check Endpoint:
  • System status at /health
  • Database connectivity check
  • Redis status monitoring

Disaster Recovery System

• Payment Recovery:
  • Automatic check for stuck CryptoPay payments (every 5 minutes)
  • Verifies payment status via CryptoPay API
  • Deadlock-safe: collects payment data, closes DB session, then processes asynchronously
  • Idempotent payment processing
  • User notification on recovery
• Health Monitoring:
  • Periodic system health checks (database, Redis, Telegram API)
  • Logs failures for observability
• Data Cleanup:
  • Scheduled daily cleanup at 4:00 UTC
  • Automatic deletion of old audit logs (configurable retention period)
  • Automatic deletion of old pending/failed payments
• Graceful Shutdown:
  • Metrics snapshot saved to data/final_metrics.json
  • Recovery tasks properly cancelled

🔒 Security

Implemented Security Measures

1. Rate Limiting

• Global limits: 30 requests per 60 seconds
• Action-specific limits:
  • Purchases: 5 per minute
  • Payments: 10 per minute
• Automatic ban system with configurable duration
• Admin bypass option
• Admin panel login rate limiting (5 attempts, 15-minute lockout per IP, periodic stale entry cleanup)
• Admin panel session timeout (30-minute max age)
• Default credentials protection: remote login blocked when using default admin/admin

2. Security Middleware

• SQL Injection Protection: Parameterized queries via SQLAlchemy ORM (no raw SQL)
• XSS Prevention: HTML sanitization for broadcast messages and category names
• Purchase Intent Verification: Item name stored in server-side FSM state, verified on buy
• Replay Attack Prevention: Timestamp validation on transactional callbacks (buy, pay, balance operations)

3. Authentication & Authorization

• Bot detection and blocking
• Telegram ID-based authentication
• Permission bitmask access control with 10 granular bits and bitwise subset validation
• Role caching with TTL for performance

4. Payment Security

• Pre-Checkout Validation: Server-side amount validation against allowed range before accepting payment
• Idempotent Payment Processing: Prevents duplicate charges
• Concurrent Payment Protection: Graceful handling of duplicate payment attempts via IntegrityError catch
• Transactional Integrity: ACID compliance for all financial operations
• Atomic Admin Balance Operations: Top-up and deduction with FOR UPDATE lock in a single transaction
• Self-Referral Prevention: Database CHECK constraints on both users and referral_earnings tables, plus transaction-level guard against self-referral bonus abuse
• Circuit Breaker for CryptoPay API: Stops calling after 5 consecutive failures, auto-recovers after 60 seconds
• External ID Tracking: Unique identifiers for payment reconciliation
• Error Sanitization: Internal error details never exposed to users; generic error codes returned, details logged to audit

5. Data Validation

• Pydantic models for request validation
• Decimal precision for monetary calculations
• HTML sanitization for user-facing text (broadcast, categories)
• Control character filtering for item names

🏗️ Architecture

System Architecture

Telegram users/groups
        |
        v
Aiogram bot handlers + i18n middleware
        |
        +--> Shop, cart, payment, points redemption, check-in, invite, lottery
        |
        v
PostgreSQL models and transactional services
        |
        +--> goods / item_values / purchases / payments / promo_codes
        +--> check_ins / group_invite_links / lottery_events / bot_settings

Local web admin
        |
        +--> SQLAdmin database views
        +--> Product Operations UI for categories, products, JSON stock, and promo codes

Database Schema

• Users: Telegram ID, balance, referral tracking
• Roles: Permission-based access control
• Products: Categories, items, stock management
• Transactions: Purchases, payments, operations
• Referrals: Earnings tracking and statistics
• Promo Codes: Discount codes with type, value, usage tracking, and category/item binding
• Cart: User shopping cart items with promo code association
• Reviews: Product ratings and text reviews (one per user per item)
• Points & Check-ins: Daily check-in records, streak rewards, and points balance
• Group Invites: Per-user group invite links and reward attribution after invited-user check-in
• Lottery: Lottery events, entries, winners, and product prize pool settings
• Audit Log: Structured action log with user, action, resource, details, and IP tracking

Key Design Patterns

• Singleton: Database connection management
• Repository Pattern: Data access layer
• Middleware Pipeline: Request processing chain
• State Pattern: FSM for multi-step processes
• Transaction Script: Business logic encapsulation
• Middleware Pattern: Metrics collection and event tracking via AnalyticsMiddleware
• Conversion Funnel: Purchase funnel tracking (view_shop → view_item → purchase)
• Natively Async DB: All database operations use async SQLAlchemy with asyncpg, no thread-pool bridges

Performance Architecture

• Async Connection Pooling: Native async PostgreSQL connection management with automatic recycling
• Multi-Level Caching: Optional Redis-based intelligent caching with TTL-based expiration
• Cache Invalidation: Smart cache clearing on data modifications
• Concurrent Load Handling: Optimized for high-traffic scenarios with connection queuing
• Metrics Pipeline: Asynchronous metrics collection without performance impact

💻 Tech Stack

Core

• Language: Python 3.11+
• Framework: Aiogram 3.22+ (async Telegram Bot API)
• Database: PostgreSQL 16+ with async SQLAlchemy 2.0 (asyncpg driver)
• Cache/Storage: Redis 7+ (optional — FSM states, intelligent data caching)
• Migrations: Alembic

Security & Validation

• Input Validation: Pydantic
• Rate Limiting: Custom in-memory middleware (per-process)
• Authentication: Role-based with 10-bit permission bitmask

Payment Integrations

• CryptoPay API: Cryptocurrency payments (with circuit breaker)
• Telegram Stars API: Native digital currency
• Telegram Payments API: Provider-token checkout such as Stripe/card payments for supported goods and services

Web Admin & Monitoring

• Admin Panel: SQLAdmin with Starlette
• Metrics Collection: Custom MetricsCollector with event tracking
• Export Formats: JSON, Prometheus metrics format

DevOps

• Containerization: Docker & Docker Compose
• Logging: Rotating file handlers + structured database audit log (audit_log table)
• Testing: Pytest with pytest-asyncio (async SQLite via aiosqlite)
• CI/CD Ready: Environment-based configuration
• Health Checks: Built-in health monitoring endpoints

⚙️ Environment Variables

The application requires the following environment variables:

🤖 Telegram

Variable	Description	Required
TOKEN	Bot Token from @BotFather	✅
OWNER_ID	Your Telegram ID	✅

💳 Payments

Variable	Description	Default
TELEGRAM_PROVIDER_TOKEN	Telegram Payments provider token for supported Stripe/card checkout	-
CRYPTO_PAY_TOKEN	CryptoPay API token	-
STARS_PER_VALUE	Stars exchange rate for internal balance top-ups (0 to disable)	0.91
PAY_CURRENCY	Real provider currency code (RUB, USD, EUR, etc.)	RUB
BALANCE_CURRENCY	Internal balance unit shown to users, for example UStars	UStars
REFERRAL_PERCENT	Referral commission percentage	0
PAYMENT_TIME	Invoice validity in seconds	1800
MIN_AMOUNT	Minimum payment amount	20
MAX_AMOUNT	Maximum payment amount	10000

🔗 Links / UI

Variable	Description	Default
CHANNEL_URL	News channel link (the bot sends notifications about new products here when setting up)	-
CHANNEL_ID	News channel ID	-
HELPER_ID	Support user Telegram ID	-
RULES	Bot usage rules text	-

🌐 Locale & Logs

Variable	Description	Default
BOT_LOCALE	Localization language (ru/en/zh)	ru
BOT_LOGFILE	Path to main log file	bot.log
BOT_AUDITFILE	Path to audit log file	audit.log
LOG_TO_STDOUT	Console logging (1/0)	1
LOG_TO_FILE	File logging (1/0)	1
DEBUG	Debug mode (1/0)	0
REVIEWS_ENABLED	Enable product review system (1/0)	1

📊 Web Admin Panel

Variable	Description	Default
WEB_ADMIN_ENABLED	Start the full SQLAdmin/admin web surface (1/0)	1
PLATFORM_WEB_ENABLED	Start only /platform/app, /platform/api, public reports, and /health when SQLAdmin is off	0
ADMIN_HOST	Admin panel bind address	localhost
ADMIN_PORT	Admin panel port	9090
PLATFORM_WEB_HOST	Optional bind address for platform-only web serving	ADMIN_HOST
PLATFORM_WEB_PORT	Optional port for platform-only web serving	ADMIN_PORT
ADMIN_USERNAME	Admin panel login	admin
ADMIN_PASSWORD	Admin panel password	admin
SECRET_KEY	Secret key for session encryption	change-me-in-production

Note: In Docker, ADMIN_HOST is automatically set to 0.0.0.0 and the admin panel is bound to 127.0.0.1:9090 ( localhost only). Change ADMIN_USERNAME, ADMIN_PASSWORD, and SECRET_KEY in production. Remote login with default credentials (admin/admin) is automatically blocked.

For Telegram Mini App deployments that should not expose SQLAdmin, keep WEB_ADMIN_ENABLED=0, set PLATFORM_WEB_ENABLED=1, bind PLATFORM_WEB_HOST/PLATFORM_WEB_PORT behind a HTTPS reverse proxy, then configure platform_webapp_url to the public /platform/app URL before enabling platform menu buttons.

📦 Redis Storage (Optional)

Variable	Description	Default
REDIS_ENABLED	Enable Redis for caching and FSM storage (1 = on, 0 = off)	1
REDIS_HOST	Redis server address	localhost
REDIS_PORT	Redis server port	6379
REDIS_DB	Redis database number	0
REDIS_PASSWORD	Redis password (leave empty for Docker)	-

Note: When REDIS_ENABLED=0, the bot uses in-memory storage for FSM states (lost on restart) and all caching is disabled. The bot remains fully functional but without caching optimizations.

🗄️ Database

Variable	Description	Default
POSTGRES_DB	PostgreSQL database name	Required
POSTGRES_USER	PostgreSQL username	Required
POSTGRES_PASSWORD	PostgreSQL password	Required
POSTGRES_HOST	PostgreSQL host (configure this only for manual deploy)	localhost (for manual) / db (for docker)
DB_PORT	PostgreSQL port	5432

🌐 Webhook Mode (Optional)

Variable	Description	Default
WEBHOOK_ENABLED	Use webhook instead of polling (1/0)	0
WEBHOOK_URL	Public URL for webhook (e.g., https://yourdomain.com)	-
WEBHOOK_PATH	Path for webhook endpoint	/webhook
WEBHOOK_SECRET	Secret token for webhook verification	-

Note: Webhook mode requires a publicly accessible HTTPS URL. When disabled (default), the bot uses long polling.

🧹 Auto-Cleanup

Variable	Description	Default
AUDIT_RETENTION_DAYS	Days to keep audit log entries (0 to disable)	90
PAYMENTS_RETENTION_DAYS	Days to keep pending/failed payments (0 to disable)	90

📦 Installation

Prerequisites

• Docker and Docker Compose (recommended)
• OR Python 3.11+ and PostgreSQL 16+
• Redis 7+ (optional — for caching and persistent FSM storage)

🐳 Deploy with Docker (Recommended)

1. Clone the repository

git clone https://github.com/leochena/tgsellbot.git
cd tgsellbot

2. Create environment file

cp .env.example .env
# Edit .env with your configuration

3. Start the bot

# With Redis (caching enabled):
docker compose --profile redis up -d --build

# Without Redis (simpler setup, no caching):
# Set REDIS_ENABLED=0 in .env first
docker compose up -d --build

Linux Users: If you encounter permission errors for ./logs or ./data directories, set PUID and PGID in your .env file to match your host user:

# Find your UID/GID
id
# Output: uid=1000(username) gid=1000(username) ...

# Add to .env file
echo "PUID=1000" >> .env
echo "PGID=1000" >> .env

The bot will automatically:

• Create database schema
• Apply all migrations
• Initialize roles and permissions
• Start accepting messages
• Launch admin panel at http://localhost:9090/admin (localhost only)
• Initialize recovery systems
• Enable Docker health check via /health endpoint

4. View logs (optional)

docker compose logs -f bot

5. Access admin panel

Open in browser: http://localhost:9090/admin

Important: Default credentials are admin/admin. Remote login with default credentials is blocked — change ADMIN_USERNAME, ADMIN_PASSWORD, and SECRET_KEY in .env before exposing the admin panel.

🔧 Manual Deployment

1. Clone the repository

git clone https://github.com/leochena/tgsellbot.git
cd tgsellbot

2. Create virtual environment

python3.11 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

pip install --upgrade pip
pip install -r requirements.txt

4. Set up PostgreSQL

# Create database (adjust credentials as needed)
createdb telegram_shop
createuser shop_user -P

5. Create environment file

cp .env.example .env
# Edit .env with your configuration

6. Run migrations

alembic upgrade head

7. Start the bot

python run.py

8. Access admin panel (optional)

Open in browser: http://localhost:9090/admin

📝 Post-Installation

1. Add bot to channel (if using news channel feature):
   • Add your bot to the channel specified in CHANNEL_URL and CHANNEL_ID
   • Grant administrator rights with "Post Messages" permission

The bot will send relevant messages to your channel when adding products.

2. Apply latest migrations (if updating):

# With Docker
docker compose run --rm bot alembic upgrade head

# Manual deployment
alembic upgrade head

3. Verify installation:
   • Send /start to your bot
   • Check that main menu appears
   • Access admin panel (owner only initially)
   • Check admin panel at http://localhost:9090/admin

📊 Admin Panel & Metrics

Web Admin Panel

The bot includes a web-based admin panel powered by SQLAdmin, accessible at http://localhost:9090/admin

• Login with credentials from your .env file (ADMIN_USERNAME / ADMIN_PASSWORD)
• Browse all database tables: users, roles, categories, products, purchases, payments, operations, referral earnings, check-ins, invite records, lottery events, bot settings, and audit logs
• Use Product Operations for day-to-day category, product, stock, JSON file, and promo-code management
• Search, filter, and sort records
• Read-only access for financial tables (purchases, payments, operations) and audit logs
• All create/edit/delete operations through the web panel are automatically audit-logged

Monitoring Endpoints

• /health - Health check endpoint (database, Redis status if enabled)
• /metrics - Raw metrics in JSON format
• /metrics/prometheus - Prometheus-compatible metrics export
• /export/users - CSV export of users (with optional date filtering)
• /export/purchases - CSV export of purchases
• /export/operations - CSV export of operations
• /export/payments - CSV export of payments

Recovery System

The bot includes a recovery system for stuck payments:

Payment Recovery

• Checks for stuck CryptoPay payments every 5 minutes
• Verifies payment status via CryptoPay API
• Automatically credits confirmed but uncredited payments
• Notifies users when recovery succeeds

Health Monitoring

• Periodic checks of database, Redis (when enabled), and Telegram API (every 60 seconds)
• Logs failures for observability

📱 Usage

User Interface

👤 User Features (click to expand)

Main Navigation

• /start - Initialize bot and show main menu
• Language switch from the bot home/profile flow
• Shop navigation through categories and product detail pages
• Quantity selection for cart purchases and points redemption
• Balance top-up with enabled payment providers
• Telegram Stars to internal balance conversion when configured
• Promo code redemption from the bot home and product detail pages
• Product reviews and purchase history
• Daily check-in for points and lottery tickets
• Group invite link generation; invite rewards are credited after the invited user checks in
• Lottery status, entries, and winners

Admin Panel

🎛️ Admin Features (click to expand)

Available for users with admin permissions (built-in ADMIN/OWNER or custom roles):

Product Operations

The unified Product Operations page manages:

• Categories
• Products and prices
• Points redemption price and per-order redemption limit
• Lottery prize-pool participation, prize level, and winner count
• Text stock and JSON stock
• Multi-file JSON upload
• Balance promo codes and product discount codes

User Management

• View profiles, block/unblock users, assign roles (USERS permission)
• Adjust balances: top-up and deduction (separate BALANCE permission)

Role Management

• 10 granular permission bits for fine-grained access control:
  • USE (1) — basic bot access
  • BROADCAST (2) — mass messaging to all users
  • SETTINGS (4) — bot settings (maintenance mode)
  • USERS (8) — view/block/unblock users, view referrals and purchases
  • CATALOG (16) — categories, positions, items/goods CRUD
  • ADMINS (32) — role CRUD and role assignment
  • OWNER (64) — owner-only operations
  • STATS (128) — statistics dashboard, log files, bought-item search
  • BALANCE (256) — top-up / deduct user balance
  • PROMOS (512) — promo code management (create, toggle, delete)
• Create custom roles with any combination of permissions via admin panel
• Edit and delete custom roles (built-in USER/ADMIN/OWNER cannot be deleted)
• Permission-aware admin panel: each user sees only the buttons their permissions allow
• Permission-safe: bitwise subset validation prevents creating or assigning roles exceeding your own

Engagement Management

• Configure check-in points and lottery ticket rewards.
• Configure group invite target chat and invite share copy.
• Configure tiered invite rewards such as 1=1,10=2,30=3.
• Manage lottery events, entries, winners, and product prize-pool fields through admin models.

Broadcasting, Analytics, and Monitoring

• Broadcast messaging for permitted admins.
• Health endpoint, JSON metrics, Prometheus metrics, and CSV exports.
• Structured audit logs for admin and financial actions.

📊 API Documentation

Core Database Methods

User Management

await create_user(telegram_id: int, registration_date: datetime, referral_id: int, role: int) -> None
await check_user(telegram_id: int) -> Optional[User]
await update_balance(telegram_id: int, amount: int) -> None

Transaction Processing

await buy_item_transaction(telegram_id: int, item_name: str, promo_code: str = None) -> tuple[bool, str, dict]
await checkout_cart_transaction(user_id: int) -> tuple[bool, str, list]
await process_payment_with_referral(
    user_id: int, amount: Decimal, provider: str, external_id: str, referral_percent: int = 0) -> tuple[bool, str]
await admin_balance_change(telegram_id: int, amount: int) -> tuple[bool, str]
await redeem_balance_promo(code: str, user_id: int) -> tuple[bool, str, Decimal | None]

Product Management

await create_item(item_name: str, item_description: str, item_price: int, category_name: str) -> None
await add_values_to_item(item_name: str, value: str, is_infinity: bool) -> bool
await delete_item(item_name: str) -> None

Role Management

await create_role(name: str, permissions: int) -> int | None
await update_role(role_id: int, name: str, permissions: int) -> tuple[bool, str | None]
await delete_role(role_id: int) -> tuple[bool, str | None]
await get_all_roles() -> list[dict]
await get_roles_with_max_perms(max_perms: int) -> list[dict]
await get_role_by_id(role_id: int) -> dict | None
await count_users_with_role(role_id: int) -> int

Middleware Configuration

# Rate limiting
RateLimitConfig(
    global_limit=30,
    global_window=60,
    action_limits={'buy_item': (5, 60)},
    ban_duration=300
)

# Security layers
SecurityMiddleware()
AuthenticationMiddleware()

Metrics Collection

# Track custom events
metrics.track_event("purchase", user_id, metadata={"item": item_name})
metrics.track_timing("database_query", duration_ms)
metrics.track_conversion("purchase_funnel", "view_item", user_id)

# Get metrics summary
summary = metrics.get_metrics_summary()
prometheus_format = metrics.export_to_prometheus()

Recovery Management

# Initialize recovery manager
recovery_manager = RecoveryManager(bot)
await recovery_manager.start()

# Manual recovery trigger
await recovery_manager.recover_pending_payments()

Audit Logging

from bot.database.methods.audit import log_audit

# Dual-write: logs to both rotating file and audit_log DB table
await log_audit(
    "purchase",  # action name
    level="INFO",  # INFO / WARNING / ERROR
    user_id=123456789,  # who performed the action
    resource_type="Item",  # affected entity type
    resource_id="Premium Account",  # affected entity ID
    details="price=100 RUB",  # free-form context
    ip_address=None,  # for web admin actions
)

Caching & Performance

# Cache configuration examples
@cache_result(ttl=900, key_prefix="user_roles")  # 15 minutes
async def get_user_role(telegram_id: int) -> str


@cache_result(ttl=300, key_prefix="catalog")  # 5 minutes  
async def get_products_by_category(category_id: int) -> List[Product]


# Cache invalidation (called automatically after purchases, admin item adds, and stock changes)
await invalidate_user_cache(telegram_id)
await invalidate_item_cache(item_name, category_name)  # category_name is optional

Async Engine Configuration

from sqlalchemy.ext.asyncio import create_async_engine

engine = create_async_engine(
    DATABASE_URL,  # postgresql+asyncpg://...
    pool_size=20,  # Base pool size
    max_overflow=40,  # Additional connections during peaks
    pool_recycle=3600,  # Refresh connections every hour
    pool_timeout=30,  # Max wait time for connection
    connect_args={
        "timeout": 10,
        "command_timeout": 30,
    },
)

🧪 Testing

The project includes a comprehensive test suite with 448 tests covering all major components, business logic, and edge cases. Tests use SQLite in-memory with real SQL queries, and a dict-based FakeCacheManager for realistic cache behavior. Coverage is measured automatically on every run via pytest-cov.

Running Tests

# Run all tests with verbose output (coverage report included by default)
pytest tests/ -v

# Run specific test modules
pytest tests/test_transactions.py -v
pytest tests/test_filters.py -v
pytest tests/test_payment_service.py -v

# Run with HTML coverage report
pytest tests/ --cov-report=html

Test Modules Overview

Module	Tests	Coverage
test_database_crud.py	71	CRUD: users, roles, categories, items, balance, stats
test_role_management.py	53	Role CRUD, handlers, helpers, Permission bitwise, regressions
test_validators.py	44	Input validation, control chars, XSS, Pydantic models
test_middleware.py	45	Rate limiting, suspicious patterns, critical/replay actions, auth
test_keyboards.py	31	All inline keyboard generators incl. admin console
test_admin_handlers.py	27	User management, assign role, balance edge cases, categories
test_transactions.py	21	Purchase & payment transactions, idempotency, admin balance
test_other_handlers.py	16	check_sub_channel, payment methods, hash, item name safety
test_filters.py	15	ValidAmountFilter, HasPermissionFilter (boundaries, permissions)
test_payment_service.py	14	currency_to_stars, minor units, Stars/Fiat invoices, CryptoPayAPI
test_metrics.py	14	MetricsCollector, AnalyticsMiddleware
test_cache_invalidation.py	13	Cache invalidation after DB mutations
test_broadcast.py	11	BroadcastManager, BroadcastStats
test_payment_handlers.py	10	Balance top-up, payment check, item purchase
test_shop_handlers.py	10	Shop browsing, item info, bought items
test_paginator.py	10	LazyPaginator with caching
test_user_handlers.py	8	/start, profile, rules, referral registration
test_i18n.py	8	get_locale, localize: fallback, formatting, error handling
test_referral_system.py	7	Referral stats, earnings, view referrals
test_recovery.py	7	RecoveryManager lifecycle, payment recovery, timeout, skip
test_login_rate_limiter.py	6	LoginRateLimiter: blocking, reset, expiry, IP isolation
test_audit.py	4	log_audit: DB record creation, levels, optional fields
Total	448	Complete system coverage

Test Architecture

• conftest.py — shared fixtures: async SQLite in-memory DB via aiosqlite (StaticPool), FakeCacheManager (dict + fnmatch), FakeFSMContext, factory fixtures (user, category, item), mock builders (CallbackQuery, Message)
• Mocks only for external services: Telegram Bot API, CryptoPay API
• Real async SQL queries via async SQLAlchemy against SQLite — no mocked DB sessions

The test suite validates:

Core Functionality

• ✅ Transactional purchase safety — balance deduction, stock removal, rollback on error
• ✅ Cart checkout integrity — atomic multi-item checkout, duplicate value prevention for same-item cart entries
• ✅ Payment idempotency — duplicate payment processing prevented via unique constraint
• ✅ Referral bonus calculation — percentage-based bonus, referrer cache invalidation
• ✅ Atomic admin balance operations — top-up, deduction, insufficient funds check in single transaction
• ✅ Cache invalidation after mutations — stale balance/stats/item count prevention (purchases, admin adds)

Security & Middleware

• ✅ Rate limiting — global limits, action-specific limits, ban after exceed, ban expiry
• ✅ Suspicious pattern detection — XSS/script injection, length-based DoS protection
• ✅ Critical action detection — audit logging for buy/pay/delete/admin operations, replay protection for transactional actions
• ✅ Authentication middleware — blocked user rejection, bot rejection
• ✅ Permission bitmask helpers — is_subset, has_any_admin_perm bitwise validation
• ✅ Admin panel login rate limiting — block after max attempts, lockout expiry, IP isolation

Database Operations

• ✅ Full CRUD — users, roles (incl. custom role create/update/delete), categories, items, item values, payments, operations, referral earnings
• ✅ Balance operations — positive/negative updates, insufficient funds check
• ✅ Duplicate handling — duplicate users ignored, duplicate categories/items rejected
• ✅ Blocking — set_user_blocked, is_user_blocked
• ✅ Stats queries — today/all orders, operations, user balance aggregation

Handler Testing

• ✅ User handlers — /start (new user, referral, self-referral, owner role, non-private chat), profile, rules
• ✅ Payment handlers — replenish balance flow, CryptoPay paid/active/expired, duplicate prevention, item purchase
• ✅ Shop handlers — category browsing, item list, item info (limited/unlimited), bought items
• ✅ Admin handlers — check user, assign role, replenish/deduct balance, block/unblock, category CRUD, item delete
• ✅ Role management — create/edit/delete roles, permission toggles, assign role to users, bitwise escalation prevention, permission-aware admin keyboard
• ✅ Referral handlers — referral page, view referrals list, earnings, earning detail

Data Validation

• ✅ Telegram ID validation — valid, zero, negative, too large, string conversion, None
• ✅ Money amount validation — min/max bounds, decimal, non-numeric, negative
• ✅ HTML sanitization — escapes dangerous tags, preserves safe formatting (bold, italic, code)
• ✅ Pydantic models — PaymentRequest, ItemPurchaseRequest, CategoryRequest, BroadcastMessage

Infrastructure

• ✅ Broadcast system — all success, partial failure, forbidden user, cancel mid-batch, progress callback
• ✅ Recovery manager — paid/expired/active payment recovery, API timeout handling, provider filtering, start/stop lifecycle
• ✅ Metrics — event/timing/error tracking, conversion funnels, Prometheus export
• ✅ Pagination — page loading, caching, cache eviction, state serialization, empty results
• ✅ Keyboards — main menu, profile, payment, item info, referral, admin buttons
• ✅ Filters — ValidAmountFilter (boundaries, non-digit, empty), HasPermissionFilter (bitmask, no role)
• ✅ Payment service — currency_to_stars rounding, minor units (JPY/KRW), invoice generation, CryptoPayAPI errors
• ✅ i18n — locale detection, fallback to default, key formatting, missing key passthrough
• ✅ Utility handlers — channel subscription check, payment method detection, hash generation, item name safety
• ✅ Audit logging — dual-write to file and DB, all log levels, optional fields

Test Quality Features

• Real async DB queries: Async SQLite in-memory via aiosqlite with StaticPool — tests catch real SQL issues
• Realistic cache: FakeCacheManager with pattern-based invalidation (fnmatch)
• Async testing: Full asyncio support with pytest-asyncio (auto mode — no manual @pytest.mark.asyncio needed)
• Per-test isolation: Automatic data cleanup between tests (FK-ordered delete)
• Factory pattern: Reusable user_factory, category_factory, item_factory fixtures
• Security Validation: XSS detection, critical action audit, and input sanitization testing
• Automatic Coverage: pytest-cov runs on every test invocation (--cov=bot --cov-report=term-missing)
• Pytest Markers: unit, integration, slow for selective test runs

🤝 Contributing

Issues and pull requests are welcome. Please use the GitHub issue templates for bug reports and feature requests, and read .github/CONTRIBUTING.md before opening a pull request.

Quick flow:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Add tests or documentation for behavior changes
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Development Guidelines

• Follow PEP 8 style guide
• Add tests for new features
• Update documentation
• Use type hints
• Write meaningful commit messages

📄 License

The main project license is the MIT License. See LICENSE for details.

Additional project terms:

• 本项目可免费商用、自用。
• 禁止二次闭源打包售卖。
• 禁止作为付费独立产品分发。

Portions of this project are derived from interlumpen/Telegram-shop, which was released under the MIT License. The original copyright and license notice are preserved in NOTICE.

🙏 Acknowledgments

• Aiogram - Telegram Bot framework
• SQLAlchemy - Database ORM
• Redis - Cache and storage
• Contributors and testers

📞 Support

• Create an Issue for bug reports
• Open a Pull Request for fixes and improvements
• Join the Telegram交流频道: https://t.me/+6dcMgO8XsN41NWNl