================================================================
  AI АСИСТЕНТ ЗА FACEBOOK MESSENGER — КАК СЕ РАБОТИ
  Дигитална Планета · версия 0.1.0
================================================================

КАКВО ПРАВИ ПРОГРАМАТА
----------------------
Чете последното входящо съобщение в отворения Messenger, генерира
отговор с AI и го ПОСТАВЯ в полето за писане. Вие само натискате Enter.
Автоматично изпращане в тази версия НЯМА (така е по задание).


КАКВО ТИ ТРЯБВА ПРЕДИ СТАРТ
---------------------------
1) Windows 10/11
2) Python 3.12 или по-нов  ->  https://www.python.org/downloads/windows/
   ВАЖНО: при инсталацията сложи отметка "Add python.exe to PATH"
3) Google Chrome (или Edge)
4) API ключ за AI (OpenAI / DeepSeek / Anthropic) — дава го този,
   който управлява акаунта. Без ключ програмата работи, но отговаря
   само с готовите шаблони от базата знания.


АКО ИМАШ .EXE (най-лесно — без Python)
--------------------------------------
Ако някой вече е пуснал BUILD-EXE.bat, получаваш папка
DigitalPlanetMessengerAI с файл DigitalPlanetMessengerAI.exe. Тогава:

1) Копирай ЦЯЛАТА папка на компютъра (не само .exe файла!).
2) Провери, че до .exe има файл ".env" с попълнен API ключ.
   Ако няма: копирай ".env.example" като ".env", отвори го с Notepad и
   попълни реда OPENAI_API_KEY=... (или друг доставчик).
3) Двоен клик на DigitalPlanetMessengerAI.exe — това е всичко.
   Python НЕ е нужен.

Проверка: CHECK-SELFTEST.bat (трябва да покаже всички проверки с ✔).


ВАРИАНТ С ИЗХОДНИЯ КОД (ако още няма .exe)
------------------------------------------
Двоен клик на:   0-START.bat

ТОВА Е ВСИЧКО. Този един файл:
  1) проверява дали има Python (ако няма — отваря страницата за сваляне),
  2) инсталира програмата (само първия път, 5–15 минути),
  3) иска API ключа (само първия път),
  4) стартира Chrome с Messenger и после приложението.

Всеки следващ ден: пак 0-START.bat.

Отделните стъпки (1-INSTALL.bat, 4-SET-API-KEY.bat, 2-START.bat) съществуват,
но 0-START.bat ги вика сам — не е нужно да ги пускате поотделно.


СТЪПКА 0 — РАЗАРХИВИРАНЕ (важно!)
---------------------------------
Десен бутон върху facebook-messenger-ai.zip -> "Extract All..." ->
избери папка (например C:\DPAI) -> Extract.

НЕ работете вътре в zip файла! Програмата не тръгва оттам.
След разархивиране влезте в папката facebook-messenger-ai.


СТЪПКА 1 — ИНСТАЛАЦИЯ (еднократно, 5–15 минути)
-----------------------------------------------
Двоен клик на:   1-INSTALL.bat   (или просто 0-START.bat)

- Черният прозорец работи сам: създава .venv, тегли пакетите и Chromium.
- Ако Windows покаже предупреждение (SmartScreen): "More info" ->
  "Run anyway". Това е нормално за файл, изтеглен от интернет.
- НЕ затваряйте прозореца, докато не пише "INSTALL DONE".

Ако пише "[ERROR] Not installed yet. Run 1-INSTALL.bat first."
означава, че сте пуснали 2-START.bat преди инсталацията.
Пуснете 0-START.bat (или 1-INSTALL.bat) и изчакайте да свърши.

Ако пише, че Python липсва — инсталирайте го (страницата се отваря сама)
и пуснете 0-START.bat отново.


СТЪПКА 2 — API КЛЮЧ (еднократно)
--------------------------------
Двоен клик на:   4-SET-API-KEY.bat

- Provider: натиснете Enter за openai (или напишете deepseek/anthropic)
- Поставете ключа с десен бутон -> Paste -> Enter

Ключът се записва само в локалния файл .env на този компютър и никъде
не се изпраща, освен към самата AI услуга.


СТЪПКА 3 — СТАРТИРАНЕ
---------------------
Двоен клик на:   2-START.bat

