# TZ.md — Продуктовая ферма (требования к продукту)

> Сжатая версия полного 17-страничного ТЗ Атвинты — только то, что нужно для реализации.
> `DESIGN.md` покрывает только визуальный язык по референсу Arounda (§3.1 полного ТЗ): цвета,
> типографика, компоненты, стиль состояний. Карта экранов, пользовательские сценарии и конкретные
> состояния по каждому сценарию (§3.2–3.3 полного ТЗ) — отдельная задача, см. §7a ниже, DESIGN.md
> её не закрывает.
> Правила работы самого агента (без чего строить, как коммитить, что нельзя) — в `AGENTS.md`.
> Пометки приоритета: **P0** — без этого баллы не считаются (обязательные условия полноты),
> **P1** — основной вес оценки (аналитика 20%, архитектура 20%, работающий сервис 20%),
> **P2** — можно сделать упрощённо и явно пометить как ограничение прототипа.

## 0. Цель одним предложением

Пользователь надиктовывает/вводит текстом идею ИИ-решения или микросервиса → система превращает
её в карточку → ставит в очередь → запускает исследование и прогоны → считает потенциальный эффект
по мат./стат. модели → выдаёт критический отчёт с рекомендацией → одна выбранная идея доходит до
работающего MVP.

**Дедлайн: 10.09, 17:00.** Не строить всё на 100% — по каждому критерию оценивается 0/25/50/75/100%,
частично реализованное с честным описанием ограничения лучше, чем недоделанное без объяснений.

## 1. Выбранная идея для сквозного сценария (P0)

> Заполни здесь: конкретная идея, исходный процесс, метрика эффекта, какое реальное ИИ-решение и
> какой реальный микросервис подключаются. Только с ней проходишь путь целиком до MVP.

- Идея: `Автоматический разбор входящих обращений: обращение клиента (текст или голос) → ИИ-классификация (категория, приоритет, ответственный отдел) → проверка микросервисом-валидатором правил → сохранённая карточка обращения.`
- Исходный процесс (что делают сейчас, без ИИ): `Оператор читает каждое обращение вручную, сам определяет категорию и приоритет, вручную заполняет поля карточки и пересылает в нужный отдел. По данным модельного датасета (200 обращений): в среднем 6 минут на обращение, ~12% обращений классифицируются неверно и требуют перенаправления, ~8% возвращаются на доработку.`
- Основная метрика: `Время на операцию (обработку одного обращения): целевое снижение с 6 мин до ≤2.5 мин (ИИ-черновик + короткая ручная проверка вместо заполнения с нуля).`
- Метрика качества: `Доля корректных классификаций: базовая 88% (ручная), целевая ≥92% у ИИ-черновика после валидации правилами (порог 85% — ниже него вариант не проходит).`
- ИИ-решение (реальный API): `LLM z-ai/glm-5.3-flash через routerai.ru (OpenAI-compatible /v1/chat/completions) — классификация обращения в структуру; STT microsoft/mai-transcribe-2 через routerai.ru — расшифровка голосовых обращений.`
- Микросервис (реальный, отдельно вызываемый): `Валидатор правил (отдельный Node-процесс с HTTP-контрактом POST /validate, версия /version, отдельный docker-контейнер): проверяет обязательные поля, допустимые значения категорий/приоритетов, согласованность (напр. категория "жалоба" → приоритет не ниже medium), возвращает {valid, errors[]}.`

#### Job Statement

> Формат: When [ситуация], I want to [мотивация], so I can [ожидаемый результат].

**When** мне приходит поток разнородных обращений клиентов (текст и голос), **I want to**, чтобы каждое обращение автоматически превращалось в заполненную, проверенную правилами карточку, **so I can** тратить время на разбор сути и решение, а не на ручную сортировку и заполнение полей.

#### Job Stories

