Add docs for cross-project task routing
This commit is contained in:
DCCONSTRUCTIONS
parent
39d9d9cd7a
commit
75ba36a318
|
|
@ -0,0 +1,357 @@
|
|||
# Межпроектная маршрутизация задач
|
||||
|
||||
## Цель
|
||||
|
||||
Добавить в `NODE.DC TM` отдельный сценарий межпроектной постановки задач между контурами без перепрошивки штатного `Intake`.
|
||||
|
||||
Базовая идея:
|
||||
- `Рабочие элементы` переименовываются в `Внутренние контуры`
|
||||
- рядом появляется новый модуль `Внешние контуры`
|
||||
- пользователь из проекта-источника создает внешний запрос
|
||||
- запрос уходит в целевой проект
|
||||
- в целевом проекте он становится обычной задачей
|
||||
- в проекте-источнике сохраняется видимый объект маршрутизации со статусом, историей и материалами
|
||||
|
||||
## Почему выбран именно этот путь
|
||||
|
||||
Не трогаем штатный `Intake` как пользовательский модуль.
|
||||
|
||||
Используем его только как внутренний backend-мост, потому что:
|
||||
- механизм уже умеет создавать bridge между `Issue` и `IntakeIssue`
|
||||
- уже есть переход из `TRIAGE` в default-state проекта
|
||||
- уже есть `extra JSON` для метаданных маршрутизации
|
||||
- это самый безопасный путь для форка и дальнейших обновлений
|
||||
|
||||
## Термины
|
||||
|
||||
### Внутренние контуры
|
||||
|
||||
То, что сейчас в UI является обычными рабочими элементами проекта.
|
||||
|
||||
### Внешние контуры
|
||||
|
||||
Новый отдельный модуль проекта, через который задача отправляется в другой проект внутри того же workspace.
|
||||
|
||||
### Проект-источник
|
||||
|
||||
Проект, из которого инициируется запрос.
|
||||
|
||||
### Целевой проект
|
||||
|
||||
Проект, в котором задача реально исполняется.
|
||||
|
||||
### Исходная карточка внешнего контура
|
||||
|
||||
Карточка или запись в проекте-источнике, где инициатор видит:
|
||||
- текущий статус
|
||||
- целевой проект
|
||||
- назначенного исполнителя
|
||||
- историю обработки
|
||||
- файлы
|
||||
- уведомления о ходе работы
|
||||
|
||||
### Целевая задача
|
||||
|
||||
Обычная задача в целевом проекте, которая попадает в обычный workflow этого проекта.
|
||||
|
||||
## Ключевой продуктовый результат
|
||||
|
||||
Пользователь из `Менеджеры` должен иметь возможность:
|
||||
- открыть `Внешние контуры`
|
||||
- выбрать целевой проект, например `Бухгалтерия`
|
||||
- описать запрос
|
||||
- назначить исполнителя из `Бухгалтерия`
|
||||
- отправить запрос
|
||||
|
||||
После этого:
|
||||
- у `Бухгалтерия` появляется обычная задача в их проекте
|
||||
- у отправителя в `Менеджеры` появляется запись во `Внешних контурах`
|
||||
- у этой записи есть статусная пришлепка
|
||||
- при любом изменении статуса в целевом проекте статус в источнике обновляется
|
||||
- если в целевом проекте меняют описание, прикладывают файлы, комментируют или закрывают задачу, это отражается в источнике
|
||||
- инициатор получает уведомления о существенных изменениях
|
||||
|
||||
## Обязательные требования
|
||||
|
||||
### 1. Отдельный модуль
|
||||
|
||||
`Внешние контуры` не должны быть переименованным `Intake`.
|
||||
|
||||
Это отдельная новая вкладка проекта.
|
||||
|
||||
### 2. Обычная задача в целевом проекте
|
||||
|
||||
Задача не должна висеть в ручном triage.
|
||||
|
||||
После отправки она должна сразу попадать в обычный workflow целевого проекта, в его default-state.
|
||||
|
||||
### 3. Статусная пришлепка в источнике
|
||||
|
||||
У каждой записи во `Внешних контурах` в списке должен быть видимый статус.
|
||||
|
||||
Для первой версии правильнее показывать фактическое имя текущего статуса целевой задачи:
|
||||
- `В плане`
|
||||
- `К выполнению`
|
||||
- `В работе`
|
||||
- `Готово`
|
||||
- `Отменено`
|
||||
- либо любой другой кастомный статус целевого проекта
|
||||
|
||||
То есть источник видит не абстрактное `accepted`, а реальный текущий статус исполнения.
|
||||
|
||||
### 4. Зеркалирование изменений из целевого проекта в источник
|
||||
|
||||
Изменения в целевой задаче должны отражаться в исходной карточке внешнего контура.
|
||||
|
||||
Минимальный обязательный набор:
|
||||
- изменение статуса
|
||||
- изменение названия
|
||||
- изменение описания
|
||||
- добавление/удаление файлов
|
||||
- комментарии и служебные заметки по задаче
|
||||
- закрытие/отмена задачи
|
||||
|
||||
### 5. Уведомления инициатору
|
||||
|
||||
Инициатор должен получать уведомления, когда:
|
||||
- задача принята в работу
|
||||
- задача переведена в другой статус
|
||||
- добавлен файл
|
||||
- добавлен комментарий
|
||||
- задача завершена
|
||||
- задача отменена
|
||||
|
||||
### 6. Трассировка между источником и целью
|
||||
|
||||
Связь между источником и целевой задачей должна быть явной и восстановимой.
|
||||
|
||||
Нельзя делать фичу как “создали задачу и забыли”.
|
||||
|
||||
## Архитектурный подход
|
||||
|
||||
## Общая схема
|
||||
|
||||
Используем существующий intake bridge как транспортный слой:
|
||||
- создаем `Issue` в целевом проекте
|
||||
- создаем `IntakeIssue`
|
||||
- сразу переводим bridge в `ACCEPTED`
|
||||
- целевая задача попадает в default-state проекта
|
||||
|
||||
Но только этого уже недостаточно.
|
||||
|
||||
Из-за требований на статусную пришлепку, зеркалирование файлов и уведомления нужен еще source-side слой отображения.
|
||||
|
||||
## Что остается от текущей идеи варианта 2
|
||||
|
||||
Сохраняем:
|
||||
- reuse intake backend-механики
|
||||
- отдельный orchestration endpoint
|
||||
- отдельный фронтовый модуль `Внешние контуры`
|
||||
|
||||
Расширяем:
|
||||
- добавляем источник правды для source-side карточки
|
||||
- добавляем синхронизацию изменений из target issue в source representation
|
||||
- добавляем уведомления
|
||||
|
||||
## Рекомендуемая модель данных для первой итерации
|
||||
|
||||
### Обязательная связь
|
||||
|
||||
Нужна явная пара:
|
||||
- `source_project_id`
|
||||
- `source_request_id`
|
||||
- `target_project_id`
|
||||
- `target_issue_id`
|
||||
|
||||
### Метаданные bridge
|
||||
|
||||
В `IntakeIssue.extra` храним:
|
||||
- тип моста: `external-contours`
|
||||
- источник
|
||||
- цель
|
||||
- автора
|
||||
- временные метки
|
||||
|
||||
Пример:
|
||||
|
||||
```json
|
||||
{
|
||||
"bridge": "external-contours",
|
||||
"source_project_id": "uuid",
|
||||
"source_project_name": "Менеджеры",
|
||||
"target_project_id": "uuid",
|
||||
"target_project_name": "Бухгалтерия",
|
||||
"requested_by_id": "uuid",
|
||||
"requested_by_name": "Иван Петров",
|
||||
"requested_at": "2026-04-18T19:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Source-side представление
|
||||
|
||||
Для source-side части есть два пути:
|
||||
|
||||
1. Легкая проекция без отдельной таблицы
|
||||
- список `Отправленные` собирается по `IntakeIssue.extra`
|
||||
- детали берутся из целевой задачи
|
||||
|
||||
2. Отдельная source-side сущность или shadow-record
|
||||
- отдельная запись для внешнего контура в проекте-источнике
|
||||
- в ней хранится mirrored state
|
||||
|
||||
Для требований текущего этапа безопаснее считать, что source-side проекция понадобится.
|
||||
|
||||
Причина:
|
||||
- нужен список со статусом
|
||||
- нужны файлы в источнике
|
||||
- нужна история изменений
|
||||
- нужны уведомления
|
||||
|
||||
Простого “читать target issue на лету” для этого, скорее всего, будет мало.
|
||||
|
||||
## UX первой рабочей вертикали
|
||||
|
||||
## Модуль `Внешние контуры`
|
||||
|
||||
В проекте появляется новая вкладка:
|
||||
- `Внешние контуры`
|
||||
|
||||
Внутри:
|
||||
- кнопка `Новый внешний запрос`
|
||||
- список `Открытые`
|
||||
- список `Завершенные`
|
||||
|
||||
## Форма создания
|
||||
|
||||
Поля:
|
||||
- целевой проект
|
||||
- название
|
||||
- описание
|
||||
- исполнитель из целевого проекта
|
||||
- приоритет
|
||||
- срок
|
||||
- метки
|
||||
|
||||
Вложения можно заложить сразу в спецификацию, но в первую техническую поставку лучше включать аккуратно.
|
||||
|
||||
## Карточка в списке
|
||||
|
||||
В строке списка должны быть:
|
||||
- название
|
||||
- целевой проект
|
||||
- исполнитель
|
||||
- дата создания
|
||||
- статусная пришлепка
|
||||
- индикатор новых изменений
|
||||
|
||||
## Детальный экран внешнего контура
|
||||
|
||||
Детальный экран источника не должен быть просто копией target issue.
|
||||
|
||||
Правильнее собрать его из блоков:
|
||||
- исходный запрос
|
||||
- текущий статус
|
||||
- целевой проект и исполнитель
|
||||
- история изменений
|
||||
- синхронизированные файлы
|
||||
- комментарии/обновления
|
||||
|
||||
Это безопаснее, чем пытаться перетирать исходное описание данными целевого проекта.
|
||||
|
||||
## Правила синхронизации
|
||||
|
||||
## Направления
|
||||
|
||||
### Источник -> цель
|
||||
|
||||
На этапе создания отправляем:
|
||||
- название
|
||||
- описание
|
||||
- исполнителя
|
||||
- приоритет
|
||||
- срок
|
||||
- метки
|
||||
|
||||
### Цель -> источник
|
||||
|
||||
После создания отражаем обратно:
|
||||
- текущий статус
|
||||
- изменения описания
|
||||
- комментарии
|
||||
- файлы
|
||||
- итоговый результат
|
||||
|
||||
## Что должно быть синхронизировано в обязательном порядке
|
||||
|
||||
- `target issue state.name`
|
||||
- `target issue updated_at`
|
||||
- файлы target issue
|
||||
- пользовательские комментарии
|
||||
- итоговый resolution state
|
||||
|
||||
## Что пока не нужно считать обязательным
|
||||
|
||||
- полная двусторонняя редакция из источника после отправки
|
||||
- редактирование чужих project labels через источник
|
||||
- полный realtime-collab режим
|
||||
|
||||
## Уведомления
|
||||
|
||||
Минимальный набор событий:
|
||||
- запрос создан
|
||||
- задача принята
|
||||
- статус изменен
|
||||
- добавлен файл
|
||||
- добавлен комментарий
|
||||
- задача завершена
|
||||
- задача отменена
|
||||
|
||||
Каналы первой версии:
|
||||
- in-app notifications
|
||||
|
||||
Каналы последующих итераций:
|
||||
- email
|
||||
- внешние integrations
|
||||
|
||||
## Ограничения текущего этапа
|
||||
|
||||
### 1. Вложения сейчас хрупкие
|
||||
|
||||
Текущий runtime уже показывал хрупкость attachment flow.
|
||||
|
||||
Поэтому вложения нужно учитывать в дизайне, но внедрять аккуратно и тестировать отдельно.
|
||||
|
||||
### 2. Права сложнее, чем кажется
|
||||
|
||||
Отправитель должен иметь право отправлять запрос из source project, но не обязан быть участником target project.
|
||||
|
||||
При этом:
|
||||
- target assignee должен быть участником target project
|
||||
- target issue создается в target project
|
||||
- источник должен иметь возможность видеть результат обработки без полного membership в target project
|
||||
|
||||
### 3. Простая “копия intake” уже недостаточна
|
||||
|
||||
Как только добавляются:
|
||||
- статусная пришлепка
|
||||
- файлы
|
||||
- история
|
||||
- уведомления
|
||||
|
||||
фича перестает быть просто формой создания.
|
||||
|
||||
Нужен отдельный источник правды для source-side представления.
|
||||
|
||||
## Что считаем текущим этапом
|
||||
|
||||
Текущий этап — это не финальная реализация, а проектирование и запуск вертикального среза.
|
||||
|
||||
В этот этап входят:
|
||||
- фиксация терминологии
|
||||
- фиксация архитектурного подхода
|
||||
- разбиение на поставки
|
||||
- определение обязательных требований для первой версии
|
||||
- определение границ MVP
|
||||
|
||||
Подробная поэтапная разработка описана в:
|
||||
- [phase-roadmap.md](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/docs_prod/cross-project-task-routing/phase-roadmap.md)
|
||||
|
|
@ -0,0 +1,203 @@
|
|||
# Этапы разработки
|
||||
|
||||
## Общий принцип
|
||||
|
||||
Не делаем сразу тяжелую доменную платформу.
|
||||
|
||||
Идем вертикальными поставками:
|
||||
1. сначала транспорт и создание задачи
|
||||
2. потом source-side представление
|
||||
3. потом синхронизация
|
||||
4. потом уведомления и полировка
|
||||
|
||||
## Этап 0. Термины и навигация
|
||||
|
||||
### Цель
|
||||
|
||||
Подготовить интерфейс и словарь сущностей без ломки backend-логики.
|
||||
|
||||
### Что входит
|
||||
|
||||
- `Рабочие элементы` -> `Внутренние контуры`
|
||||
- новая вкладка `Внешние контуры`
|
||||
- подготовка i18n-ключей и текстов
|
||||
- фиксация терминов в продуктовой документации
|
||||
|
||||
### Результат
|
||||
|
||||
В проекте уже есть новая структура навигации, но бизнес-логика еще не внедрена.
|
||||
|
||||
## Этап 1. Маршрутизация запроса в целевой проект
|
||||
|
||||
### Цель
|
||||
|
||||
Сделать рабочий сценарий отправки задачи из source project в target project.
|
||||
|
||||
### Что входит
|
||||
|
||||
- новая create-form во `Внешних контурах`
|
||||
- выбор целевого проекта
|
||||
- выбор исполнителя из целевого проекта
|
||||
- orchestration endpoint
|
||||
- использование intake bridge как backend-моста
|
||||
- немедленный перевод в default-state целевого проекта
|
||||
- создание target issue
|
||||
- запись source/target metadata
|
||||
|
||||
### Что не входит
|
||||
|
||||
- полноценная синхронизация файлов
|
||||
- полноценная зеркальная история
|
||||
- сложные уведомления
|
||||
|
||||
### Критерий приемки
|
||||
|
||||
- пользователь отправляет внешний запрос
|
||||
- в целевом проекте появляется обычная задача
|
||||
- задача не зависает в triage
|
||||
- source-side список уже видит факт отправки
|
||||
|
||||
## Этап 2. Source-side список и статусная пришлепка
|
||||
|
||||
### Цель
|
||||
|
||||
Дать инициатору читаемый контроль за отправленными запросами.
|
||||
|
||||
### Что входит
|
||||
|
||||
- список `Открытые`
|
||||
- список `Завершенные`
|
||||
- текущий статус задачи как пришлепка
|
||||
- отображение целевого проекта
|
||||
- отображение исполнителя
|
||||
- отображение даты обновления
|
||||
- индикатор новых изменений
|
||||
|
||||
### Критерий приемки
|
||||
|
||||
- в проекте-источнике виден список отправленных запросов
|
||||
- у каждой записи отображается актуальный статус целевой задачи
|
||||
|
||||
## Этап 3. Source-side детальный экран и зеркалирование изменений
|
||||
|
||||
### Цель
|
||||
|
||||
Сделать так, чтобы отправитель видел ход исполнения не только по одной плашке статуса.
|
||||
|
||||
### Что входит
|
||||
|
||||
- детальный экран внешнего контура
|
||||
- блок `Исходный запрос`
|
||||
- блок `Текущий статус`
|
||||
- mirrored activity stream
|
||||
- mirrored comments
|
||||
- mirrored files
|
||||
- mirrored description updates
|
||||
|
||||
### Важное правило
|
||||
|
||||
Исходный запрос не должен теряться.
|
||||
|
||||
Поэтому target-изменения лучше показывать отдельным блоком истории, а не просто затирать исходное описание.
|
||||
|
||||
### Критерий приемки
|
||||
|
||||
- если в target issue добавили файл, инициатор видит его в source-side карточке
|
||||
- если в target issue поменяли статус, это видно в source-side карточке
|
||||
- если в target issue написали комментарий, это видно в source-side карточке
|
||||
|
||||
## Этап 4. Уведомления
|
||||
|
||||
### Цель
|
||||
|
||||
Не заставлять инициатора вручную проверять изменения.
|
||||
|
||||
### Что входит
|
||||
|
||||
- in-app notification на:
|
||||
- принятие
|
||||
- перевод статуса
|
||||
- добавление файла
|
||||
- новый комментарий
|
||||
- завершение
|
||||
- отмену
|
||||
|
||||
### Критерий приемки
|
||||
|
||||
- инициатор получает уведомления по ключевым событиям жизненного цикла внешнего запроса
|
||||
|
||||
## Этап 5. Полировка и правила эксплуатации
|
||||
|
||||
### Что входит
|
||||
|
||||
- edge cases
|
||||
- повторная отправка
|
||||
- отмена
|
||||
- защита от удаления target issue
|
||||
- аудит прав
|
||||
- тест-кейсы
|
||||
- регламент эксплуатации
|
||||
|
||||
## Технические решения, которые желательно держать с самого начала
|
||||
|
||||
### 1. Не ломать штатный intake
|
||||
|
||||
Он остается отдельным продуктовым модулем.
|
||||
|
||||
### 2. Явно хранить source/target связь
|
||||
|
||||
Даже если первая версия идет через `IntakeIssue.extra`, связь не должна быть неявной.
|
||||
|
||||
### 3. Использовать фактический статус target issue
|
||||
|
||||
В source-side плашке лучше показывать не abstract intake status, а реальный текущий статус исполнения.
|
||||
|
||||
### 4. Не пытаться делать полную двустороннюю редакцию сразу
|
||||
|
||||
На старте безопаснее сделать:
|
||||
- создание из источника
|
||||
- исполнение в цели
|
||||
- синхронизацию результата обратно в источник
|
||||
|
||||
## Открытые вопросы
|
||||
|
||||
### 1. Source-side сущность
|
||||
|
||||
Нужно принять решение:
|
||||
- достаточно ли source-side проекции
|
||||
- или нужна отдельная таблица/модель для внешних контуров
|
||||
|
||||
### 2. Файлы
|
||||
|
||||
Нужно решить:
|
||||
- показываем ли мы source-side ссылку на target asset
|
||||
- или физически копируем файл в source representation
|
||||
|
||||
### 3. Комментарии
|
||||
|
||||
Нужно решить:
|
||||
- комментарии зеркалируются односторонне из цели в источник
|
||||
- или источник тоже может отвечать прямо из source-side карточки
|
||||
|
||||
### 4. Уровень realtime
|
||||
|
||||
Нужно решить:
|
||||
- хватит ли near-realtime через polling и existing refresh
|
||||
- или сразу нужен realtime через live-события
|
||||
|
||||
### 5. Доступ к target issue
|
||||
|
||||
Нужно решить:
|
||||
- должен ли инициатор иметь прямую ссылку на target issue
|
||||
- или доступ к target issue должен быть скрыт, а source-side карточка должна быть единственной точкой просмотра
|
||||
|
||||
## Рекомендуемый порядок фактической разработки
|
||||
|
||||
1. Этап 0
|
||||
2. Этап 1
|
||||
3. Этап 2
|
||||
4. Этап 3
|
||||
5. Этап 4
|
||||
6. Этап 5
|
||||
|
||||
Это даст быстрый полезный результат и не загонит проект в ранний тяжелый refactor.
|
||||
Loading…
Reference in New Issue