Skip to content

README.md

Latest commit

 

History

History
130 lines (100 loc) · 3.74 KB

README.md

File metadata and controls

130 lines (100 loc) · 3.74 KB

🎓 Edu Center Card Bot

Telegram bot for an educational center — card-based subscription management with admin & student roles.

Built with aiogram 3, PostgreSQL (asyncpg), and modular architecture.

✨ Features

Admin Panel

  • ➕ Add students — by phone number + password (default 123 on /skip)
  • 👤 View all users — click to see phone, subscription status, card details
  • 🔑 Reset password — admin can reset any student's password
  • 📊 Statistics — weekly / monthly sales and subscription stats
  • 📢 Broadcast — send announcements to all users
  • 📋 Plan management — view, add, edit, delete subscription plans

Student Features

  • 🔐 Login — phone + password authentication
  • 📋 View plans — browse available subscription plans
  • 💳 Purchase — select plan, make payment, send proof (screenshot)
  • 🎴 Digital card — visually rich card displayed after payment approval
  • 📜 Payment history — track past and pending payments
  • ℹ️ Profile — view personal info and subscription status

Card Types

Card Duration Visual
🥉 Bronze 1 month Brown theme
🥈 Silver 3 months Silver theme
🥇 Gold 6 months Gold theme
💎 Platinum 12 months Blue diamond theme

Coming Soon (placeholder buttons)

  • ⭐ Rating
  • ❓ Q&A
  • 📚 Course Info
  • 🧠 Daily Quiz

📁 Project Structure

card-bot/
├── .env                  # Environment variables
├── .env.example          # Template
├── requirements.txt      # Dependencies
├── run.py                # Entry point
├── bot/
│   ├── __init__.py
│   ├── config.py         # Configuration loader
│   ├── main.py           # Bot & dispatcher setup
│   ├── db/
│   │   ├── database.py   # Connection pool & table init
│   │   └── models.py     # All database queries
│   ├── handlers/
│   │   ├── common.py     # /start, shared handlers
│   │   ├── admin.py      # Full admin panel
│   │   └── student.py    # Student features
│   ├── keyboards/
│   │   ├── admin_kb.py   # Admin keyboards
│   │   └── student_kb.py # Student keyboards
│   ├── states/
│   │   ├── admin_states.py
│   │   └── student_states.py
│   └── utils/
│       ├── card_generator.py  # Card visual generator
│       └── helpers.py         # Utility functions

🚀 Setup & Run

1. Prerequisites

  • Python 3.11+
  • PostgreSQL running locally or remotely

2. Create the database

CREATE DATABASE card_bot;

3. Configure environment

cp .env.example .env

Edit .env with your values:

  • BOT_TOKEN — from @BotFather
  • ADMIN_IDS — comma-separated Telegram user IDs
  • DATABASE_URL — PostgreSQL connection string
  • PAYMENT_CARD_NUMBER — payment card for students
  • PAYMENT_CARD_HOLDER — cardholder name

4. Install dependencies

pip install -r requirements.txt

5. Run the bot

python run.py

Tables are auto-created on startup. Default plans (Bronze, Silver, Gold, Platinum) are seeded if the plans table is empty.

🔄 Workflow

  1. Admin adds a student via phone number
  2. Student sends /start, logs in with phone + password
  3. Student browses plans and selects one to purchase
  4. Payment details are shown; student sends proof (screenshot)
  5. Admin receives the proof and approves/rejects
  6. On approval, a digital subscription card is generated and sent to the student
  7. Student can view their card, expiry, and payment history anytime

📝 License

MIT