UI/UX ТЗ: карточка объекта и экран монтажников

Детализация интерфейсов для CRM-модуля alatyr-service. Базовая модель данных: crm-objects-spec.md.

Дата решения: 2026-08-09
Статус: дизайн v1 утверждён для реализации MVP
Стек: React, Wouter, TanStack Query, Radix UI, Tailwind CSS, Lucide

---

Цели интерфейса

Карточка объекта должна за 10–15 секунд отвечать:

1. Что это за объект, кто заказчик и кто ответственный?
2. Где объект находится по срокам и статусу?
3. Что выполнено, что просрочено и что блокирует работу?
4. Кто сейчас работает на объекте?
5. Сколько начислено монтажникам и сколько выплачено?
6. Какие договоры, счета, акты и платежи связаны с объектом?

Экран сотрудников должен за 10–15 секунд отвечать:

1. Кто сегодня на смене и где?
2. У кого незакрытая или спорная смена?
3. Сколько часов и денег начислено за период?
4. Сколько выплачено и какой остаток?
5. На какие объекты назначен конкретный сотрудник?

---

Навигационная архитектура

Новые рабочие сущности не добавляются девятой и десятой вкладками в существующую сетку /admin. Для них создаются отдельные маршруты:

• /admin/requests — список заявок;
• /admin/requests/:id — полная карточка заявки;
• /admin/objects — список объектов;
• /admin/objects/new — создание объекта;
• /admin/objects/:id — карточка объекта;
• /admin/workers — экран сотрудников производственного блока;
• /admin/workers/:id — карточка сотрудника;
• /admin/timesheet — полный табель смен.

В существующем /admin добавляются две заметные ссылки: Объекты и Сотрудники. На первом этапе они могут быть кнопками в заголовке. После появления трёх и более отдельных CRM-разделов следует выделить общий AdminLayout с боковой навигацией.

Карточки заявки, объекта и сотрудника открываются отдельными страницами, а не Dialog/модальными окнами. Модальные окна используются только для коротких атомарных действий: назначить сотрудника, закрыть смену, добавить начисление, зафиксировать выплату или подтвердить опасное действие.

Текущую вкладку /admin с управлением системными ролями следует переименовать из Сотрудники в Доступ, чтобы не смешивать права входа с производственным учётом.

Хлебные крошки

• Админка / Объекты / 2026-015
• Админка / Сотрудники / Иван Петров
• Админка / Заявки / #125

Клик по коду или имени возвращает на соответствующий список. Кнопка браузера «Назад» не должна терять фильтры списка: они хранятся в query string.

---

Карточка объекта

Маршрут и роли

Маршрут: /admin/objects/:id

• admin — полный доступ, включая финансы, ставки и выплаты;
• manager — объект, документы, задачи, бригада и смены; выплаты по настройке прав;
• пользователь с permission crm.assigned_objects.read — только назначенные объекты, задачи, состав бригады и смены без финансов;
• master — в MVP не открывает админскую карточку, работает через Telegram и /master.

Компоновка desktop

Рабочая ширина увеличивается с текущих max-w-6xl до max-w-7xl. Страница состоит из закрепляемой шапки объекта, полосы KPI и вкладок.

┌──────────────────────────────────────────────────────────────────────────────┐
│ Админка / Объекты / 2026-015                          [Действия ▾] [Изменить]│
│ 2026-015 · Склад Иванова в Химках                     [В работе]             │
│ ООО Иванов и Ко · Химки, ул. Заводская, 10 · ИП Головин                     │
│ Ответственный: Роман · Дедлайн: 28.08.2026 · обновлено 12 минут назад         │
├──────────────────────────────────────────────────────────────────────────────┤
│ Договоры       Получено          Остаток           Бригада       Задачи       │
│ 4 800 000 ₽    2 100 000 ₽       2 700 000 ₽       4 человека   3 просрочено │
│                44% [████░░░░░]                                              │
├──────────────────────────────────────────────────────────────────────────────┤
│ Обзор | Работы | Бригада и смены | Финансы | Документы | История             │
├──────────────────────────────────────────────────────────────────────────────┤
│ Основная колонка 2/3                                │ Правая колонка 1/3     │
│                                                     │                        │
│ Ближайшие этапы                                     │ Состояние объекта      │
│ Открытые задачи                                     │ Ответственные          │
│ Последние события                                   │ Быстрые действия       │
└──────────────────────────────────────────────────────────────────────────────┘

