No description
  • PHP 85.9%
  • CSS 12.1%
  • Shell 2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
MirAbolfazl b4c4b69d33 Implement background import worker functionality and logging
- Added `import-worker.php` script to manage background import workers.
- Introduced `start-workers.sh` and `stop-workers.sh` scripts for starting and stopping workers.
- Created `RateLimiter` class to manage rate limiting for import operations.
- Implemented `RuntimeLog` class for structured logging of method calls and responses.
- Added SQL migration to include `lease_until` column in `import_job_items` table.
- Enhanced `run.php` test suite to validate new logging and rate limiting features.
- Created `searchmuti.php` and `searchsingle.php` scripts for testing contact searches with logging.
- Updated `start-termux.sh` and `stop-termux.sh` scripts to integrate worker management.
2026-11-17 09:20:16 +03:30
app Implement background import worker functionality and logging 2026-11-17 09:20:16 +03:30
config Build Bale contact manager application 2026-11-14 20:52:56 +03:30
database Implement background import worker functionality and logging 2026-11-17 09:20:16 +03:30
public Implement background import worker functionality and logging 2026-11-17 09:20:16 +03:30
samples Implement background import worker functionality and logging 2026-11-17 09:20:16 +03:30
scripts Implement background import worker functionality and logging 2026-11-17 09:20:16 +03:30
tests Implement background import worker functionality and logging 2026-11-17 09:20:16 +03:30
var Build Bale contact manager application 2026-11-14 20:52:56 +03:30
.env.example Implement background import worker functionality and logging 2026-11-17 09:20:16 +03:30
.gitignore Build Bale contact manager application 2026-11-14 20:52:56 +03:30
composer.json Build Bale contact manager application 2026-11-14 20:52:56 +03:30
composer.lock Build Bale contact manager application 2026-11-14 20:52:56 +03:30
README.md Implement background import worker functionality and logging 2026-11-17 09:20:16 +03:30
searchmuti.php Implement background import worker functionality and logging 2026-11-17 09:20:16 +03:30
searchsingle.php Implement background import worker functionality and logging 2026-11-17 09:20:16 +03:30

مدیر مخاطبان بله

یک برنامه شخصی PHP برای نگهداری و بررسی مخاطبان حساب بله. برنامه فقط از قابلیت‌های موجود در بسته نصب‌شده aiobale/aiobale-php استفاده می‌کند: ورود با شماره/کد/رمز دومرحله‌ای، SearchContact برای جست‌وجوی مجاز، LoadUsers و LoadFullUsers برای اطلاعات پروفایل قابل‌دسترسی، و LoadAvatars به‌همراه GetFileUrl برای تصویرهای قابل‌دسترسی. تصویرها پس از دریافت در حافظه خصوصی برنامه ذخیره می‌شوند؛ نشانی‌های موقت بله نگهداری نمی‌شوند. شماره‌ها به دفترچه مخاطبان بله افزوده نمی‌شوند. این بسته ابزار رسمی بله نیست؛ استفاده از حساب شخصی و رعایت محدودیت‌های سرویس بر عهده کاربر است.

نیازمندی‌ها

  • PHP 8.2 یا جدیدتر با افزونه‌های PDO, pdo_mysql, json, mbstring, fileinfo
  • Composer
  • MySQL یا MariaDB
  • Apache با mod_rewrite و PHP Apache

نصب در Termux

در ریشه پروژه:

chmod +x scripts/*.sh
./scripts/install-termux.sh

نصب‌کننده بسته‌های PHP، PHP-Apache، MariaDB و Composer را با pkg نصب می‌کند؛ Docker و systemd لازم نیست. سپس:

  1. در .env مقادیر DB_* و مسیر امن APP_STORAGE_PATH را تنظیم کنید. پوشه var/ باید خارج از DocumentRoot وب باشد و برای کاربر Apache قابل‌نوشتن بماند. مقدار پیش‌فرض var در ریشه پروژه است.

  2. سرویس‌ها را اجرا کنید تا MariaDB برای نخستین بار مقداردهی شود:

    ./scripts/start-termux.sh
    

    start-termux.sh در نبود دیتادایرکتوری اولیه، mariadb-install-db را اجرا می‌کند. اگر قبلاً دیتادایرکتوری دارید، از حذف یا مقداردهی دوباره آن خودداری کنید. پس از شروع MariaDB، رمز قوی تعیین کنید و پایگاه‌داده را آماده کنید:

    mariadb -u root -p
    

    پایگاه‌داده را بسازید:

    CREATE DATABASE bale_finder CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    CREATE USER 'bale_finder_app'@'127.0.0.1' IDENTIFIED BY 'یک-رمز-قوی';
    GRANT ALL PRIVILEGES ON bale_finder.* TO 'bale_finder_app'@'127.0.0.1';
    FLUSH PRIVILEGES;
    

    سپس با کاربر مدیریتی، اسکیما را وارد کنید:

    ./scripts/init-db.sh
    

    اسکریپت اسکیما از شما رمز root می‌خواهد. دسترسی برنامه را با همان کاربر مدیریت نکنید؛ یک کاربر محدود به پایگاه‌داده bale_finder بسازید و مقادیر اتصال را در .env وارد کنید. اگر پایگاه‌داده از نسخه‌ای استفاده می‌کند که قبلاً اسکیما داشته، مهاجرت ورود محلی را یک‌بار اجرا کنید:

    mariadb -u bale_finder_app -p bale_finder < database/migrations/001_local_app_login.sql
    

    برای پایگاه‌داده‌ای که قبلاً ساخته شده، مهاجرت lease پردازش موازی را هم اجرا کنید:

    mariadb -u bale_finder_app -p bale_finder < database/migrations/002_import_worker_leases.sql
    
  3. فایل config/apache-vhost.conf.example را با مسیر واقعی پروژه تطبیق دهید و آن را در تنظیمات Apache بارگذاری کنید. اگر Listen 8080 یا بارگذاری PHP/rewrite از قبل در httpd.conf وجود دارد، از اضافه‌کردن دوباره آن‌ها خودداری کنید. مسیر DocumentRoot حتماً باید به public/ ختم شود.

  4. مطمئن شوید php-apache و mod_rewrite فعال‌اند؛ همچنین محدودیت‌های upload_max_filesize و post_max_size در تنظیمات PHP با UPLOAD_MAX_BYTES هماهنگ باشند.

  5. اگر نصب Apache یا تنظیمات آن را تغییر داده‌اید، تنظیمات را بارگذاری مجدد کنید:

    apachectl restart
    

    این اسکریپت علاوه بر MariaDB و Apache، پردازشگرهای واردسازی را هم در پس‌زمینه اجرا می‌کند. سپس http://127.0.0.1:8080 را در مرورگر باز کنید. برای توقف:

    ./scripts/stop-termux.sh
    

start-termux.sh از mysqld_safe و apachectl استفاده می‌کند و سرویس‌ها را با ابزارهای خود Termux اجرا می‌کند. پردازشگرهای واردسازی PHP CLI هستند و مستقل از صفحه مرورگر کار می‌کنند؛ در اندروید ممکن است برای ادامه کار پس‌زمینه لازم باشد Termux را از بهینه‌سازی باتری خارج کنید.

پیکربندی

فایل .env.example را به .env کپی کنید. فایل .env در ریشه پروژه است و به‌علت DocumentRoot محدودشده به public/ از وب قابل‌دسترسی نیست. نمونه:

APP_ENV=production
APP_TIMEZONE=Asia/Tehran
APP_STORAGE_PATH=var
SESSION_NAME=bale_finder
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=bale_finder
DB_USERNAME=bale_finder_app
DB_PASSWORD=یک-رمز-قوی
UPLOAD_MAX_BYTES=5242880
IMPORT_MAX_ROWS=10000
IMPORT_BATCH_SIZE=10
IMPORT_DELAY_MS=700
IMPORT_WORKERS=1

IMPORT_WORKERS تعداد پردازش‌های PHP CLI هم‌زمان را بین ۱ تا ۶ تعیین می‌کند (پیش‌فرض ۱). این پردازشگرها با scripts/start-workers.sh شروع می‌شوند و با scripts/stop-workers.sh متوقف می‌شوند؛ در نصب Termux، اسکریپت‌های شروع/توقف سرویس این کار را خودکار انجام می‌دهند. بعد از تغییر .env، پردازشگرها را restart کنید. مکث تنظیم‌شده برای هر کار، بین تمام workerها به‌صورت سراسری و از طریق قفل فایل مشترک اعمال می‌شود؛ تعداد workerها نرخ مجاز کلی را چندبرابر نمی‌کند. با بسته‌شدن مرورگر، پردازش ادامه دارد؛ فقط خود PHP worker و MariaDB باید روشن بمانند.

نشست کتابخانه در APP_STORAGE_PATH/sessions/bale-session.json و تصویرهای دریافت‌شده در APP_STORAGE_PATH/avatars/ قرار می‌گیرند؛ هر دو خارج از DocumentRoot و با مجوز محدود فایل/پوشه نگهداری می‌شوند. از قرار دادن APP_STORAGE_PATH داخل public/ خودداری کنید. نشست PHP نیز با کوکی HttpOnly و SameSite=Strict نگهداری می‌شود. HTTPS برای هر دسترسی از شبکه ضروری است؛ در نصب محلی، برنامه را فقط روی loopback در دسترس قرار دهید.

استفاده

  1. در ورود نخست، شماره حساب شخصی را وارد کنید و کد بله را تأیید کنید. اگر رمز دومرحله‌ای بله خواسته شود، فقط برای همان مرحله استفاده می‌شود و ذخیره نمی‌شود.
  2. پس از تأیید بله، نام کاربری برنامه و رمز عبور محلی (حداقل ۱۲ نویسه و حداکثر ۷۲ بایت) بسازید. رمز فقط به شکل hash ذخیره می‌شود. در مراجعات بعدی با همین مشخصات وارد شوید؛ نشست بله خارج از پوشه عمومی باقی می‌ماند.
  3. برای تغییر نام کاربری یا رمز، وارد «تنظیمات ← ورود به برنامه» شوید. تغییر عادی رمز، رمز فعلی را می‌خواهد؛ اگر رمز محلی را فراموش کردید، «ورود یا بازیابی با حساب بله» را انتخاب و دوباره با کد بله تأیید کنید.
  4. «قفل برنامه» فقط نشست محلی را می‌بندد و نشست بله را نگه می‌دارد. برای لغو نشست ذخیره‌شده بله، در تنظیمات «قطع اتصال حساب بله» را انتخاب کنید؛ ورود بعدی نیاز به تأیید دوباره بله دارد.
  5. فایل TXT یا CSV با حداکثر ۵ مگابایت بارگذاری کنید. شماره باید در ستون اول یا ابتدای هر خط باشد. ابتدا پیش‌نمایش تعداد ردیف‌ها، شماره‌های معتبر، نامعتبر و تکراری را ببینید؛ سپس پردازش را جداگانه تأیید کنید. پیشوندهای بین‌المللی و قالب‌های رایج ایرانی، از جمله ارقام فارسی، به E.164 تبدیل می‌شوند. فقط شماره‌های صریح و مجاز پذیرفته می‌شوند؛ الگوهایی مانند +98938155**** به شماره‌های احتمالی گسترش داده نمی‌شوند و نامعتبر شمرده خواهند شد.
  6. برنامه شماره‌های موجود را از کارهای جدید حذف می‌کند. worker سمت سرور به‌طور خودکار کارهای جدید را اجرا می‌کند؛ بستن یا refresh کردن مرورگر آن را متوقف نمی‌کند. کارهای ناتمام از داشبورد قابل مکث و ادامه‌اند. اندازه دسته (۱ تا ۱۰۰۰) و مکث درخواست (۰ تا ۱۰۰۰ میلی‌ثانیه) از صفحه تنظیمات قابل تغییر است؛ تعداد worker هم‌زمان از IMPORT_WORKERS در .env تنظیم می‌شود و مکث درخواست بین آن‌ها مشترک است.
  7. جدول مخاطبان قابلیت جست‌وجو، فیلتر، مرتب‌سازی، صفحه‌بندی، مشاهده جزئیات، حذف تکی/گروهی و خروجی CSV/JSON دارد.

فیلدهای خالی در API به‌صورت NULL می‌مانند تا «در دسترس نبودن» با داده واقعی اشتباه نشود. اطلاعات جداگانه نام و نام خانوادگی در مدل‌های بررسی‌شده وجود ندارد؛ بنابراین ساخته یا حدس زده نمی‌شوند. تصویر پروفایل در صورت دسترسی، هنگام نمایش تنبل در جدول از LoadAvatars دریافت و خارج از DocumentRoot ذخیره می‌شود. FullUser.contact_info در نسخه نصب‌شده فقط یک مقدار عددی و عنوان عمومی دارد و نوع این مقدار را مشخص نمی‌کند؛ برنامه آن را به‌عنوان شماره تلفن ذخیره نمی‌کند و profile_phone تا زمان ارائه داده صریح و قابل‌تأیید خالی می‌ماند.

گزارش فعالیت‌ها

درخواست‌های API کاربران واردشده در جدول activity_logs با نوع رویداد api_call، روش HTTP و مسیر ثبت می‌شوند. مسیرهای دارای شناسه به شکل عمومی ذخیره می‌شوند؛ افزودن و حذف مخاطب نیز با تعداد رکوردها رویداد جداگانه دارند. رویدادهای ورود، ایجاد/پردازش واردسازی و تغییر تنظیمات هم ثبت می‌شوند. برای حفظ حریم خصوصی، بدنهٔ درخواست‌ها، شماره تلفن‌ها، رمزها و نشست بله در گزارش فعالیت قرار نمی‌گیرند.

برای دیدن اجرای زندهٔ متدهای بله از ریشه پروژه اجرا کنید:

tail -F var/logs/runtime.jsonl

همین گزارش در پنل وب، از گزینهٔ «لاگ زنده» در منوی کناری، با به‌روزرسانی خودکار هر ۲٫۵ ثانیه قابل مشاهده است. به‌روزرسانی را می‌توان موقتاً متوقف کرد یا دستی تازه‌سازی کرد. این API فقط پس از ورود به برنامه قابل دسترسی است و درخواست‌های دوره‌ای آن در گزارش فعالیت دیتابیس ثبت نمی‌شوند.

این فایل فقط رویدادهای فراخوانی متدهای بله، نام و نوع پارامترها، نوع پاسخ، ساختار ثابت مدل پاسخ، مدت اجرا و نوع/کد خطاهای بله را ثبت می‌کند. شماره‌ای که به Bale.SearchContact فرستاده می‌شود در لاگ می‌آید؛ شمارهٔ ورود به بله و مقادیر حساس دیگر مانند کد ورود، رمز، شناسه و توکن به‌صورت [redacted] نمایش داده می‌شوند. مقادیر واقعی پاسخ، نتیجهٔ تطبیق و اطلاعات پروفایل ثبت نمی‌شوند. درخواست‌ها و پاسخ‌های داخلی API برنامه در این فایل نوشته نمی‌شوند. فایل با دسترسی خصوصی ساخته می‌شود و پس از ۵ مگابایت چرخش می‌یابد. گزارش‌های حسابرسی عملیات برنامه در جدول activity_logs جدا باقی می‌مانند.

برای تست زندهٔ یک شمارهٔ مجاز، در ریشهٔ پروژه اجرا کنید:

php searchsingle.php

برای تست آرایه‌ای با دو شمارهٔ مجاز، اجرا کنید:

php searchmuti.php

هر دو اسکریپت شماره‌ها را از ورودی می‌گیرند و RPC واقعی می‌فرستند؛ فقط وجود فیلد user یا group را گزارش می‌کنند و اطلاعات پروفایل را چاپ نمی‌کنند. هیچ‌کدام چیزی به دیتابیس محلی اضافه نمی‌کنند. شماره‌های تست در فایل لاگ خصوصی ثبت می‌شوند. اسکریپت آرایه‌ای پیش از ارسال دو RPC (ترتیب اصلی و وارونه) تأیید می‌گیرد؛ تفاوت نتیجه‌ها نشانه‌ای است که کل آرایه جست‌وجو نمی‌شود، اما یکسان بودن نتیجه‌ها هم پشتیبانی دسته‌ای را ثابت نمی‌کند. schema نصب‌شده همچنان request را یک رشته تعریف می‌کند.

برای مشاهده رویدادهای اخیر یک کاربر از MySQL/MariaDB استفاده کنید:

SELECT event_type, detail_json, created_at
FROM activity_logs
WHERE user_id = ?
ORDER BY id DESC
LIMIT 100;

فایل‌های نمونه

  • samples/contacts.csv
  • samples/contacts.txt

این نمونه‌ها از شماره‌های ساختگی/رزروشده برای مثال استفاده می‌کنند.

آزمون

composer test

آزمون‌ها مستقل از شبکه و حساب بله هستند و نرمال‌سازی شماره، تجزیه فایل، اعتبارسنجی/هش رمز برنامه و ذخیره امن تصویر را پوشش می‌دهند. برای بررسی اتصال واقعی، از یک حساب شخصی در رابط برنامه استفاده کنید؛ اجرای خودکار آزمون‌ها هیچ درخواست ورود یا جست‌وجویی به بله نمی‌فرستد.

ساختار

  • app/: تنظیمات، PDO، API، اعتبارسنجی ورودی و درگاه کتابخانه بله
  • public/: DocumentRoot، رابط RTL و دارایی‌های وب
  • database/schema.sql: اسکیما و ایندکس‌های MySQL/MariaDB
  • database/migrations/: مهاجرت‌های افزایشی برای پایگاه‌داده‌های موجود
  • scripts/: نصب، مقداردهی پایگاه‌داده و شروع/توقف Termux
  • var/: نشست‌های حساس؛ خارج از DocumentRoot و در Git نادیده گرفته می‌شود

نکته امنیتی و محدودیت

این برنامه فقط از جست‌وجوی مخاطب و پروفایل‌هایی که خود کتابخانه در اختیار حساب قرار می‌دهد استفاده می‌کند؛ تلاش برای دور زدن حریم خصوصی یا یافتن اطلاعات پنهان انجام نمی‌دهد. برای استقرار عمومی، HTTPS، محدودسازی دسترسی شبکه و تهیه نسخه پشتیبان رمزگذاری‌شده از پایگاه‌داده را فعال کنید. فایل نشست Bale را مانند رمز عبور حساب محافظت کنید.