1) Отваря се Chrome с отворен "debugging port" и адрес messenger.com
2) ВЛЕЗТЕ в профила си в Messenger (това се помни за следващия път)
3) След 10 секунди се отваря прозорецът на приложението

Ако в приложението пише  Messenger: CONNECTED  — всичко е наред.
Ако пише DISCONNECTED — натиснете бутона "Свържи".


СТЪПКА 4 — РАБОТА С КАНДИДАТ
----------------------------
1) В Chrome отворете разговора с кандидата (или оставете прозореца
   на Messenger отпред — програмата чете ОТВОРЕНИЯ разговор)
2) В приложението натиснете:  Генерирай
3) Прочетете предложението. Ако трябва — редактирайте го в полето.
4) Натиснете:  Постави в Messenger
5) Текстът се появява в полето за писане на Messenger.
   ВИЕ натискате Enter, за да го изпратите.

Бутони:
  Генерирай            — AI предложение за последното входящо съобщение
  Постави в Messenger  — поставя текста (без Enter)
  Изпрати              — само в SEMI_AUTO режим (по подразбиране забранен)
  Редактирай           — записва вашата редакция в историята
  Предай на човек      — маркира разговора за консултант
  Export CSV           — изнася историята в data\exports\*.csv
  Knowledge Base       — редактиране на отговорите и фактите
  Settings             — AI, браузър, режим, интервал на проверка

Режими (горна лента):
  MANUAL    — AI само показва предложение, не пише в Messenger
  ASSIST    — поставя текста в Messenger (ПО ПОДРАЗБИРАНЕ)
  SEMI_AUTO — позволява автоматично изпращане само за безопасни теми
              (изключено по подразбиране)


ВСЕКИ СЛЕДВАЩ ДЕН
-----------------
Само:  0-START.bat  ->  вход в Messenger (ако иска)  ->  работа.
(2-START.bat прави същото, но без проверките за инсталация и ключ.)


ЗАЩО ПРОГРАМАТА ОТКАЗВА ДА ПОСТАВИ ТЕКСТ
----------------------------------------
- "Активният разговор се смени" — защита: отворили сте друг чат, докато
  AI е генерирал отговора. Натиснете Генерирай отново в правилния чат.
- "Не намирам полето за писане" — разговорът не е отворен или Messenger
  е сменил страницата. Отворете чата и опитайте пак.
- "Няма връзка с Messenger" — натиснете "Свържи" или пуснете Chrome
  през 2-START.bat (не отваряйте Chrome ръчно без debugging port).


АКО НЕЩО НЕ РАБОТИ
------------------
1) Пуснете  3-SELFTEST.bat  — проверява ядрото без браузър.
   10/10 OK означава, че програмата е здрава и проблемът е във връзката
   с Messenger или с AI ключа.
2) Отворете logs\app.log (технически) и logs\dialogs.log (история).
3) Чести случаи:
   - "AI: NO KEY" -> пуснете 4-SET-API-KEY.bat
   - "Messenger: ERROR" -> Chrome не е стартиран с debugging port;
     затворете всички прозорци на Chrome и пуснете 2-START.bat
   - Отговорите са от шаблон -> AI не е достъпен (ключ/интернет);
     вижте logs\app.log


ПРАВИЛА ЗА СИГУРНОСТ (важни)
----------------------------
- НИКОГА не искайте от кандидата ПИК код, парола, КЕП PIN или SMS код
  в Messenger. Програмата също не ги иска и ги премахва от отговорите.
- При ПИК/КЕП/SMS/e-mail проблем, отказан ваучер или искане за човек,
  програмата връща стандартен текст и маркира разговора за консултант.
- Не обещавайте одобрение и дата на ваучера — AI е инструктиран да не
  го прави, а safety слоят спира такива отговори.


ТЕХНИЧЕСКИ ДЕТАЙЛИ (за IT)
--------------------------
- Пълен README: README.md
- Деинсталация: изтрийте папката. Нищо не се инсталира в Windows.
- Историята е в data\messenger_ai.db (SQLite), логове в logs\.
- Порт за debugging: 9222 (сменя се в Settings или .env: CDP_URL).
- Всички данни остават на този компютър.
