DocUA's picture
Єдиний коміт - очищення історії
4ad5efa
# 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 та векторного пошуку для покращення релевантності результатів