1. **Оператор поддержки:** «Когда приходит поток обращений, я хочу видеть готовый черновик карточки с категорией и приоритетом, чтобы за минуту проверить и отправить обращение в отдел, а не заполнять всё с нуля».
2. **Руководитель поддержки:** «Когда я планирую нагрузку на отделы, я хочу видеть долю корректных классификаций и время обработки по каждому варианту решения, чтобы решить, стоит ли внедрять ИИ-разбор».
3. **Проверяющий (демо-доступ):** «Когда я открываю сервис, я хочу проследить путь одной идеи от расшифровки до MVP с реальными вызовами и метриками, чтобы оценить обоснованность расчёта эффекта».

#### Ревизия полноты §2

Все поля карточки из §2 покрываются существующими артефактами пайплайна: `source_transcript` — расшифровка STT или введённый текст; `structured_idea/problem/audience/value` — роль «Аналитик идеи»; `baseline_metrics` — модельный датасет 200 обращений (метки: время обработки, корректность); `ai_solution_variants` — минимум 2 варианта (разный промпт/состав цепочки); `datasets_for_runs` — тот же датасет для исходного процесса и вариантов. Дополнение: для идеи §1 карточка дополнительно хранит поля MVP-сценария (категория, приоритет, отдел) в `structured_idea` — отдельного поля не требуется.

## 2. Сущность "Карточка идеи" (P0)

Обязательные поля:

```
id, title, source_transcript, structured_idea, problem, audience, value,
constraints, assumptions, priority (high|medium|low), funnel_stage,
execution_status (running|paused|error|waiting_for_data — отдельно от funnel_stage),
created_at, version, change_history[], result_links[],
original_process_description, baseline_metrics, expected_effect,
ai_solution_variants[], datasets_for_runs[]
```

Решение по статусам: `funnel_stage` — где идея в воронке (бизнес-смысл), `execution_status` —
техническое состояние текущего шага (пауза/ошибка/ожидание данных). Разделены, чтобы пауза на любом
этапе воронки не плодила отдельные стадии.

## 3. Воронка (funnel_stage) (P0)

```
draft → queued → research → critical_evaluation → decision → mvp_in_progress → mvp_ready | archived
```

Для каждого перехода агент должен зафиксировать: входное условие, что происходит на этапе, что на
выходе. Изменение карточки после анализа → новая версия → зависимые выводы помечаются устаревшими →
повторный анализ обновляет только нужные этапы, старый отчёт остаётся доступен в истории.

## 4. Методика критической оценки (P1 — 20% баллов)

Обязательные направления анализа (веса и глубину выбирает агент, но зафиксировать явно в конфиге,
не хардкодить в промптах):

| Что проверяем | Минимум в отчёте |
|---|---|
| Проблема и аудитория | ≥3 прото-персоны, боли, альтернативы, возражения |
| Рынок и конкуренты | границы рынка, ≥3 конкурента/альтернативы с источниками (или честное "меньше найдено") |
| Тренды и прогноз | драйверы, горизонт, 3 сценария (базовый/благоприятный/неблагоприятный) |
| Ценность и гипотезы | ≥3 проверяемые гипотезы: аудитория, эксперимент, метрика, порог успеха |
| Потенциальная эффективность | баз. показатели, мат.+стат. модель эффекта (см. §6) |
| Реализуемость и риски | тех/операционные/рыночные/правовые риски + данные, вероятность/влияние/меры |
| Основание для решения | за/против, стоп-факторы, уверенность, что дешевле всего проверить дальше |

**Правила доказательности:** факт = URL + источник + дата публикации (если есть) + дата обращения +
что именно поддерживает. Полный демо-прогон — минимум 5 источников. Разделять факт / оценку /
прогноз / допущение / результат симуляции. Симуляция аудитории (ИИ играет прото-персону) всегда
помечается `synthetic` — это не подтверждение спроса.

**Рекомендации:** `develop | validate_first | postpone | reject | insufficient_data`. Общий балл не
должен скрывать стоп-фактор (если есть стоп-фактор — рекомендация не может быть `develop`).

## 5. Расчёт потенциальной эффективности (P0 — обязательное условие полноты)

