🤖🎯 Spec-Driven Development: научи AI-агента делать то, что нужно

# spec: анализ YouTube видео

Статус: актуально  
Версия: 1.1  
Автор: @ivanov  

---

## Зачем
Создатели контента хотят учиться на успешных видео.
Мы автоматизируем анализ: хук, темп, ключевые моменты, рекомендации.

---

## Контракт
POST /api/videos/analyze
Body: {"url": "https://youtube.com/watch?v=..."}
Успешный ответ -- 200:

{
  "video_id": "...",
  "title": "...",
  "analysis": {
    "hook": {"summary": "...", "rating": "strong"},
    "pacing": {"summary": "..."},
    "key_points": [{"timestamp": "0:15", "description": "..."}],
    "improvements": ["..."]
  }
}

Ошибки:

400 -- невалидный URL 
404 -- видео не найдено 
422 -- нет субтитров или видео > 60 мин 
429 -- rate limit (5 запросов/мин) 
502 -- ошибка сервиса анализа (невалидный ответ Claude или недоступность Claude API) 
503 -- сервис субтитров недоступен (UltraData API не отвечает) 

---

## Инварианты
- Анализ только через Claude Opus
- Субтитры кешируются на 7 дней
- Результат анализа кешируется на 30 дней
- Максимальная длина видео -- 60 минут
- Rate limit: 5 запросов в минуту на IP-адрес, fixed window  
- Авторизация: эндпоинт публичный, без авторизации (вне scope этой итерации)

---

## Граничные случаи

**Видео без субтитров**
→ 422: {"error": "no_subtitles", "message": "Субтитры недоступны"}

**UltraData API упал**
Retry 3 раза (интервал 5 сек, без экспоненциального backoff), потом 503:
{"error": "transcript_service_unavailable"}

**Видео удалено**
→ 404: {"error": "video_not_found"}

**Видео > 60 минут**
→ 422: {"error": "video_too_long", "max_duration": 3600}

**Rate limit превышен**
Fixed window 60 сек, лимит 5 запросов на IP-адрес. 
→ 429: {"retry_after": <секунды до конца текущего окна>}
Пример: окно открылось в 12:00:00, 6-й запрос пришел в 12:00:18 → retry_after: 42

**Claude API вернул невалидный JSON или оборванный ответ**
Retry 2 раза (интервал 3 сек). Если после всех попыток ответ все еще
невалиден → 502: {"error": "analysis_failed", "message": "Не удалось получить анализ, попробуйте позже"}
Невалидный ответ не кешируется.

**Claude API недоступен (5xx/timeout)**
Retry 2 раза (интервал 3 сек), потом 502: {"error": "analysis_service_unavailable"}

---

## Архитектурные правила
- Фронтенд вызывает только `/api/videos/analyze`
- Claude API вызывает только backend
- Кеширование только через Redis
- Компоненты не вызывают внешние API напрямую, минуя соответствующий сервис
  (TranscriptService — единственная точка входа к UltraData, AnalysisService — к Claude)

---

## Технические требования
- Используй UltraData API для субтитров (API key в `.env`), не используй
  другие источники субтитров
- Используй Claude Opus через Anthropic SDK
- Для кеширования используй `RedisCache` из `utils/cache.py`
- Если результат анализа есть в кеше — он возвращается сразу, без обращения к TranscriptService и без повторной проверки длительности видео  
- НЕ добавляй youtube-transcript-api, yt-dlp
- НЕ скачивай видео на диск
- НЕ храни сырой транскрипт в ответе

---

## Вне scope
- ❌ Анализ визуального ряда -- только текст субтитров
- ❌ Поддержка Vimeo/TikTok -- только YouTube
- ❌ История анализов в UI -- не в этом спринте
- ❌ Экспорт в PDF -- не сейчас
- ❌ Авторизация и квоты по пользователям -- не в этом спринте

---

## Задачи

### Task 1: TranscriptService
**Файлы:** `services/transcript_service.py`
- `extract_video_id(url)` -- парсинг URL
- `fetch_transcript(video_id)` -- вызов UltraData API
- Retry 3 раза при 5xx (интервал 5 сек)
- Кеширование через Redis (TTL 7 дней)

**Верификация:**
- [ ] `pytest tests/test_transcript_service.py` проходит
- [ ] Вызов с реальным video_id возвращает транскрипт
- [ ] Повторный вызов берет из кеша
- [ ] Мокнутый 503 от UltraData во всех 4 попытках (1 исходный запрос + 3 retry) → TranscriptServiceUnavailableError наверх (роут конвертирует в HTTP 503 согласно разделу «Граничные случаи») 

---

### Task 2: AnalysisService
**Файлы:** `services/analysis_service.py`
- `analyze_video(video_id, transcript)` -- промпт для Claude
- Retry 2 раза (интервал 3 сек) при ошибках API и при невалидном/
  оборванном JSON в ответе
- Кеширование результата (TTL 30 дней), невалидный ответ не кешируется

**Верификация:**
- [ ] `pytest tests/test_analysis_service.py` проходит
- [ ] Mock Claude API возвращает валидный JSON → сохраняется в кеш
- [ ] Mock Claude API возвращает невалидный JSON во всех 3 попытках (1 исходный запрос + 2 retry) → AnalysisFailedError наверх, кеш не записан 
- [ ] Повторный вызов берет из кеша

---

