HELP.md

# Jira AI Assistant - Керівництво користувача

## Загальна інформація

Jira AI Assistant — це потужний інструмент для аналізу, візуалізації та інтелектуальної обробки даних Jira за допомогою штучного інтелекту. Додаток дозволяє імпортувати дані з CSV-експорту Jira, аналізувати їх, створювати різноманітні візуалізації та використовувати можливості AI для глибокого розуміння стану проєкту.

### Основні можливості

- Аналіз CSV-експорту з Jira з виявленням ключових метрик
- Генерація візуалізацій різних типів для кращого розуміння даних
- AI-аналіз даних з використанням моделей OpenAI та Google Gemini
- Гібридний чат з відповідями на питання про проєкт
- Автоматична генерація структурованих звітів на основі даних
- Збереження результатів аналізу та візуалізацій


## Інтерфейс користувача

Інтерфейс додатку складається з кількох вкладок, кожна з яких відповідає за певну функціональність:

1. **CSV Аналіз** - завантаження, ініціалізація та аналіз даних з CSV-файлів
2. **Візуалізації** - створення та налаштування візуальних представлень даних
3. **AI Асистенти** - робота з AI моделями для аналізу та генерації контенту
4. **Jira API** - прямий зв'язок з Jira API (у розробці)
5. **Інтеграції** - інтеграція з іншими сервісами (у розробці)


## CSV Аналіз

Ця вкладка призначена для роботи з даними Jira у форматі CSV.

### Завантаження CSV-файлу

1. Перейдіть на вкладку "CSV Аналіз"
2. У блоці "Завантаження CSV" натисніть кнопку для вибору файлу або перетягніть файл у відповідну область
3. Встановіть значення "Кількість днів для визначення неактивних тікетів" (за замовчуванням 14 днів)

### Робота з локальними файлами

Програма може працювати з CSV-файлами, що зберігаються в директорії `current_data`:

1. Натисніть кнопку "Оновити список файлів" для відображення доступних локальних файлів
2. У випадаючому списку "Виберіть файли з директорії current_data" виберіть один або кілька файлів
3. Для перегляду вмісту конкретного файлу:
   - Виберіть файл у списку "Виберіть файл для перегляду"
   - Натисніть кнопку "Переглянути"

### Ініціалізація та аналіз даних

Для аналізу даних натисніть кнопку "Ініціалізація та Аналіз". Процес виконає наступні кроки:

1. Завантаження та об'єднання вибраних файлів (якщо вибрано кілька)
2. Обробка даних для аналізу
3. Генерація статистики та виявлення неактивних тікетів
4. Відображення звіту з результатами

Звіт містить:
- Загальну статистику проєкту (кількість тікетів, розподіл за статусами, типами, пріоритетами)
- Аналіз неактивних тікетів (тікети без змін протягом вказаного періоду)
- Рекомендації

### Очищення тимчасових даних

У розділі "Обслуговування" можна виконати очищення тимчасових даних:

1. Розгорніть секцію "Обслуговування"
2. Натисніть кнопку "Очистити тимчасові дані"

Ця функція видаляє всі тимчасові файли, включаючи індекси, сесії та звіти, але не видаляє файли в директорії `current_data`.

## Візуалізації

Вкладка "Візуалізації" дозволяє створювати різні графічні представлення даних.

### Створення візуалізацій

1. Виберіть тип візуалізації зі списку:
   - **Статуси** - розподіл тікетів за статусами
   - **Пріоритети** - розподіл тікетів за пріоритетами
   - **Типи тікетів** - розподіл за типами (Bugs, Tasks, Stories тощо)
   - **Призначені користувачі** - розподіл тікетів за виконавцями
   - **Активність створення** - кількість нових тікетів за період
   - **Активність оновлення** - кількість оновлених тікетів за період
   - **Кумулятивне створення** - наростаюча кількість тікетів з часом
   - **Неактивні тікети** - аналіз тікетів без руху
   - **Теплова карта: Типи/Статуси** - взаємозв'язок між типами та статусами
   - **Часова шкала проекту** - загальна шкала активності
   - **Склад статусів з часом** - зміна складу статусів з часом