1. **Данные и база**: источник, период, единицы, число наблюдений, пропуски. Один и тот же набор
   задач для сравнения исходного процесса и вариантов.
2. **Математическая модель**: явная формула изменения показателя (напр. время = базовое −
   ИИ-обработка − ручная проверка). Формулы/параметры/единицы видны в отчёте. Не задваивать эффект.
3. **Статистическая модель**: доверительный интервал для средней разницы или bootstrap. Метод и
   предпосылки объяснены. Для случайных методов — зафиксированный seed (воспроизводимость при
   перезапуске с теми же параметрами — это тест, который будут проверять).
4. **Потенциальный эффект**: 3 сценария (базовый/благоприятный/неблагоприятный) с чувствительностью
   к объёму задач, качеству ИИ, доле ручной доработки.
5. **Условия решения**: порог полезного эффекта задаётся заранее. Отрицательный эффект / ухудшение
   качества / интервал, включающий "без изменений" → влияет на рекомендацию автоматически.

**Критично**: расчёт выполняется программно на сервере (детерминированный код), не ИИ "на словах".
ИИ выбирает методику и комментирует, но число берётся из проверяемого вычисления. Хранить
формулу/версию модели, входные данные, параметры, результат.

## 6. Архитектура — поток данных (P1 — 20% баллов)

```
UI → API (Nitro routes) → Postgres (карточки, версии, аудио, источники, прогоны, расчёты)
                              ↓
                    очередь + оркестратор (persistent worker)
                              ↓
              ИИ-решения и микросервисы (реальные вызовы, каталог компонентов)
                              ↓
                    журнал прогонов → расчётный модуль → отчёт → MVP
```

Промпты/роли/критерии оценки/модели/лимиты — в конфиге, отдельно от логики интерфейса (чтобы можно
было заменить ИИ-провайдера или добавить этап без пересборки). Микросервисы — с явным
контрактом (вход/выход/версия), заменяемые независимо.

## 7. Роли (консолидировано под 5-дневный срок) (P1)

ТЗ перечисляет 12 ролей, явно разрешая объединять близкие — качество передачи важнее количества
агентов. Рекомендуемая консолидация (зафиксировать это решение в документации сервиса):

| Роль в сервисе | Покрывает из ТЗ | Вход → выход |
|---|---|---|
| **Оркестратор** | Оркестратор | идея, приоритет, состояние → план, вызовы, контроль лимитов |
| **Аналитик идеи** | Аналитик идеи | текст/расшифровка → структура карточки, допущения |
| **Аналитик рынка и аудитории** | Аналитик рынка + Исследователь + Продуктовый маркетолог | карточка → рынок, конкуренты, прото-персоны, синтетические возражения, сегменты |
| **Стратег-аналитик** | Стратег/визионер + Бизнес-консультант + Трекер | рынок+прогноз → варианты развития, применимость, приоритет эксперимента |
| **Аналитик эффективности** | Аналитик эффективности/прогнозист | метрики, прогоны → мат/стат модель, сценарии |
| **Критик** | Критик | всё вышеперечисленное → слабые места, стоп-факторы, рекомендация |
| **Редактор отчёта** | Редактор отчёта | детерминированная сборка (не LLM-роль) — компилирует версии в один отчёт |
| **Агент реализации** | Агент реализации и тестирования | это сам Codex/агент в основном рабочем окне, не отдельная роль в runtime |

UX-аналитик — не runtime-роль (он не анализирует каждую идею), а разовый артефакт, который нужно
сделать один раз в начале, до/параллельно с кодированием экранов. См. §7a.

## 7a. Карта экранов и состояния (P1, разовый артефакт — не покрыт DESIGN.md)

Обязательные экраны из §3.2 полного ТЗ:

1. **Воронка** — список/доска идей, приоритеты, этапы, фильтры, очередь, действия
2. **Новая идея** — запись голоса, индикатор записи, расшифровка, редактирование, сохранение
3. **Карточка** — исходная идея, уточнения, история версий, запуск/пауза/продолжение
4. **Ход работы** — какой агент занят, что завершено, почему остановка, что делать дальше
5. **Отчёт (по одной ссылке)** — резюме+решение, рынок, аудитории+гипотезы, эффективность+прогноз,
   риски, эксперименты+метрики, MVP, источники, история
