NEWSTRACE FLOW — ІНСТРУКЦІЯ ЗІ ВСТАНОВЛЕННЯ ТА ВИКОРИСТАННЯ
Версія: 2.2.1
Авторський модуль для Google Sheets

==================================================
1. ЩО ТАКЕ NEWSTRACE FLOW
==================================================

NewsTrace Flow — це модуль для Google Sheets, створений для автоматизації роботи з доменами, історичними даними та перевірками через Web Archive / Wayback Machine.

Модуль працює безпосередньо всередині Google Таблиць через Google Apps Script і додає власне меню, панель керування, чергу завдань і фонову обробку.

Основне призначення:
- передавати домени з Web Archive / Wayback Audit у NewsTrace;
- працювати зі спільними архівними snapshots та індексами;
- запускати перевірки у фоні;
- ставити задачі в чергу;
- підтримувати pause / resume;
- повторювати тимчасово невдалі перевірки;
- дозволяти ручну передачу доменів;
- очищати та готувати службові дані.

==================================================
2. ЩО СТВОРЮЄ МОДУЛЬ
==================================================

Після встановлення NewsTrace Flow створює або готує службові вкладки Google Sheets.

Основні вкладки:

NT Відбір
- Run ID
- Домен
- Етап
- Допуск
- Причина
- Пріоритет
- Спроби аудиту
- Не раніше
- Рядок Web Archive
- Оновлено

NT Архівні дані
- Ключ
- Покоління
- Частина
- Частин
- JSON
- Дійсне до
- Домен

Також модуль використовує фоновий worker:
newsTraceFlowWorker

і внутрішній parser:
news-facts-1

==================================================
3. ЩО ПОТРІБНО ДЛЯ ВСТАНОВЛЕННЯ
==================================================

Потрібно:

1. Google-акаунт.
2. Нова або тестова Google Таблиця.
3. Файли модуля:
   - Code-v2.2.1.txt
   - Panel-v2.2.1.txt
   - appsscript.json, якщо він входить у ZIP
4. Доступ до Extensions → Apps Script.

Для базового запуску не потрібні:
- окремий зовнішній сервер;
- Common Crawl;
- AI API keys.

==================================================
4. ВСТАНОВЛЕННЯ
==================================================

КРОК 1
Створіть нову порожню Google Таблицю.

КРОК 2
У Google Sheets відкрийте:

Розширення → Apps Script

КРОК 3
Відкрийте файл Code.gs.

Видаліть його стандартний вміст і вставте весь код із:

Code-v2.2.1.txt

Збережіть файл.

КРОК 4
Створіть HTML-файл:

Panel

У нього вставте весь вміст:

Panel-v2.2.1.txt

Збережіть файл.

КРОК 5
Якщо в архіві є appsscript.json, використовуйте його лише відповідно до комплекту модуля.

Для оновлення з попередньої версії 2.2.x appsscript.json змінювати не потрібно, якщо в пакеті оновлення прямо не зазначено інше.

КРОК 6
У редакторі Apps Script запустіть функцію:

setupNewsTraceFlow

Під час першого запуску Google попросить надати дозволи.

Підтвердьте дозволи для роботи скрипта з Google Таблицею.

КРОК 7
Поверніться до Google Sheets і оновіть сторінку.

Після оновлення у верхньому меню повинно з'явитися:

🔎 NewsTrace Flow

==================================================
5. ПЕРШИЙ ТЕСТ
==================================================

Для першої перевірки рекомендується використати нову тестову таблицю.

1. Внесіть тестові домени у:

NT Домени!A2:A

2. Відкрийте:

🔎 NewsTrace Flow → Відкрити панель

3. Для першого тесту виберіть режим:

Швидка — до 12 HTML URL

4. Натисніть:

Запустити

Після цього завдання переходять у фонову обробку.

Планувальник працює приблизно раз на хвилину.

Створювати trigger вручну для стандартного запуску не потрібно.

==================================================
6. ЯК КОРИСТУВАТИСЯ
==================================================

Типовий робочий процес:

1. Додайте домени у робочу таблицю.
2. Відкрийте меню NewsTrace Flow.
3. Відкрийте панель.
4. Виберіть потрібний режим перевірки.
5. Запустіть аналіз.
6. Слідкуйте за статусом у панелі та службових вкладках.
7. За потреби використовуйте pause / resume.
8. Після завершення перевіряйте результати відбору й архівні дані.

NewsTrace Flow побудований так, щоб довгі перевірки не вимагали постійно тримати відкритою вкладку браузера.

==================================================
7. ЧЕРГА І ФОНОВА ОБРОБКА
==================================================

Модуль використовує власну чергу завдань.

У черзі зберігається:
- домен;
- поточний етап;
- статус допуску;
- причина;
- пріоритет;
- кількість спроб;
- час наступної дозволеної спроби;
- прив'язка до рядка Web Archive;
- час останнього оновлення.

Тимчасові помилки не повинні автоматично означати втрату завдання.

NewsTrace Flow підтримує повторні спроби і продовження обробки.

==================================================
8. PAUSE / RESUME
==================================================

Якщо потрібно тимчасово зупинити роботу:

використовуйте Pause.

Для продовження:

Resume.

Це дозволяє не запускати весь процес заново після тимчасових обмежень або технічної паузи.

==================================================
9. ВАЖЛИВО ПРИ ОНОВЛЕННІ
==================================================

Перед оновленням рекомендується зберегти копію старих файлів Code.gs і Panel.

Для оновлення на 2.2.1:

1. Зупиніть активну обробку через Pause.
2. Замініть Code.gs кодом із Code-v2.2.1.txt.
3. Замініть Panel кодом із Panel-v2.2.1.txt.
4. Збережіть зміни.
5. appsscript.json не змінюйте, якщо окремо не вказано інше.
6. Поверніться в таблицю.
7. Продовжіть роботу через Resume.

Версія 2.2.1 виправляє помилкове визначення quota-помилки у випадках, коли слово "daily" зустрічалося всередині URL.

==================================================
10. ЯК ПЕРЕВІРИТИ, ЩО МОДУЛЬ ВСТАНОВЛЕНИЙ ПРАВИЛЬНО
==================================================

Після встановлення повинно бути:

- меню 🔎 NewsTrace Flow;
- команда Відкрити панель;
- команда Підготувати вкладки;
- службові вкладки NT Відбір та NT Архівні дані;
- можливість запуску перевірки;
- оновлення статусів у фоні.

Якщо меню не з'явилося:
- оновіть Google Таблицю;
- перевірте, чи збережено Apps Script;
- переконайтеся, що setupNewsTraceFlow було виконано;
- перевірте надані Google дозволи.

==================================================
11. БЕЗПЕЧНЕ ВИКОРИСТАННЯ
==================================================

Рекомендується:

- перший запуск робити у копії або тестовій Google Таблиці;
- не видаляти службові вкладки під час активної перевірки;
- не запускати кілька конфліктуючих процесів одночасно;
- перед заміною версії ставити процес на Pause;
- зберігати резервну копію попередньої версії коду.

==================================================
12. ПРИЗНАЧЕННЯ
==================================================

NewsTrace Flow створений для спеціалістів, які працюють з:
- дроп-доменами;
- Web Archive;
- історією сайтів;
- великими списками доменів;
- попереднім відбором кандидатів;
- автоматизацією рутинних перевірок у Google Sheets.

Головна ідея модуля — перетворити Google Таблицю з пасивного списку доменів у керований робочий процес із чергою, архівними даними та фоновою обробкою.

==================================================
13. КОРОТКО
==================================================

Встановлення:
Google Sheets → Extensions → Apps Script
→ Code.gs
→ Panel.html
→ setupNewsTraceFlow
→ дозволи
→ reload.

Запуск:
NT Домени
→ додати домени
→ 🔎 NewsTrace Flow
→ Відкрити панель
→ вибрати режим
→ Запустити.

NewsTrace Flow — модуль Google Sheets для автоматизації роботи з доменами та Web Archive.
