88 lines
7.1 KiB
Markdown
88 lines
7.1 KiB
Markdown
# 02-ТЗ — ORCH-017: Прямые ссылки в Telegram-уведомлении об апруве BRD
|
||
|
||
Work Item: **ORCH-017** · Repo: `orchestrator`
|
||
Опирается на 01-brd.md. Уточняет конкретные изменения кода/конфигурации.
|
||
|
||
> Примечание по канону: ТЗ фиксирует ТРЕБОВАНИЯ к изменениям, а не готовое
|
||
> архитектурное решение. Выбор формата (текст vs inline-кнопки) и точного формата
|
||
> Plane-URL — за стадией architecture (см. открытые вопросы 01-brd.md §8). Если по
|
||
> ходу разработки ТЗ окажется неполным/неверным — возврат на стадию Анализ, без
|
||
> правок ТЗ задним числом.
|
||
|
||
## 1. Задействованные модули `src/`
|
||
| Модуль | Роль в задаче |
|
||
|--------|---------------|
|
||
| `src/notifications.py` | **Основной.** Функция `notify_approve_requested(task_id)` (≈ строки 547–566) — единственная точка отправки пингующего уведомления об апруве BRD. Сюда добавляются ссылки. |
|
||
| `src/config.py` | Класс `Settings`. Добавить настройку внешнего web-URL Plane (`plane_web_url`, env `ORCH_PLANE_WEB_URL`) с дефолтом-фоллбэком. |
|
||
| `src/projects.py` | (Чтение) `get_project_by_repo(repo)` → `plane_project_id` для построения Plane-URL. |
|
||
| `src/usage.py` | (Референс, не править) Эталонный паттерн branch-view ссылки на доки (`{base}/{owner}/{repo}/src/branch/{branch}/<rel>`), строки ≈483–503 — переиспользовать тот же формат. |
|
||
| `src/db.py` | (Чтение) Таблица `tasks`: поля `work_item_id`, `repo`, `branch`, `plane_issue_id`. Источник данных для ссылок. |
|
||
|
||
## 2. Источники данных (из `tasks` по `task_id`)
|
||
- `work_item_id` — путь к BRD-документу и (опц.) идентификатор issue.
|
||
- `repo`, `branch` — построение Gitea branch-view URL.
|
||
- `plane_issue_id` — uuid issue в Plane для прямой ссылки.
|
||
- `project_id` — через `projects.get_project_by_repo(repo).plane_project_id`.
|
||
|
||
`notify_approve_requested` сейчас принимает только `task_id` и тянет лишь `work_item_id`
|
||
через `_get_work_item_id`. Требуется дополнительно прочитать `repo`, `branch`,
|
||
`plane_issue_id` из `tasks` (один SELECT, в защищённом try/except).
|
||
|
||
## 3. Требуемые изменения
|
||
|
||
### 3.1 `src/notifications.py`
|
||
- Построить **BRD-ссылку** (FR-1/FR-5):
|
||
`{base}/{owner}/{repo}/src/branch/{branch}/docs/work-items/{work_item_id}/01-brd.md`,
|
||
где `base = (settings.gitea_public_url or settings.gitea_url).rstrip('/')`,
|
||
`owner = settings.gitea_owner`. Если нет `base`/`repo`/`branch`/`work_item_id` — ссылку
|
||
опустить (NFR-1).
|
||
- Построить **Plane-ссылку** (FR-2/FR-6):
|
||
`{plane_web_base}/{workspace_slug}/projects/{project_id}/issues/{plane_issue_id}/`
|
||
(точный формат — решение architecture, см. 01-brd §8.4). Если нет данных — опустить.
|
||
- Встроить обе ссылки в текст того же сообщения (FR-3/FR-4), формат HTML-`<a>` по умолчанию.
|
||
Сохранить существующий призыв «Переведите задачу в статус Approved …».
|
||
- Сохранить вызов как **одно** `send_telegram(msg)` (пингующее, не silent). Порядок
|
||
существующих действий не менять: старт BRD-часов (`mark_brd_review_started`) →
|
||
`update_task_tracker(task_id)` → `send_telegram(msg)`.
|
||
- Динамические подписи экранировать `html.escape` (NFR-3).
|
||
|
||
### 3.2 `src/config.py`
|
||
- Добавить в `Settings` поле `plane_web_url: str = ""` (env `ORCH_PLANE_WEB_URL`).
|
||
- Семантика фоллбэка: `plane_web_base = (settings.plane_web_url or settings.plane_api_url).rstrip('/')`.
|
||
|
||
### 3.3 Опционально (если выбран вариант inline-кнопок — открытый вопрос 01-brd §8.1)
|
||
- Расширить `send_telegram(text, disable_notification=False, reply_markup=None)`:
|
||
при наличии `reply_markup` прокидывать его в payload `sendMessage`. Обратная
|
||
совместимость — обязательна (текущие вызовы без аргумента работают как раньше).
|
||
- ⚠️ Это РАСШИРЯЕТ объём; включается только по явному решению Owner на стадии architecture.
|
||
|
||
## 4. Изменения API
|
||
Нет. Публичные HTTP-эндпоинты (`/webhook/*`, `/status`, `/queue`, `/health`) не затрагиваются.
|
||
|
||
## 5. Изменения схемы БД
|
||
Нет. Все нужные поля (`repo`, `branch`, `work_item_id`, `plane_issue_id`) уже существуют в `tasks`.
|
||
|
||
## 6. Изменения конфигурации / окружения
|
||
- Новая env-переменная `ORCH_PLANE_WEB_URL` (внешний web-адрес Plane). Прописать в
|
||
`.env.example` (канон секретов/настроек), описать в env-карте (`CLAUDE.md` /
|
||
`docs/operations/INFRA.md`). Реальное значение задаётся в `.env`/`.env.staging` на хосте.
|
||
- Существующие `ORCH_GITEA_PUBLIC_URL`, `ORCH_GITEA_OWNER`, `ORCH_PLANE_WORKSPACE_SLUG`
|
||
переиспользуются как есть.
|
||
|
||
## 7. Требования к новым QG checks
|
||
Нет. Реестр `QG_CHECKS`, стадии и машинные вердикты не меняются (правка — отображение,
|
||
не управление конвейером).
|
||
|
||
## 8. Артефакты pipeline, которые должны быть обновлены в ЭТОМ PR
|
||
- `CHANGELOG.md` — запись о фиче.
|
||
- `.env.example` — новая `ORCH_PLANE_WEB_URL`.
|
||
- При добавлении настройки — env-карта в `CLAUDE.md` / `docs/operations/INFRA.md`.
|
||
- ADR (стадия architecture): `docs/work-items/ORCH-017/06-adr/ADR-001-*.md` — фиксирует выбор
|
||
формата (текст vs кнопки) и формат Plane-URL.
|
||
|
||
## 9. Ограничения
|
||
- Не трогать `:approved:`-handler и `check_analysis_approved` (только текст/формат уведомления).
|
||
- Не плодить сообщения: одно отдельное пингующее сообщение; живой трекер (PR #21/#22) не дублировать.
|
||
- Соблюдать self-hosting: не ронять/не рестартить прод сверх штатного деплоя; обязательная
|
||
страховка `deploy-staging` (8501) перед прод-деплоем орка.
|