TELEGRAM GIVEAWAY & VOTING BOT — বাংলা নির্দেশিকা
=================================================

প্রয়োজন
-------
- PHP 8.1 বা নতুন সংস্করণ
- MySQL 5.7+ / MySQL 8
- PHP extension: PDO, pdo_mysql, cURL, OpenSSL, JSON
- HTTPS-সহ একটি ওয়েব হোস্টিং
- Telegram BotFather থেকে তৈরি Bot Token
- Bot-কে নির্ধারিত Telegram channel-এ Administrator করতে হবে

ইনস্টলেশন
---------
1. ZIP extract করে সব ফাইল আপনার hosting-এর public_html বা নির্দিষ্ট সাবফোল্ডারে upload করুন।
2. cPanel থেকে MySQL Database ও Database User তৈরি করে user-কে database-এর প্রয়োজনীয় privileges দিন।
3. ব্রাউজারে https://আপনার-ডোমেইন/ফোল্ডার/install.php খুলুন।
4. DB Host, DB Name, DB Username, DB Password, Bot Token, Numeric Admin ID এবং Channel Username/ID দিন।
5. Dashboard-এর জন্য নিজের শক্তিশালী Admin Password দিন। এটি password_hash() দিয়ে সংরক্ষিত হয়।
6. Install বোতাম চাপুন। সফল হলে config.php স্বয়ংক্রিয়ভাবে তৈরি হবে।
7. সফলতার পর install.php মুছে ফেলুন বা server-level access দিয়ে বন্ধ করুন। config.php web থেকে সরাসরি পড়া যায় কি না পরীক্ষা করুন; সম্ভব হলে public_html-এর বাইরে রাখুন বা hosting protection ব্যবহার করুন।
8. admin.php খুলে dashboard password দিয়ে লগইন করুন। এখান থেকে নতুন Giveaway তৈরি, প্রার্থী যোগ এবং সরাসরি Channel-এ Publish করা যাবে।
9. Bot Settings অংশে Verify Bot Connection চাপুন। Bot Name, Username এবং ID Telegram getMe API থেকে আসবে।
10. Webhook URL ঘরে https://আপনার-ডোমেইন/ফোল্ডার/index.php লিখে Set HTTPS Webhook চাপুন। এতে chat_member update গ্রহণ চালু হবে।
11. Bot-কে configured channel-এ Administrator করুন। Channel-এ post করার অনুমতি এবং সদস্যদের status দেখার উপযুক্ত permission দিন। সদস্য চ্যানেল ছাড়লে ভোট স্বয়ংক্রিয়ভাবে বাতিল করার জন্য এই ধাপটি জরুরি।

Telegram ব্যবহার
----------------
Admin Bot-এ /start চাপলে স্থায়ী Reply Keyboard মেনু আসবে। কমান্ড না লিখে নিচের বাটন ব্যবহার করুন:
- ➕ Create Giveaway — নতুন giveaway তৈরি
- 📋 All Giveaways — সব giveaway ও Pause/Resume/Stop controls
- 📊 Statistics — ব্যবহারকারী, giveaway ও vote পরিসংখ্যান
- ⚙️ Bot Settings — Bot identity ও channel তথ্য
- ❌ Cancel — চলমান creation flow বাতিল

