66 lines
7.9 KiB
Markdown
66 lines
7.9 KiB
Markdown
# 01 — BRD: Telegram live-tracker, режим bump + русификация карточки
|
||
|
||
**Work Item:** ORCH-042
|
||
**Тип:** UX-улучшение (notifications)
|
||
**Приоритет:** средний
|
||
**Запрос:** Слава, 05.06. Связь: `feat/telegram-live-tracker` (Variant B+).
|
||
**Self-hosting:** да — правка самого оркестратора, проходит через его же конвейер (общая БД/очередь с enduro-trails). См. `docs/operations/INFRA.md`.
|
||
|
||
## 1. Контекст и проблема
|
||
|
||
Live-tracker задачи (`src/notifications.py`) — это ОДНА карточка на задачу в Telegram, которая обновляется на каждом переходе стадии через `editMessageText` (Variant B+). Так сделано СПЕЦИАЛЬНО, чтобы убить старую проблему «~15 отдельных карточек/дублей на задачу».
|
||
|
||
Побочный эффект текущего решения: карточка редактируется **на месте в истории чата**. При активной переписке в чате карточка «тонет» вверху и её неудобно искать — приходится скроллить вверх к старому сообщению, чтобы увидеть актуальный статус задачи.
|
||
|
||
Дополнительно накопились косметические претензии к тексту карточки: смесь англоязычных меток стадий с русским текстом, неудачная формулировка «Ревью БРД», и финальный технический хвост `deployed` вместо человекочитаемого «Внедрено».
|
||
|
||
## 2. Цель
|
||
|
||
1. Дать Славе альтернативный режим отображения трекера — **bump**: при каждом обновлении карточка «падает вниз» свежим сообщением (всегда последняя в чате), но БЕЗ возврата к проблеме дублей (по-прежнему ОДНА карточка на задачу) и БЕЗ спама звуками/пингами.
|
||
2. Привести текст карточки к единому русскому виду и поправить формулировки.
|
||
|
||
## 3. Заинтересованные лица
|
||
|
||
- **Слава (Owner)** — единственный получатель Telegram-уведомлений; принимает UX.
|
||
- **Агенты конвейера** — косвенно: трекер обновляется из `notify_*`-хелперов на каждой стадии.
|
||
|
||
## 4. Требования (бизнес-уровень)
|
||
|
||
### 4.1. Режим работы трекера (флаг)
|
||
- **BR-1.** Новый конфиг-флаг `ORCH_TRACKER_MODE` с двумя значениями:
|
||
- `edit` — текущее поведение (редактирование на месте). **Это ДЕФОЛТ** (обратная совместимость, никакой регрессии без явного включения).
|
||
- `bump` — новый режим «карточка падает вниз».
|
||
- **BR-2.** Неизвестное/пустое значение флага трактуется как `edit` (безопасный фолбэк, оркестратор не падает).
|
||
|
||
### 4.2. Поведение режима bump
|
||
- **BR-3.** При обновлении карточки в режиме `bump`: старое сообщение удаляется (`deleteMessage`), отправляется новое (`sendMessage`), указатель `tracker_message_id` перенаправляется на новое сообщение. Итог: в чате всегда ровно ОДНА карточка задачи, и она всегда внизу.
|
||
- **BR-4.** Bump тихий: новое сообщение отправляется с `disable_notification=true` — карточка всплывает внизу, но БЕЗ звука/пинга на каждой стадии (как и сейчас в edit-режиме).
|
||
- **BR-5.** Первое обновление (карточки ещё нет) в режиме `bump` — просто тихо отправить новое и запомнить id (удалять нечего).
|
||
|
||
### 4.3. Устойчивость (критично — не сломать защиту от дублей)
|
||
- **BR-6.** Fallback: если `deleteMessage` не удался (сообщение старше 48 ч / уже удалено / недоступно) — карточка всё равно отправляется заново, оркестратор НЕ падает.
|
||
- **BR-7.** Любой сбой нотификации (сеть/таймаут/5xx/Telegram-ошибка) НЕ роняет оркестратор (контракт «never raises» сохраняется) и НЕ плодит дубли карточек в пределах одного обновления.
|
||
- **BR-8.** Режим `edit` после изменений работает строго как раньше — без регрессий (защита от ~15 дублей сохранена).
|
||
|
||
### 4.4. Текстовые правки карточки (применяются в ОБОИХ режимах)
|
||
- **BR-9.** Метку «Ревью БРД» заменить на «Подтверждение BRD».
|
||
- **BR-10.** После того как задача переведена в Approved (человеческий gate пройден, время ревью зафиксировано), эмодзи в строке подтверждения BRD заменить на галочку (✅) вместо текущей паузы (⏸️). Пока ждём человека — оставить прежний индикатор ожидания.
|
||
- **BR-11.** Русифицировать метки стадий карточки: `Analysis → Анализ`, `Architecture → Архитектура`, `Development → Разработка`, `Review → Код ревью`, `Testing → Тестирование`, `Deploy → Внедрение`.
|
||
- **BR-12.** В итоговой (последней) строке готовой задачи заменить технический `deployed` на «Внедрено».
|
||
|
||
## 5. Вне scope
|
||
- Изменение состава событий, которые шлются ОТДЕЛЬНЫМИ пингами (approve-gate / deploy-fail / agent-fail / error) — остаётся как есть.
|
||
- Изменение формата метрик (токены/стоимость/длительность), макета строк, логики «попытка N».
|
||
- Любые изменения в Plane-комментариях агентов (`usage.build_status_comment`).
|
||
- Хранение истории карточек / несколько карточек на задачу.
|
||
|
||
## 6. Влияние на документацию (golden source)
|
||
- `CHANGELOG.md` — запись в `[Unreleased]`.
|
||
- `docs/architecture/internals.md` (или соответствующая секция про live-tracker) — описать режимы `edit`/`bump` и `ORCH_TRACKER_MODE`.
|
||
- `.env.example` — добавить `ORCH_TRACKER_MODE` с пояснением.
|
||
|
||
## 7. Критерии успеха (резюме)
|
||
Слава может выставить `ORCH_TRACKER_MODE=bump` и видеть актуальную карточку всегда внизу чата, одну на задачу, без звона; при откате на `edit` (дефолт) поведение неотличимо от текущего; текст карточки полностью русифицирован по BR-9..BR-12. Полные условия PASS/FAIL — `03-acceptance-criteria.md`.
|
||
</content>
|
||
</invoke>
|