# FinanceGPT

راهنمای کامل نصب، پیکربندی و بهره‌برداری — نسخه ۲.۰

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

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 را از منوی کاربران تغییر دهید.
۳
ترتیب داخلی راه‌اندازی

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

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

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

### پیاده‌سازی

1. ثبت `startup_time`: در لحظه شروع فرآیند، `datetime.now(timezone.utc)` در `app/core/state.py` ذخیره می‌شود.
2. حذف `catch_up()`: فراخوانی `tg_client.catch_up()` که باعث بازپخش تمام بروزرسانی‌های از-دست-رفته می‌شد حذف شد.
3. فیلتر تاریخ در Event Handler: هر پیام دریافتی با `startup_time` مقایسه می‌شود. اگر `message.date < startup_time` باشد، پیام رد می‌شود و یک لاگ debug ثبت می‌شود.
4. حذف 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]` بررسی کنید.