Шапка объекта

Шапка остаётся видимой при прокрутке вкладки на desktop. Она содержит:

• неизменяемый objects.code моноширинным небольшим текстом;
• редактируемое objects.name;
• статус с текстом и Badge, не только цветом;
• клиент, адрес и ownCompanyId;
• менеджер, плановый дедлайн, дата последнего изменения;
• предупреждение о паузе или просрочке отдельной строкой;
• основную кнопку Изменить;
• меню Действия.

Меню Действия:

• изменить статус;
• добавить договор;
• выставить счёт по этапу;
• добавить монтажника;
• создать задачу;
• открыть Telegram-чат;
• скопировать ссылку;
• закрыть или отменить объект.

Опасные действия отделяются Separator и требуют подтверждения. Изменение objects.code в UI отсутствует.

Полоса KPI

Пять компактных показателей:

1. сумма активных договоров;
2. получено и процент оплаты;
3. остаток к получению;
4. активная бригада и открытые смены сегодня;
5. открытые и просроченные задачи.

KPI кликабельны и переключают на соответствующую вкладку. Числа используют табличные цифры. Красный цвет применяется только для фактической просрочки или ошибки; обычный остаток не красный.

Вкладка «Обзор»

Главная рабочая сводка. Она не дублирует все таблицы целиком.

Основная колонка:

• Ближайшие этапы — до пяти этапов по плановой дате;
• Требует внимания — просрочки, спорные смены, неподписанные акты, непривязанные документы МД;
• Открытые задачи — до семи задач с исполнителем и сроком;
• Последние события — хронология из audit_log.

Правая колонка:

• статус и причина паузы;
• клиент и основной контакт;
• менеджер и прораб;
• направления работ;
• даты старта, дедлайна и гарантии;
• быстрые действия.

Если проблем нет, блок Требует внимания показывает спокойное пустое состояние «Критичных вопросов нет», а не исчезает.

Вкладка «Работы»

Объединяет этапы и задачи в производственный контекст.

Верхняя часть:

• переключатель Этапы / Задачи;
• фильтры по разделу, исполнителю, статусу;
• кнопки Добавить этап или Новая задача.

Этапы показываются вертикальным списком:

• название, тип и период;
• плановая и фактическая дата;
• сумма и оплачено;
• статус;
• связанный счёт или акт МД;
• меню редактирования.

Задачи показываются таблицей на desktop и карточками на mobile:

• приоритет;
• раздел и место;
• задача;
• исполнитель;
• срок;
• фото до/после;
• статус и проверка прорабом.

Вкладка «Бригада и смены»

Верхний блок Состав бригады:

• сотрудник;
• роль на объекте;
• период назначения;
• ставка по умолчанию;
• статус Telegram;
• активная смена;
• меню назначения.

Кнопка Добавить монтажника открывает Sheet справа:

1. сотрудник;
2. роль;
3. период;
4. тип ставки;
5. значение ставки;
6. примечание;
7. подтверждение.

Ниже Смены по объекту:

• диапазон дат, по умолчанию текущий месяц;
• фильтр по сотруднику и статусу;
• строки: дата, сотрудник, старт, конец, часы, ставка-снимок, начисление, статус;
• итоги: человеко-часы, начислено, подтверждено, выплачено;
• переход в полный табель.

Ставка в прошлой смене отображается как снимок и не редактируется напрямую. Исправление делается корректирующим начислением.

Вкладка «Финансы»

Доступна только ролям с финансовым разрешением.

Верх:

• сумма договоров;
• получено;
• дебиторка;
• начислено бригаде;
• выплачено бригаде;
• фактическая маржа, если включён учёт себестоимости.

Далее три внутренних переключателя:

• Клиентские платежи;
• Начисления бригаде;
• Выплаты бригаде.