Create Giveaway flow-তে Title, Description এবং Minimum votes লিখুন। Candidate ধাপে প্রতিটি candidate-এর নাম আলাদা মেসেজে পাঠান। Prize delivery-এর জন্য format: নাম | Telegram numeric ID (যেমন Munna | 123456789)। প্রতিটি নাম যোগ হলে bot candidate list দেখাবে। কমপক্ষে ২টি নাম যোগ করার পর ✓ Done বাটন চাপুন। এরপর document/video prize পাঠান অথবা Skip Prize চাপুন। সবশেষে Preview দেখে 🚀 Publish Giveaway চাপুন। Giveaway channel-এ Poll Board style পোস্ট ও voting buttons-সহ প্রকাশিত হবে।
ভোট ও সদস্যপদ
-------------
- প্রত্যেক Telegram user একটি giveaway-তে একবার ভোট দিতে পারে।
- ভোটের আগে configured channel membership যাচাই হয়।
- একই Giveaway-তে কেউ দ্বিতীয়বার ভোট দিলে তাকে শুধু “আপনি ইতিমধ্যে একটি ভোট দিয়েছেন” বার্তা দেখানো হয়; শুধু দ্বিতীয়বার চাপার কারণে কোনো Warning বা Disqualification দেওয়া হয় না।
- কেউ configured channel থেকে বেরিয়ে গেলে Telegram-এর chat_member update পাওয়া মাত্র active/paused Giveaway-তে তার ভোট বাতিল (invalid) করা হয় এবং চ্যানেলের ভোটসংখ্যা আপডেট হয়।
- পরে আবার channel-এ যোগ দিয়ে একই Giveaway-র Vote button চাপলে আগের বাতিল ভোটটি পুনরায় সক্রিয় হবে; একই সময়ে এক ব্যক্তির একটিই বৈধ ভোট থাকবে।
- এই Leave/Join tracking-এর জন্য Bot-কে channel Administrator করতে হবে এবং Dashboard থেকে Webhook সেট করতে হবে; webhook-এর allowed_updates-এ chat_member চালু রাখা আছে। Channel username/ID config-এর সঙ্গে হুবহু মিলতে হবে।

Admin Dashboard
---------------
- Dashboard overview-তে users, active/paused/completed giveaway, votes এবং disqualified users দেখা যায়।
- Premium responsive Admin Dashboard থেকে শিরোনাম, বিবরণ, minimum votes এবং একাধিক Candidate-এর নাম ও Username দিয়ে Giveaway তৈরি করা যায়।
- Create & Publish চাপলে Bot-এর Channel Admin permission যাচাই করে সরাসরি Channel-এ Poll Board প্রকাশ হয়।
- Channel permission না থাকলে Giveaway Draft হিসেবে সংরক্ষিত থাকবে; Channel-এ Bot-কে Admin করার পর Dashboard-এর Publish Draft বাটন দিয়ে আবার প্রকাশ করা যাবে।
- Giveaway pause/resume/stop করা যায়।
- Bot identity ও webhook status দেখা যায়।
- Failed prize delivery থেকে Retry করা যায়।
- Dashboard-এর প্রতিটি action POST ও CSRF token দিয়ে সুরক্ষিত; login password hash করা থাকে।

Winner ও tie policy
-------------------
প্রার্থী minimum votes পূরণ করলে সর্বোচ্চ valid vote পাওয়া candidate winner হয়। সমান ভোট হলে candidate-এর database ID সবচেয়ে কম—অর্থাৎ আগে তৈরি হওয়া candidate—জয়ী হয়। কেউ minimum vote পূরণ না করলে কোনো winner ঘোষণা হয় না। Results database-এ সংরক্ষিত হয়।

Prize delivery সীমাবদ্ধতা
------------------------
Telegram Bot সাধারণত কোনো user-কে private message পাঠাতে পারে না, যতক্ষণ না user আগে bot-কে /start করে বা নিজে bot-এর সঙ্গে conversation শুরু করে। তাই winner-কে আগে bot-এ /start করতে বলুন। Delivery ব্যর্থ হলে Dashboard-এ failed status দেখাবে; অনুমোদিত admin Retry করতে পারবেন।

গুরুত্বপূর্ণ নিরাপত্তা
--------------------
- config.php-তে Bot Token, database password ও webhook secret থাকে। ফাইলটি কাউকে দেবেন না।
- Bot Token dashboard-এ কখনো সম্পূর্ণ দেখানো হয় না।
- HTTPS ছাড়া webhook ব্যবহার করবেন না।
- Admin ID অবশ্যই নিজের Telegram numeric ID দিন।
- Hosting-এ directory listing বন্ধ রাখুন।
- PHP error display production-এ বন্ধ রাখুন; error log private রাখুন।
- install.php সফলতার পর মুছে ফেলুন।
- শক্তিশালী dashboard password ব্যবহার করুন।
- Backup রাখুন এবং database user-কে শুধু প্রয়োজনীয় database-এ সীমাবদ্ধ রাখুন।

