# API Documentation

## Оглавление

- [Описание](#описание)
- [Установка](#установка)
- [Конфигурация](#конфигурация)
- [API Endpoints](#api-endpoints)
- [Команды Artisan](#команды-artisan)
- [Теги](#теги)
- [Telegram Bot](#telegram-bot)
- [Разработка](#разработка)

## Описание

API для управления ссылками с интеграцией Telegram бота и AI-анализа.

## Установка

```bash
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate
```

## Конфигурация

### Переменные окружения

```env
# OpenRouter API для AI
OPENROUTER_API_KEY=your_key
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_MODEL=anthropic/claude-3.5-sonnet

# Telegram Bot
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_WEBHOOK_SECRET=your_webhook_secret

# Google Safe Browsing
GOOGLE_SAFE_BROWSING_API_KEY=your_api_key
```

## API Endpoints

### Аутентификация

- `POST /api/auth/login` - Вход в систему
- `POST /api/auth/logout` - Выход из системы

### Ссылки

- `GET /api/links` - Список ссылок пользователя
- `POST /api/links` - Создание новой ссылки
- `GET /api/links/{id}` - Получение ссылки
- `PUT /api/links/{id}` - Обновление ссылки
- `DELETE /api/links/{id}` - Удаление ссылки

### Теги

- `GET /api/tags` - Список тегов пользователя
- `POST /api/tags` - Создание тега
- `PUT /api/tags/{id}` - Обновление тега
- `DELETE /api/tags/{id}` - Удаление тега

### Telegram API

- `GET /api/telegram/auth-token` - Получение токена для привязки
- `GET /api/telegram/connection-status` - Статус подключения
- `POST /api/telegram/disconnect` - Отключение от Telegram

## Команды Artisan

### Управление тегами

```bash
# Универсальное объединение тегов (все операции)
php artisan tags:merge

# Объединение для конкретного пользователя
php artisan tags:merge --user-id=1

# Только AI-теги
php artisan tags:merge --ai-only

# Предварительный просмотр изменений
php artisan tags:merge --dry-run

# Выборочные операции
php artisan tags:merge --semantic --duplicates
php artisan tags:merge --standardize
```

### Telegram

```bash
# Генерация токена для привязки к Telegram
php artisan telegram:generate-token user@example.com

# Генерация токена для конкретного пользователя
php artisan telegram:generate-token --user-id=1
```

## Теги

### AI-система анализа

Система автоматически анализирует теги с помощью ИИ:

- **Поиск алиасов** - автоматическое обнаружение похожих тегов
- **Семантическая группировка** - группировка по смыслу
- **Канонические названия** - предложение лучших вариантов

### Универсальное объединение тегов

```bash
# Все операции: семантический анализ, дубликаты, стандартизация
php artisan tags:merge

# Только AI-теги → #AI
php artisan tags:merge --ai-only

# Выборочные операции
php artisan tags:merge --semantic --duplicates
php artisan tags:merge --standardize

# Паттерны AI: искусственный интеллект, ИИ, AI, artificial intelligence
```

Подробнее: [TAGS_NORMALIZATION.md](TAGS_NORMALIZATION.md)

## Telegram Bot

### Привязка аккаунта

1. Получить токен: `GET /api/telegram/auth-token`
2. Отправить в бота: `/auth <token>`
3. Аккаунт автоматически привяжется

### Команды бота

- `/auth <token>` - Привязка аккаунта
- `/stats` - Статистика ссылок
- `/help` - Справка

### Настройка webhook

```bash
# Установка webhook
curl -X POST "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-domain.com/api/telegram/webhook"}'
```

## Разработка

### Запуск тестов

```bash
# Все тесты
php artisan test

# Конкретная группа
php artisan test --filter=TagAnalysisServiceTest

# С покрытием
php artisan test --coverage
```

### Структура проекта

```
app/
├── Console/Commands/          # Artisan команды
├── Http/Controllers/          # API контроллеры
├── Models/                    # Eloquent модели
├── Services/                  # Бизнес-логика
│   ├── AiService.php         # AI интеграция
│   ├── TagAnalysisService.php # Анализ тегов
│   └── TelegramService.php   # Telegram логика
└── Jobs/                     # Фоновые задачи
```

### Логирование

```bash
# Просмотр логов
tail -f storage/logs/laravel.log

# Фильтр по тегам
grep "Tags normalization" storage/logs/laravel.log
grep "AI analysis" storage/logs/laravel.log
```