ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Реализовать user feedback loop (лайк/дизлайк + free text)

1. Цель задачи

Разработать и внедрить в существующее AI-приложение (чат-бот, RAG-ассистент или генеративный интерфейс) механизм сбора обратной связи от пользователей. Обратная связь должна включать бинарную оценку (лайк/дизлайк) и опциональное текстовое пояснение. Основная метрика успеха — feedback rate ≥ 5% (доля сессий/ответов, по которым получена хотя бы бинарная оценка). Задача учит проектировать UX-компоненты, API, хранилище событий и простую аналитику.

Ключевой результат Рабочий прототип фидбек-лупа в AI-приложении, измеренный feedback rate ≥ 5% при тестировании на 100+ запросах.

2. Исходные данные

Если нет реального AI-приложения — симулируем:

1. Развернуть минимальный чат-бот на FastAPI, который отвечает заглушками или использует OpenAI API.
2. Создать простой HTML-интерфейс с полем ввода и историей сообщений.
3. После каждого ответа бота добавить кнопки «👍 / 👎» и текстовое поле (опционально).

3. Технологический стек

4. Этапы выполнения

Этап 1: Проектирование API и модели данных (30 минут)

Действия

1. Определить структуру события фидбека:

   class Feedback(BaseModel):
       answer_id: str          # ID ответа, к которому относится фидбек
       session_id: str         # ID сессии пользователя
       rating: int             # 1 (лайк), 0 (дизлайк)
       text: Optional[str]     # Свободный текст (max 500 символов)
       timestamp: int          # Unix time (milliseconds)
   

2. Спроектировать REST-endpoint:

   • POST /api/v1/feedback — принимает JSON с фидбеком.
   • Ответ: {"status": "ok", "feedback_id": "uuid"} или ошибка.
   • Валидация: rating обязателен (1 или 0), text опционально.

3. Выбрать хранилище: использовать PostgreSQL с таблицей:

   CREATE TABLE feedback (
       id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
       answer_id TEXT NOT NULL,
       session_id TEXT NOT NULL,
       rating INTEGER NOT NULL CHECK (rating IN (0,1)),
       text TEXT,
       created_at TIMESTAMPTZ NOT NULL DEFAULT now()
   );
   CREATE INDEX idx_answer_id ON feedback(answer_id);
   

Ожидаемый результат этапа Документ с API-спецификацией (OpenAPI/Swagger), модель данных, миграция БД.

Этап 2: Реализация бэкенд-сервиса (1.5–2 часа)

Действия

1. Создать новый микросервис или добавить эндпоинт в существующий бэкенд FastAPI.
2. Реализовать эндпоинт POST /feedback:
   • Логировать входящий запрос.
   • Валидировать с помощью Pydantic.
   • Сохранять в БД (через asyncpg / SQLAlchemy).
   • Возвращать ID фидбека.
3. Добавить rate limiting (100 запросов/с на IP) и защиту от дублирования (check answer_id + session_id).
4. Подготовить эндпоинт для получения статистики (только для разработчика): GET /feedback/stats?from=...&to=... — возвращает total, likes, dislikes, rate.

Пример кода (FastAPI):

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
import asyncpg
import uuid

app = FastAPI()
DB_POOL = ...

class FeedbackIn(BaseModel):
    answer_id: str = Field(..., min_length=1, max_length=128)
    session_id: str = Field(..., min_length=1, max_length=128)
    rating: int = Field(..., ge=0, le=1)
    text: str | None = Field(None, max_length=500)

@app.post("/api/v1/feedback")
async def create_feedback(fb: FeedbackIn):
    async with DB_POOL.acquire() as conn:
        row = await conn.fetchrow(
            "INSERT INTO feedback (answer_id, session_id, rating, text) "
            "VALUES ($1,$2,$3,$4) RETURNING id",
            fb.answer_id, fb.session_id, fb.rating, fb.text
        )
    return {"status": "ok", "feedback_id": str(row["id"])}

