📚 API Документація Discord AI Assistant Bot

Оновлено: 28.07.2025 Детальна документація API для всіх команд та сервісів Discord AI Assistant Bot.

📋 ЗМІСТ

🔍 Команда Пошуку
🤖 AI Асистент
📄 Управління Документами
📊 Аналітика
⚔️ Операції
🏗️ Архітектура API
🔒 Безпека
📊 Метрики

🔍 КОМАНДА ПОШУКУ

Опис

Синтаксис


/пошук запит: <текст> [тип_документа: <тип>] [дата_від: <дата>] [дата_до: <дата>] [підрозділ: <назва>] [пріоритет: <рівень>] [ліміт: <число>]

Параметри

запит

тип_документа

дата_від

дата_до

підрозділ

пріоритет

ліміт

Типи документів

all - Всі документи
orders - Накази
reports - Доповіді
statistics - Звіти
plans - Плани
instructions - Інструкції
protocols - Протоколи
cards - Картки
journals - Журнали

Пріоритети

all - Всі
critical - Критичний
high - Високий
medium - Середній
low - Низький

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

Простий пошук


/пошук запит: "сержанти"

Пошук з фільтрами


/пошук запит: "техніка" тип_документа: "накази" дата_від: "01.01.2025" пріоритет: "високий" ліміт: 10

Пошук по підрозділу


/пошук запит: "особовий склад" підрозділ: "2-й батальйон" дата_до: "31.12.2025"

Відповідь

Успішна відповідь

json
{
  "embeds": [
    {
      "title": "🔍 Результати пошуку",
      "description": "Знайдено 15 результатів для запиту: \"сержанти\"",
      "fields": [
        {
          "name": "1. Сержант Іванов І.І.",
          "value": "Посада: командир відділення, Статус: активний",
          "inline": false
        }
      ]
    }
  ],
  "components": [
    {
      "type": "ACTION_ROW",
      "components": [
        {
          "type": "BUTTON",
          "label": "◀️ Попередня",
          "style": "SECONDARY",
          "disabled": true
        },
        {
          "type": "BUTTON",
          "label": "Наступна ▶️",
          "style": "PRIMARY"
        }
      ]
    }
  ]
}

Помилка валідації

json
{
  "content": "❌ Помилка валідації: Запит не може бути порожнім",
  "ephemeral": true
}

Кешування

Тривалість: 5 хвилин
Ключ: search:${JSON.stringify(searchQuery)}
Умовне кешування: тільки при наявності результатів

🤖 AI АСИСТЕНТ

Опис

Синтаксис


/ai запит: <текст> [контекст: <текст>] [режим: <режим>]

Параметри

запит

контекст

режим

Режими роботи

general - Загальний (за замовчуванням)
analysis - Аналіз даних
report - Генерація звіту
explanation - Пояснення
recommendations - Рекомендації

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

Загальний запит


/ai запит: "Як покращити бойову готовність підрозділу?"

Аналіз з контекстом


/ai запит: "Проаналізуй особовий склад" контекст: "Дані за останній місяць" режим: "аналіз"

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


/ai запит: "Створи звіт про технічний стан" режим: "звіт"

Відповідь

Успішна відповідь

json
{
  "embeds": [
    {
      "title": "🤖 AI Відповідь",
      "description": "На основі аналізу даних особового складу...",
      "fields": [
        {
          "name": "📝 Режим",
          "value": "Аналіз даних",
          "inline": true
        },
        {
          "name": "👤 Користувач",
          "value": "testuser#1234",
          "inline": true
        }
      ]
    }
  ],
  "components": [
    {
      "type": "ACTION_ROW",
      "components": [
        {
          "type": "BUTTON",
          "label": "🔍 Пояснити",
          "style": "SECONDARY"
        },
        {
          "type": "BUTTON",
          "label": "📊 Аналізувати",
          "style": "SECONDARY"
        }
      ]
    }
  ]
}

Кешування

Тривалість: 30 хвилин
Ключ: ai:${base64(JSON.stringify(aiRequest))}
Умовне кешування: тільки успішні відповіді

📄 УПРАВЛІННЯ ДОКУМЕНТАМИ

Опис

Синтаксис


