admin/orchestrator
1
0
Fork 0
Code Issues Pull Requests 4 Actions Packages Projects Releases Wiki Activity
Files
main
orchestrator/docs/work-items/ORCH-067/02-trz.md

14 KiB
Raw Permalink Blame History

ТЗ — ORCH-067: Telegram tracker (bump + статусы Plane + кликабельный номер задачи)

Work Item: ORCH-067 Документ описывает КОНКРЕТНЫЕ изменения кода/конфигурации/тестов и документации. Архитектурные развилки помечены [ARCH] — решение принимает архитектор (ADR), здесь зафиксированы только требования и ограничения к ним.

0. Задействованные модули src/

Модуль Роль в задаче
src/config.py Дефолт tracker_mode; поле plane_web_url/plane_workspace_slug (уже есть).
src/notifications.py Основные изменения: bump-дефолт, статус-строка карточки, хелпер ссылки, применение хелпера в notify_*.
src/plane_sync.py Источник имён статусов/маппинга ORCH-066 (_PLANE_NAME_TO_KEY, _STAGE_TO_STATE_KEY); при необходимости reverse-map UUID→имя [ARCH].
src/projects.py get_project_by_repo(repo).plane_project_id — per-task project_id для ссылки.
src/db.py Чтение tasks.plane_issue_id, tasks.repo (без изменений схемы).
src/stage_engine.py, src/agents/launcher.py, src/merge_gate.py, src/job_reaper.py, src/security_gate.py, src/reconciler.py, src/main.py Точки send_telegram, где есть work_item_id — применить хелпер ссылки (требование 4).

Изменения API (HTTP endpoints) — нет. Изменения схемы БД — нет. Новые QG checks — нет.

1. Требование 1 — bump по умолчанию

1.1. Изменение

  • src/config.py (~стр. 408): сменить дефолт tracker_mode: str = "edit" → tracker_mode: str = "bump".
  • Обновить docstring-комментарий рядом (ORCH-042): отметить, что дефолт теперь bump, edit остаётся доступен через ORCH_TRACKER_MODE=edit.

1.2. Без изменений (сохранить инвариант)

  • Логика update_task_tracker (src/notifications.py, ветка if mode == "bump"): delete_telegram(old) best-effort → send_telegram(text, disable_notification=True) → set_tracker_message_id ТОЛЬКО при new_mid is not None. Не менять.
  • send_telegram/edit_telegram/delete_telegram — не трогать.

1.3. Прод-аспект

  • Для прод-инстанса орка можно дополнительно выставить ORCH_TRACKER_MODE=bump в .env на хосте (как страховку), но код должен работать «из коробки» и без env. Канон env — .env.example (обновить, если там фигурирует tracker_mode).

2. Требование 2 — статус-строка карточки по модели ORCH-066

2.1. Новый чистый хелпер маппинга

Добавить в src/notifications.py функцию, возвращающую отображаемый Plane-статус для карточки на основе доступных данных задачи. Сигнатура (ориентир):

def plane_status_label(task_row) -> str:
    """Вернуть строку текущего Plane-статуса для шапки карточки (с emoji).
    Никогда не падает: на неизвестном входе -> разумный дефолт по stage."""

Хелпер обязан быть чистым/детерминированным от входных данных и никогда не бросать исключения (любая ошибка → дефолт по stage, рендер карточки не ломается).

2.2. Маппинг внутреннее состояние → Plane-статус (обязательные строки)

Имена статусов — финальные из модели ORCH-066 (см. _PLANE_NAME_TO_KEY в plane_sync.py).

Источник (данные задачи в БД) Plane-статус (отображение в карточке)
stage == "created" To Analyse
stage == "analysis", BRD-clock не запущен Analysis
stage == "analysis", brd_review_started_at есть, brd_review_ended_at пуст ⏸️ In Review — ожидание согласования BRD
stage == "architecture" Architecture
stage == "development" Development
stage == "review" Code-Review
stage == "testing" Testing
stage == "deploy" (ожидание Confirm Deploy) ⏸️ Awaiting Deploy — ожидание Confirm Deploy
stage == "done" Done

