supersam/docs/superpowers/specs/2026-03-15-role-aware-orders-kanban-design.md

# Role-Aware Orders Kanban Design

**Date:** 2026-03-15

**Goal:** Add a shared orders kanban that can switch between stage-based and status-based views, shows responsibility by role, highlights stalled orders, and lets each employee work only within their responsibility zone while managers see the full pipeline.

## Context

- The current orders workspace already has filters, a registry, a calendar, a basic kanban, and an order detail panel.
- Status ownership already exists in `src/constants/deliveryWorkflow.js` via `ownerRole`.
- Current order visibility is assignment-based for manager, logisticians, and drivers, which conflicts with the requested "see all orders at your current work stage" behavior.
- The current kanban is hard-coded to a few grouped columns and does not support dual display modes, responsibility coloring, or aging/SLA highlighting.
- Status changes are already supported from the detail panel and by drag-and-drop in the kanban, but both paths need to be aligned around the same responsibility-aware rules.

## Decision

Implement one kanban engine with two display modes:

- `by_stage` for managers and employees who want a compact pipeline view
- `by_status` for detailed operational work

The kanban will derive its structure entirely from status metadata. Each status will describe:

- which role owns it
- which stage it belongs to
- how long it can stay there before warning/critical aging states apply

Managers and admins will see the full pipeline. Other roles will see only orders whose current status belongs to their responsibility zone. Status changes will remain available from both kanban drag-and-drop and the order detail panel, but only within transitions allowed for the current user role.

## Architecture

### Shared workflow metadata

Extend delivery workflow metadata so every status becomes a full configuration record:

- `ownerRole`
- `stageKey`
- `stageLabel`
- `tone`
- `warningAfterHours`
- `criticalAfterHours`

This keeps filters, visibility, kanban columns, card badges, and notifications driven from one source of truth.

### Responsibility-aware visibility

Order visibility will be split into two concepts:

- assignment fields such as `managerId`, `logisticianIds`, `assignedDriverId`
- current responsibility, derived from the current status metadata

Managers and admins see all visible orders. Other roles see any order whose current `ownerRole` matches their role, even if a different specific employee is assigned. Assignment remains searchable and filterable, but it no longer limits the kanban itself.

### Two kanban modes

The kanban workspace will expose a view switch:

- `По этапам`
- `По статусам`

In `by_stage`, columns represent large business steps such as manager, production, logistics, delivery, and completed. Cards still display the exact current status.

In `by_status`, each working status gets its own column. Completed statuses can remain hidden by default with an explicit toggle.

Both modes reuse the same card component, filter state, drag-and-drop logic, and permissions.

### Responsibility colors

Responsibility color communicates who currently owns the order:

- manager
- production lead
- logistician
- driver
- completed/cancelled neutral state

To avoid collision with aging signals, responsibility will use a stable visual element on the card such as a top border, side rail, or role badge. Aging state will use separate warning/critical styling on the card frame and badge text.

### Aging and SLA signals

Every status receives two aging thresholds:

- warning
- critical

The app computes time spent in the current status using the latest history entry that moved the order into that status. Each order then gets a derived aging state:

- `normal`
- `warning`
- `critical`

Cards show the elapsed time in the current status and visually escalate when thresholds are crossed. Kanban columns can also show counts of warning/critical orders.

### Notifications

In the current frontend-only demo architecture, notifications will be in-app derived alerts. The same data model should later support background processing in Supabase or another backend.

Phase 1 notification behavior:

- emit a notification when an order first enters warning
- emit a notification when an order first enters critical
- show warning/critical counts in the dashboard and kanban workspace
- allow filtering to only warning/critical orders

For the demo, these alerts can be recalculated from client state during render/hook updates instead of requiring background timers.

## UX Behavior

### Search and filters

The order filters should work consistently for the registry, calendar, and both kanban modes:

- search by order number
- search by customer first/last name
- search by customer phone
- filter by exact status
- filter by stage
- filter by responsibility role
- filter by manager
- filter by logistician
- filter by messenger/channel
- filter by aging state

Search should include order number, customer name, customer phone, status, tags, comments, and item names.

### Kanban cards

Each card should surface at a glance:

- order number
- customer name
- short item summary
- exact current status
- responsibility role color
- aging badge such as `24ч в статусе`

Critical orders should be visually distinct enough that one scan of the board reveals stuck work.

### Status changes

Users can change status in two places:

- drag a card to another column
- choose a new status inside the order detail panel

Both paths must use the same permission logic:

- available transitions are derived from `ORDER_STATUS_TRANSITIONS`
- transitions are then filtered by the current role's allowed targets

When dragging in stage mode, the target stage may contain several statuses. The drop handler must resolve the best allowed target status for that role in that stage, or reject the drop if no valid target exists.

## File Responsibilities

- `src/constants/deliveryWorkflow.js` — enrich status metadata with stage and SLA config
- `src/constants/orderStatuses.js` — continue re-exporting workflow-driven statuses
- `src/services/orderService.js` — expand search blob and responsibility-aware filtering helpers if needed
- `src/services/orderViews.js` — build stage/status kanban columns, aging state, and stalled counts
- `src/services/orderViews.test.js` — verify kanban modes, visibility helpers, and aging calculations
- `src/hooks/useOrders.js` — switch visible order rules from assignment-based to responsibility-based and expose derived alert data
- `src/components/orders/OrderFilters.jsx` — add stage/responsibility/aging filters and richer search copy
- `src/components/orders/OrderDetailPanel.jsx` — keep role-limited status changes aligned with kanban behavior
- `src/pages/DashboardPage.jsx` — wire the new kanban controls, counts, and notification summaries
- optional new helper/component files under `src/components/orders/` if the kanban card or toolbar becomes too large

## Testing Strategy

- Add unit tests for status metadata derived helpers and kanban column building in both modes.
- Add unit tests for aging state calculation at normal, warning, and critical thresholds.
- Add unit tests for responsibility-based visibility and filters.
- Verify that the same allowed transition set is used by both kanban drag-and-drop and detail-panel status editing.
- Run the existing order service and order views test suites to catch regressions in registry/calendar behavior.

## Out Of Scope

- Real background schedulers or push notifications
- New backend tables for SLA tracking
- Per-user notification preferences
- Reworking unrelated driver-only planning screens