পরীক্ষার সীমা
-------------
এই প্যাকেজে PHP syntax check করা হয়েছে যদি PHP CLI পরিবেশে পাওয়া যায়। এই build environment-এ আপনার hosting database, Bot Token, live Telegram channel বা webhook access নেই; তাই live API/DB integration test সম্পন্ন হয়েছে বলে দাবি করা হচ্ছে না। Hosting-এ install করার পর Verify Bot Connection এবং webhook status দিয়ে বাস্তব সংযোগ পরীক্ষা করুন।

গুরুত্বপূর্ণ বাস্তব সীমাবদ্ধতা
----------------------------
- Telegram channel-এ ভোট প্রকাশিত হয়; bot-এর membership verification-এর জন্য channel admin access দরকার।
- Webhook secret header Telegram থেকে আসা update যাচাই করে।
- Telegram file_id database-এ রাখা হয়; prize file server-এ upload করা হয় না।
- Prize send-এর ক্ষেত্রে bot private chat শুরু না করা user-কে DM করতে পারবে না।


নতুন Button-based Giveaway flow:
- Create Giveaway বাটন থেকে Title, Description ও Minimum Votes দিন।
- প্রতিটি Candidate-এর নাম এবং Telegram Username আলাদাভাবে দিন; Username না থাকলে বোতাম আছে।
- Add Another / Done বাটন দিয়ে Candidate list শেষ করুন।
- Prize file দিতে চাইলে হ্যাঁ, না চাইলে না চাপুন।
- Preview দেখে হ্যাঁ, Publish করুন চাপলে লিংক করা Channel-এ পোস্ট হবে।
- Publish করার আগে Bot-কে Channel Admin এবং Post Messages permission দিতে হবে।
- স্প্যাম/duplicate vote-এ warning count বাড়ে; ৩ বার হলে user-এর ভোট বাতিল ও voting থেকে disqualify করা হয়।
- Prize winner-কে DM পাঠাতে হলে বিজয়ীকে আগে Bot-এ /start করতে হবে; Telegram Bot username দিয়ে নতুন private chat শুরু করতে পারে না।
- Candidate username সংরক্ষিত হয়। যদি ঐ username আগে Bot-এ /start করে থাকে, তার numeric Telegram ID মিলিয়ে prize DM পাঠানোর জন্য রাখা হয়।


নতুন Poll Board সুবিধা (আপডেট):
- প্রতিটি Candidate-এর জন্য আলাদা Share বাটন আছে। Share করা লিংক থেকে ব্যবহারকারী বট Start করলে Channel membership যাচাই করে ভোট গণনা হবে।
- Channel-এ সদস্য না হলে Join Channel বাটন দেখাবে; Join করার পর “আমি Join করেছি” চাপলে আবার যাচাই হবে।
- Poll Board-এর নিচে Admin Contact বাটন এবং স্প্যামবিরোধী সতর্কবার্তা থাকবে।
- একই Giveaway-তে একজনের ভোট একবারই গণনা হবে।
- Telegram-এর আসল Premium animated/custom emoji দেখাতে হলে আপনার Telegram Premium custom emoji-এর নির্দিষ্ট custom_emoji_id প্রয়োজন; এই ZIP-এ নিরাপদ Unicode emoji ব্যবহার করা হয়েছে।


