# Mini App startup JSON fix — v0.20.1

এই patch `Unable to start / An unexpected error occurred` troubleshooting-এর সময় পাওয়া JSON decoding bug ঠিক করে। Screenshot-এর request ID একা hosting-এর exception প্রমাণ করে না; নিচের bug-টি project-এর installed mysql2 driver দিয়ে স্থানীয়ভাবে পুনরুৎপাদন করা হয়েছে।

## কারণ ও পরিবর্তন

Project-এর mysql2 3.24.3 MariaDB extended metadata-সহ JSON এবং MySQL native JSON স্বয়ংক্রিয়ভাবে decode করে। কিন্তু repositories ইতিমধ্যে string JSON-এর জন্য `JSON.parse()` ব্যবহার করে। ফলে stored JSON string `"Telegram Task Earning"` driver থেকে `Telegram Task Earning` হয়ে এলে দ্বিতীয় `JSON.parse()` ব্যর্থ হয়। `"true"`-এর মতো string ভুলভাবে boolean-এও রূপান্তরিত হতে পারে। App settings ও maintenance message পড়ার সময় এর প্রভাব পড়ে।

`src/core/database/mysql.js`-এর connection pool-এ `jsonStrings: true` যোগ করা হয়েছে। এখন driver JSON text অক্ষত ফেরায় এবং repository একবার decode করে। [mysql2-এর MariaDB documentation](https://sidorares.github.io/node-mysql2/docs/documentation/mariadb-data-types) এই option-এর আচরণ ব্যাখ্যা করে।

## Hosting-এ প্রয়োগ

1. এই patch ZIP `/home/peglhpszdl/nodebot.monaklab.com/` folder-এ extract করুন। একই নামের patch files replace করুন। ZIP-এ সরাসরি `src/`, `bin/`, `tests/`, `docs/`, `acceptance/` আছে।
2. cPanel → Setup Node.js App থেকে application **Restart** করুন। চালু process-এর পুরোনো connection pool বদলাতে restart প্রয়োজন।
3. Telegram Mini App পুরো বন্ধ করে bot থেকে আবার খুলুন।

নতুন dependency install, migration, seed বা database reset দরকার নেই। `.env`, startup file এবং `package.json` এই patch-এ নেই।

## Error থাকলে diagnostic command

`package.json`-এর বিদ্যমান `scripts` object-এ এই entry যোগ করুন; পাশের entry অনুযায়ী comma দিন:

```json
"diagnose:miniapp": "node bin/diagnose-miniapp.js"
```

Mini App-এ **Try again** চাপার পর cPanel-এর **Run JS Script** থেকে `diagnose:miniapp` চালিয়ে output পাঠান। SSH থাকলে application-এর Node environment-এ চালানো যায়:

```bash
cd /home/peglhpszdl/nodebot.monaklab.com
node bin/diagnose-miniapp.js
```

একটি request ID অনুযায়ী log বাছতে চাইলে:

```bash
node bin/diagnose-miniapp.js --request-id=5fcf6072-e38d-4ff7-8b89-386eeb883d7e
```

Command বর্তমান config দিয়ে release schema, maintenance, public settings, links, currency, theme ও feature flags পড়ে। Active user পাওয়া গেলে সর্বশেষ active user-এর bootstrap data গঠন করে যাচাই করে; user data output-এ দেয় না। নির্দিষ্ট application log পাওয়া গেলে সর্বশেষ matching HTTP errors-এর code, message ও location দেখায়।

Database পরীক্ষা একটি `READ ONLY` transaction-এ চলে, শেষে rollback করে। কোনো user তৈরি বা login, session refresh, reward, Telegram message বা migration চালায় না। নতুন public diagnostic endpoint যোগ করে না। সর্বোচ্চ 25 seconds-এ command বন্ধ হয়; timeout হলে সর্বশেষ step output-এ থাকে।

Log scanning প্রতি file-এর শেষ 128 KiB এবং সর্বোচ্চ পাঁচটি matching error পর্যন্ত সীমিত। Application-এর বাইরে configured log directory বা symlink অনুসরণ করে না। তাই log না পাওয়া মানে server-এ error নেই—এমন নয়। Configured password, secret ও token output থেকে mask করা হয়; SQL statement, query parameters, cookies ও request body output করা হয় না।

`returncode: 0` মানে এই সীমিত diagnostic checks-এ failure পাওয়া যায়নি। এটি live Telegram login বা HTTP middleware test নয় এবং app পুরোপুরি ঠিক হয়েছে বলে ঘোষণা করে না। Output-এ `fixed: false` diagnostic command-এর এই সীমাটি বোঝায়।

## যাচাই

Installed mysql2-এর text, binary, static text ও static binary parser দিয়ে MySQL/MariaDB JSON scalar ও object decoding পরীক্ষা করা হয়েছে। পুরোনো policy-তে failure ও নতুন pool policy-তে সঠিক ফল যাচাই করা হয়। Diagnostic tests read-only query guard, stage reporting, secret masking, bounded logs ও user-data omission পরীক্ষা করে।

সম্পূর্ণ quality-check output: `docs/MINIAPP-STARTUP-QUALITY-CHECK.txt`। প্রকৃত hosting-এ Telegram login ও full database acceptance এখনো চালানো হয়নি।