/документи <підкоманда> дія: <дія> [запит: <текст>]

Підкоманди

Особовий склад


/документи особовий-склад дія: <дія> [запит: <текст>]

Техніка


/документи техніка дія: <дія> [запит: <текст>]

Матеріали


/документи матеріали дія: <дія> [запит: <текст>]

Операції


/документи операції дія: <дія> [запит: <текст>]

Накази


/документи накази дія: <дія> [запит: <текст>]

Дії для всіх підкоманд

search

add

update

report

Спеціальні дії

Особовий склад

status - Статус особового складу
check - Перевірка документів

Техніка

maintenance - Обслуговування
status - Статус техніки

Матеріали

stock - Складські залишки
replenish - Поповнення

Операції

planning - Планування
archive - Архівування

Накази

create - Створення
edit - Редагування
approve - Підтвердження
archive - Архівування

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

Пошук особового складу


/документи особовий-склад дія: "пошук" запит: "сержанти"

Обслуговування техніки


/документи техніка дія: "обслуговування"

Складські залишки


/документи матеріали дія: "склад"

Планування операцій


/документи операції дія: "планування"

Створення наказу


/документи накази дія: "створення"

Відповідь

Успішна відповідь

json
{
  "embeds": [
    {
      "title": "👥 Особовий склад",
      "description": "Знайдено 25 сержантів у системі",
      "fields": [
        {
          "name": "🔧 Дія",
          "value": "Пошук",
          "inline": true
        },
        {
          "name": "👤 Користувач",
          "value": "testuser#1234",
          "inline": true
        }
      ]
    }
  ],
  "components": [
    {
      "type": "ACTION_ROW",
      "components": [
        {
          "type": "BUTTON",
          "label": "🔍 Пошук",
          "style": "SECONDARY"
        },
        {
          "type": "BUTTON",
          "label": "📊 Звіт",
          "style": "SECONDARY"
        }
      ]
    }
  ]
}

📊 АНАЛІТИКА

Опис

Синтаксис


/аналітика <підкоманда> [параметри]

Підкоманди

Звіт


/аналітика звіт тип: <тип> період: <період>

Статистика


/аналітика статистика категорія: <категорія>

Прогноз


/аналітика прогноз показник: <показник>

Порівняння


/аналітика порівняння період1: <період1> період2: <період2>

Параметри

Типи звітів

особовий-склад - Звіт по особовому складу
техніка - Звіт по техніці
матеріали - Звіт по матеріалам
операції - Звіт по операціях
накази - Звіт по наказах

Періоди

день - За день
тиждень - За тиждень
місяць - За місяць
квартал - За квартал
рік - За рік

Показники

боєготовність - Бойова готовність
особовий-склад - Стан особового складу
техніка - Технічний стан
матеріали - Забезпеченість матеріалами

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

Звіт по особовому складу


/аналітика звіт тип: "особовий-склад" період: "місяць"

Статистика техніки


/аналітика статистика категорія: "техніка"

Прогноз бойової готовності


/аналітика прогноз показник: "боєготовність"

Порівняння періодів


/аналітика порівняння період1: "січень" період2: "лютий"

⚔️ ОПЕРАЦІЇ

Опис

Синтаксис


/операції <підкоманда> [параметри]

Підкоманди

Ситуація


/операції ситуація сектор: <сектор> координати: <координати>

Завдання


/операції завдання дія: <дія> підрозділ: <підрозділ>

Координація


/операції координація тип: <тип> частота: <частота>

Розвідка


/операції розвідка тип: <тип> район: <район>

Зв'язок


/операції зв'язок тип: <тип> стан: <стан>

Параметри

Сектори

A, B, C, D - Основні сектори
Alpha, Bravo, Charlie - Альтернативні назви

Дії

розвідка - Розвідувальні дії
наступ - Наступальні дії
оборона - Оборонні дії
відхід - Відхід

Типи координації

зв'язок - Радіозв'язок
навігація - Навігація
логістика - Логістика

Типи розвідки

повітряна - Повітряна розвідка
наземна - Наземна розвідка
технічна - Технічна розвідка

Типи зв'язку

радіо - Радіозв'язок
супутник - Супутниковий зв'язок
оптичний - Оптичний зв'язок

