# Role-Aware Orders Kanban Implementation Plan

> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Сделать единый канбан заказов с переключением `по этапам / по статусам`, ролевой видимостью, цветовой индикацией ответственности, подсветкой зависших заказов и едиными правилами изменения статусов.

**Architecture:** Логика канбана и зависаний строится из метаданных статусов в `deliveryWorkflow`, а сервис `orderViews` собирает колонки и вычисляемые поля для обоих режимов отображения. `useOrders` меняет правила видимости на responsibility-based, а UI в `DashboardPage`, `OrderFilters` и `OrderDetailPanel` переиспользует общие transition-правила и новые aging-флаги.

**Tech Stack:** React 18, Vite, existing UI components, Vitest, existing order services/hooks.

---

## Chunk 1: Workflow Metadata And View Builders

### Task 1: Зафиксировать stage/SLA-логику в тестах order views

**Files:**
- Modify: `src/services/orderViews.test.js`
- Reference: `src/constants/deliveryWorkflow.js`
- Reference: `src/data/mockAppData.js`

- [ ] Добавить падающие тесты на:
  - построение колонок в режиме `by_stage`
  - построение колонок в режиме `by_status`
  - вычисление aging state `normal / warning / critical`
  - скрытие завершённых заказов по умолчанию
- [ ] Прогнать только тесты order views.
  - Run: `npm test -- src/services/orderViews.test.js`
  - Expected: FAIL по отсутствующим полям/логике

### Task 2: Расширить метаданные статусов

**Files:**
- Modify: `src/constants/deliveryWorkflow.js`

- [ ] Добавить для каждого статуса:
  - `stageKey`
  - `stageLabel`
  - `warningAfterHours`
  - `criticalAfterHours`
- [ ] Экспортировать вспомогательные константы и функции:
  - список этапов
  - получение stage для статуса
  - получение ownerRole/status SLA
- [ ] Сохранить обратную совместимость существующих комментариев, tone и transitions.
- [ ] Не менять набор доступных переходов без прямой необходимости.

### Task 3: Реализовать новый builder для канбана и aging

**Files:**
- Modify: `src/services/orderViews.js`
- Test: `src/services/orderViews.test.js`

- [ ] Добавить helper для вычисления времени в текущем статусе через history.
- [ ] Добавить helper для вычисления aging badge и state.
- [ ] Реализовать общий builder колонок с режимами:
  - `by_stage`
  - `by_status`
- [ ] Добавить в элементы колонок вычисляемые поля:
  - `ownerRole`
  - `stageKey`
  - `stageLabel`
  - `agingState`
  - `statusAgeHours`
  - `statusAgeLabel`
- [ ] Прогнать тесты order views.
  - Run: `npm test -- src/services/orderViews.test.js`
  - Expected: PASS

## Chunk 2: Responsibility-Based Visibility And Filters

### Task 4: Зафиксировать новую видимость и поиск в тестах order service

**Files:**
- Modify: `src/services/orderService.test.js`
- Modify: `src/services/orderService.js`

- [ ] Добавить падающие тесты на:
  - видимость всех заказов текущей роли по `ownerRole`, а не по assignment
  - поиск по телефону клиента
  - фильтр по этапу
  - фильтр по зоне ответственности
  - фильтр по aging state
- [ ] Прогнать только тесты order service.
  - Run: `npm test -- src/services/orderService.test.js`
  - Expected: FAIL

### Task 5: Реализовать responsibility-based фильтрацию

**Files:**
- Modify: `src/services/orderService.js`
- Modify: `src/hooks/useOrders.js`
- Test: `src/services/orderService.test.js`

- [ ] Расширить `buildSearchBlob` полем телефона клиента и stage/responsibility значениями при необходимости.
- [ ] Изменить фильтрацию видимости:
  - manager/admin видят всё
  - остальные роли видят заказы по текущему `ownerRole`
- [ ] Добавить в filters новые поля:
  - `stage`
  - `ownerRole`
  - `agingState`
- [ ] Передавать новые filters через `useOrders`.
- [ ] Прогнать тесты order service.
  - Run: `npm test -- src/services/orderService.test.js`
  - Expected: PASS

## Chunk 3: Kanban And Detail UI

### Task 6: Обновить фильтры заказов

**Files:**
- Modify: `src/components/orders/OrderFilters.jsx`
- Reference: `src/constants/deliveryWorkflow.js`
- Reference: `src/constants/roles.js`

- [ ] Добавить select-поля для:
  - этапа
  - зоны ответственности
  - зависаний
- [ ] Обновить placeholder поиска под номер заявки, имя/фамилию и телефон клиента.
- [ ] Сохранить текущие фильтры менеджера, логиста и канала.

### Task 7: Переделать канбан-вкладку вокруг общего builder

**Files:**
- Modify: `src/pages/DashboardPage.jsx`
- Optionally Create: `src/components/orders/OrdersKanbanBoard.jsx`
- Optionally Create: `src/components/orders/OrdersKanbanCard.jsx`

- [ ] Добавить переключатель режима:
  - `По этапам`
  - `По статусам`
- [ ] Подключить новый builder колонок с параметрами режима и completed toggle.
- [ ] Показать счётчики warning/critical по колонкам.
- [ ] Обновить карточки:
  - роль-ответственный цвет
  - точный статус
  - aging badge
  - явная подсветка зависших заказов
- [ ] Оставить открытие карточки заказа по клику.

### Task 8: Свести drag-and-drop к единым transition-правилам

**Files:**
- Modify: `src/pages/DashboardPage.jsx`
- Modify: `src/components/orders/OrderDetailPanel.jsx`
- Reference: `src/constants/deliveryWorkflow.js`

- [ ] Добавить helper выбора drop-status внутри stage/status колонок.
- [ ] Разрешать перенос только если для роли пользователя есть допустимый target status.
- [ ] Если перенос невозможен, не менять заказ и не маскировать ошибку.
- [ ] Убедиться, что detail panel и kanban используют один и тот же список доступных переходов.

## Chunk 4: Notification Signals And Verification

### Task 9: Добавить in-app сигналы по зависшим заказам

**Files:**
- Modify: `src/hooks/useOrders.js`
- Modify: `src/pages/DashboardPage.jsx`

- [ ] Вычислить warning/critical summary по видимым заказам.
- [ ] Показать краткий блок или баннер с количеством зависающих и просроченных заказов.
- [ ] Добавить быстрый переход/фильтр на зависшие заказы из канбана.

### Task 10: Проверить регрессии и завершить

**Files:**
- Modify: `README.md` if needed
- Reference: `docs/superpowers/specs/2026-03-15-role-aware-orders-kanban-design.md`

- [ ] Прогнать таргетированные тесты.
  - Run: `npm test -- src/services/orderViews.test.js src/services/orderService.test.js`
  - Expected: PASS
- [ ] Прогнать полный тестовый набор.
  - Run: `npm test`
  - Expected: PASS
- [ ] Прогнать линтер.
  - Run: `npm run lint`
  - Expected: PASS
- [ ] Запустить production build.
  - Run: `npm run build`
  - Expected: PASS
- [ ] Коротко вручную проверить:
  - менеджер видит весь поток
  - логист/водитель/производство видят только свою текущую зону
  - канбан переключается между этапами и статусами
  - зависшие карточки подсвечиваются
  - статус меняется и drag-and-drop, и из detail panel