6. **Прогоны и эффективность** — исходный процесс, сравнение вариантов, наборы данных, журнал
   вызовов, метрики качества, формулы, стат. интервалы, сценарии, график чувствительности
7. **Настройки и документация** — управляемые параметры анализа, лимиты, всё для проверки Ксенией

Для каждого экрана и каждого сценария на нём (§3.3) зафиксировать 6 состояний: начало, успешный
результат, пустое состояние, ожидание, ошибка, восстановление. Явно проверить: длинные названия,
нет доступа к микрофону, отклонённый доступ, неполная расшифровка, отчёт без данных. Требования к
доступности: работа с клавиатуры, видимый фокус, подписи полей, статус понятен без цвета, на 390px
основные действия без горизонтальной прокрутки.

**Рекомендация по срокам**: сделать это одним ранним промптом агенту (после SPEC/DESIGN, до
основной бизнес-логики) — попроси агента на основе этого списка и `DESIGN.md` сгенерировать
`FLOWS.md` с конкретными состояниями по каждому экрану. Это тот самый разовый вывод UX-аналитика,
просто произведённый через агента, а не отдельной runtime-ролью.

Для каждой роли (в конфиге, не в коде): цель, триггер, вход/выход, инструменты, таймаут, число
повторов, критерий готовности, проверка формата ответа перед сохранением (битый ответ не должен
попасть в отчёт молча).

## 8. Очередь и автономность (P0/P1)

- До 10 активных идей; 11-я → понятное сообщение об отказе; архивирование освобождает место.
- Приоритеты high/medium/low; при равенстве — по времени постановки; anti-starvation для low
  (например: если задача ждёт дольше N циклов — поднять приоритет на шаг).
- Один обработчик, продолжающий очередь — параллелизм всех 10 не требуется.
- Состояние — на сервере: закрытие вкладки не останавливает выполнение; перезапуск обработчика
  продолжает с последнего корректного шага (не с нуля).
- Пауза/продолжение/отмена/повтор шага/смена приоритета. Повторный клик не создаёт дубль запуска.
- Изменение идеи после анализа → новая версия → зависимые выводы помечаются устаревшими.

## 9. Прогоны ИИ-решений и микросервисов (P0 — обязательное условие)

Каталог компонентов: назначение, API/способ вызова, схема входа/выхода, версия, зависимости,
ограничения, измеряемые показатели.

Минимум для демо: **1 реальное ИИ-решение + 1 реально вызываемый микросервис** (например,
валидатор по правилам). Сравнение: исходный процесс vs минимум 2 варианта решения на сопоставимых
данных. Протокол прогона хранит: id идеи, id набора данных, версии компонентов/конфига, входы,
выходы, результат проверки качества, ошибки, длительность, ручную доработку.

**Запрещено**: молча заменять недоступную интеграцию имитацией. Если используешь заглушку —
подписать явно, включать явным флагом, не выдавать за реальный прогон.

## 10. MVP (P0 — обязательное условие: полный путь хотя бы одной идеи)

Для идеи из §1: один завершённый пользовательский сценарий с реальными входами/выходами каждого
компонента. Пример по образцу из ТЗ (разбор обращений): обращение → классификация ИИ → проверка
микросервисом правил → сохранение → показ пользователю. Статичный экран/презентация не считаются
MVP. Результат размещается внутри отчёта сервиса (отдельную ссылку слать не нужно).

## 11. Безопасность и доступы (P0)

- Владелец (рабочий кабинет) может менять идеи и запускать анализ; проверяющий — read-only демодоступ
  или отдельная демосессия. Публичный отчёт — только чтение. Нельзя изменить чужую идею подстановкой ID.
