# Канбан — Администрирование

Документ описывает администрирование канбан-представлений платформы: включение канбана в категории, настройку шаблона карточки, группировок, агрегаций и сортировки, а также альтернативные режимы (Lookup, публикации). Для администраторов категорий и инженеров внедрения.

## Что настраивается и типовой канбан категории

Админ-контур канбана состоит из трех блоков:

1. включение канбана как представления категории;
2. настройка карточки и поведения доски через шаблон задач;
3. ~~настройка пользовательского канбана через публикации~~ *(устарело, не поддерживается)*.

Канбан категории доступен по URL:

- `~/spa/tasks/subcat/{subcatId}/kanban`
- устаревший формат: `~/spa/kanban/subcat/{subcatId}`

Что контролируется настройками категории:

- доступность представления "Канбан";
- маршрут и статусы, из которых строятся колонки — порядок колонок по статусам не настраивается, его рассчитывает система по графу переходов;
- права на принудительную смену статуса;
- параметры, доступные для фильтрации/группировки.

## 2. Шаблон карточки канбана

Шаблон настраивается через "Шаблоны задач" (динамический шаблон, контекст `kanban`).

![Карточка канбана: заголовок, индикатор-счётчик, теги, переход по маршруту, номер задачи с префиксом # и аватар](https://help.1forma.ru/help-images/kanban/kanban_card_new.png)

Ключевые параметры:

- `templateClass: "kanban"` — тип шаблона;
- `showHeaderColors` — включение/выключение цветных заголовков статусов;
- `leftBorder` — цветовая левая обводка карточки;
- `groupings` — список доступных группировок и признак группировки по умолчанию;
- `aggregations` — агрегаты по числовым/денежным ДП (sum/avg/max/min).

В карточке настраиваются блоки:

- `header` и `footer` — предопределенные блоки;
- `body` — динамический вывод ДП и системных полей.

### 2.1 Элементы блоков header и footer

Каждый элемент блока описывается JSON:

```json
{ "type": "mainParam"|"extparam", "dataKey": "..."|123, "alias": "...", "viewMode": "...", "settings": {} }
```

- `type` — `mainParam` (системный параметр) или `extparam` (ДП);
- `dataKey` — для `mainParam` ключ системного поля; для `extparam` — ID ДП;
- `alias` — роль элемента в блоке (см. таблицы ниже);
- `hideIfEmpty` — корневой ключ элемента (на одном уровне с `type`, `dataKey` и `alias`, не внутри `settings`): `false` — показывать элемент даже без значения, `true` или отсутствие ключа — скрыть. Действует в карточках только для чтения: галерея, канбан, карточка масштаба «Расписание» в календаре, ресурсная карточка и всплывающая подсказка, предпросмотр шаблона в администрировании. Карточка задачи, форма создания и лента задач читают свои шаблоны другими компонентами и на этот ключ не реагируют.

Пустые элементы карточки скрываются по умолчанию: числовой параметр со значением `0` и признак со значением «нет» пустыми не считаются и показываются как обычно.

**Alias для header:**

| Alias | Описание | Ключевые settings |
|-------|----------|-------------------|
| `title` | Заголовок — текст задачи (`dataKey: "taskText"`) | — |
| `headerCounter` | Индикатор с количеством задач | `color`, `emphasis` |
| `subtitle` | Подзаголовок, вторая строка | — |
| `mainTag` | Главный тег | `color` |
| `tags` | Теги задачи (из `viewTags`) | — |
| `headerDate` | Срок задачи | — |
| `cover` | Обложка карточки | `ratioWH`, устаревший `showEmptyCover` |
| `cardIdentifier` | Номер задачи (`dataKey: "taskId"`) | `prefix` |

**Теги задачи (alias `tags`).** Набор тегов берётся из настройки тегов категории (Дополнительно → Наборы тегов). Цвет каждого тега — из его настройки: тег, привязанный к мультилукап-параметру, показывается отдельным бейджем на каждое выбранное значение, а при цвете «из значения» каждый бейдж окрашивается в цвет своей задачи-значения. Тег без заданного цвета выводится серым. Теги статуса и приоритета в карточку не попадают: статус показывают колонки доски, приоритет — цветовая обводка слева. Набор, порядок и цвета тегов одинаковы для карточки без шаблона и для элемента `mainParam`/`tags` в `header`; тот же конструктор карточки используют галерея, календарь, «Ресурсы» и превью шаблона в администрировании.

**Alias для footer:**

| Alias | Описание | Ключевые особенности |
|-------|----------|---------------------|
| `avatar` | Аватар карточки (из ДП-файла) | `dataKey` = ID ДП с типом «Файл» |
| `priority` | Приоритет | `valueMapper` для пользовательских подписей |
| `users` | Пользователи (исполнители, ДП-выбор пользователей) | `viewMode: "table"` обязателен |
| `cardIdentifier` | Номер задачи | `settings.prefix` добавляет префикс (напр. `#`) |
| `totalSubtasks` | Общее количество подзадач | Поддерживает `extparam` с типом «Число» |
| `activeSubtasks` | Количество активных подзадач | Аналогично `totalSubtasks` |

`totalSubtasks` и `activeSubtasks` также поддерживают значения из ДП с типом «Число»: `"type": "extparam"`, `"dataKey": {ID ДП}`, `alias` остаётся без изменений.

Бейдж подзадач на карточке канбана виден по умолчанию: если в шаблоне нет элемента подзадач, счётчики `totalSubtasks`/`activeSubtasks` подставляются из задачи (у задач без подзадач — 0/0). Чтобы скрыть бейдж, у элемента подзадач задают `settings.showInFooter: false` (флаг срабатывает и при нулевом счётчике). В представлении «Галерея» и в админ-превью бейдж показывается только при счётчике больше нуля.

**Параметры `settings` для элемента `headerCounter`:**

| Параметр | Значения | Описание |
|----------|----------|----------|
| `color` | `primary` `accent` `info` `success` `warning` `fav` `danger` `error` `default` `blackWhite` | Цвет индикатора |
| `emphasis` | `accent` `container` | Акцент индикатора |

**Параметры `settings` для элемента `cover`:**

| Параметр | Тип | Описание |
|----------|-----|----------|
| `ratioWH` | string | Соотношение сторон обложки строкой `W:H`, где `W` и `H` — положительные числа, например `1:1`, `16:9`, `2:3`, `9:21`. Значение произвольное, закрытого перечня нет. Если ключ не задан или значение не разобрано, используется `16:9` |
| `showEmptyCover` | bool | Устаревший частный ключ обложки: `true` — показывать пустую обложку. Читается только тогда, когда у элемента не задан корневой `hideIfEmpty`. Для новых шаблонов используйте `hideIfEmpty` |

Порядок чтения для обложки: сначала корневой `hideIfEmpty`; если он не задан — `showEmptyCover`; если не задан ни один ключ, пустой слот обложки скрыт, как и у любого другого пустого элемента. Шаблон с обоими ключами подчиняется `hideIfEmpty`.

**Параметры `settings` для элемента `priority` (footer):**

`valueMapper` позволяет задать пользовательские подписи для уровней приоритета:

```json
"settings": {
  "valueMapper": { "0": "low", "3": "high" }
}
```

### 2.2 Элементы блока body

Блок `body` — динамический: отображаются только те ДП, в которых есть значение. Для каждого элемента обязателен параметр `viewMode`.

**Значения `viewMode`:**

| Значение | Описание |
|----------|----------|
| `normal` | Названия параметров строкой выше значений |
| `compact` | Названия слева от значений (по умолчанию) |
| `valueOnly` | Только значения, без названий |
| `one` | Параметры не отображаются |
| `table` | Табличный вид (для пользователей; в `settings`: `showUserStatus: true` для статуса «как в ленте») |
| `icon` | Иконка слева вместо названия (требует `settings.icon`) |
| `iconSet` | Для Multilookup — иконки задач вместо текста; `showColor: true` окрашивает по цвету задачи |
| `tags` | Lookup/Multilookup в виде тегов; `showIcon` и `showColor` управляют иконкой/цветом задачи |

**Параметры `settings` для элементов body:**

| Параметр | Тип | Описание |
|----------|-----|----------|
| `icon` | string | Иконка при `viewMode: icon` (из `/spa/content-icons`) |
| `truncate` | bool | Обрезка текста троеточием (`true` — по умолчанию) |
| `showUserStatus` | bool | Статус пользователя при `viewMode: table` |
| `showIcon` | bool | Иконка задачи в тегах при `viewMode: tags` |
| `showColor` | bool | Цвет задачи в тегах при `viewMode: tags`; при использовании в `leftBorder` — автоматическое определение цвета |
| `style` | string | `secondary` — второстепенный стиль: уменьшенный шрифт и серый цвет текста. Применяется к подписи поля и к текстовому значению; на теги, иконки и списки пользователей не влияет. По умолчанию (`primary` или параметр не задан) — обычный вид |

### 2.3 Секция settings шаблона

В `settings` внутри `contexts[]` задаются глобальные настройки карточки канбана:

- `leftBorder` — левая обводка;
- `showHeaderColors` — цветные заголовки статусов;
- `groupings` — группировки;
- `aggregations` — агрегаты по числовым/денежным ДП;
- `sortings` — сортировка карточек внутри колонки.
- `readonly` — режим «только просмотр»: перетаскивание карточек и перестановка колонок отключены для всех (с версии 2.268).
- `readonly` — режим «только просмотр»: перетаскивание карточек и перестановка колонок отключены для всех (с версии 2.268).

#### showHeaderColors, leftBorder и groupings

**showHeaderColors.** По умолчанию `true` (цвета статусов из настроек маршрута). Завершающие статусы всегда зелёные, отклоняющие — красные; изменение цвета для них недоступно. `false` — все статусы серые.

![Цветные заголовки колонок-статусов при showHeaderColors=true](https://help.1forma.ru/help-images/kanban/kanban_state_color.png)

**leftBorder.** Настраивается как элемент с source/mainParam. Два режима:

1. **Ручной** — через `dynamicSettings` со значениями и цветами:
   ```json
   "leftBorder": {
     "type": "mainParam", "dataKey": "priority", "alias": "leftBorder",
     "dynamicSettings": {
       "0": { "color": "var(--base-info)" },
       "3": { "color": "var(--base-danger)" }
     }
   }
   ```

2. **Автоматический** — через `"settings": { "showColor": true }`:
   - для `dataKey: "priority"` — все 5 уровней приоритета;
   - для Lookup-полей — цвет значения (`taskColor`);
   - `dynamicSettings` в этом режиме игнорируется.

   Минимальная настройка:
   ```json
   "leftBorder": {
     "type": "mainParam", "dataKey": "priority",
     "alias": "leftBorder",
     "settings": { "showColor": true }
   }
   ```

**groupings.** Список доступных группировок. Элемент с `"settings": { "isDefault": true }` — группировка по умолчанию при открытии канбана.

Если `groupings` не задан, в выпадающем списке по умолчанию доступны: Исполнители, Заказчик, Срок, Дата создания, Дата изменения.

Пример:
```json
"groupings": [
  {
    "type": "mainParam", "dataKey": "performer",
    "name": "Исполнители",
    "settings": { "isDefault": true }
  }
]
```

#### aggregations

Сумма, среднее, максимум, минимум по числовым/денежным ДП. Параметры:

| Параметр | Описание |
|----------|----------|
| `column` | ID ДП в формате `ExtParam{ID}` |
| `name` | Отображаемое имя |
| `operation` | `sum` `avg` `max` `min` |
| `postfix` | Текст после значения |
| `separator` | Разделитель между агрегациями |

Пример:
```json
"aggregations": [
  { "column": "ExtParam12872", "name": "Efforts(сумма)", "operation": "sum", "postfix": "сум", "separator": "/" },
  { "column": "ExtParam12872", "name": "Efforts(среднее)", "operation": "avg", "postfix": "ср" }
]
```

#### sortings (v2.259+)

Сортировка карточек внутри колонки. Задаётся на уровне конфигурации канбана, без пользовательского переключателя. Поддерживает множественные правила — второе правило применяется к карточкам, равным по первому, и т.д.

**Параметры элемента сортировки:**

| Параметр | Описание |
|----------|----------|
| `type` | `mainParam` или `extParam` |
| `dataKey` | Ключ системного поля или ID ДП |
| `name` | Отображаемое имя |
| `settings.direction` | `asc` (по возрастанию) или `desc` (по убыванию) |
| `settings.isDefault` | Признак сортировки по умолчанию (может быть несколько — все применяются последовательно) |

**Ограничения:**

- сортировка действует **внутри колонки**, порядок колонок не меняется;
- если сортировка не задана — используется порядок от источника данных;
- **при настроенной сортировке перетаскивание карточек внутри колонки отключено** (карточка возвращается на исходную позицию);
- параметр сортировки не должен передаваться в запрос получения данных, если настройка не выбрана.

Пример:
```json
"sortings": [
  {
    "type": "mainParam", "dataKey": "order",
    "name": "Порядок", "settings": { "direction": "desc" }
  },
  {
    "type": "extParam", "dataKey": 76690,
    "name": "Фича", "settings": { "isDefault": true, "direction": "desc" }
  }
]
```

#### readonly (v2.268+)

Режим «только просмотр» доски. Задаётся в секции `settings` контекста `kanban`, рядом с группировками и сортировками.

| Ключ | Тип | По умолчанию | Значение |
|---|---|---|---|
| `readonly` | boolean | отсутствует (равносильно `false`) | `true` — перетаскивание карточек и перестановка колонок отключены для всех пользователей |

Что отключается при `true`:

- перетаскивание карточек между колонками и внутри колонки — и на канбане по статусам, и на канбане по дополнительному параметру, на любом срезе;
- пункт «Режим принудительной смены статуса» в меню «Прочее»: настройка сильнее этого режима и действует независимо от прав, включая администратора категории и администратора задач;
- перестановка колонок перетаскиванием заголовков на канбане по дополнительному параметру.

Ключ не влияет на остальные действия доски: создание задачи в колонке, отметки в списке задач на карточке и контекстное меню карточки работают как прежде, а статус по-прежнему можно сменить в карточке задачи. Настройка действует только в интерфейсе: переход, выполненный напрямую через API, проверяется сервером по обычным правилам. Если ключ отсутствует или его значение отлично от `true`, доска ведёт себя как раньше.

Пример:

```json
"settings": {
  "templateClass": "kanban",
  "readonly": true
}
```

Отдельного флажка в редакторе шаблонов нет: ключ задаётся в JSON шаблона (кнопка «JSON» в редакторе динамического шаблона).

#### readonly (v2.268+)

Режим «только просмотр» доски. Задаётся в секции `settings` контекста `kanban`, рядом с группировками и сортировками.

| Ключ | Тип | По умолчанию | Значение |
|---|---|---|---|
| `readonly` | boolean | отсутствует (равносильно `false`) | `true` — перетаскивание карточек и перестановка колонок отключены для всех пользователей |

Что отключается при `true`:

- перетаскивание карточек между колонками и внутри колонки — и на канбане по статусам, и на канбане по дополнительному параметру, на любом срезе;
- пункт «Режим принудительной смены статуса» в меню «Прочее»: настройка сильнее этого режима и действует независимо от прав, включая администратора категории и администратора задач;
- перестановка колонок перетаскиванием заголовков на канбане по дополнительному параметру.

Ключ не влияет на остальные действия доски: создание задачи в колонке, отметки в списке задач на карточке и контекстное меню карточки работают как прежде, а статус по-прежнему можно сменить в карточке задачи. Настройка действует только в интерфейсе: переход, выполненный напрямую через API, проверяется сервером по обычным правилам. Если ключ отсутствует или его значение отлично от `true`, доска ведёт себя как раньше.

Пример:

```json
"settings": {
  "templateClass": "kanban",
  "readonly": true
}
```

Отдельного флажка в редакторе шаблонов нет: ключ задаётся в JSON шаблона (кнопка «JSON» в редакторе динамического шаблона).

### Добавление ДП из карточки канбана

Дополнительный параметр можно создать прямо из карточки на доске — без перехода в настройки категории.

Меню вызывается по клику на карточке (в Канбане правого клика на карточках нет — используется кликовое меню доски). В меню есть пункт **«Добавить ДП»** с подменю типов дополнительных параметров.

Пункт виден в двух случаях:

- пользователь — администратор площадки;
- в категории у пользователя есть право «Администратор категории» — тогда пункт открыт и без прав администратора площадки.

Если ни одного из этих прав нет, пункт в меню не показывается.

По выбору типа открывается окно создания параметра — то же, что и на странице настроек ДП: поле имени и список типов. Имя не обязательно: если его не заполнить, параметр получит название типа. Указать тип-специфичные настройки в этом окне нельзя (см. «Ограничения быстрого создания» ниже).

После успешного создания доска пересчитывается автоматически — новое поле появляется на карточках **без перезагрузки страницы**.

Ограничения быстрого создания:

- параметр создаётся с настройками по умолчанию;
- тип-специфичные настройки (флаг форматирования для «Большого текста», режим отображения времени для «Даты» и «Даты и времени», выбор справочника и первых значений для «Лукапа» и «Мультилукапа») в окне не задаются — их настраивают потом на странице настроек ДП категории;
- типы «Таблица» и «Выбор нескольких задач из категории» (Мультилукап) без настройки колонок и источника ломают отображение всей панели ДП на форме задачи. Быстрое создание их допускает, но сразу после создания параметр нужно донастроить.

Дальнейшая настройка ДП — на странице настроек ДП категории, см. [Настройка ДП](https://help.1forma.ru/domains/ext-params/admin.md).

### Когда шаблон не применяется к канбану

Шаблон доходит до доски, только если правило его назначения подходит запросу. Если правило не отобралось, канбан рисует карточку и меню сортировок по умолчанию — там остаётся стандартный набор, а секция `sortings` шаблона не применяется, хотя её содержимое верное.

Что проверить в назначении шаблона:

- категория правила совпадает с категорией доски;
- тип клиента правила подходит запросу: значение «Все» действует для любого клиента, иначе нужен «Веб». Значение может храниться и именем, и числовым кодом — отбор принимает оба вида;
- шаблон содержит контекст `kanban`, а в его настройках у `templateClass` стоит значение `kanban`;
- секция `sortings` лежит в настройках именно канбан-контекста;
- у правила включён признак размещения, соответствующий представлению карточки.
## Альтернативные режимы канбана: Lookup и публикации

**Канбан по Lookup-полю.** Админ может переключить построение канбана с маршрута на конкретный Lookup-параметр.

Особенности:

- порядок колонок задается настройкой Lookup "Колонка сортировки";
- если «Колонка сортировки» не задана, колонки идут в ручном порядке задач категории-источника; администратор этой категории или администратор задач в ней может переставлять колонки, перетаскивая заголовки на доске;
- при переносе карточки меняется значение Lookup;
- появляется колонка "Не заполнено" для пустых значений.

**Пользовательский канбан на публикациях *(устаревший способ)***.

> **⚠️ Устарело.** Настройка через публикации больше не поддерживается. Пользовательский канбан настраивается через шаблон задач (см. раздел 2).

Канбан вызывается по URL:

- `~/spa/kanban/{publicationAlias}`

Нужно настроить 3 публикации:

1. публикация структуры (`columns`, `rows`, `templates`, ссылки на data/move);
2. публикация данных;
3. публикация перемещения карточки между колонками/строками.

Ключевые элементы структуры:

- `columns` — колонки с `movableFrom/movableTo`, `template`, `showArrow`;
- `rows` — строки доски, опционально с `movableFrom/movableTo`;
- `dataSet` — URL публикации данных;
- `moveWebRequest` — URL публикации перемещения.

Важно:

- права на публикации должны быть настроены отдельно;
- ограничение прав на move можно сделать через доступ к публикации перемещения.

## Типовые ошибки настройки

Частые ошибки настройки канбана:

1. Канбан не отображается в категории:

- не включено представление "Канбан" в настройках категории;
- у пользователя нет прав на категорию.

2. Колонки не соответствуют ожиданиям:

- основной маршрут не настроен или настроен не тот;
- выбран режим канбана по Lookup, а не по маршруту.

4. Перетаскивание не работает:

- в шаблоне задач контекста `kanban` задано `settings.readonly: true` — тогда перетаскивание отключено для всех, независимо от маршрута и прав.

4. Перетаскивание не работает:

- в шаблоне задач контекста `kanban` задано `settings.readonly: true` — тогда перетаскивание отключено для всех, независимо от маршрута и прав.

3. Карточка выглядит "по-старому":

- шаблон задач не привязан в шаблонизации категории;
- контекст шаблона задан не как `kanban`.

4. Перетаскивание не работает:

- в пользовательском канбане не задан `moveWebRequest`;
- нет прав на публикацию перемещения;
- в типовом канбане переход запрещен маршрутом/правами.

## Связанные контуры

### Карточка масштаба «Расписание»

Масштаб «Расписание» календарного представления категории использует тот же конструктор карточки, что и канбан: шаблон берётся по категории задачи, состав шапки, тела и подвала — общий. Если шаблон у категории не задан, календарь показывает собственную карточку с фиксированным набором полей. Пользовательская часть — в [Календаре](https://help.1forma.ru/domains/calendar/business.md), настройка представления — в [администрировании календаря](https://help.1forma.ru/domains/calendar/admin.md).

### Галерея и мобильный дашборд

**Шаблон карточки галереи.** Представление категории «Галерея» использует конструктор шаблона, **аналогичный канбан-шаблону**: те же блоки `header`/`body`/`footer`, элементы, `viewMode`, `settings`. Отличия:

- `context: "gallery"` (вместо `"kanban"`);
- `templateClass: "gallery"`;
- уникальный параметр `bootstrapSize` (`sm`/`md`/`lg`), влияющий на минимальное количество элементов в строке и размер карточек (`sm` — до 6 элементов в ряду).

Галерея использует тот же конструктор карточки, что и канбан, отличаясь только контекстом (`gallery`) и размером bootstrap-сетки.

![Представление «Галерея»: карточки задач с обложками в сетке](https://help.1forma.ru/help-images/kanban/gallery_custom_task_template-001.png)

Подробнее о представлениях списков задач — в [администрировании списков](https://help.1forma.ru/domains/grids/admin.md).

**Мобильный дашборд (Dashboard-контейнер).** Функциональность мобильного дашборда (AllDashboards, Dashboard-контейнер с плитками/баннерами/стеками, Избранное в дашборде) **не относится к домену kanban**. Это сквозная функциональность мобильного клиента, администрируемая через контейнеры мобильного приложения.