From 969c218e9940ce72194681a184160d515ef7836a Mon Sep 17 00:00:00 2001 From: DCCONSTRUCTIONS Date: Mon, 20 Apr 2026 19:51:02 +0300 Subject: [PATCH] =?UTF-8?q?=D0=90=D0=A0=D0=A5=20-=20=D0=9C=D0=95=D0=96?= =?UTF-8?q?=D0=9F=D0=A0=D0=9E=D0=95=D0=9A=D0=A2=D0=9D=D0=90=D0=AF=20=D0=9A?= =?UTF-8?q?=D0=9E=D0=9C=D0=9C=D0=A3=D0=9D=D0=98=D0=9A=D0=90=D0=A6=D0=98?= =?UTF-8?q?=D0=AF:=20roadmap=20=D0=B4=D0=B2=D1=83=D1=81=D1=82=D0=BE=D1=80?= =?UTF-8?q?=D0=BE=D0=BD=D0=BD=D0=B5=D0=B9=20=D0=B4=D0=BE=D1=81=D0=BA=D0=B8?= =?UTF-8?q?=20=D0=B2=D0=BD=D0=B5=D1=88=D0=BD=D0=B8=D1=85=20=D0=BA=D0=BE?= =?UTF-8?q?=D0=BD=D1=82=D1=83=D1=80=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../11_STEP_external-contours-detail-shell.md | 148 +++++++++++++ ...P_external-contours-bidirectional-board.md | 197 ++++++++++++++++++ .../README.md | 75 ++++++- .../phase-roadmap.md | 131 ++++++++++++ 4 files changed, 550 insertions(+), 1 deletion(-) create mode 100644 docs_prod/1_STEP_cross-project-task-routing/11_STEP_external-contours-detail-shell.md create mode 100644 docs_prod/1_STEP_cross-project-task-routing/12_STEP_external-contours-bidirectional-board.md rename docs_prod/{cross-project-task-routing => 1_STEP_cross-project-task-routing}/README.md (79%) rename docs_prod/{cross-project-task-routing => 1_STEP_cross-project-task-routing}/phase-roadmap.md (72%) diff --git a/docs_prod/1_STEP_cross-project-task-routing/11_STEP_external-contours-detail-shell.md b/docs_prod/1_STEP_cross-project-task-routing/11_STEP_external-contours-detail-shell.md new file mode 100644 index 0000000..88d6179 --- /dev/null +++ b/docs_prod/1_STEP_cross-project-task-routing/11_STEP_external-contours-detail-shell.md @@ -0,0 +1,148 @@ +# Шаг 11. Единый shell карточки внешнего контура + +## Зачем нужен этот шаг + +Сейчас карточка деталей во `Внешних контурах` решает прикладную задачу, но UX-паттерн у нее другой, чем во `Внутреннем контуре`. + +Из-за этого: +- у пользователя ломается ожидаемая логика открытия карточки +- верхний action-bar живет по другим правилам +- повторяется UI-логика, которая уже есть у стандартного peek-shell +- дальнейшее развитие `Внешних контуров` начинает расходиться с остальным продуктом + +Следующий шаг должен выровнять не данные, а каркас взаимодействия. + +## Целевой результат + +По клику на карточку во `Внешних контурах` пользователь получает тот же класс панели, что и во `Внутреннем контуре`: +- закрытие просмотра +- полноэкранный режим +- переключение макета +- подписка или отписка +- копирование ссылки +- меню дополнительных действий + +При этом тело карточки остается отдельным и специфичным для `Внешних контуров`. + +## Что обязательно сохраняем + +Карточка внешнего контура не должна деградировать до обычной карточки `Issue`. + +Нужно сохранить: +- source-side режим без обязательного membership в target project +- блок `Маршрутизация` +- зеркалирование комментариев, вложений и activity +- внешний lifecycle `Принять / Отклонить / Ответ во внешний контур` +- правила доступа, отличающиеся от обычного внутреннего рабочего элемента + +Иначе мы потеряем главный смысл модуля. + +## Что меняем + +Меняем только shell и верхний UX-паттерн: +- каркас панели +- поведение открытия и закрытия +- поведение полноэкранного режима +- верхний блок действий +- раскладку заголовка и служебных controls + +То есть цель шага — унификация оболочки, а не унификация доменной модели. + +## Что не входит + +В этот шаг не входят: +- новые колонки `Исходящие / Входящие` +- drag-and-drop +- пользовательские кастомные представления +- перенос всех операций внешнего контура на стандартные issue services +- удаление запроса как обязательное действие из header action set + +## Архитектурный принцип + +Нельзя копировать целиком реализацию `peek overview` внутреннего контура и натягивать ее поверх внешней сущности. + +Правильный путь: +- переиспользовать shell-контракт +- переиспользовать header action pattern +- оставить внешний data-flow отдельным +- оставить body карточки отдельным + +То есть нужен не clone существующей карточки, а повторное использование общего слоя представления. + +## Рекомендуемое разбиение реализации + +### 1. Общий слой shell + +Нужен общий контракт боковой карточки, который умеет: +- sidebar-режим +- full-screen режим +- общий overlay и поведение закрытия +- общий header slot +- общий body slot + +### 2. Отдельный adapter для `Внешних контуров` + +Нужен внешний adapter, который подает в shell: +- title +- служебные действия +- доступные действия меню +- состояние source-only или target-access +- body контент внешнего контура + +### 3. Отдельный action set + +Нельзя слепо использовать меню обычной задачи. + +Нужно отдельное правило доступных действий для внешнего контура: +- закрыть +- fullscreen +- layout toggle +- subscribe/unsubscribe +- copy link +- `...` + +При этом `...` для внешнего контура должен быть ограничен собственным набором действий и не обязан повторять delete-flow внутреннего рабочего элемента. + +## Риски, которые надо избежать + +### 1. Смешение доменных сущностей + +Если внешний запрос начать вести как обычный `Issue`, то быстро сломаются: +- source-side права +- логика bridge +- роутинг действий `Принять / Отклонить` +- зеркальная история + +### 2. Дублирование shell-кода + +Если сделать второй независимый peek-shell только для `Внешних контуров`, то дальше появятся: +- рассинхрон верхних action-bar +- повторная поддержка полноэкранного режима +- повторная поддержка keyboard и close behavior + +### 3. Преждевременная универсальная платформа + +Не нужно ради одного шага строить абстрактный UI-framework на все возможные будущие сущности. + +Нужен только тот общий контракт, который уже доказан двумя режимами: +- `Внутренний контур` +- `Внешние контуры` + +## Критерий приемки + +- карточка `Внешних контуров` открывается по тому же UX-паттерну, что и во `Внутреннем контуре` +- верхняя панель действий выглядит и ведет себя единообразно +- body карточки остается внешнеконтурным +- source-only сценарий не ломается +- без прямого доступа в target project пользователь все равно видит рабочую карточку + +## Зависимость следующего шага + +Этот шаг желательно сделать до полной двусторонней доски. + +Причина простая: +- доска `Исходящие / Входящие` увеличит число точек входа в карточку +- если shell не унифицирован заранее, новый board-layer закрепит текущую раздвоенную архитектуру + +Следующий связанный шаг описан в: +- [12_STEP_external-contours-bidirectional-board.md](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/docs_prod/1_STEP_cross-project-task-routing/12_STEP_external-contours-bidirectional-board.md) diff --git a/docs_prod/1_STEP_cross-project-task-routing/12_STEP_external-contours-bidirectional-board.md b/docs_prod/1_STEP_cross-project-task-routing/12_STEP_external-contours-bidirectional-board.md new file mode 100644 index 0000000..db9d7ef --- /dev/null +++ b/docs_prod/1_STEP_cross-project-task-routing/12_STEP_external-contours-bidirectional-board.md @@ -0,0 +1,197 @@ +# Шаг 12. Двусторонняя доска внешних контуров + +## Главная продуктовая задача + +Во `Внешних контурах` пользователь должен видеть не только прилетевшие или уже принятые задачи, но и те запросы, которые его проект сам отправил в другие контуры. + +Без этого теряется управляемость: +- пользователь отправляет запрос +- но не может нормально наблюдать его как отдельную рабочую сущность +- и не получает полноценный рабочий экран для исходящих запросов + +Поэтому следующий обязательный этап — двусторонняя доска. + +## Обязательный состав первой версии + +В первой версии должны быть только две системные зоны: +- `Исходящие` +- `Входящие` + +Это фиксированные рабочие представления, а не свободный конструктор колонок. + +## Что означает каждая зона + +### Исходящие + +Запросы, которые текущий проект отправил в другие контуры. + +Для них пользователь должен видеть: +- текущий статус исполнения +- целевой контур +- назначенного +- последнее изменение +- признаки новых изменений + +### Входящие + +Запросы, которые пришли в текущий проект из других контуров. + +Они должны оставаться видимыми во `Внешних контурах` как отдельный контекст межконтурной работы, даже если фактическая работа по исполнению идет во `Внутреннем контуре`. + +Это не отменяет текущий lifecycle появления задачи во `Внутреннем контуре`. + +Наоборот, это добавляет отдельный рабочий слой наблюдения и управления межконтурным потоком. + +## Обязательное ограничение + +Во `Внешних контурах` нельзя реализовывать перетаскивание карточек между блоками. + +Причина: +- блоки здесь не равны стадиям workflow +- это не kanban статусов +- это представления по направлению и фильтрам + +Следовательно: +- никаких drag-and-drop переходов между `Исходящими` и `Входящими` +- никаких попыток “перетащить” запрос в другой блок как способ смены состояния + +Смена состояния остается доменной операцией, а не визуальным переносом. + +## Требования к фильтрации + +Обе системные зоны должны поддерживать гибкую фильтрацию по аналогии с `Внутренним контуром`. + +Минимально нужно уметь фильтровать: +- по пользователям +- по назначенным +- по автору +- по статусам +- по связанным контурам или проектам +- по приоритету +- по срокам и датам + +Если часть фильтров недоступна на первой итерации из-за backend-модели, это нужно закрывать адаптером или агрегированным endpoint, а не урезать целевой продуктовый контракт. + +## Текущее архитектурное препятствие + +На сегодня `Исходящие` и `Входящие` живут в разных подсистемах: +- source-side отправленные запросы приходят из модуля `external-contours` +- входящие рабочие объекты и bridge-история живут вокруг `intake` и связанной target issue + +Поэтому полноценная двусторонняя доска не собирается простым склеиванием текущего UI. + +Нужен единый слой представления данных. + +## Рекомендуемое архитектурное решение + +### 1. Не собирать эту доску фронтовыми хаками + +Можно временно склеить две разные выдачи на frontend, но это быстро упрется в: +- сортировки +- пагинацию +- счетчики +- консистентность фильтров +- unread-индикаторы + +Поэтому базовый путь должен вести к агрегированному data contract. + +### 2. Ввести единый board-level view model + +Нужна единая проекция, условно: +- `direction` +- `source_project` +- `target_project` +- `status` +- `assignee` +- `created_by` +- `updated_at` +- `unread` +- `target_issue_id` +- `external_request_id` + +Этот view model не обязан ломать существующие доменные сущности. + +Он нужен как стабильный контракт уровня доски. + +### 3. Сделать board как фиксированные системные представления + +Первая версия не должна строиться как свободный пользовательский конструктор. + +Нужны два системных блока: +- блок `Исходящие` +- блок `Входящие` + +И только поверх этого позже можно добавлять дополнительные пользовательские представления. + +## Как не уйти в крайности + +### Плохой путь 1 + +Сделать поверх текущего экрана несколько разрозненных переоберток и локальных фильтров. + +Результат: +- быстрое накопление технического долга +- отсутствие общего контракта +- трудная интеграция следующих board-type модулей + +### Плохой путь 2 + +Остановить проект и начать строить универсальную платформу на все будущие доски сразу. + +Результат: +- высокий срок поставки +- риск поломать текущий runtime +- потеря фокуса на реальной продуктовой потребности + +### Рабочий путь + +Сделать ограниченный, но расширяемый board contract именно для межконтурных задач: +- фиксированные системные зоны +- единый тип board item +- единый фильтровый слой +- переиспользуемый detail-shell из шага 11 + +## Связь с будущими пользовательскими колонками + +Пользовательские представления нужны, но не должны быть частью первой двусторонней доски. + +Их нужно проектировать как следующий слой поверх уже введенного board contract: +- пользователь создает свой блок +- задает имя +- задает фильтр +- получает еще одно представление рядом с системными блоками + +Но это именно представление. + +Это не новая стадия исполнения и не область для drag-and-drop. + +## Связь с будущими типами досок + +Архитектура этого шага должна допускать расширение на: +- агентные доски +- специализированные operational boards +- гибридные наблюдательные представления по нескольким контурам + +Из этого следуют два правила: +- доска должна собираться вокруг контракта представления, а не вокруг одной конкретной сущности `Issue` +- колонка должна означать выборку или представление, а не обязательно статус workflow + +## Критерий приемки + +- пользователь видит во `Внешних контурах` две системные зоны: `Исходящие` и `Входящие` +- отправленные запросы не теряются после отправки и остаются видимыми как рабочие объекты +- обе зоны фильтруются через единый механизм +- открытие карточки из любой зоны ведет в единый shell шага 11 +- между зонами нет drag-and-drop + +## Что идет следующим шагом после этого + +После стабилизации двусторонней доски можно переходить к пользовательским представлениям поверх того же контракта. + +Но только после того, как: +- подтверждена стабильность системных зон +- подтверждена консистентность фильтров +- подтверждена работа detail-shell в обоих направлениях + +Связанный документ: +- [11_STEP_external-contours-detail-shell.md](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/docs_prod/1_STEP_cross-project-task-routing/11_STEP_external-contours-detail-shell.md) diff --git a/docs_prod/cross-project-task-routing/README.md b/docs_prod/1_STEP_cross-project-task-routing/README.md similarity index 79% rename from docs_prod/cross-project-task-routing/README.md rename to docs_prod/1_STEP_cross-project-task-routing/README.md index 29e8829..9babdbc 100644 --- a/docs_prod/cross-project-task-routing/README.md +++ b/docs_prod/1_STEP_cross-project-task-routing/README.md @@ -116,6 +116,77 @@ На этом месте разработка следующего шага останавливается до фиксации продуктовых решений. +## Зафиксированные продуктовые решения на 2026-04-20 + +После freeze point приняты дополнительные продуктовые решения по следующему циклу развития `Внешних контуров`. + +### 1. Нужны две обязательные системные зоны + +Во `Внешних контурах` должны появиться: +- `Исходящие` +- `Входящие` + +`Исходящие` обязательны, потому что пользователь должен видеть запросы, которые он сам отправил в другие контуры, до и после обработки. + +`Входящие` обязательны, потому что проект должен видеть запросы, пришедшие к нему из других контуров, в отдельном специализированном режиме работы, а не только как обычные задачи `Внутреннего контура`. + +### 2. Обе зоны должны фильтроваться так же гибко, как во `Внутреннем контуре` + +Минимальный целевой принцип: +- фильтрация по пользователям +- фильтрация по статусам +- фильтрация по назначенным +- фильтрация по автору +- фильтрация по контурам и связанным проектам + +То есть `Внешние контуры` должны получить не просто статичный список, а управляемое рабочее представление. + +### 3. Карточка деталей внешнего контура должна перейти на тот же UX-паттерн, что и во `Внутреннем контуре` + +При клике по карточке должна открываться панель того же класса: +- закрыть просмотр +- открыть на весь экран +- переключить макет +- подписка или отписка +- копирование ссылки +- меню дополнительных действий + +При этом: +- действие удаления в этом shell не является обязательным +- тело карточки остается внешнеконтурным, а не превращается в обычную карточку внутренней задачи + +### 4. Внешний контур — это не workflow-kanban + +Важно зафиксировать заранее: +- пользователь не должен перетаскивать задачи между блоками +- блоки во `Внешних контурах` — это представления и выборки, а не стадии исполнения +- нельзя переносить сюда механику drag-and-drop из `Внутреннего контура` + +### 5. Пользовательские колонки нужны, но не входят в ближайший обязательный срез + +Собственные пользовательские блоки и сортировки нужны как следующий этап развития, но не должны размыть ближайшие обязательные поставки: +1. единый shell карточки внешнего контура +2. двусторонняя доска `Исходящие / Входящие` + +### 6. Архитектура должна остаться расширяемой + +Следующий слой развития не ограничивается только внешними контурами. + +Дальше в проекте могут появиться: +- новые типы досок +- агентные доски +- специализированные мониторинговые представления +- пользовательские рабочие поверхности под разные роли + +Поэтому нельзя решать следующий этап только переобертками и точечными хаками. + +Но и полный демонтаж текущего проекта ради абстрактной платформы тоже недопустим. + +Рабочий принцип: +- не ломать текущий runtime +- не дублировать уже существующие механики без причины +- выносить только те контракты, которые реально переиспользуются дальше + ## Что нужно решить перед продолжением - Что именно делает действие `Принять`: @@ -415,4 +486,6 @@ - определение границ MVP Подробная поэтапная разработка описана в: -- [phase-roadmap.md](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/docs_prod/cross-project-task-routing/phase-roadmap.md) +- [phase-roadmap.md](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/docs_prod/1_STEP_cross-project-task-routing/phase-roadmap.md) +- [11_STEP_external-contours-detail-shell.md](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/docs_prod/1_STEP_cross-project-task-routing/11_STEP_external-contours-detail-shell.md) +- [12_STEP_external-contours-bidirectional-board.md](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/docs_prod/1_STEP_cross-project-task-routing/12_STEP_external-contours-bidirectional-board.md) diff --git a/docs_prod/cross-project-task-routing/phase-roadmap.md b/docs_prod/1_STEP_cross-project-task-routing/phase-roadmap.md similarity index 72% rename from docs_prod/cross-project-task-routing/phase-roadmap.md rename to docs_prod/1_STEP_cross-project-task-routing/phase-roadmap.md index cbe5275..dce54eb 100644 --- a/docs_prod/cross-project-task-routing/phase-roadmap.md +++ b/docs_prod/1_STEP_cross-project-task-routing/phase-roadmap.md @@ -27,6 +27,21 @@ Дальше по roadmap пока не идем, пока не приняты продуктовые решения по внутреннему жизненному циклу принятого запроса. +## Новая рамка после freeze point на 2026-04-20 + +После дополнительной продуктовой фиксации следующий цикл делится на три слоя: +1. единый shell карточки внешнего контура +2. двусторонняя доска `Исходящие / Входящие` +3. пользовательские представления поверх той же доски + +При этом обязательное архитектурное ограничение фиксируется заранее: +- во `Внешних контурах` нет drag-and-drop между блоками +- блоки здесь означают представления, а не стадии workflow + +Подробные архитектурные шаги вынесены в: +- [11_STEP_external-contours-detail-shell.md](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/docs_prod/1_STEP_cross-project-task-routing/11_STEP_external-contours-detail-shell.md) +- [12_STEP_external-contours-bidirectional-board.md](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/docs_prod/1_STEP_cross-project-task-routing/12_STEP_external-contours-bidirectional-board.md) + ## Этап 0. Термины и навигация ### Цель @@ -236,6 +251,122 @@ - тест-кейсы - регламент эксплуатации +## Этап 6. Единый shell карточки внешнего контура + +### Цель + +Привести карточку деталей `Внешних контуров` к тому же UX-паттерну, что и во `Внутреннем контуре`, не ломая при этом внешний data-flow. + +### Что входит + +- общий shell открытия карточки +- тот же класс верхнего action-bar: + - закрытие просмотра + - полноэкранный режим + - переключение макета + - подписка или отписка + - копирование ссылки + - меню дополнительных действий +- переиспользование общего представления shell без подмены доменной модели внешнего контура +- сохранение внешнеконтурного body: + - `Маршрутизация` + - зеркальные комментарии + - зеркальные вложения + - external lifecycle + +### Что не входит + +- две системные зоны `Исходящие / Входящие` +- пользовательские колонки +- drag-and-drop +- насильственный перевод внешнего запроса в обычный issue detail + +### Критерий приемки + +- карточка `Внешних контуров` открывается по тому же UX-паттерну, что и внутренний peek +- source-only сценарий не ломается +- body карточки остается внешнеконтурным + +### Статус + +Запланировано. + +Подробно описано в: +- [11_STEP_external-contours-detail-shell.md](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/docs_prod/1_STEP_cross-project-task-routing/11_STEP_external-contours-detail-shell.md) + +## Этап 7. Двусторонняя доска `Исходящие / Входящие` + +### Цель + +Дать проекту единый рабочий экран межконтурной работы, где видны и отправленные, и полученные запросы. + +### Что входит + +- две фиксированные системные зоны: + - `Исходящие` + - `Входящие` +- единый board-level data contract +- фильтрация обеих зон по аналогии с `Внутренним контуром` +- счетчики +- открытие карточки в shell этапа 6 + +### Важное правило + +Это не kanban статусов. + +Во `Внешних контурах`: +- нет drag-and-drop между блоками +- блоки означают представления по направлению и фильтрам +- смена состояния не должна кодироваться визуальным переносом карточки + +### Что не входит + +- пользовательские кастомные зоны +- свободный конструктор колонок +- превращение доски во второй workflow движок + +### Критерий приемки + +- пользователь видит и `Исходящие`, и `Входящие` +- отправленные запросы не теряются после отправки +- обе системные зоны фильтруются через единый механизм +- карточка из любой зоны открывается единообразно + +### Статус + +Запланировано. + +Подробно описано в: +- [12_STEP_external-contours-bidirectional-board.md](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/docs_prod/1_STEP_cross-project-task-routing/12_STEP_external-contours-bidirectional-board.md) + +## Этап 8. Пользовательские представления поверх двусторонней доски + +### Цель + +Разрешить пользователю собирать собственные рабочие выборки поверх уже стабилизированной двусторонней доски. + +### Что входит + +- пользовательские блоки или представления +- пользовательское имя блока +- сохранение набора фильтров +- персональные рабочие выборки по контурам, статусам, пользователям и другим признакам + +### Важное правило + +Пользовательские блоки не меняют базовый принцип: +- это не стадии workflow +- это не drag-and-drop +- это не замена `Внутреннего контура` + +### Зависимость + +Этап начинается только после стабилизации этапов 6 и 7. + +### Статус + +Запланировано как следующий слой развития, но не входит в ближайший обязательный срез. + ## Технические решения, которые желательно держать с самого начала ### 1. Не ломать штатный intake