Ожидаемый результат этапа Рабочий API, доступный через Swagger (http://localhost:8000/docs). Сохранение фидбека в БД подтверждено тестовым запросом.

Этап 3: Интеграция UI-компонента (2–3 часа)

Действия

1. Выбрать UI-фреймворк: React с TypeScript (или чистый HTML+JS для минимализма).
2. После каждого ответа бота отобразить блок фидбека:
   • Две кнопки: 👍 (лайк), 👎 (дизлайк).
   • После нажатия кнопки появляется текстовое поле «Опишите проблему / идею (необязательно)».
   • Кнопка «Отправить» отправляет POST на /api/v1/feedback.
   • После отправки кнопки становятся неактивными, текст поля очищается.
3. UX-рекомендации:
   • Кнопки появляются через 2–3 секунды после ответа (чтобы не отвлекать).
   • Текстовое поле не блокирует отправку бинарной оценки (можно отправить и без текста).
   • Показывать анимацию успешной отправки (галочка).
4. Сохранять answer_id и session_id на фронте (например, в состоянии компонента).

Пример React-компонента

interface FeedbackProps {
  answerId: string;
  sessionId: string;
  onFeedbackSent: () => void;
}

const FeedbackWidget: React.FC<FeedbackProps> = ({ answerId, sessionId }) => {
  const [rating, setRating] = useState<1|0|null>(null);
  const [text, setText] = useState('');
  const [sent, setSent] = useState(false);

  const sendFeedback = async () => {
    await fetch('/api/v1/feedback', {
      method: 'POST',
      body: JSON.stringify({ answer_id: answerId, session_id: sessionId, rating, text }),
      headers: {'Content-Type':'application/json'}
    });
    setSent(true);
  };
  // ... рендер кнопок и поля
};

Ожидаемый результат этапа Интерфейс отображается, фидбек отправляется и сохраняется.

Этап 4: Мониторинг и аналитика (1 час)

Действия

1. Написать скрипт (Python) для подсчёта feedback_rate:

   import psycopg2
   conn = psycopg2.connect(...)
   cur = conn.cursor()
   cur.execute("""
       SELECT
           COUNT(*) AS total_answers,
           COUNT(DISTINCT answer_id) FILTER (WHERE f.answer_id IS NOT NULL) AS feedback_answers,
           ROUND(100.0 * COUNT(DISTINCT answer_id) FILTER (WHERE f.answer_id IS NOT NULL) / NULLIF(COUNT(*),0), 2) AS rate
       FROM answers a
       LEFT JOIN feedback f ON a.id = f.answer_id
   """)
   print(cur.fetchone())
   

2. Создать дашборд (Grafana или просто консоль) для отслеживания:
   • Feedback rate за последний час/день.
   • Распределение лайков/дизлайков.
   • Средняя длина текста.
3. Настроить алерт: если feedback rate < 3% — уведомление в Slack/telegram (опционально).

Ожидаемый результат этапа Скрипт аналитики, график метрики, понимание динамики.

Этап 5: Тестирование и достижение 5% feedback rate (1 час)

Действия

1. Провести ручное тестирование: сделать 100+ запросов к боту, часть с фидбеком.
2. Запустить автоматическое тестирование (например, pytest + locust) с симуляцией пользователей.
3. Измерить итоговый feedback rate.
4. Если rate < 5%, применить улучшения:
   • Добавить подсказку «Оцените ответ» (tooltip).
   • Уменьшить задержку появления кнопок до 1 секунды.
   • Использовать ненавязчивый pop-up после 3–5 ответов.
5. Повторить замеры.

Ожидаемый результат этапа Метрика ≥ 5% на 100+ запросах. Отчёт о тестировании.

5. Критерии приемки (Definition of Done)

• API эндпоинт POST /api/v1/feedback принимает бинарную оценку (0/1) и опциональный текст.
• Фидбек сохраняется в БД с корректными полями и индексами.
• UI-виджет появляется после каждого ответа бота; после отправки кнопки деактивируются.
• Реализована валидация: rating обязателен, текст не более 500 символов, защита от дублирования.
• Написан скрипт для расчёта feedback rate (доля ответов с фидбеком).
• При тестировании на 100+ запросах feedback rate ≥ 5%.
• Код покрыт unit-тестами (хотя бы для API-эндпоинта).
• README с описанием как запустить, протестировать и интерпретировать метрику.

6. Ожидаемый результат

Основной результат Проект (репозиторий) с реализованным user feedback loop. Содержит:

• Исходный код бэкенда (FastAPI/Flask) с эндпоинтом.
• Фронтенд-компонент (React/JS) с кнопками и полем.
• SQL-миграция для БД.
• Скрипт аналитики analyze_feedback.py.
• README с инструкцией и результатами тестирования.

Опциональные дополнительные результаты

• Дашборд Grafana с метриками.
• Alert на падение feedback rate.
• A/B-тестирование двух вариантов UI (с задержкой / без).

7. Возможные сложности и их решение

8. Бюджет времени (оценка)

Примечание Для первого раза с изучением инструментов заложите +2 часа.

9. Связанные вопросы из базы знаний

10. Чек-лист самопроверки

• Я спроектировал(а) API и модель данных до начала кодирования.
• Эндпоинт обрабатывает ошибки (400, 422, 500) корректно.
• Фронтенд корректно отправляет answer_id и session_id.
• Feedback rate считаю как distinct answer_id with feedback / total answer_id, а не число строк.
• После отправки фидбека кнопки блокируются, чтобы избежать дубликатов.
• Я протестировал(а) сценарий «10 запросов без фидбека, 10 с фидбеком» — rate = 50%.
• На случай если rate < 5% — у меня есть план по улучшению UX.
• README содержит команды для запуска и пример расчёта метрики.
• Код покрыт хотя бы одним unit-тестом на эндпоинт.
• Вся личная/тестовая информация удалена из репозитория (не коммичу токены).