# GuaranteeApp — راهنمای استقرار (cPanel: وب + ربات) و نصب سیستم چاپ

> زمان تقریبی: وب ۱۵ دقیقه + ربات ۱۵ دقیقه. هرجا `_____` هست، مقدار هنگام نصب پر می‌شود.

---

## ۱. مقادیر موردنیاز

| # | مورد | از کجا | مقدار |
|---|---|---|---|
| ۱ | نام دیتابیس | cPanel → MySQL® Databases (با پیشوند cPanel) | `_____` |
| ۲ | یوزر دیتابیس | همان‌جا | `_____` |
| ۳ | رمز یوزر | خودتان (قوی) | `_____` |
| ۴ | TEST_KEY | رشتهٔ تصادفی (`SELECT UUID();`) | `_____` |
| ۵ | توکن ربات | @BotFather | `_____` |
| ۶ | chat_id ادمین‌ها | `/start` به خود ربات (§۶.۳) یا @userinfobot | `_____` |
| ۷ | آدرس نهایی پروژه | `https://_____/guarantee/` | `_____` |
| ۸ | مسیر خانگی cPanel (برای کرون CLI) | معمولاً `/home/<یوزر>` | `_____` |
| ۹ | کلید API اپ دسکتاپ | رشتهٔ تصادفی ≥ ۳۲ کاراکتر | `_____` |

> در cPanel نام دیتابیس و یوزر **پیشوند** `cpaneluser_` می‌گیرند؛ دقیقاً همان را در config بنویس.

### بررسی‌های پیش از شروع (روی هاست)
- نسخهٔ PHP ≥ ۸٫۰؛ افزونهٔ `pdo_mysql`، `curl`، `mbstring`.
- `post_max_size ≥ 8M` و `max_allowed_packet ≥ 8M` (پشتیبان قالب‌ها).
- اتصال خروجی HTTPS به `api.telegram.org` و `api.qrserver.com`.
- Cron با `php` CLI (وگرنه روش URL).

---

## ۲. دیتابیس

1. cPanel → **MySQL® Databases**: ساخت دیتابیس، ساخت یوزر با رمز قوی، اتصال یوزر به دیتابیس با **ALL PRIVILEGES**.
2. **phpMyAdmin** → دیتابیس → **Import** → `database.sql` (utf8mb4) ← ۱۱ جدول: `option_families, device_options, product_models, product_model_options, production_batches, products, warehouse_events, warranty_activations, telegram_admins, api_keys, label_template_backups`.
3. ثبت کلید API (تب SQL):
```sql
INSERT INTO api_keys (key_hash, workshop_name, active, created_at)
VALUES (SHA2('<کلید ردیف ۹>', 256), 'کارگاه', 1, NOW());
```

## ۳. `config.php`
```php
define('DB_NAME', '_____');  define('DB_USER', '_____');  define('DB_PASS', '_____');
define('TEST_KEY', '_____');
define('TELEGRAM_BOT_TOKEN', '_____');   // اختیاری برای وب؛ لازم برای ربات
// DB_HOST معمولاً localhost؛ APP_TIMEZONE = Asia/Tehran
```

## ۴. آپلود
1. ZIP از: `config.php, panel.php, warranty.php, test.php, database.sql, .htaccess, api/, lib/, assets/, logs/ (فقط .htaccess), telegram/`.
2. File Manager → `public_html` → پوشهٔ `guarantee` → Upload ZIP → Extract → حذف ZIP.
3. **Show Hidden Files** را بزن و مطمئن شو `.htaccess`ها منتقل شده‌اند (`.htaccess` ریشه، `lib/`، `logs/`).
4. ساب‌دامنه هم ممکن است؛ مسیرها نسبی‌اند و کد تغییر نمی‌کند.

## ۵. HTTPS (اجباری)
cPanel → **SSL/TLS Status** → Run **AutoSSL**. صفحات را فقط با `https://` باز کن.

### ۵.۱ تست وب (`test.php`)
1. `https://.../guarantee/test.php?key=<TEST_KEY>`
2. بخش ۱ (وضعیت سرور) همه ✅؛ ❌ «تنظیمات» = config ناقص؛ «اتصال» = نام/یوزر/رمز؛ «جدول‌ها» = Import ناقص.
3. بخش ۲: دکمه‌ها را **به ترتیب ۱ تا ۹** بزن (محصول تست، scan، تکراری، Orphan، خروج، فعال‌سازی، تکراری، استعلام، تلگرام) — همه ✅.
4. بخش ۳ (لاگ): رویدادها دیده شوند. سپس «پاک‌سازی دادهٔ تست».
5. روی گوشی: `panel.php` ← دوربین؛ `warranty.php?serial=TEST-WEB-0001`.
6. در پایان `test.php` را حذف کن یا `TEST_KEY` را خالی بگذار.

---

## ۶. ربات تلگرام

### ۶.۱ ساخت ربات
@BotFather ← `/newbot` ← نام و یوزرنیم (ختم به `bot`) ← توکن را در config (ردیف ۵) بگذار.