### Task 3: POST /api/videos/analyze
**Файлы:** `api/routes/videos.py`
- Парсинг URL, валидация
- Rate limiting (5 req/min, fixed window, на IP-адрес) 
- Проверка длины видео (< 60 мин)
- Обработка всех ошибок согласно разделу «Граничные случаи»

**Верификация:**
- [ ] `curl -X POST /api/videos/analyze -d '{"url":"..."}'` → 200
- [ ] Невалидный URL → 400
- [ ] Видео без субтитров → 422
- [ ] 6-й запрос в минуту → 429 с корректным retry_after
- [ ] Мокнутый невалидный JSON от Claude → 502 с error=analysis_failed 
- [ ] Мокнутая недоступность Claude API → 502 с error=analysis_service_unavailable 

---

### Task 4: UI
**Файлы:** `frontend/src/pages/AnalyzePage.tsx`
- Input для YouTube URL
- Loader во время анализа
- Отображение результата (хук, темп, ключевые моменты, рекомендации)
- Обработка ошибок: 
  - error=analysis_service_unavailable → «Сервис анализа временно недоступен» 
  - error=analysis_failed → «Не удалось получить анализ, попробуйте позже» 

**Верификация:**
- [ ] Вставка валидного URL → результат отображается
- [ ] Видео без субтитров → показывается «Субтитры недоступны»
- [ ] Rate limit → показывается таймер обратного отсчета на retry_after секунд
- [ ] Mock 502 с error=analysis_service_unavailable → «Сервис анализа временно недоступен» 
- [ ] Mock 502 с error=analysis_failed → «Не удалось получить анализ, попробуйте позже» 

---

## Критерии приемки
- [ ] Пользователь вставляет URL → видит полный анализ
- [ ] Видео без субтитров → видит понятное сообщение
- [ ] Видео > 60 мин → видит «Слишком длинное»
- [ ] 6-й запрос → видит таймер с корректным временем ожидания
- [ ] Повторный анализ того же видео → мгновенный результат (берется
      из кеша анализа, а не пересчитывается заново)
- [ ] Claude вернул невалидный ответ → пользователь видит понятную
      ошибку, а не зависший loader

Напиши спецификацию для фичи: анализ YouTube видео.

Структура: Зачем, Что, Контракты, Инварианты, Граничные случаи, 
Архитектурные правила, Технические требования, Вне scope, 
Задачи (3-5 штук с верификацией).

Контекст: Python/FastAPI, React, Redis, Claude Opus, 
UltraData API для субтитров.

Прежде чем писать, проверь, хватает ли тебе информации для 
Инвариантов и Граничных случаев (лимиты по длительности видео, 
правила кеширования, поведение при отсутствии субтитров и т.д.). 
Если каких-то решений не хватает -- задай мне вопросы списком, 
не придумывай их сам.

Каждый пункт делай конкретным и проверяемым: коды ошибок, 
точные числа лимитов, названия библиотек -- без общих формулировок 
вроде "обрабатываем ошибки корректно".

Прочитай spec.md. Реализуй только Task 1 (минимальный прототип).
Протестируй, что базовая механика работает.

Прочитай spec.md. Реализуй Task 1.

Прочитай spec.md. Реализуй Task 2.

Проверь, что Task 1 работает:
1. Запусти pytest
2. Попробуй вызвать функцию вручную
3. Убедись, что кеширование работает

- Retry 3 раза при ошибках UltraData API 
+ Retry 3 раза (интервал 5 сек), потом 503 — без этого агент зависал в бесконечном retry при недоступности сервиса 

Ты пишешь спецификацию для AI-агента по методологии Spec-Driven Development.

Контекст проекта:
- Стек: [впиши свой, например Python/FastAPI, React, Redis]
- Фича: [опиши задачу в 1-2 предложениях]

Прежде чем писать спеку, проверь, хватает ли тебе информации.
Если не хватает -- НЕ придумывай, а задай мне уточняющие вопросы
по каждому из пунктов ниже и жди ответа.

Структура спеки:
- Зачем: зачем это нужно, для кого
- Что: что делаем (1-2 абзаца, без деталей реализации)
- Контракты: эндпоинты, форматы запросов/ответов, коды ошибок
- Инварианты: правила без исключений (лимиты, ограничения, выбор модели/сервиса)
- Граничные случаи: что происходит, когда что-то идет не так
  (минимум 3-5 случаев: невалидный вход, отказ внешнего сервиса, превышение лимита)
- Архитектурные правила: какой компонент с каким имеет право общаться
- Технические требования: какие библиотеки/сервисы использовать,
  что использовать запрещено
- Вне scope: что НЕ делаем в этой итерации (минимум 3 пункта)
- Задачи: 3-5 атомарных задач, каждая -- отдельный коммит,
  с конкретной командой/способом верификации
- Критерии приемки: 3-5 проверяемых сценариев "пользователь делает X → видит Y"

Правила:
- Будь конкретным: не "используй кеш", а "используй Redis с TTL 7 дней"
- Не гадай -- если решение неочевидно, спроси меня, а не выбирай сам
- Спека описывает ЧТО и контракты, а не КАК реализовывать алгоритм
- Каждый пункт должен умещаться в 1-3 предложения -- если получается больше,
  значит, это две задачи, а не одна
- Если фича маленькая (один файл, очевидное поведение) -- скажи мне,
  что спека не нужна, вместо того чтобы писать ее формально

Выведи результат в формате markdown, готовом для сохранения в spec.md.