# BoostWithKagujje - Phase 3 Setup Guide

## 📋 Telegram Bot Integration Setup

### Step 1: Create Telegram Bots

1. Open Telegram and search for **@botfather**
2. Send `/start` and follow instructions
3. Send `/newbot` to create a new bot
4. Enter name: `BoostWithKagujje User Bot`
5. Enter username: `boost_kagujje_user_bot`
6. Copy the **token** (example: `123456789:ABCDefGHIJKlmnoPQRSTuvWxyz1234567`)
7. Repeat for admin bot: `BoostWithKagujje Admin Bot`

### Step 2: Configure Environment Variables

Your Telegram credentials are already configured in `.env`:

```env
# Telegram Bot Tokens (Already set)
TELEGRAM_USER_BOT_TOKEN=8666723098:AAFGA13TlH_tcOKCVULKpPEhcVfhwplPZXQ
TELEGRAM_ADMIN_BOT_TOKEN=8666723098:AAFGA13TlH_tcOKCVULKpPEhcVfhwplPZXQ

# Admin Chat ID (Already set)
TELEGRAM_ADMIN_CHAT_IDS=2102059396

# Enable features
TELEGRAM_WEBHOOK_ENABLED=1
TELEGRAM_WEBHOOK_URL=https://boost.kagujje.com/webhooks/telegram.php
```

**If these values are NOT in your `.env` file:**
1. Open `.env` in a text editor
2. Add the above lines
3. Save the file

### Step 3: Run Database Migration

```bash
php database/migrate.php 003
```

This adds:
- `telegram_user_id` column to users table
- `telegram_chat_id` column to users table
- `settings` table for configuration
- `telegram_logs` table for debugging

### Step 4: Register Webhooks

```bash
php config/telegram-config.php register https://boost.kagujje.com/webhooks/telegram.php
```

### Step 5: Verify Setup

```bash
php config/telegram-config.php info user
php config/telegram-config.php info admin
```

---

## 🤖 User Bot Commands

Users can interact with the bot using commands:

| Command | Description |
|---------|-------------|
| `/start` | Welcome message & quick start |
| `/balance` | Check account balance |
| `/services` | Browse available services |
| `/orders` | View order history |
| `/deposit` | Deposit instructions |
| `/support` | Contact support |
| `/help` | All available commands |

### User Bot Flow:
1. User sends `/start` → Links Telegram account
2. User sends `/services` → Shows available services
3. User redirects to website to place order
4. User sends `/orders` → Shows order status
5. Order auto-updates when status changes

---

## ⚙️ Admin Bot Commands

Admin-only bot for monitoring:

| Command | Description |
|---------|-------------|
| `/start` | Welcome message |
| `/stats` | Platform statistics (users, balance, revenue) |
| `/orders` | Recent orders (last 5) |
| `/users` | User statistics (active, suspended) |
| `/settings` | Configuration management |

### Admin Bot Features:
- Automatic alerts on:
  - New large orders (>$100)
  - Payment deposits
  - Service sync completions
  - System errors

### Admin Notifications:
Add admin chat ID to enable notifications:

```bash
curl "https://api.telegram.org/botTOKEN/getUpdates"
```

Get your chat ID from the response, then add to `TELEGRAM_ADMIN_CHAT_IDS`.

---

## 🔄 Cron Jobs Setup

### In cPanel:

1. Go to **Cron Jobs**
2. Set time zone to your preference
3. Add these jobs:

```
# Service Sync (Every hour)
0 * * * * /usr/bin/php /home/kagujje/public_html/cronjobs/sync_services.php

# Email Queue (Every 5 minutes)
*/5 * * * * /usr/bin/php /home/kagujje/public_html/cronjobs/process_emails.php

# Order Status Sync (Every 15 minutes)
*/15 * * * * /usr/bin/php /home/kagujje/public_html/cronjobs/sync_order_status.php
```

### Log Files:
Check logs in `/cronjobs/logs/`:
- `sync_services.log` - Service sync history
- `email_queue.log` - Email processing log
- `order_sync.log` - Order status sync history

---

## 💰 Profit Model Verification

### 80% Markup Calculation

The platform applies 80% markup to all service prices:

```
Display Price = Provider Price × 1.80

Example:
- Provider charges: $10
- Display to user: $18
- Platform profit: $8 (44.4% of display price)
```

### Verification:
Check [OrderController.php](../app/controller/OrderController.php#L15):
```php
const PROFIT_MARKUP = 0.80;
$displayPrice = $basePrice * (1 + self::PROFIT_MARKUP);
```

---

## 🔒 Security Checklist

- [ ] Telegram tokens stored in `.env` (not in code)
- [ ] Admin chat IDs configured securely
- [ ] Webhook URL uses HTTPS
- [ ] Database backups configured
- [ ] Email queue secured against injection
- [ ] Order prices verified on checkout
- [ ] API keys invalidated after security incidents
- [ ] Admin panel password strong (12+ chars)

---

## 📊 Testing

### Test User Bot:
1. Message the user bot `/start`
2. Try commands: `/balance`, `/services`, `/orders`

### Test Admin Bot:
1. Message admin bot `/start`
2. Try commands: `/stats`, `/orders`, `/users`

### Test Payment:
1. Click "Deposit" in user panel
2. Complete Marzpay payment
3. Verify balance updates
4. Check admin bot receives notification

### Test Service Sync:
```bash
php cronjobs/sync_services.php
```

Check `cronjobs/logs/sync_services.log` for results.

---

## 🆘 Troubleshooting

### Webhook not receiving messages:
1. Verify URL is HTTPS: `https://boost.kagujje.com/webhooks/telegram.php`
2. Test URL manually: `curl -X POST https://boost.kagujje.com/webhooks/telegram.php`
3. Check nginx/Apache logs for 404/500 errors
4. Re-register webhook: `php config/telegram-config.php delete && php config/telegram-config.php register`

### Messages not processing:
1. Check `telegram_logs` table for errors
2. Verify tokens in `.env` are correct
3. Check admin chat IDs if admin bot not responding
4. Look at PHP error logs: `/var/log/php-errors.log`

### Order status not updating:
1. Run manually: `php cronjobs/sync_order_status.php`
2. Check MrGoViral API connection in [OrderController](../app/controller/OrderController.php)
3. Verify API credentials in `app/config.php`

### Emails not sending:
1. Check `email_queue` table for pending emails
2. Run manually: `php cronjobs/process_emails.php`
3. Verify mail server configuration: `php -i | grep -i mail`
4. Check logs: `cronjobs/logs/email_queue.log`

---

## 📞 Support

For issues or questions:
- Email: admin@kagujje.com
- Telegram: @boostwithkagujje
- Website: https://boost.kagujje.com

---

## 📝 Maintenance

### Weekly:
- Check telegram_logs for errors
- Review admin bot alerts
- Verify payment flows working

### Monthly:
- Clean old logs (>30 days) in telegram_logs
- Review profit margins (should be 80%)
- Test webhook connectivity
- Update service catalog

### Quarterly:
- Security audit of API keys
- Database optimization
- Performance review

---

## 🎯 Phase 3 Completion Status

- ✅ User Authentication & auto-approval
- ✅ Order Management with 80% markup
- ✅ Telegram Bot Integration (User + Admin)
- ✅ Payment Processing with Marzpay webhooks
- ✅ Service Synchronization engine
- ✅ Database migrations
- ✅ Cron job setup
- ✅ Configuration files

**Ready for:** User panel templates, API endpoints, Admin dashboard customization
