# ТЗ: Модуль Графики

Связанные документы:

- [План реорганизации](plan.md)
- [Карта нового меню](menu.md)
- [ТЗ: График заказов от 20.08.2026](tz-order-schedule.md)
- [Ответы заказчика от 27.08.2026](tz-order-schedule-answers.md)
- [ТЗ: Каталог общий](tz-catalog-common.md)
- [ТЗ: Модуль ДКР](tz-dkr.md)

## 1. Назначение

Модуль `Графики` объединяет календарные и производственные представления Manager 2.0:

- график заказов на производстве;
- график доставок;
- график монтажей.

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

## 2. Статус

Статус модуля: **частично реализован; ТЗ и ответы заказчика проанализированы, ручное ядро готово к проектированию и реализации, обмен с 1С ожидает отдельного согласования со специалистом 1С**.

В текущей CRM реализован:

- `График монтажей`;
- маршрут: `schedule.index`;
- контроллер: `ScheduleController`;
- модель: `Schedule`;
- создание записей из площадок/заказов;
- создание записей из рекламаций;
- экспорт графика;
- недельное/месячное представление, если доступно в текущей реализации.

Нужно реализовать:

- `График заказов`;
- `График доставок`;
- связи между графиками.

После анализа `manager.stroyprofit.com` установлено:

- текущий `График отгрузок` хранится в одной таблице `graf1` и совмещает данные заказа, статусы, доставку, монтаж и ручные комментарии;
- данные поступают из 1С HTTP-запросом с JSON в поле `data`;
- payload содержит заказ, клиента, договор, оплату, доставку, менеджера и список позиций;
- позиции сейчас не нормализуются, а сохраняются только в сформированный Excel-файл;
- поддерживаются до трёх доставок через фиксированные колонки;
- новое ТЗ от 20.08.2026 существенно расширяет сценарии: ручное создание, отдельные экземпляры МАФ, файлы и чат, документы, уведомления, аудит, импорт/экспорт и рекламации типа `Прочее`.

## 3. Место в меню

Целевое меню:

```text
Графики
├── График заказов
├── График доставок
└── График монтажей
```

Требования:

- добавить верхний пункт меню `Графики`;
- перенести текущий пункт `График монтажей` внутрь `Графики`;
- текущий маршрут `schedule.index` оставить без переименования;
- для `График заказов` и `График доставок` на первом этапе добавить страницы-заглушки `В разработке`;
- выбранный год в CRM не влияет на новые модули `График заказов` и `График доставок`;
- реорганизация меню выполняется сразу общей для всей платформы Manager 2.0.

## 4. Права доступа

На первом этапе оставляем текущие права.

| Раздел | Permission |
|---|---|
| График монтажей | `schedule.view` |
| График заказов | Заглушка доступна всем авторизованным пользователям |
| График доставок | Заглушка доступна всем авторизованным пользователям |

Требования:

- не переименовывать текущие права;
- не вводить новую систему прав на первом этапе;
- верхний пункт `Графики` показывать, если пользователю доступен хотя бы один дочерний пункт.

## 5. График заказов

Статус: **ТЗ и ответы заказчика получены; ручное ядро, доставки, монтажи, уведомления, аудит и документы готовы к реализации независимо от будущего обмена с 1С**.

Полный состав требований и анализ: [ТЗ: График заказов от 20.08.2026](tz-order-schedule.md), [ответы заказчика от 27.08.2026](tz-order-schedule-answers.md).

Назначение:

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

Требования по ТЗ Manager 2.0:

- таблица с графиком заказов на производстве;
- перенос функционала `график отгрузок` из старого manager с адаптацией под текущие реалии;
- загрузка данных через 1С;
- связь с `Каталог общий`;
- связь с `График монтажей`.

Архитектурные требования с учётом нового ТЗ:

- не переносить таблицу `graf1` как есть;
- хранить заказ, позиции заказа, доставки и загрузки 1С отдельными нормализованными сущностями;
- не использовать сериализованные данные для монтажей, позиций и доставок;
- не ограничивать заказ фиксированным количеством доставок;
- отделить поля, которыми управляет 1С, от полей ручного планирования;
- повторная загрузка должна быть идемпотентной и не должна сбрасывать ручные статусы и комментарии;
- сохранять журнал загрузок, ошибки сопоставления и исходный payload для диагностики;
- предусмотреть миграцию исторических данных старого Manager с отчётом о дублях и конфликтах;
- сохранять возможность расширения модели без денормализации после получения дополнительных требований заказчика.

Предварительный функционал:

- список заказов/позиций в производственном графике;
- дата/период производства;
- адрес/объект, если приходит из источника данных;
- позиции заказа из общего каталога;
- статусы или этапы производства, если они есть в источнике;
- фильтры по дате, заказу, позиции, статусу;
- импорт/обновление данных из 1С;
- история последней загрузки;
- обработка ошибок загрузки;
- переход в карточку заказа;
- выбор одного или нескольких МАФ заказа;
- действие `Добавить рекламацию` для выбранных МАФ;
- открытие существующей формы создания рекламации с передачей заказа и выбранных МАФ.