Ветки (Needs Input / Blocked / Rejected / Cancelled / Deploying / Monitoring after Deploy):

  • ❓ Needs Input — нужны уточнения — состояние «аналитик задал вопросы»;
  • Blocked, Rejected, Cancelled, Deploying, Monitoring after Deploy.

[ARCH] Источник сигнала для веток, не выводимых из tasks.stage (Needs Input, Blocked, Rejected, Cancelled, Deploying, Monitoring after Deploy):

  • запрещено менять схему БД (нельзя добавлять колонку-флаг);
  • варианты для архитектора: (а) best-effort чтение живого Plane-статуса (fetch_issue_state + reverse-map UUID→имя через get_project_states/ _PLANE_NAME_TO_KEY) с обязательным fail-safe (нет сети/ответа → деградация на stage-маппинг, без задержки, блокирующей конвейер); (б) только stage-выводимые статусы, а ветки — по уже имеющимся сигналам (например, In Review через brd-clock).
  • ОБЯЗАТЕЛЬНО к покрытию (DoD): ⏸️ In Review, ⏸️ Awaiting Deploy, ❓ Needs Input. In Review полностью выводится из brd-clock (см. таблицу) и должен работать без сети.

2.3. Встраивание в render_task_tracker

  • В render_task_tracker (src/notifications.py) добавить в шапку/верх карточки отдельную СТРОКУ статуса (под заголовком 🛠️ ORCH-NNN · <title> / над разделителем bar), напр.: 📍 <status_label>.
  • Существующие строки по стадиям (✅ done / 🔄 active), строка «Подтверждение BRD», тоталы токенов/стоимости, done-строка с PR/⏱️ — СОХРАНИТЬ (семантику не ломать).
  • Семантика строки «Подтверждение BRD» (⏸️+⏳ при ожидании, ✅ при пройденном гейте) сохраняется; новая статус-строка дублирует её смысл в терминах Plane-статуса.

3. Требование 3 + 4 — кликабельный номер задачи

3.1. Единый хелпер

Добавить в src/notifications.py:

def plane_issue_link(work_item_id, plane_issue_id=None, project_id=None, repo=None) -> str:
    """Вернуть HTML с кликабельным номером задачи (<a href=...>ORCH-NNN</a>),
    либо просто html.escape(work_item_id), если ссылку построить нельзя.
    Никогда не падает."""

Поведение:

  • База URL: settings.plane_web_url → fallback settings.plane_api_url; loopback-база (localhost/127.0.0.1/…) трактуется как «нет web URL» (переиспользовать _is_loopback_base).
  • workspace_slug: settings.plane_workspace_slug.
  • project_id: явный аргумент → иначе резолв по repo через get_project_by_repo(repo).plane_project_id.
  • issue_id: plane_issue_id (UUID из tasks.plane_issue_id).
  • URL-шаблон: {web_base}/{workspace}/projects/{project_id}/issues/{issue_id}/.
  • Текст ссылки = html.escape(work_item_id); href = html.escape(url, quote=True).
  • Fail-safe: если не хватает любого из (web_base валидный/не loopback, workspace, project_id, plane_issue_id) → вернуть html.escape(work_item_id) (номер без ссылки).
  • Логика построения URL уже существует в _build_plane_issue_link (ORCH-017) — допустимо переиспользовать/обобщить её, разнеся «текст-ссылки = номер» и «текст-ссылки = ✅ Задача в Plane», чтобы не дублировать резолв проекта и loopback-guard.

3.2. Применение в карточке (требование 3)

  • В render_task_tracker заголовок строится из work_item_id. Заменить html.escape(work_item_id) в обоих вариантах заголовка (done / not-done) на plane_issue_link(work_item_id, plane_issue_id, repo=repo) — номер становится кликабельным.
  • Для этого render_task_tracker должен дополнительно выбрать из БД repo и plane_issue_id (расширить существующий SELECT по tasks). Схему НЕ менять — колонки уже есть.
  • title уже экранируется (html.escape(title)) — сохранить.