ব্যক্তিগত বট অ্যাক্সেস:
- Admin ID ছাড়া অন্য কেউ সাধারণ /start করলে বট জানাবে যে এটি শুধুমাত্র ডেভেলপার/অনুমোদিত অ্যাডমিনের জন্য এবং ডেভেলপারের সঙ্গে যোগাযোগের বাটন দেখাবে।
- ভোটের জন্য Channel-এর Poll Board থেকে আসা নির্দিষ্ট Vote/Share deep link আগের মতো কাজ করবে; সাধারণ ব্যবহারকারী বটের Admin menu বা Giveaway creation নিয়ন্ত্রণ করতে পারবে না।
- Dashboard-এ প্রবেশ করতে আলাদা Admin Password প্রয়োজন।

============================================================
নতুন সংস্করণ: BOT + WEBSITE DUAL CONTROL
============================================================

এই সংস্করণে Telegram Bot এবং Website Dashboard একই MySQL Database ব্যবহার করে।

Telegram Bot-এর Admin Menu:
- ➕ Giveaway তৈরি: ধাপে ধাপে Title, Description, Minimum Votes, Candidate Name ও Username যোগ করুন।
- 📋 সব Giveaway: সাম্প্রতিক Giveaway এবং Pause / Resume / Stop নিয়ন্ত্রণ দেখুন।
- 📊 পরিসংখ্যান: ব্যবহারকারী, ভোট, চলমান ও বন্ধ Giveaway দেখুন।
- ⚙️ বট সেটিংস: Bot identity ও সংযুক্ত Channel দেখুন।
- 🔧 Webhook ঠিক করুন: HTTPS hosting থেকে বটের Webhook পুনরায় সেট করার চেষ্টা করে।

Website Dashboard:
- একই Database থেকে Giveaway তৈরি ও Publish করা যায়।
- Draft Publish, Pause, Resume, Stop এবং prize delivery retry করা যায়।
- প্রার্থীভিত্তিক ভোটের বিস্তারিত দেখা যায়।
- Premium responsive glass dashboard এবং motion effects রয়েছে।

যদি Telegram-এ /start চাপলে উত্তর না আসে:
1. Website-এর admin.php খুলে Dashboard-এ লগইন করুন।
2. Bot Settings অংশে “স্বয়ংক্রিয় Webhook সেট করুন” চাপুন।
3. Telegram Bot-এ ফিরে /start পাঠান।
4. Webhook URL অবশ্যই HTTPS হতে হবে এবং index.php সার্ভারে সরাসরি খুলতে হবে।
5. Bot Token সঠিক, PHP cURL + PDO MySQL সক্রিয়, config.php readable এবং database credentials সঠিক কিনা দেখুন।
6. Telegram Channel-এ Bot-কে Admin করুন; Post Messages permission দিন.

গুরুত্বপূর্ণ: Webhook ঠিক করার জন্য Dashboard-এ একবার লগইন করে Auto Webhook বাটন চাপা সবচেয়ে নির্ভরযোগ্য উপায়। Bot-এর ভিতরের Webhook বাটন কেবল তখন কাজ করবে যখন Telegram ইতিমধ্যেই index.php-তে আপডেট পাঠাতে পারছে।

নিরাপত্তা:
- config.php কখনো কারও সঙ্গে শেয়ার করবেন না।
- install.php ইনস্টলেশনের পর মুছে ফেলুন বা rename করুন।
- Dashboard password শক্তিশালী রাখুন।
- Bot Token প্রকাশ পেলে BotFather থেকে regenerate করুন।

এই ZIP-এ config.php নেই। বিদ্যমান config.php এবং Database রেখে index.php ও admin.php আপলোড করে replace করুন। install.php শুধু নতুন ইনস্টলেশনের জন্য; পুরোনো Database-এর উপর পুনরায় চালাবেন না।


এই Full Version build-এর অতিরিক্ত নোট
-------------------------------------
- Channel post-এর প্রতিটি candidate-এর জন্য Vote button থাকবে; Share button নেই।
- Telegram Bot-এর /start থেকে Admin হলে Reply Keyboard menu দেখানো হয়।
- Bot ও Website উভয় দিক থেকে একই polls/candidates/votes database পরিচালিত হয়।
- সাধারণ ব্যবহারকারীর /start-এ বাংলা private-bot notice ও developer contact button দেখানো হয়।
- Telegram API সীমাবদ্ধতা: কোনো user bot-কে আগে Start না করলে bot তার username দিয়ে private warning বা prize file পাঠাতে পারে না।