- Ключи — только на сервере (не в клиентском коде, репо, скринкасте, логах). Пример `.env.example`
  без значений секретов.
- Текст идеи и внешние страницы — данные, а не инструкции сервису (защита от prompt injection —
  проверить попытку заставить агента раскрыть ключ/игнорировать правила).
- Сгенерированный код MVP не запускается в процессе с ключами оркестратора — изолированная среда.
- Указать: какие данные уходят провайдерам, сколько хранятся, как удалить идею с аудио и результатами.

## 12. Тестирование — минимум (P1, можно сократить объём, но не имитировать)

Матрица по группам (см. полное ТЗ §5.1 для деталей): Ввод, Данные, Очередь, Выполнение, Сбои,
Версии, Качество анализа, Доступы, Интерфейс, Расчёт эффективности, Интеграции в прогоне, Финал.

Для расчёта эффективности отдельно проверить: нулевая база, пропуски, малая/вырожденная выборка,
отрицательный эффект, ухудшение качества, повторяемость вычислений при том же seed.

**3 аналитических кейса минимум**: 1 перспективная идея, 1 с сильным контраргументом, 1 с нехваткой
данных. Один из трёх — с полным путём до MVP (это и есть идея из §1), остальные два могут быть
облегчённой глубины — явно это пометить.

## 13. Документация внутри сервиса (P1 — 15% баллов)

Раздел «Документация» должен содержать: контекст и границы, функц./нефункц. требования с критериями
приёмки, архитектуру, интеграции (с поведением при отказе), модели эффективности (что измерено vs
смоделировано), запуск/поддержка (команды, .env.example, бэкап/восстановление), что можно развивать
дальше, доказательства (тестовая матрица, журнал агентной разработки, ссылка на исходники).

## 14. Журнал агентной разработки (P0 — обязательное условие)

`DEVLOG.md`, ведётся с первого коммита: запрос → план агента → результат → твоя проверка →
исправление. Обязательно показать минимум 1 цикл исправления ошибки и 1 изменение требования через
агента (например, добавление критерия оценки).

## 15. Что сознательно упрощаем под дедлайн 10.09 (документировать как допущение, не скрывать)

- Не все 12 ролей отдельными агентами — консолидация по §7.
- Не 3 полноценных глубоких аналитических кейса — 1 полный (до MVP) + 2 облегчённых.
- Стресс-тест очереди на 10 одновременных идеях — не критичен, важна корректность логики очереди на
  меньшем числе + объяснение, как масштабируется.
- Полировка UI — по DESIGN.md, без излишней доработки сверх состояний, явно требуемых ТЗ.
- Брендбук не передан → визуальная основа: референс Arounda через `DESIGN.md` (временное допущение,
  принято на этапе 0).

### Реестр допущений по расчёту (этап 7)

- Базовые метрики исходного процесса (6 мин/обращение, 88% корректных) взяты из модельного
  датасета 200 обращений — это симулированные данные, в отчёте помечаются как `simulation`,
  не как измерение реального процесса.
- Целевое время ИИ-обработки (≤2.5 мин) — допущение методики; чувствительность к нему
  показывается отдельно в сценариях.

## 16. Финальный чек перед отправкой

- [ ] Голос/текст → карточка → сохранение работает
- [ ] Очередь (приоритеты, лимит 10, фоновое выполнение) работает
- [ ] Минимум 1 реальное ИИ-решение + 1 микросервис реально вызываются, метрики сохраняются
- [ ] 3 аналитических кейса, факты/прогнозы/симуляции различимы
- [ ] Расчёт эффекта: мат. модель + стат. модель + 3 сценария, воспроизводим при повторном запуске
- [ ] 1 идея дошла до работающего MVP с реальными входами/выходами
- [ ] Сценарии, сбои, версии, сохранность данных проверены (хотя бы минимально)
- [ ] Доступы разделены (владелец / read-only демо), нет открытых секретов
- [ ] Документация и DEVLOG открываются из сервиса
- [ ] Скринкаст ≤10 минут, обе ссылки открываются в приватном окне