راهنمای نصب و راه‌اندازی

۱. معرفی پروژه

FinanceGPT یک سرویس خودکار است که پیام‌های رسیده از کانال‌های منبع تلگرام را دریافت کرده، با هوش مصنوعی بازنویسی کرده، و بدون هیچ انتسابی به کانال‌های مقصد (تلگرام و بله) ارسال می‌کند.

دریافت

اتصال به چند کانال منبع تلگرام
فقط پیام‌های جدید پس از راه‌اندازی
پشتیبانی از متن و رسانه (عکس، ویدیو، فایل)

پردازش

بازنویسی با API سازگار با OpenAI
بدون انتساب یا نمایش منبع
پشتیبانی از مدل‌های مختلف

ارسال

کانال مقصد تلگرام
کانال مقصد بله (Bale)
ارسال همزمان به هر دو پلتفرم

مدیریت

پنل مدیریت وب مدرن (Flask)
پایگاه داده SQLite
لاگ کامل و گزارش‌گیری

۲. معماری سیستم

FinanceGPTlab/ ├── app/ │ ├── core/ │ │ ├── config.py # تنظیمات و مقادیر پیش‌فرض │ │ ├── database.py # SQLAlchemy engine و session │ │ ├── logger.py # لاگر چرخشی + ثبت در DB │ │ ├── security.py # هش رمز عبور (bcrypt) │ │ └── state.py # وضعیت مشترک (startup_time) │ ├── models/ │ │ ├── channel.py # کانال‌های منبع و مقصد │ │ ├── log_entry.py # رکورد لاگ در DB │ │ ├── message_record.py # سابقه پیام‌های پردازش‌شده │ │ ├── prompt_history.py # تاریخچه پرامپت‌های AI │ │ ├── settings.py # تنظیمات key-value │ │ └── user.py # کاربران پنل مدیریت │ ├── services/ │ │ ├── ai_service.py # بازنویسی (بدون انتساب منبع) │ │ ├── bale_service.py # ارسال به Bale API │ │ ├── message_processor.py # هماهنگ‌کننده پردازش │ │ └── telegram_service.py # Telethon + event handler │ └── admin/ │ ├── app.py # Flask app factory │ ├── routes/ # Blueprint‌های ۸ بخش │ └── templates/ # قالب‌های Jinja2 (بازطراحی‌شده) ├── run.py # نقطه ورود اصلی ├── init_app.py # seed اولیه دیتابیس ├── requirements.txt ├── data/ # app.db + secret.key (خودکار) ├── logs/ # app.log (خودکار) └── downloaded_media/ # فایل‌های دانلودشده

جریان پردازش پیام

کانال منبع تلگرام event handler بررسی تاریخ پیام ai_service (بازنویسی) ارسال به تلگرام + بله

۳. پیش‌نیازها

نیازمندی	نسخه حداقل	توضیح
Python	3.10+	برای type hints و asyncio پیشرفته
Telethon	1.34+	کلاینت تلگرام (MTProto)
Flask	3.0+	پنل مدیریت وب
SQLAlchemy	2.0+	ORM دیتابیس
openai	1.30+	کلاینت OpenAI-compatible API
requests	2.31+	HTTP برای Bale API
PySocks	1.7+	پشتیبانی پروکسی SOCKS5
پروکسی SOCKS5	—	در صورت دسترسی محدود به تلگرام (پیش‌فرض: پورت 2080)

۴. نصب

۱

ایجاد محیط مجازی Python

cd "Receive messages only from declared channels for FinanceGPTlab"
python -m venv venv

# Windows:
venv\Scripts\activate
# Linux / macOS:
source venv/bin/activate

۲

نصب وابستگی‌ها

pip install -r requirements.txt

۳

تولید Session String تلگرام

Session String یک‌بار تولید می‌شود و در تنظیمات ذخیره می‌شود:

python -c "
from telethon.sync import TelegramClient
from telethon.sessions import StringSession
api_id   = int(input('API ID: '))
api_hash = input('API Hash: ')
with TelegramClient(StringSession(), api_id, api_hash) as c:
    print('\\nSession String:')
    print(c.session.save())
"

Session String معادل رمز ورود حساب تلگرام شماست. آن را امن نگه دارید.

۴

اولین اجرا

python run.py

جداول دیتابیس و مقادیر پیش‌فرض به صورت خودکار ایجاد می‌شوند.

۵. پیکربندی