2. Налаштуйте параметри візуалізації (в акордеоні "Параметри візуалізації"):
   - **Ліміт для топ-візуалізацій** - кількість елементів для відображення (для топ-списків)
   - **Групування для часових діаграм** - рівень деталізації (день, тиждень, місяць)

3. Натисніть кнопку "Генерувати" для створення візуалізації

### Збереження візуалізацій

Щоб зберегти створену візуалізацію:

1. Введіть ім'я файлу (або залиште порожнім для автоматичного імені)
2. Натисніть кнопку "Зберегти візуалізацію"
3. Візуалізація буде збережена в директорії `reports/visualizations`

## AI Асистенти

Вкладка "AI Асистенти" надає доступ до функцій аналізу даних за допомогою штучного інтелекту.

### Налаштування параметрів

Для всіх режимів AI можна налаштувати:

- **Модель LLM** - вибір між моделями:
  - `gemini` - використовує Google Gemini моделі
  - `openai` - використовує OpenAI моделі (GPT)
- **Температура** - параметр для контролю креативності відповідей (вищі значення = більше креативності, нижчі = більше детермінованості)

### Ініціалізація індексів

Перед використанням режиму Гібридного чату необхідно створити індекси для ефективного пошуку:

1. Переконайтеся, що дані вже завантажені через вкладку "CSV Аналіз"
2. Натисніть кнопку "Ініціалізувати індекси"
3. Дочекайтеся повідомлення про успішне створення індексів

Цей крок створює:
- Векторні індекси FAISS для семантичного (смислового) пошуку
- BM25 індекси для пошуку за ключовими словами

### Режими роботи з AI

#### Q/A з повним контекстом

Режим для загальних питань про проєкт, який надає доступ до всіх даних одночасно:

1. Введіть питання у відповідне поле
2. Натисніть "Отримати відповідь"
3. Система аналізує всі дані та надає комплексну відповідь

Приклади питань:
- "Які тікети мають найвищий пріоритет?"
- "Скільки помилок було виправлено за останній місяць?"
- "Хто найактивніший розробник у проєкті?"

#### Гібридний чат

Режим діалогу з системою, який використовує комбінацію BM25 і векторного пошуку:

1. Введіть питання у поле для повідомлення
2. Натисніть Enter або Shift+Enter для відправки
3. Система відповідає на основі аналізу даних
4. Можна вести діалог з послідовними питаннями

Переваги:
- Підтримує контекст розмови (враховує попередні питання та відповіді)
- Показує релевантні документи/тікети для кожної відповіді
- Оптимальний для детальних специфічних запитань

#### Генерація звіту

Режим для автоматичного створення структурованого аналітичного звіту:

1. Виберіть формат звіту (markdown або html)
2. Натисніть "Згенерувати звіт"
3. Система аналізує всі дані та створює детальний звіт

Звіт зазвичай містить:
- Короткий огляд проєкту
- Аналіз поточного стану
- Виявлені проблеми та ризики
- Рекомендації для покращення процесу
- Висновки та наступні кроки


## Експорт даних з Jira у CSV-формат

Для коректної роботи з Jira AI Assistant необхідно правильно експортувати дані з Jira у форматі CSV. Нижче наведено детальні інструкції з експорту.

### Пошук та налаштування даних для експорту

1. **Відкрийте Jira** та авторизуйтеся у системі
2. **Перейдіть до функції пошуку**: натисніть "Issues" у верхньому меню, потім виберіть "Search for issues"
3. **Налаштуйте фільтри пошуку** для відбору потрібних тікетів:
   - Виберіть проєкт (наприклад, "IEE DS") з випадаючого списку
   - Вкажіть тип завдань ("Type") або залиште "All"
   - Вкажіть статус завдань ("Status") або залиште "All"
   - За потреби вкажіть виконавця ("Assignee")
   - Використовуйте поле пошуку для конкретного тексту
   - Для більш складних запитів натисніть "Advanced" і використовуйте JQL-запити

