SAS-TelegramBot (Student Attendance Statistics - Telegram Bot)

This repository contains the SAS-TelegramBot project, a bot designed to maintain student attendance statistics via Telegram. The addition of groups, students, lessons, and custom types of visits/passes is supported. Logging is available for users with administrator status. Export to an XLSX table is also available. The bot is designed to be run and used on your server. Viewing of personal data by students is not provided.

Features

• User Management: Simple user registration via the /start command. Admin privileges can be granted using a Django management command.
• CRUD Operations: A full suite of admin commands accessible via an inline keyboard menu (/menu) for managing:
  • Groups: Create, edit, and delete student groups.
  • Students: Add, edit, and delete students, and assign them to groups.
  • Lessons: Schedule lessons with specific topics, groups, dates, and times.
  • Attendance Types: Define custom attendance statuses (e.g., "Present," "Absent," "Sick").
• Attendance Tracking: A multi-step workflow for marking student attendance for specific lessons.
• Data Export: Export attendance data for a specific group and date range to an .xlsx file using the /export command.
• Message History: Logs all non-command messages from registered users.

Project Structure

• bot.py: The core application logic for the Telegram bot.
• telegram_bot_db/: The Django app containing the database models, admin configurations, and migrations.
• telegram_bot_django/: The main Django project configuration.
• settings/: Contains project settings, including the bot token.
• main.py: A command-line utility for running the bot, web server, and management commands.
• manage.py: The standard Django management script.

Available Commands

• /start: Registers the user with the bot.
• /profile: Shows the user's profile information.
• /menu: Displays the main admin menu with inline keyboards for managing the database.
• /export: Starts the process to export attendance data to an XLSX file.
• /cancel: Cancels any ongoing multi-step operation (like adding a new student).

Requirements

• Python 3.13
• Python libraries from Core:
  • You can install the bot's dependency libraries in the "CORE" directory automatically via install_core.bat/.sh file or do it manually via requirements_core.txt

Installation and Usage

1. Backend Setup

1. Clone this repository to your local machine.
2. Install the required Python libraries as listed above.
3. Open your Telegram client and find the bot you created with @BotFather.
4. Edit settings/settings.py and add your Telegram bot token. Configure MySQL DataBase.
5. Open a terminal in the project's root directory and run the server:

   python main.py runserver

   This will start both the Flask URL collector and the Telegram bot.

2. Bot Configuration and Usage

1. Start a conversation with your bot on Telegram and send the /start command to register your user.
2. Find your Telegram User ID. You can get this from the bot's console output when you send /profile.
3. Run the following management command, replacing <your_user_id> with your actual ID:

   python manage.py set_admin <your_user_id> --grant

License

This project is licensed under the MIT License.