### ۶.۲ ثبت webhook
```
https://_____/telegram/setup_webhook.php?key=<TEST_KEY>&action=set
```
`"ok": true` یعنی موفق. بررسی: `action=info`؛ حذف: `action=delete`. خطا معمولاً یعنی HTTPS یا آدرس. **بعد از پایان راه‌اندازی `setup_webhook.php` را حذف کن** (webhook می‌ماند).

### ۶.۳ ثبت ادمین‌ها
هر ادمین به ربات `/start` بزند ← پاسخ می‌دهد «…chat_id شما: N» (یا @userinfobot). سپس در phpMyAdmin:
```sql
INSERT INTO telegram_admins (chat_id, name, active) VALUES ('<N>', 'نام ادمین', 1);
```

### ۶.۴ Cron گزارش ۲۰:۰۰
cPanel → **Cron Jobs**: `Minute 0, Hour 20, بقیه *`.
- CLI (ترجیحی): `php /home/<یوزر>/public_html/guarantee/telegram/daily_report.php`
- URL: `wget -q -O /dev/null "https://_____/telegram/daily_report.php?key=<TEST_KEY>"`
- ساعت کرون = ساعت سرور؛ اگر UTC است، ۳:۳۰ (و در تغییر ساعت تابستانی ۴:۳۰) اختلاف را لحاظ کن.
- تست فوری: URL بالا را در مرورگر باز کن؛ باید `sent: N/M` ببینی و گزارش برسد.

### ۶.۵ تست ربات

| # | تست | نتیجه |
|---|---|---|
| ۱ | `/start` | راهنما |
| ۲ | `/start` با اکانت ثبت‌نشده | «⛔️ … chat_id شما» |
| ۳ | `/inventory` | فهرست یا «انبار خالی است» |
| ۴ | `/report` | گزارش با تاریخ جلالی |
| ۵ | عکس QR | تاریخچهٔ سریال |
| ۶ | تایپ سریال | همان تاریخچه |
| ۷ | URL کرون | گزارش در همان لحظه |
| ۸ | لاگ در `test.php` | رویدادهای webhook/گزارش |

---

## ۷. نصب سیستم چاپ (کامپیوتر تولید)

۱) پیش‌نیازها: `04-BarTender-Printing §۱۲`. ۲) نصب اپ و تنظیم `ApiBaseUrl`، `ApiKey`، `WarrantyUrlTemplate`. ۳) ساخت پوشه‌ها و ACL. ۴) «بررسی BarTender». ۵) «تست اتصال به سرور». ۶) قالب‌ها: آماده‌سازی طبق `04 §۵` **یا** «بازیابی از سرور».

---

## ۸. عیب‌یابی

| علامت | علت | راه‌حل |
|---|---|---|
| صفحهٔ سفید / ۵۰۰ | خطای PHP / config ناقص | `test.php` بخش سلامت |
| «خطا در اتصال به دیتابیس» | نام/یوزر/رمز یا پیشوند cPanel | بررسی؛ یوزر به دیتابیس متصل باشد |
| همهٔ اسکن‌ها «در دیتابیس نیست» | هنوز سینک نشده | طبیعی؛ Orphan تا سینک بعدی |
| دکمهٔ دوربین خطا | HTTPS نیست / اجازه داده نشده | `https://` و Allow |
| متن فارسی به‌هم‌ریخته | Import بدون utf8mb4 / کش | Import مجدد با utf8mb4 |
| Rate limit | تست پشت‌سرهم | ۳۰/دقیقه/IP؛ یک دقیقه صبر |
| ربات جواب نمی‌دهد | webhook ثبت نشده / HTTPS | `action=info` |
| «⛔️ مجاز نیستید» برای ادمین | chat_id ثبت نشده یا `active=0` | INSERT عدد دقیق |
| `action=set` خطا | TEST_KEY خالی یا توکن غلط | config |
| «کد QR خوانده نشد» همیشه | خروجی هاست به api.qrserver.com بسته | سریال متنی؛ یا باز کردن خروجی / کتابخانهٔ PHP |
| آپلود قالب `sync/templates` خطا | `post_max_size`/`max_allowed_packet` کم | افزایش به ≥ ۸M |
| ساعت‌ها اشتباه | `APP_TIMEZONE` | `Asia/Tehran` |

## ۹. نکات امنیتی
- `.htaccess`ها را حذف نکن؛ `config.php` و `logs/` بسته می‌مانند.
- `setup_webhook.php` و (پس از تست) `test.php` را حذف کن.
- رمز DB، توکن ربات، TEST_KEY و کلید API را در چت/عکس منتشر نکن.
- `warranty.php` عمداً عمومی و فقط با Rate limit محافظت می‌شود.
- پشتیبان دورهٔ دیتابیس (cPanel Backup / export phpMyAdmin) توصیه می‌شود؛ بازیابی اپ به سرور متکی است.