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 та векторного пошуку для покращення релевантності результатів