همه تنظیمات از طریق پنل مدیریت (http://localhost:5000/settings/) ویرایش می‌شوند و در دیتابیس ذخیره می‌شوند.

تلگرام

کلید	توضیح	مثال
`telegram.api_id`	شناسه عددی API از my.telegram.org	`12345678`
`telegram.api_hash`	رشته هش API	`abcdef123...`
`telegram.session_string`	Session String احراز هویت	`1BJWap1w...`
`telegram.use_proxy`	فعال‌سازی پروکسی SOCKS5	`true`
`telegram.proxy_host`	آدرس پروکسی	`127.0.0.1`
`telegram.proxy_port`	پورت پروکسی	`2080`

بله (Bale)

کلید	توضیح
`bale.bot_token`	توکن ربات از BotFather بله
`bale.chat_id`	شناسه کانال یا گروه مقصد
`bale.base_url`	آدرس پایه API بله (پیش‌فرض: `https://tapi.bale.ai`)

هوش مصنوعی

کلید	توضیح
`ai.api_key`	کلید API سرویس هوش مصنوعی
`ai.base_url`	Endpoint (برای APIهای سازگار با OpenAI)
`ai.model`	نام مدل (`qwen3-32b`، `gpt-4o`، ...)
`ai.temperature`	خلاقیت خروجی (۰ تا ۲، پیشنهاد: ۰.۷)
`ai.timeout`	حداکثر زمان انتظار (ثانیه، پیش‌فرض: ۶۰)

کانال‌ها

از منوی کانال‌ها در پنل مدیریت اضافه کنید. برای هر کانال یکی از موارد زیر لازم است:

Chat ID: برای گروه‌ها و کانال‌های خصوصی (مثال: -1001234567890)
Username: برای کانال‌های عمومی (مثال: @channelname)

تغییرات کانال‌ها پس از راه‌اندازی مجدد اعمال می‌شوند.

۶. راه‌اندازی

۱

اجرای سرویس

venv\Scripts\activate   # فعال‌سازی محیط مجازی (Windows)
python run.py

۲

ورود به پنل مدیریت

http://localhost:5000

اعتبار پیش‌فرض: admin / admin123

فوری: رمز عبور admin را از منوی کاربران تغییر دهید.

۳

ترتیب داخلی راه‌اندازی

ساخت جداول دیتابیس
seed مقادیر پیش‌فرض
ثبت startup_time (UTC-aware) — نقطه مرجع پیام‌های جدید
راه‌اندازی پنل Flask در thread جداگانه
اتصال Telethon و ثبت event handler
resolve کانال‌های منبع و مقصد
آماده‌باش — فقط پیام‌هایی که بعد از این لحظه ارسال شوند دریافت می‌شوند

۷. مکانیزم «فقط پیام جدید» تغییر اساسی

تضمین می‌کند که پیام‌هایی که قبل از شروع سرویس ارسال شده‌اند — حتی اگر در زمان خاموش بودن سرویس باشند — هرگز پردازش نمی‌شوند.

پیاده‌سازی

ثبت startup_time: در لحظه شروع فرآیند، datetime.now(timezone.utc) در app/core/state.py ذخیره می‌شود.
حذف catch_up(): فراخوانی tg_client.catch_up() که باعث بازپخش تمام بروزرسانی‌های از-دست-رفته می‌شد حذف شد.
فیلتر تاریخ در Event Handler: هر پیام دریافتی با startup_time مقایسه می‌شود. اگر message.date < startup_time باشد، پیام رد می‌شود و یک لاگ debug ثبت می‌شود.
حذف Poll Loop: حلقه‌ای که get_messages(limit=1) می‌زد و پیام آخر را بدون بررسی تاریخ پردازش می‌کرد حذف شد. سرویس کاملاً مبتنی بر رویداد (event-driven) است.

پس از هر راه‌اندازی مجدد، checkpoint به زمان فعلی تنظیم می‌شود. پیام‌هایی که در زمان خاموشی سرویس ارسال شده‌اند هرگز پردازش نخواهند شد.

۸. حذف انتساب منبع رفع مشکل

پیام‌های ارسال‌شده به مقصد هیچ اطلاعاتی درباره منبع اصلی ندارند. نام کانال، Chat ID، لینک، یا هر متادیتای دیگری در پیام خروجی وجود ندارد.

تغییرات اعمال‌شده

ai_service.py: کد out = f"منبع: {source_title}\n\n{out}" که نام منبع را به ابتدای هر پیام بازنویسی‌شده اضافه می‌کرد، حذف شد.
message_processor.py: caption پشتیبان برای رسانه‌ها از f"منبع: {source_title}" به رشته خالی ("") تغییر یافت.

source_title همچنان برای لاگ‌های داخلی و پایگاه داده ثبت می‌شود، اما در هیچ پیام ارسالی نمایش داده نمی‌شود.

۹. پنل مدیریت

پنل روی http://0.0.0.0:5000 اجرا می‌شود. پورت از تنظیمات سیستم قابل تغییر است.

بخش	مسیر	عملکرد
داشبورد	`/`	آمار لحظه‌ای، نمودار ۷ روزه، وضعیت اتصال، لاگ‌های اخیر
کانال‌ها	`/channels/`	افزودن، ویرایش، فعال/غیرفعال کردن کانال‌های منبع و مقصد
پرامپت AI	`/prompts/`	ویرایش پرامپت سیستم و کاربر، تاریخچه نسخه‌ها
تنظیمات	`/settings/`	پیکربندی تلگرام، بله، هوش مصنوعی، و سیستم
وضعیت سرویس	`/service-status/`	health check زنده تمام سرویس‌ها با بروزرسانی خودکار
گزارش‌ها	`/reports/`	آمار دوره‌ای با نمودار روزانه و جدول کانال‌ها
لاگ‌ها	`/logs/`	جستجو و فیلتر لاگ‌ها با نمایش امن جزئیات خطا
کاربران	`/users/`	مدیریت حساب‌های کاربری و تغییر رمز عبور

۱۰. تغییرات نسخه ۲.۰

فایل	نوع	شرح تغییر
`app/core/state.py`	جدید	اضافه شدن `_startup_time` (UTC-aware) و `get_startup_time()`؛ counter پیام‌های دریافتی/ارسالی
`app/services/telegram_service.py`	تغییر اساسی	حذف `catch_up()`؛ حذف `_poll_sources`؛ فیلتر تاریخ پیام در event handler
`app/services/ai_service.py`	رفع مشکل	حذف افزودن `منبع: {source_title}` به خروجی هوش مصنوعی
`app/services/message_processor.py`	رفع مشکل	حذف caption پشتیبان `f"منبع: ..."` برای پیام‌های رسانه‌ای
`app/admin/app.py`	بهبود	اضافه شدن `SESSION_COOKIE_SAMESITE=Lax` و `PERMANENT_SESSION_LIFETIME=8h`
`app/admin/templates/base.html`	بازطراحی	سایدبار جدید با انیمیشن؛ topbar بهبودیافته؛ متغیرهای CSS مدرن
`app/admin/templates/login.html`	بازطراحی	کارت مدرن با پس‌زمینه شبکه‌ای؛ show/hide رمز عبور
`app/admin/templates/dashboard.html`	بازطراحی	stat card گرادیانی؛ progress bar نرخ موفقیت؛ نمودارهای بهبودیافته
`app/admin/templates/channels.html`	بازطراحی	جداول بهتر؛ badge پلتفرم؛ empty state با دکمه سریع
`app/admin/templates/settings.html`	بازطراحی	فرم‌های توصیف‌دار؛ تنظیمات پروکسی گروه‌بندی‌شده؛ toggle نمایش رمز
`app/admin/templates/logs.html`	بازطراحی + رفع XSS	جزئیات خطا با `textContent` (نه innerHTML)؛ فیلتر بهتر
`app/admin/templates/service_status.html`	بازطراحی	کارت‌های وضعیت رنگی؛ status dot انیمیشن‌دار؛ جدول فعالیت‌های اخیر
`app/admin/templates/prompts.html`	بازطراحی	نمایش پرامپت فعال؛ تاریخچه نسخه‌ها با scroll
`app/admin/templates/users.html`	بازطراحی	avatar با حرف اول؛ chip‌های نقش؛ پنل اطلاعات امنیتی
`app/admin/templates/reports.html`	بازطراحی	progress bar نرخ موفقیت؛ نمودار line chart بهبودیافته

۱۱. امنیت

رمزهای عبور با bcrypt (Werkzeug) هش می‌شوند — هرگز plain-text ذخیره نمی‌شود.
کوکی نشست با HttpOnly، SameSite=Lax تنظیم شده؛ مدت ۸ ساعت.
Secret Key در data/secret.key ذخیره می‌شود — یک بار تولید، دائمی.
جزئیات خطا در modal با textContent نمایش داده می‌شوند (XSS رفع شد).
Session String و API key‌ها در data/app.db هستند — دسترسی فایل را محدود کنید.
در production با HTTPS: SESSION_COOKIE_SECURE = True را در admin/app.py فعال کنید.

اقدام ضروری: رمز پیش‌فرض admin123 را فوری تغییر دهید.

۱۲. عیب‌یابی

تلگرام متصل نمی‌شود

Session String را تجدید کنید (ممکن است منقضی شده باشد).
پروکسی SOCKS5 را بررسی کنید (اگر فعال است).
API ID و API Hash را از my.telegram.org تأیید کنید.

پیام‌های قدیمی پردازش می‌شوند

مطمئن شوید از نسخه ۲.۰ استفاده می‌کنید.
در لاگ‌ها دنبال [TG] Skipping pre-startup message باشید — نشانه صحیح بودن فیلتر است.
مطمئن شوید catch_up() در telegram_service.py وجود ندارد.

هوش مصنوعی پاسخ نمی‌دهد

صفحه وضعیت سرویس را بررسی کنید.
ai.base_url و ai.api_key را تأیید کنید.
ai.timeout را در صورت کندی شبکه افزایش دهید.

ارسال به بله ناموفق است

توکن ربات و Chat ID را بررسی کنید.
ربات باید admin کانال مقصد باشد.
صفحه وضعیت سرویس، API بله را به صورت زنده بررسی می‌کند.

پنل مدیریت باز نمی‌شود

پورت 5000 آزاد باشد (netstat -ano | findstr :5000).
لاگ‌های ترمینال را برای [ADMIN ERROR] بررسی کنید.

فهرست مطالب

FinanceGPT