4. **Натисніть кнопку "Search"** для отримання результатів

### Експорт результатів пошуку у CSV

1. **У результатах пошуку натисніть кнопку "Export"** (знаходиться у правому верхньому куті)
2. **Виберіть "CSV (Current fields)"** або "CSV (All fields)" залежно від того, які дані вам потрібні:
   - "Current fields" - експортує тільки поля, що відображаються у поточному представленні
   - "All fields" - експортує всі доступні поля (рекомендовано для повного аналізу)

3. **Налаштуйте опції експорту**:
   - Переконайтеся, що включені всі важливі поля: Issue key, Summary, Status, Issue Type, Priority, Created, Updated, Description, Assignee, Reporter
   - Якщо використовуєте власні поля (custom fields), переконайтеся, що вони також включені

4. **Підтвердіть експорт** і збережіть CSV-файл на вашому комп'ютері

### Рекомендації щодо експорту

- **Експортуйте всі можливі поля**, особливо якщо плануєте використовувати AI аналіз. Більше даних дозволяє отримати більш глибокі та точні інсайти.
- **Включіть поле Description** для аналізу текстового вмісту тікетів.
- **Включіть поля з коментарями**, якщо вони доступні у вашій конфігурації Jira.
- **Експортуйте вкладення або посилання**, якщо вони важливі для аналізу.
- **Для великих проєктів** розгляньте можливість створення кількох експортів з різними наборами фільтрів для більш цілеспрямованого аналізу.


## Поради з використання

### Оптимальні практики

1. **Підготовка даних**:
   - Експортуйте з Jira максимально повний набір даних з усіма важливими полями
   - Упевніться, що CSV-файл містить колонки: Issue key, Summary, Status, Issue Type, Priority, Created, Updated

2. **Правильна послідовність дій**:
   - Спочатку завантажте і проаналізуйте дані (вкладка "CSV Аналіз")
   - Створіть необхідні візуалізації (вкладка "Візуалізації")
   - Ініціалізуйте індекси перед використанням AI асистентів
   - Використовуйте функції AI для глибшого аналізу

3. **Вибір режиму AI**:
   - "Q/A з повним контекстом" - для загальних питань про проєкт
   - "Гібридний чат" - для детальних питань з контекстом розмови
   - "Генерація звіту" - для створення структурованих звітів

### Вирішення поширених проблем

1. **Не вдається завантажити CSV**:
   - Перевірте формат CSV-файлу та наявність необхідних колонок
   - Переконайтеся, що файл не порожній і не пошкоджений
   - Спробуйте скопіювати файл у директорію `current_data` і використати через локальні файли

2. **Помилки при створенні індексів**:
   - Переконайтеся, що встановлені всі необхідні бібліотеки для AI
   - Очистіть тимчасові дані та спробуйте знову
   - Перевірте наявність достатньої кількості вільного місця на диску

3. **AI асистент не відповідає**:
   - Перевірте наявність та валідність API ключів (OpenAI або Gemini)
   - Для гібридного чату переконайтеся, що індекси успішно ініціалізовані


## Додаткова інформація

Для додаткових запитань і технічної підтримки звертайтеся до розробника (szabolotnii@healthprecision.com).

---

### Глосарій

- **CSV-файл** - формат файлу для зберігання табличних даних, який можна експортувати з Jira
- **Неактивні тікети** - тікети, які не оновлювалися протягом визначеного періоду
- **FAISS** - бібліотека для ефективного пошуку схожих векторів, використовується для семантичного пошуку
- **BM25** - алгоритм ранжування для пошуку за ключовими словами
- **Гібридний пошук** - комбінація BM25 та векторного пошуку для покращення релевантності результатів