Стани

активний - Активний
резерв - Резерв
ремонт - На ремонті

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

Ситуація в секторі


/операції ситуація сектор: "A" координати: "50.4501,30.5234"

Розвідувальне завдання


/операції завдання дія: "розвідка" підрозділ: "1-й батальйон"

Координація зв'язку


/операції координація тип: "зв'язок" частота: "123.45 МГц"

Повітряна розвідка


/операції розвідка тип: "повітряна" район: "північний"

Статус радіозв'язку


/операції зв'язок тип: "радіо" стан: "активний"

🏗️ АРХІТЕКТУРА API

Загальна структура

Всі команди мають:

Валідацію вхідних даних
Централізовану обробку помилок
Інтеграцію з сервісами
Кешування результатів
Метрики та логування

Структура відповіді

json
{
  "embeds": [
    {
      "title": "Заголовок",
      "description": "Опис",
      "fields": [],
      "timestamp": "2025-07-28T12:00:00.000Z"
    }
  ],
  "components": [
    {
      "type": "ACTION_ROW",
      "components": []
    }
  ]
}

Обробка помилок

Типи помилок

VALIDATION_ERROR - Помилка валідації
PERMISSION_ERROR - Помилка прав доступу
SERVICE_ERROR - Помилка сервісу
NETWORK_ERROR - Мережева помилка
UNKNOWN_ERROR - Невідома помилка

Структура помилки

json
{
  "content": "❌ Опис помилки",
  "ephemeral": true
}

Валідація

Загальні правила

Максимальна довжина запиту: 500 символів
Максимальна довжина контексту: 1000 символів
Обов'язкові поля повинні бути заповнені
Дати у форматі ДД.ММ.РРРР

Санітизація

Видалення HTML тегів
Екранування спеціальних символів
Обмеження розміру вхідних даних

🔒 БЕЗПЕКА

Авторизація

Ролі Discord

Адміністратор - Повний доступ
Бот-Користувач - Базовий доступ
Sheets-Доступ - Доступ до Google Sheets
AI-Доступ - Доступ до AI функцій
Експорт-Доступ - Доступ до експорту

Перевірка прав

javascript
// Приклад перевірки ролі
if (!interaction.member.roles.cache.some(role => role.name === 'Бот-Користувач')) {
  return interaction.reply({
    content: '❌ У вас немає прав для використання цієї команди',
    ephemeral: true,
  });
}

Rate Limiting

Обмеження

Загальні команди: 100 запитів/15 хвилин
AI команди: 50 запитів/15 хвилин
Пошук: 200 запитів/15 хвилин

Структура обмеження

javascript
{
  windowMs: 900000, // 15 хвилин
  maxRequests: 100, // Максимум запитів
  message: '❌ Забагато запитів. Спробуйте пізніше.'
}

Логування безпеки

Події, що логуються

Спроби доступу без прав
Перевищення лімітів запитів
Підозріла активність
Помилки валідації

Формат логу

json
{
  "timestamp": "2025-07-28T12:00:00.000Z",
  "level": "warn",
  "event": "SECURITY_VIOLATION",
  "user": "testuser#1234",
  "userId": "123456789",
  "command": "пошук",
  "details": "Попытка доступа без прав"
}

📊 МЕТРИКИ

Команди

Лічильники

commands_total - Загальна кількість команд
commands_success - Успішні команди
commands_error - Помилки команд

Гістограми

command_duration_seconds - Час виконання команд
command_response_time_seconds - Час відповіді

Сервіси

AI сервіс

ai_requests_total - Загальна кількість AI запитів
ai_requests_success - Успішні AI запити
ai_requests_error - Помилки AI запитів
ai_response_time_seconds - Час відповіді AI

Google сервіс

google_requests_total - Загальна кількість Google запитів
google_requests_success - Успішні Google запити
google_requests_error - Помилки Google запитів
google_response_time_seconds - Час відповіді Google

Кеш сервіс

cache_hits_total - Попадання в кеш
cache_misses_total - Промахи кешу
cache_size_bytes - Розмір кешу

Система

Ресурси

memory_usage_bytes - Використання пам'яті
cpu_usage_percent - Використання CPU
uptime_seconds - Час роботи