3.3. Применение во всех уведомлениях (требование 4)

Во всех точках send_telegram/notify_*, где в тексте есть work_item_id, заменить «сырой» номер на plane_issue_link(...). Перечень точек (из src):

  • src/notifications.py: notify_approve_requested, notify_error (и любые будущие notify_* с work_item_id);
  • src/stage_engine.py: все send_telegram(...) с work_item_id (≈ строки 613, 672, 719, 776, 820, 916, 971, 1057, 1134, 1192, 1228, 1257, 1355, 1367, 1425, 1447, 1601 — проверить каждую: применять ТОЛЬКО где упоминается номер задачи);
  • src/agents/launcher.py: deploy-failed alert (≈685–686), agent-failed alert (≈698–699), alert ≈821–822;
  • src/merge_gate.py (≈431–432);
  • src/job_reaper.py (≈395–396);
  • src/security_gate.py (≈673–674);
  • src/reconciler.py (≈449);
  • src/main.py (≈45–47).

[ARCH] Способ доступа к plane_issue_id/project_id в каждой точке (часто там уже есть work_item_id, но не обязательно plane_issue_id): хелпер должен уметь резолвить недостающее по repo/БД, оставаясь fail-safe. Допустимо добавить тонкую обёртку, которая по work_item_id/task_id достаёт repo+plane_issue_id из БД и зовёт plane_issue_link (аналогично существующему _get_task_link_fields). Везде, где данных нет — деградация на просто номер, без падения.

3.4. HTML-экранирование

  • parse_mode=HTML уже стоит в send_telegram/edit_telegram. Любой пользовательский текст (title, описания, причины QG-fail, сообщения об ошибках), попадающий в сообщение с ссылками, должен экранироваться html.escape, чтобы не сломать <a>-разметку.

4. Конфигурация

  • plane_web_url (env ORCH_PLANE_WEB_URL) — уже существует (src/config.py), значение прод — plane.mva154.duckdns.org (схему https:// учесть при сборке URL). Дополнительных полей конфигурации не требуется.
  • tracker_mode — сменить дефолт на bump (раздел 1).
  • Обновить .env.example, если в нём фигурируют ORCH_TRACKER_MODE / ORCH_PLANE_WEB_URL (канон секретов/настроек — .env.example, не коммитить реальные секреты).

5. Артефакты pipeline, которые должны быть созданы/обновлены

  • docs/work-items/ORCH-067/06-adr/ADR-NNN-*.md — архитектурное решение (минимум: источник «истинного» Plane-статуса для веток при запрете изменения схемы БД; дефолт bump; единый хелпер ссылки).
  • CLAUDE.md — раздел про нотификации/tracker (дефолт bump; статус-строка карточки; кликабельный номер в карточке и уведомлениях).
  • CHANGELOG.md — запись ORCH-067.
  • docs/architecture/README.md — при необходимости синхронизировать описание tracker'а.

6. Ограничения (что НЕ трогать)

  • Транспорт send_telegram/edit_telegram/delete_telegram.
  • Инвариант «одна карточка на задачу».
  • Логику disable_notification (карточка тихая; пингуют только alert-хелперы).
  • STAGE_TRANSITIONS, Quality Gates, схему БД.
  • Поведение агентов/конвейера.

7. Замечания по самохостингу

Орк правит сам себя в проде (общий инстанс/БД с enduro-trails):

  • НЕ перезапускать прод-контейнер orchestrator в рамках задачи.
  • Обязательная страховка через deploy-staging (8501) до прод-деплоя.
  • Смена дефолта tracker_mode затрагивает ВСЕ проекты — проверить отсутствие регресса для enduro-trails (тесты + staging-наблюдение карточки).
Reference in New Issue View Git Blame Copy Permalink