Каждая таблица имеет собственную кнопку добавления. Начисления и выплаты не объединяются в одну сущность.

Вкладка «Документы»

Группы:

• договоры и допсоглашения;
• счета из «Моё Дело»;
• акты из «Моё Дело»;
• производственные файлы и фотографии.

Панель действий:

• Обновить из Моё Дело;
• Привязать документ;
• Добавить файл;
• Выставить счёт;
• Сформировать акт.

Для каждой ссылки МД показываются собственное ИП, тип, номер, дата, сумма, статус синхронизации и время последнего обновления. Если документ нельзя однозначно связать, показывается Требует привязки.

Вкладка «История»

Неизменяемый журнал:

• дата и время;
• пользователь или автоматизация;
• действие;
• сущность;
• старое и новое значение для важных полей;
• источник: CRM, Telegram, cron, «Моё Дело».

Фильтры: тип события, автор, период. Журнал только для чтения.

Mobile

На ширине меньше 768px:

• шапка не sticky и складывается в одну колонку;
• KPI становятся горизонтально прокручиваемыми карточками;
• вкладки прокручиваются по горизонтали;
• таблицы смен, задач и документов превращаются в карточки;
• основная кнопка находится внизу экрана как sticky action bar;
• вторичные действия остаются в меню;
• минимальная зона нажатия 44×44 px.

---

Экран сотрудников

Назначение

Экран показывает всех людей, у которых есть employee_profiles, независимо от системной роли входа.

Рабочие должности:

• Монтажник;
• Бригадир;
• Прораб;
• ИТР;
• Сотрудник.

Рабочая должность не определяет доступ. Например, прораб может иметь системную роль master с расширенным permission-набором, а ИТР — manager. Управление системными ролями admin | manager | master | client остаётся в отдельном разделе Доступ.

Маршрут: /admin/workers

Компоновка

┌──────────────────────────────────────────────────────────────────────────────┐
│ Сотрудники                                      [Экспорт] [Добавить сотрудника]│
│ Смены, назначения, начисления и выплаты                                    │
├──────────────────────────────────────────────────────────────────────────────┤
│ Сегодня на смене  3 │ Требуют проверки  2 │ Начислено август  184 500 ₽     │
│ К выплате  72 000 ₽ │ Без Telegram  1                                      │
├──────────────────────────────────────────────────────────────────────────────┤
│ Сотрудники | Табель | Начисления | Выплаты                                  │
├──────────────────────────────────────────────────────────────────────────────┤
│ Поиск...  Статус ▾  Объект ▾  Telegram ▾  Период ▾          [Сбросить]      │
├──────────────────────────────────────────────────────────────────────────────┤
│ Сотрудник │ Сегодня │ Объекты │ Часы │ Начислено │ Выплачено │ Остаток │ ...│
│ Иван      │ 09:12–  │ 2       │ 126  │ 94 500    │ 70 000    │ 24 500  │ ...│
└──────────────────────────────────────────────────────────────────────────────┘

KPI

• Сегодня на смене — число активных смен;
• Требуют проверки — auto_closed, disputed и черновые начисления;
• Начислено за период;
• К выплате;
• Без Telegram — сотрудники без привязки.

Клик применяет соответствующий фильтр.

Вкладка «Сотрудники»

Основная таблица:

• имя, телефон, Telegram;
• должность: монтажник, бригадир, прораб, ИТР или сотрудник;
• текущая смена и объект;
• активные назначения;
• часы за выбранный период;
• начислено;
• выплачено;
• остаток;
• статус сотрудника;
• меню действий.

Фильтры: поиск по имени, должность, активность, объект, Telegram, период. Сортировка по имени, часам, начислению и остатку. По умолчанию сначала показываются активные смены, затем сотрудники с проблемами, затем остальные.

Меню строки:

• открыть карточку;
• назначить на объект;
• пригласить в Telegram;
• изменить резервную ставку;
• добавить начисление;
• зафиксировать выплату;
• деактивировать.

Вкладка «Табель»

Полный журнал worker_shifts:

• дата;
• сотрудник;
• объект;
• начало и конец;
• перерыв;
• часы;
• тип и значение ставки-снимка;
• сумма;
• статус;
• фото начала и конца;
• действия проверки.

Группировка: по дням или сотрудникам. Итоговая строка пересчитывается по текущим фильтрам.

Действия:

• закрыть забытую смену;
• оспорить;
• подтвердить;
• создать корректировку;
• открыть фото.

Вкладка «Начисления»

Таблица worker_accruals:

• дата;
• сотрудник;
• объект;
• вид;
• основание;
• сумма;
• статус;
• кто подтвердил.

Массовое действие P0: выбрать несколько черновиков и подтвердить. Отмена подтверждённого начисления создаёт обратную корректировку, а не удаляет запись.

Вкладка «Выплаты»

Таблица worker_payments:

• дата;
• сотрудник;
• объект или «несколько объектов»;
• вид выплаты;
• способ;
• период;
• сумма;
• комментарий;
• автор.

Кнопка Зафиксировать выплату открывает Dialog. Перед сохранением показываются начислено, уже выплачено и остаток. Переплата разрешается только admin после дополнительного подтверждения.

---

Карточка сотрудника

Маршрут: /admin/workers/:id

Шапка:

• имя и статус;
• должность и системная роль доступа отдельными Badge;
• телефон и Telegram;
• резервная ставка;
• активная смена;
• кнопки Назначить на объект, Начислить, Выплатить.

KPI за выбранный период:

• часы;
• смены;
• начислено;
• выплачено;
• остаток.

Вкладки:

• Обзор — активные назначения, должность и предупреждения;
• Объекты и условия — история назначений и версия условий оплаты на каждом объекте;
• Смены;
• Разовые работы;
• Начисления;
• Выплаты;
• История.

Финансовые вкладки скрываются для ролей без разрешения, а не только блокируются на клиенте: API также проверяет право.

Вкладка Объекты и условия показывает по каждому назначению:

• объект, роль и период;
• схема оплаты: почасовая, сменная, сдельная, за завершение или смешанная;
• ставку, фиксированную сумму и условия премии;
• согласованные разовые работы вне основной компетенции;
• кто и когда изменил условия;
• ссылку на версию условий, по которой рассчитаны прошлые смены.

Вкладка Разовые работы показывает цепочку: Предложено → Принято → Выполняется → Сдано → Принято → Начислено. Сумма видна до принятия задания и после принятия не меняется без новой версии договорённости.

Вкладка Смены дополнительно показывает источник отметки: Telegram, MAX, web или менеджер, а также фото/сообщения, которые подтверждают присутствие. Спорные и незакрытые смены выделяются статусом, а не только цветом.

Персональная расшифровка

Вкладка Обзор содержит таблицу По объектам:

Объект	Роль на объекте	Смены	Часы	Начислено	Выплачено	Остаток
2026-015 · Склад Иванова	Бригадир	14	126,0	94 500 ₽	70 000 ₽	24 500 ₽

Клик по строке применяет objectId ко вкладкам Смены, Начисления и Выплаты.

Вкладка Смены показывает, где и сколько человек отработал:

• объект и роль на нём;
• дата;
• начало, конец и перерыв;
• итоговые часы;
• ставка-снимок;
• рассчитанная сумма;
• статус и подтверждение.

Вкладка Начисления показывает, сколько человек заработал:

• начисления за смены;
• сдельные работы;
• премии;
• штрафы;
• корректировки;
• итог подтверждённых начислений.

Вкладка Выплаты показывает, сколько и как выплачено:

• дата выплаты;
• сумма;
• способ: банк, наличные или перевод на карту;
• объект или несколько объектов;
• расчётный период;
• назначение: зарплата, аванс, премия, компенсация;
• комментарий и автор записи.

В шапке расчёта всегда видна формула: Начислено − Выплачено = Остаток. Неподтверждённые начисления показываются рядом отдельной суммой и не входят в остаток.

---

Формы и диалоги

Добавление монтажника на объект

Обязательные поля:

• сотрудник;
• роль;
• дата начала;
• схема оплаты;
• почасовая/сменная ставка или фиксированная сумма;
• условие начисления за завершение;
• премия: нет, фиксированная, процентная или ручная;
• текст согласованных условий.

Проверки:

• нельзя создать дублирующее активное назначение того же сотрудника на тот же объект;
• значение ставки больше нуля;
• дата окончания не раньше даты начала;
• процентная ставка хранится отдельно от денежной;
• изменение ставки действующего назначения показывает предупреждение: прошлые смены не изменятся.

Закрытие смены вручную

Поля:

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

После сохранения создаются закрытая смена и черновик начисления. Причина обязательна для auto_closed и при изменении времени более чем на 30 минут.

Начисление

Поля:

• сотрудник;
• объект;
• тип;
• сумма;
• основание;
• связанная смена или задача;
• статус Сохранить черновик / Подтвердить.

Для Штраф/удержание дополнительно обязательны причина, подтверждающий и ссылка на нарушение/событие. UI не предлагает автоматический штраф за незакрытую смену; сначала создаётся задача проверки табеля.

Карточка заявки как отдельная страница

Маршрут: /admin/requests/:id.

Страница сохраняет уже реализованные данные: клиент, источник, описание, компания, будущий объект, типы объекта, договор, счета, оплату и историю. Дополнительно:

• URL можно отправить менеджеру и восстановить после перезагрузки;
• браузерная кнопка «Назад» возвращает к прежним фильтрам списка;
• документы и история не ограничены высотой модального окна;
• кнопки Сохранить, Выставить счёт, В объект находятся в явной панели действий;
• при автоматическом переходе после оплаты страница перенаправляет на созданный /admin/objects/:id и показывает ссылку на исходную заявку.

Выплата

Поля:

• сотрудник;
• объект или несколько объектов;
• тип выплаты;
• сумма;
• способ;
• дата;
• расчётный период;
• комментарий.

После сохранения показывается новый остаток. Выплату нельзя редактировать после закрытия расчётного периода; исправление выполняется корректирующей записью.

---

Состояния интерфейса

Каждая страница и вкладка обязана иметь:

• skeleton при первой загрузке;
• локальный spinner только на изменяемой кнопке при мутации;
• пустое состояние с объяснением и основным действием;
• ошибку загрузки с кнопкой Повторить;
• toast после успешной операции;
• предупреждение о несохранённых изменениях;
• явное состояние отсутствия прав;
• дату последней синхронизации для данных «Моё Дело».

Optimistic update разрешён для заметок и простых статусов. Для денег, ставок, смен, начислений и выплат UI ждёт подтверждённый ответ сервера.

---

Визуальные правила

Используется существующая тема alatyr-service:

• основной акцент --primary — терракотовый;
• нейтральные фон, карточки и границы;
• текущие Button, Badge, Card, Tabs, Table, Sheet, Dialog;
• Lucide-иконки только вместе с подписью для основных действий;
• финансовые числа с font-variant-numeric: tabular-nums;
• Badge всегда содержит текст статуса;
• не более одной основной filled-кнопки в видимой области;
• без декоративных иллюстраций и лишних теней.

Семантика:

• destructive — ошибка, отмена, просрочка;
• предупреждение — пауза, спорная смена, документ без связи;
• success — подтверждённое завершение или оплата;
• обычные рабочие статусы остаются нейтральными.

---

Компонентная декомпозиция

pages/
  admin/
    RequestsPage.tsx
    RequestDetailPage.tsx
    ObjectsPage.tsx
    ObjectCreatePage.tsx
    ObjectDetailPage.tsx
    WorkersPage.tsx
    WorkerDetailPage.tsx
    TimesheetPage.tsx

components/crm/
  AdminCrmNav.tsx
  ObjectHeader.tsx
  ObjectKpiStrip.tsx
  ObjectOverviewTab.tsx
  ObjectWorksTab.tsx
  ObjectCrewTab.tsx
  ObjectFinanceTab.tsx
  ObjectDocumentsTab.tsx
  AuditHistoryTab.tsx
  AssignmentSheet.tsx
  ShiftReviewDialog.tsx
  AccrualDialog.tsx
  WorkerPaymentDialog.tsx
  WorkerSummaryTable.tsx
  TimesheetTable.tsx