Требования к созданию рекламации:

- рекламация создается из карточки заказа, а не напрямую из строки списка;
- пользователь должен выбрать минимум один МАФ;
- допускается выбор нескольких МАФ;
- после нажатия `Добавить рекламацию` открывается текущая форма создания рекламации;
- рекламации назначается тип `other` (`Прочее`) из справочника типов;
- рекламация отображается в общей вкладке рекламаций и не отображается во вкладке `ДКР`;
- для такой рекламации не формируется документация для оплаты.

Открытые вопросы:

- может ли 1С передавать стабильный GUID заказа вместо ключа, собранного из номера и года;
- может ли 1С передавать артикул общего каталога и идентификатор каждого экземпляра МАФ;
- какие поля принадлежат 1С, а какие должны сохраняться при повторной синхронизации;
- как 1С сообщает аннулирование и частичное изменение состава заказа;
- может ли ручной XLS-импорт создавать новые заказы и как передавать в нём отдельные экземпляры МАФ.

## 6. График доставок

Статус: **нужно реализовать**.

Назначение:

- показывать недельный список доставок;
- позволять вручную планировать занятость водителей;
- брать адреса автоматически из `График заказов`.

Требования по ТЗ Manager 2.0:

- отображение в виде недельного списка;
- адреса добавляются автоматически из `График заказов`;
- вручную указывается занятость водителей: какой заказ и когда везут;
- добавление через модальное окно;
- возможная связь с вкладкой `Отгрузки` требует уточнения.

Предварительный функционал:

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

Открытые вопросы:

- какие статусы есть у доставки;
- нужна ли связь с отдельным разделом `Отгрузки`;
- нужен ли отдельный экспорт недельного списка помимо полученного шаблона заявки на одну доставку.

Согласовано:

- водитель выбирается среди пользователей роли `Водитель` и, согласно исходному ТЗ, `Бригадир`;
- один заказ может иметь несколько отдельных записей доставки;
- получен шаблон печатной заявки на конкретную доставку `templates/DeliveryRequest.xls`.

## 7. График монтажей

Статус: **есть, переносится в новую группу меню**.

Текущая основа:

- маршрут: `schedule.index`;
- контроллер: `ScheduleController`;
- создание записи из заказа/площадки;
- создание записи из рекламации;
- обновление записи;
- удаление записи;
- экспорт;
- недельное/месячное представление.

Требования:

- сохранить текущую бизнес-логику;
- сохранить текущий маршрут `schedule.index`;
- перенести пункт меню внутрь `Графики`;
- сохранить текущие права `schedule.view` и связанные права обновления/экспорта;
- сохранить связь с площадками ДКР;
- сохранить связь с рекламациями;
- добавить/подготовить связь с `График заказов`, когда он будет реализован.

Что не менять на первом этапе:

- структуру таблиц графика монтажей;
- существующие маршруты `schedule.*`;
- текущие правила создания записей из заказов и рекламаций;
- текущий UI графика, кроме положения в меню.

## 8. Связи между графиками

Целевая логика связей:

| Источник | Получатель | Связь |
|---|---|---|
| Каталог общий | График заказов | Позиции заказа и справочные данные по номенклатуре. |
| График заказов | График доставок | Адреса и заказы для планирования доставки. |
| График заказов | График монтажей | Связь производственного графика с монтажом. |
| График заказов | Рекламации | Создание рекламации из заказа по выбранным МАФ через текущую форму. |
| ДКР / Площадки | График монтажей | Площадки для монтажных работ. |
| Рекламации | График монтажей | Работы по рекламациям. |

Требования:

- связи не должны ломать автономность ДКР;
- текущий график монтажей должен работать до реализации графика заказов;
- новые графики должны опираться на `Каталог общий`, а не на каталог внутри ДКР;
- рекламация из графика заказов должна получать тип `other` (`Прочее`) из справочника типов.

## 9. Данные и модели

Для `График монтажей` использовать текущие модели и таблицы.

Для `График заказов` и `График доставок` проектируются отдельные модели. Полученные ответы позволяют начинать проектирование ручного контура; модели интеграционных загрузок уточняются после согласования контракта с 1С. Независимо от точных имён таблиц модель должна быть нормализована.

Минимально потребуются сущности:

- производственный заказ;
- отдельный экземпляр МАФ производственного заказа со ссылкой на `Каталог общий`, когда сопоставление возможно;
- произвольное количество доставок по заказу;
- произвольное количество монтажных этапов по заказу;
- водитель или ответственный доставки;
- журнал загрузок из 1С;
- журнал ошибок и результатов сопоставления;
- журнал значимых изменений заказа;
- безопасно сохранённый исходный payload или ссылка на него для диагностики.