সংশোধনী (Minimum Vote / Live Poll): Minimum Vote কেবল বিজয়ী হওয়ার যোগ্যতার শর্ত; এটি ভোট বন্ধ করে না। অ্যাডমিন Stop না করা পর্যন্ত Poll active থাকবে। প্রতিটি ভোটের পর পোস্টের ভোটসংখ্যা আপডেট হবে এবং প্রার্থীদের Vote বাটনগুলো আগের মতোই থাকবে।


নতুন Minimal UI ফিচার: 
- Telegram Admin Menu-তে 🏆 লাইভ লিডারবোর্ড এবং 🛡️ নিরাপত্তা কেন্দ্র যোগ হয়েছে।
- Website Dashboard-এ একই ডেটাবেসভিত্তিক Leaderboard ও Security Center যোগ হয়েছে।
- Security log-এ vote counted, duplicate vote blocked, channel membership fail, channel leave, warning এবং rate-limit event সংরক্ষিত হয়।
- ১০ সেকেন্ডে ৮টির বেশি vote-button interaction হলে সাময়িকভাবে ওই interaction rate-limit করা হয়। Duplicate vote-এ নিজে থেকে warning বা ban দেওয়া হয় না।
- security_logs টেবিল স্বয়ংক্রিয়ভাবে তৈরি হবে; install.php-তেও schema যোগ করা হয়েছে।


নতুন Analytics / Winner / Countdown / Delivery ফিচার:
- Telegram ও Website একই polls/votes/deliveries Database ব্যবহার করে।
- পোল তৈরির সময় ১/৬/১২/২৪/৭২ ঘণ্টা অথবা সময়সীমা ছাড়া নির্বাচন করা যায়। সময় শেষ হলে cron চালালে পোল বন্ধ, ফলাফল প্রকাশ এবং Prize delivery হবে।
- Countdown cron URL: https://YOUR-DOMAIN/index.php?cron=WEBHOOK_SECRET (config.php-এর webhook_secret ব্যবহার করুন; গোপন রাখুন)। Hosting cPanel Cron Jobs-এ প্রতি মিনিটে এই URL curl/wget দিয়ে চালান।
- Webhook update এলেও মেয়াদোত্তীর্ণ active poll পরীক্ষা হয়; তবে নির্ভরযোগ্য স্বয়ংক্রিয় সময়মতো ফলাফলের জন্য প্রতি মিনিটের cron আবশ্যক।
- Analytics-এ আজ, গত ৭ দিন, স্বতন্ত্র ভোটার ও দৈনিক ভোট দেখা যায়। Winner নির্বাচন Stop/সময় শেষ হলে Minimum Vote-যোগ্য প্রার্থীদের মধ্যে সর্বোচ্চ বৈধ ভোটপ্রাপ্ত প্রার্থী; সমান হলে আগের candidate ID অগ্রাধিকার পায়।
- Prize file Telegram Bot থেকে পাঠাতে হলে বিজয়ীর Telegram numeric ID candidate record-এ থাকতে হবে এবং বিজয়ীকে আগে Bot Start করতে হবে। শুধু username দিয়ে private delivery সম্ভব নয়।