Discord

discord_guilds_total - Кількість серверів
discord_users_total - Кількість користувачів
discord_connections_total - Кількість підключень

Доступ до метрик

Prometheus endpoint


GET /metrics

Приклад відповіді


HELP commands_total Total number of commands
TYPE commands_total counter
commands_total{command="пошук"} 150
HELP command_duration_seconds Command execution duration
TYPE command_duration_seconds histogram
command_duration_seconds_bucket{command="пошук",le="0.1"} 50
command_duration_seconds_bucket{command="пошук",le="0.5"} 100
command_duration_seconds_bucket{command="пошук",le="1.0"} 150

📝 ПРИКЛАДИ ІНТЕГРАЦІЇ

JavaScript/Node.js

Виклик команди пошуку

javascript
const { Client, GatewayIntentBits } = require('discord.js');
const client = new Client({
  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages],
});
client.on('interactionCreate', async interaction => {
  if (!interaction.isChatInputCommand()) return;
  if (interaction.commandName === 'пошук') {
    const query = interaction.options.getString('запит');
    const documentType = interaction.options.getString('тип_документа');
    // Логіка обробки команди
    await interaction.reply(Пошук: ${query}, Тип: ${documentType});
  }
});

Інтеграція з сервісами

javascript
const bot = require('./src/core/Bot');
// Отримання сервісу
const aiService = bot.getService('ai');
const googleService = bot.getService('google');
// Використання сервісів
const response = await aiService.generateResponse('Запит');
const data = await googleService.getSheetData();

Python

Виклик через Discord API

python
import discord
from discord.ext import commands
bot = commands.Bot(command_prefix='!')
@bot.command()
async def search(ctx, query: str):
    # Логіка пошуку
    await ctx.send(f'Пошук: {query}')
bot.run('YOUR_TOKEN')

cURL

Тестування API

bash
Тест команди пошуку
curl -X POST "https://discord.com/api/v10/interactions" \
  -H "Content-Type: application/json" \
  -d '{
    "type": 2,
    "data": {
      "name": "пошук",
      "options": [
        {
          "name": "запит",
          "value": "сержанти"
        }
      ]
    }
  }'

🔧 НАЛАШТУВАННЯ

Конфігурація

Основні налаштування

javascript
// config/Config.js
module.exports = {
  discord: {
    token: process.env.DISCORD_TOKEN,
    clientId: process.env.DISCORD_CLIENT_ID,
  },
  google: {
    spreadsheetId: process.env.GOOGLE_SPREADSHEET_ID,
    apiKey: process.env.GOOGLE_API_KEY,
  },
  ai: {
    provider: process.env.AI_PROVIDER || 'openai',
    openai: {
      apiKey: process.env.OPENAI_API_KEY,
    },
  },
};

Налаштування кешування

javascript
const cacheConfig = {
  ttl: 300, // 5 хвилин
  maxSize: 1000, // Максимум елементів
  cleanupInterval: 60000, // Очищення кожну хвилину
};

Налаштування метрик

javascript
const metricsConfig = {
  enabled: true,
  port: 9090,
  path: '/metrics',
  collectDefaultMetrics: true,
};

Моніторинг

Health Check

bash
curl http://localhost:9090/health

Метрики

bash
curl http://localhost:9090/metrics

Логи

bash
tail -f logs/bot.log

📞 ПІДТРИМКА

Корисні команди

Допомога


/допомога

Статистика


/статистика

Очищення кешу


/очистити-кеш

Логування

Рівні логування

error - Помилки
warn - Попередження
info - Інформація
debug - Детальна інформація

Файли логів

logs/bot.log - Загальні логи
logs/error.log - Помилки
logs/commands.log - Логи команд

Діагностика

Перевірка стану сервісів

javascript
const bot = require('./src/core/Bot');
const services = bot.getServiceManager().getServicesStatus();
console.log('Статус сервісів:', services);

Перевірка метрик

javascript
const metrics = bot.getService('metrics');
const stats = metrics.getStats();
console.log('Метрики:', stats);

--- 📚 Ця документація оновлюється регулярно. Останнє оновлення: 28.07.2025