Не добавлять новые CRM-компоненты внутрь уже крупного client/src/pages/Admin.tsx. Общие типы запросов и ответов вынести в shared/ или client/src/types/crm.ts.

---

Требования к API-ответам

Карточка объекта не должна выполнять десятки последовательных запросов. P0:

• GET /api/objects/:id/summary — шапка, KPI, предупреждения и права;
• отдельные paginated endpoints для вкладок;
• каждый финансовый ответ содержит суммы в копейках;
• сервер возвращает вычисленные права permissions, чтобы UI скрывал недоступные действия;
• мутации возвращают обновлённую сущность и updatedAt;
• ошибки используют единый формат { code, message, fieldErrors? }.

Для списка монтажников:

• один агрегирующий endpoint для строк и KPI;
• фильтры и сортировка выполняются на сервере;
• pagination cursor или page/limit;
• query string является источником состояния фильтров.

---

Приоритет реализации

P0

1. Маршруты и общий CRM-nav; заявки, объекты и сотрудники открываются страницами.
2. Карточка объекта: шапка, KPI, Обзор.
3. Версионируемые условия назначения: почасовая, сменная, сдельная, фиксированная за завершение и смешанная оплата.
4. Вкладка Бригада и смены.
5. Экран сотрудников: список, должности и KPI.
6. Табель, события Telegram/web, ручное закрытие спорной смены; MAX через адаптер после проверки его API.
7. Разовые согласованные работы, включая задачи вне основной компетенции.
8. Начисления, премии, отрицательные корректировки и выплаты с раздельными формами.
9. Права admin/manager и отдельные permissions для прораба или ИТР.
10. Mobile-режим для основных операций.

P1

• массовое подтверждение начислений;
• сохранённые наборы фильтров;
• экспорт табеля;
• глубокая интеграция документов «Моё Дело»;
• сдельные и процентные автоматические расчёты;
• расширенная история изменений.

Не входит в MVP

• календарь с drag-and-drop;
• карта и геолокация;
• биометрия;
• автоматическое распознавание фото;
• полноценная бухгалтерская зарплата и налоги;
• удаление подтверждённых финансовых записей.

---

Критерии приёмки

• Given менеджер открывает объект, when загружается карточка, then без переходов видны статус, клиент, дедлайн, финансовая сводка, бригада и проблемы.
• Given у объекта несколько договоров, when открывается карточка, then объект показывается под одним неизменяемым кодом.
• Given сотрудник создан, when администратор выбирает должность, then доступны варианты Монтажник, Бригадир, Прораб, ИТР и Сотрудник независимо от системной роли.
• Given сотрудник назначается на объект, when менеджер сохраняет назначение, then сотрудник появляется в бригаде с ролью, периодом и ставкой.
• Given сотрудник на разных объектах имеет разные условия, when открывается его отдельная страница, then по каждому объекту видны своя схема, ставка, премия, разовые работы и история изменений.
• Given сотрудник отмечается или отправляет фото в привязанный Telegram/MAX канал, when событие обработано, then оно связано с объектом и показано в табеле с источником и статусом проверки.
• Given карточка заявки, объекта или сотрудника открыта, when пользователь копирует URL или обновляет страницу, then открывается та же сущность, а не общий список или потерянное модальное окно.
• Given открыта карточка сотрудника за период, when загружается расчёт, then видны все объекты, смены, часы, начисления, выплаты по способам и остаток.
• Given смена закрывается, when сервер подтверждает расчёт, then в табеле видны часы, ставка-снимок, сумма и черновик начисления.
• Given ставка назначения меняется, when открывается старая смена, then её сумма остаётся прежней.
• Given фиксируется выплата, when операция завершена, then обновляются выплачено и остаток, но начисления не изменяются.
• Given пользователь без финансового права открывает объект, when строится UI, then финансовые вкладки и суммы не возвращаются API и не отображаются.
• Given экран открыт на телефоне, when пользователь выполняет основное действие, then оно доступно без горизонтальной прокрутки всей страницы.