আপডেট: Minimal Analytics + Countdown + Winner + Prize Delivery
- Live Leaderboard menu ও dashboard section বাদ দেওয়া হয়েছে। Channel post-এ প্রার্থীর পাশে vote count থাকবে এবং ভোট পড়লে একই পোস্ট edit করে count আপডেট হবে।
- Advanced Security Center চালু আছে: rate-limit, duplicate-vote prevention, membership checks, warning/security logs।
- Giveaway তৈরি করার সময় Bangladesh time অনুযায়ী শেষ তারিখ/সময় নির্বাচন করা যাবে। সময় ফাঁকা রাখলে manual Stop পর্যন্ত চলবে।
- Countdown নির্ভুল সময়ে চালাতে cPanel Cron Jobs-এ প্রতি মিনিটে এই URL চালান: https://YOUR-DOMAIN/index.php?cron=YOUR_WEBHOOK_SECRET । YOUR_WEBHOOK_SECRET হলো config.php-তে থাকা webhook_secret; এটি কাউকে প্রকাশ করবেন না।
- Website Dashboard-এর Prize File Upload থেকে PDF/ZIP/JPG/PNG/MP4/DOC/DOCX/TXT (সর্বোচ্চ ২০ MB) যুক্ত করা যাবে। Telegram Bot থেকে Document/Video পাঠানোর সুবিধাও আছে।
- Telegram ব্যক্তিগত Winner delivery-এর জন্য Winner-এর Telegram numeric ID প্রয়োজন এবং Winner-কে আগে bot Start করতে হবে। শুধু @username দিয়ে private file delivery সম্ভব নয়।
- referral credit / public multi-user self-service workspace এই build-এ সক্রিয় নয়; সেটির জন্য পৃথক tenant ownership, referral ledger এবং user-specific poll permissions যোগ করতে হবে।


============================================================
VERSION 3.0 — CONTROL CENTER ADD-ON
============================================================
নতুন ফাইল:
- app_common.php: shared dashboard/session/database helpers
- upgrade_v3.php: নতুন Wallet, Referral, Ad Session, Prize Claim ও Event tables
- settings.php: poll cost, referral reward, ad reward, ad URL/time, daily cap, branding/promotion
- wallet.php: Telegram ID দিয়ে credit add/deduct এবং ledger
- ads.php: two-step ad watch flow; URL uid parameter দিয়ে user session শুরু
- referral.php: pending referral approval/rejection ও reward ledger
- analytics.php: users, polls, votes, credits overview
- winner.php: prize claim delivery status monitor

আপগ্রেড:
1. আগে Database backup নিন।
2. ZIP-এর ফাইলগুলো পুরোনো ফোল্ডারে upload/replace করুন; config.php replace করবেন না।
3. আগে admin.php-তে লগইন করুন।
4. /upgrade_v3.php একবার খুলুন; সফল হলে ফাইলটি delete করুন।
5. Settings থেকে সব amount, ad URL, duration ও daily cap দিন।
6. Dashboard থেকে Settings/Wallet/Ads/Referral/Analytics/Winners খুলুন।

সীমাবদ্ধতা ও সতর্কতা:
- এই V3 add-on হলো বর্তমান single-owner installation-এর control center; এটি নিজে থেকে public multi-tenant signup বা আলাদা customer bot-token isolation চালু করে না।
- Ad viewer সময় মাপে, প্রকৃত বিজ্ঞাপন দেখা বা ad network-এর valid impression প্রমাণ করে না। কেবল incentivized iframe views অনুমোদিত provider ব্যবহার করুন।
- Referral panel reward approval করে; Telegram /start referral parameter capture যুক্ত না করা পর্যন্ত referral auto-registration সক্রিয় নয়।
- Prize claim status schema/panel প্রস্তুত; webhook deep-link token redemption ও winner-এর candidate-to-user matching যুক্ত না করা পর্যন্ত auto-claim live নয়। পুরোনো delivery logic আগের মতো কাজ করবে।
- Credits wallet/admin ledger প্রস্তুত; poll creation charge gate এখনো existing poll-create transaction-এ সংযুক্ত নয়। তাই credit deduct হচ্ছে বলে ধরে নেবেন না।
- PHP syntax check করা হয়েছে; live Telegram API, hosting MySQL, iframe advertiser এবং production webhook পরীক্ষা করা হয়নি।

Production deployment-এর আগে উপরের integration points সম্পূর্ণ করতে হবে।