Запрещённые варианты модели:

- одна таблица, совмещающая заказ, позиции, доставки и монтаж;
- колонки вида `delivery_1`, `delivery_2`, `delivery_3`;
- сериализованные массивы в текстовых колонках как основная модель данных;
- перезапись ручных плановых данных значениями по умолчанию при импорте из 1С.

Открыто:

- точные имена таблиц и моделей;
- стабильные идентификаторы заказа и экземпляров МАФ в 1С;
- принадлежность синхронизируемых и локально редактируемых полей;
- источник и обновление производственного календаря;
- формат импорта отдельных экземпляров МАФ и обработка отсутствующего/неизвестного ID;
- способ связи с существующими `Order`, `ProductSKU`, `Schedule` и `Reclamation` без смешивания с ДКР;
- правила миграции дублей и некорректных дат старого `graf1`.

## 10. Первый этап реализации

В первый этап модуля `Графики` входит:

- общая реорганизация меню;
- перенос `График монтажей` внутрь группы `Графики`;
- сохранение текущего маршрута `schedule.index`;
- добавление заглушки `График заказов`;
- добавление заглушки `График доставок`;
- сохранение текущих прав;
- проверка доступности текущего графика монтажей.

В первый этап не входит:

- разработка обмена с 1С;
- проектирование БД графика заказов;
- проектирование БД графика доставок;
- реализация недельного календаря доставок;
- изменение текущей логики графика монтажей.

## 11. Этапы реализации

- [x] Проверить текущие маршруты `schedule.*`.
- [x] Проверить текущие permissions графика монтажей.
- [x] Добавить верхнюю группу меню `Графики`.
- [x] Перенести текущий пункт `График монтажей` внутрь `Графики`.
- [x] Оставить маршрут `schedule.index` без переименования.
- [x] Добавить страницу-заглушку `График заказов`.
- [x] Добавить страницу-заглушку `График доставок`.
- [x] Проверить активное состояние меню для `Графики`.
- [x] Проверить, что текущий график монтажей открывается и работает.
- [x] Проверить создание записи графика из площадки/заказа.
- [x] Проверить создание записи графика из рекламации.
- [x] Проверить экспорт графика монтажей.
- [x] Изучить старый график заказов/отгрузок и существующий обмен с 1С.
- [x] Зафиксировать нормализованную модель как обязательный архитектурный принцип.
- [x] Получить отдельное ТЗ на график заказов.
- [x] Конвертировать ТЗ от 20.08.2026 в Markdown, сохранить референс интерфейса и сопоставить требования с планом и кодовой базой.
- [x] Получить и проанализировать ответы заказчика от 27.08.2026.
- [x] Согласовать календарь, даты отгрузки, несколько доставок/монтажей, роль водителя, права, уведомления и аудит.
- [x] Получить и разобрать шаблон заявки на доставку `templates/DeliveryRequest.xls`.
- [ ] Согласовать со специалистом 1С контракт API, идентификаторы и правила повторной синхронизации.
- [ ] Уточнить создание новых заказов и передачу экземпляров МАФ через ручной XLS-импорт.
- [x] Составить базовый список полей для графика доставок.
- [ ] Реализовать карточку заказа с выбором одного или нескольких МАФ.
- [ ] Добавить действие `Добавить рекламацию`.
- [ ] Открывать текущую форму рекламации с переданными заказом и выбранными МАФ.
- [ ] Назначать созданной рекламации тип `other` (`Прочее`).

## 12. Критерии приемки

- В верхнем меню есть группа `Графики`.
- Внутри группы есть пункты `График заказов`, `График доставок`, `График монтажей`.
- `График монтажей` открывается по текущему маршруту `schedule.index`.
- Текущая логика графика монтажей не изменилась.
- Заглушки `График заказов` и `График доставок` открываются без 404/403 у авторизованных пользователей.
- Пользователи с текущим доступом к графику монтажей сохраняют доступ.
- График монтажей продолжает работать с площадками ДКР.
- График монтажей продолжает работать с рекламациями.
- Из карточки заказа можно выбрать один или несколько МАФ и открыть форму создания рекламации.
- Созданная рекламация связана с заказом и выбранными МАФ.
- Созданная рекламация имеет тип `other` (`Прочее`), не попадает во вкладку `ДКР` и не позволяет формировать документацию для оплаты.

## 13. Открытые вопросы

Актуальный перечень сформирован в [ответах заказчика](tz-order-schedule-answers.md#4-что-осталось-уточнить). Вопросы по 1С блокируют только интеграцию с 1С. Для ручного импорта отдельно нужно уточнить создание новых заказов, обработку неизвестного ID и передачу экземпляров МАФ.