# 🤖 Rambot Todo Bot & Telegram Mini App

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PHP Version](https://img.shields.io/badge/PHP-%3E%3D%208.0-777bb4.svg?logo=php)](https://www.php.net/)
[![Telegram Bot API](https://img.shields.io/badge/Telegram%20Bot%20API-v7.0%2B-0088cc.svg?logo=telegram)](https://core.telegram.org/bots/api)
[![MySQL](https://img.shields.io/badge/MySQL-8.0%2B-4479a1.svg?logo=mysql&logoColor=white)](https://www.mysql.com/)

A premium, modern task management system powered by a Telegram Bot and a native Telegram Mini App (TMA). Designed with an elegant PHP backend using PSR-4 autoloading and a vanilla HTML5/JS/CSS frontend.

سامانه پیشرفته و هوشمند مدیریت تسک و برنامه‌ریزی تیمی رم‌بات (Rambot Todo) در بستر ربات و مینی‌اپ تلگرام. طراحی شده با معماری مدرن شیءگرا در سمت بک‌اند و رابط کاربری تعاملی و زیبا در سمت مینی‌اپ.

---

## 📸 Overview / پیش‌نمایش

- **Bot Username / آیدی ربات:** [@todorambot](https://t.me/todorambot)
- **Features / ویژگی‌ها:**
  - 📝 **Task Management**: Create, filter, prioritize, and track tasks.
  - ⏱ **Time Tracker**: Start/stop task sessions with live work location reports.
  - 🗺 **Location Handler**: Geolocation check-ins/check-outs for field personnel.
  - 💳 **Star Payments**: Purchase digital items using Zarinpal and Telegram Stars.
  - 🧠 **AI Integration**: AI assistant recommendations and automated sprint reports.

---

## 📂 Project Structure / ساختار پروژه

```text
todo/
├── .github/workflows/    # CI/CD deployment pipelines (GitHub Actions)
├── api/                  # Backend REST APIs for the Mini App
│   ├── log_error.php     # Centralized logging for frontend errors
│   └── get_user_info.php # Fetch user profile info to prefill forms (new)
├── assets/               # Static images, icons, and media files
├── classes/              # Core PHP domain classes & handlers
│   ├── Handler/          # Sub-handlers for Callback Queries (Sprint, Project, etc.)
│   ├── BotHandler.php    # Main Bot handler class (decomposed using Traits)
│   ├── Database.php      # Database abstractions and query handlers
│   └── Logger.php        # Centralized system logger (with admin Telegram alerts)
├── config/               # System and date configurations
├── cronjobs/             # Scheduled background tasks (cron)
├── json/                 # Offline geographic database (cities, countries)
├── log/                  # Centralized log storage (writable)
├── mini-app/             # Front-end Telegram Mini App source code
├── payment/              # Payment processors (Zarinpal & Telegram Stars)
├── public/               # Public web folder (Webhook entry points)
│   ├── bot.php           # Telegram Webhook endpoint
│   └── diagnose.php      # Diagnostic utility dashboard
└── composer.json         # PSR-4 autoloading config
```

---

## 🛠️ Diagnostics & Webhook Control / سامانه عیب‌یابی

This project includes a standalone diagnostic dashboard located at `public/diagnose.php` which allows admins to troubleshoot deployment issues on cPanel hosts in real time:

ابزار مدیریت و عیب‌یابی مستقل سیستم در مسیر `public/diagnose.php` به صورت زنده وضعیت سرور را تحلیل می‌کند:

- **Database Connection Check**: Validates database username, password, and connection latency.
- **Write Permissions Audit**: Verifies read/write permissions on critical folders (`log/`, root `.`, and JSON files).
- **Telegram API Ping**: Tests internet connectivity and IP blacklisting to Telegram API using `getMe`.
- **Automatic Webhook Setter**: Detects the host's configuration and registers/updates the webhook URL targeting `public/bot.php` at the click of a button.

> [!CAUTION]
> **Security Alert / توصیه امنیتی:** 
> This tool exposes sensitive configurations. Remember to delete `diagnose.php` from your server or restrict directory access once debugging is complete.
> این ابزار اطلاعات حساسی از سرور را نمایش می‌دهد. حتماً پس از اتمام کار، این فایل را از روی هاست حذف کنید یا دسترسی به آن را محدود نمایید.

---

## ⚙️ Host & Permissions Configuration / تنظیمات دسترسی هاست

Ensure the following permissions are configured on your cPanel or target server for smooth operation:

برای جلوگیری از خطای `Permission Denied` در نوشتن لاگ‌ها و وضعیت موقت کاربران، دسترسی‌های زیر را روی هاست تنظیم کنید:

| Path / مسیر | Perm / سطح دسترسی | Description / توضیحات |
| :--- | :---: | :--- |
| **`.` (Root Directory)** | `755` / `777` | Required to initialize temporary state files. |
| **`log/`** | `777` | Destination for `php_errors.log` and `request.json` log records. |
| **`parent_ids.json`** | `666` | User state tracking storage. |
| **`active_task_views.json`** | `666` | Active task viewer states. |

*These permissions are automatically enforced during deployment using the `.github/workflows/deploy.yml` pipeline.*

---

## 🚀 Installation & Setup / راه‌اندازی پروژه

### 1. Clone & Install Dependencies
```bash
git clone https://github.com/ramtinmehraz/todo.git
cd todo
composer install --no-dev
```

### 2. Environment Setup
Create a `.env` file in the root directory:
```env
APP_NAME=todo
APP_ENV=production
APP_DEBUG=false

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_db_name
DB_USERNAME=your_db_user
DB_PASSWORD=your_db_password

BOT_TOKEN=your_telegram_bot_token
BOT_LINK=https://t.me/your_bot_username?start=
```

### 3. Deploy & Set Webhook
1. Upload the files to your server (e.g., `public_html/Rambot/todo/`).
2. Point your domain or subdirectory correctly.
3. Open your browser and navigate to `https://yourdomain.com/todo/public/diagnose.php`.
4. Click the **"Set Webhook / ست کردن وبهوک"** button to register your bot.

---

## 📜 License / لایسنس
This project is open-source and available under the [MIT License](LICENSE).
این پروژه تحت لایسنس MIT منتشر شده و توسعه آن برای عموم آزاد است.