# План реорганизации Manager 2.0

Рабочая папка рефакторинга: `docs/refactor/`.

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

- [Исходное ТЗ](source-tz.md)
- [Карта нового меню](menu.md)
- [ТЗ: ДКР](tz-dkr.md)
- [ТЗ: Каталог общий](tz-catalog-common.md)
- [ТЗ: Графики](tz-schedules.md)
- [ТЗ: Рекламации](tz-reclamations.md)
- [ТЗ: Запчасти](tz-spare-parts.md)
- [ТЗ: Склад](tz-stock-availability.md)
- [ТЗ: Документация](tz-documents.md)
- [ТЗ: Технич. описание](tz-technical-description.md)
- [ТЗ: Калькуляции](tz-calculations.md)
- [ТЗ: Администратор](tz-admin.md)

## Цель

Перевести текущую CRM в структуру Manager 2.0: реорганизовать верхнее меню, сохранить самостоятельный модуль ДКР с его собственным каталогом, добавить отдельный `Каталог общий`, добавить заглушки для новых модулей и подготовить отдельные ТЗ по каждому разделу перед глубокой разработкой.

## Принятые решения

- [x] ДКР остается самостоятельным модулем.
- [x] Каталог ДКР и `Каталог общий` — разные сущности.
- [x] Каталог ДКР остается внутри меню ДКР.
- [x] `Каталог общий` реализуется отдельно как общий справочник платформы.
- [x] `Запчасти` — общий модуль для всей платформы, включая ДКР.
- [x] `Склад` должен быть реализован полностью по образцу раздела `Запчасти`, с адаптацией под МАФ/позиции из `Каталог общий`.
- [x] Новые модули на первом этапе получают страницы-заглушки `В разработке`.
- [x] Основная карта меню хранится в [docs/refactor/menu.md](menu.md).
- [x] Текущие рабочие маршруты оставляем без переименования.
- [x] На первом этапе оставляем текущие права доступа.
- [x] Реорганизацию меню делаем сразу общей для всей платформы Manager 2.0.
- [x] Заглушки новых модулей показываем всем авторизованным пользователям.
- [x] На новые модули выбранный год не влияет.
- [x] `Технич. описание` встроено в модуль `Каталог общий`; готовый Laravel-модуль используем как источник экспорта.
- [x] Модуль техописаний `to.stroyprofit.com` изучен: его данные и DOCX-экспорты переносятся в `Каталог общий` без отдельного раздела.
- [x] Цены принадлежат `Каталог общий` и хранятся непосредственно у позиции; актуальный формат и реальные значения определены файлом `docs/refactor/Каталог общий.xlsx`.
- [x] В общем каталоге используются восемь видов цен: `строители`, `опт`, `рек`, `розница`, `проект`, `проект+м`, `пик`, `рек+10`.
- [x] По умолчанию цены и экспорт общего каталога доступны только администратору; просмотр и редактирование цен управляются существующими permissions отдельных полей.
- [x] Исходный калькулятор `calc.stroyprofit.com` используется как источник модели данных, формул и экспортов, но его код и текущие формулы не переносятся без проверки.
- [x] Финальный состав и способ реализации `Калькуляций` определяются отдельным ТЗ; допустимы внутренняя реализация в Laravel и интеграционный вариант.
- [x] Старый `График отгрузок` и действующий обработчик 1С в `manager.stroyprofit.com` изучены как исходная система для `Графика заказов`.
- [x] `График заказов` проектируется максимально нормализованно: заказ, позиции, доставки и загрузки 1С хранятся отдельными сущностями, без сериализованных полей и фиксированных колонок для нескольких доставок.
- [x] Финальные поля, статусы, права и пользовательские сценарии `Графика заказов` определяются отдельным ТЗ заказчика.
- [x] `Рекламации -> ДКР` реализуется как отдельная вкладка на основе текущего списка с обязательным фильтром по типу `dkr`.
- [x] Тип рекламации хранится через обязательную связь со справочником `reclamation_types`; начальные типы `ДКР` и `Прочее` создаются сидером.
- [x] В интерфейсе рекламаций обязательны отдельные вкладки `Все` и `ДКР`.
- [x] Из графика заказов рекламация создается по выбранным МАФ через текущую форму и получает тип `other` (`Прочее`).
- [x] Документация для оплаты доступна только для рекламаций типа `ДКР`.
- [x] Маршруты `Каталог общий` используют префикс `common-catalog/...`.
- [x] Таблицы и права `Каталог общий` используют техническое имя `common-catalog`.
- [x] Техническое имя модуля `Склад`: `stock`.
- [x] Роль `помощник руководителя`: `assistant_head`.

## Этап 0. Документация

- [x] Изучить ТЗ Manager 2.0 и схему зависимостей.
- [x] Составить карту нового меню.
- [x] Перенести карту меню в `docs/refactor/menu.md`.
- [x] Создать общий план реализации в `docs/refactor/plan.md`.
- [x] Написать отдельное ТЗ для модуля `ДКР`: [tz-dkr.md](tz-dkr.md).
- [x] Написать отдельное ТЗ для модуля `Каталог общий`: [tz-catalog-common.md](tz-catalog-common.md).
- [x] Написать отдельное ТЗ для модуля `Графики`: [tz-schedules.md](tz-schedules.md).
- [x] Написать отдельное ТЗ для модуля `Рекламации`: [tz-reclamations.md](tz-reclamations.md).
- [x] Написать отдельное ТЗ для модуля `Запчасти`: [tz-spare-parts.md](tz-spare-parts.md).
- [x] Написать отдельное ТЗ для модуля `Склад`: [tz-stock-availability.md](tz-stock-availability.md).
- [x] Написать отдельное ТЗ для модуля `Документация`: [tz-documents.md](tz-documents.md).
- [x] Написать отдельное ТЗ для модуля `Технич. описание`: [tz-technical-description.md](tz-technical-description.md).
- [x] Написать отдельное ТЗ для модуля `Калькуляции`: [tz-calculations.md](tz-calculations.md).
- [x] Написать отдельное ТЗ для модуля `Администратор`: [tz-admin.md](tz-admin.md).

## Статус готовности этапов

| Этап | Статус | Почему |
|---|---|---|
| 1. Реорганизация меню и заглушки | Реализован и проверен | Новое меню и заглушки приняты по результатам пользовательской проверки. |
| 2. Адаптация существующих разделов после переноса | Реализован и проверен | Рабочие разделы и их отображение приняты по результатам пользовательской проверки. |
| 3. Рекламации: вкладки и тип | Реализован, ожидает пользовательской проверки | Добавлены вкладки, справочник типов, перенос существующих данных и запрет платежных документов для `Прочее`; создание из графика остается в этапе 10. |
| 4. Общий каталог | Расширение реализовано, ожидает пользовательской проверки | Импорт, экспорт и карточка переведены на фактический 30-колоночный формат `Каталог общий.xlsx`; добавлены восемь цен и ограничения доступа. |
| 5. Документация | Реализован и проверен | Пользователь проверил дерево папок, работу с документами и версиями; права и приватное хранение дополнительно покрыты автоматическими тестами. |
| 6. Склад: ядро | Реализован и проверен | Ядро склада принято после пользовательской проверки. Цены относятся к общему каталогу; для склада остаётся отдельной задачей только PDF-экспорт после согласования шаблона. |
| 7. Техническое описание | Анализ завершён, готово к реализации | Изучены данные, импорт, изображения, DOCX-шаблоны и массовый/раздельный экспорт `to.stroyprofit.com`; требуется перенос в общий каталог. |
| 8. Калькуляции | Исходник изучен, ожидается отдельное ТЗ | Восстановлены сущности, формулы и экспорты `calc.stroyprofit.com`; финальная архитектура, формулы и сценарии не фиксируются до ТЗ. Рабочая база источника сейчас не содержит расчётных данных. |
| 9. Графики заказов и доставок | Исходная система изучена, ожидается отдельное ТЗ | Найдены старый график и фактический формат обмена с 1С. Нормализация принята как архитектурный принцип, но финальные поля, статусы и правила уточнит заказчик. |
| 10. Рекламации из графика заказов | Готово только после графика заказов | Сценарий согласован, но точка входа зависит от карточки заказа в графике. |

## Этап 1. Реорганизация меню и заглушки

Статус: **ядро проверено пользователем; расширение под актуальный каталог реализовано и ожидает пользовательской проверки**.

- [x] Проверить текущие permissions для всех существующих пунктов меню.
- [x] Для новых пунктов-заглушек открыть доступ всем авторизованным пользователям.
- [x] Добавить общий механизм страницы `В разработке`.
- [x] Добавить маршруты для новых разделов-заглушек.
- [x] Перестроить `resources/views/layouts/menu.blade.php` под новую древовидную структуру.
- [x] Сгруппировать существующие пункты ДКР внутрь верхнего меню `ДКР`.
- [x] Оставить `Каталог` внутри меню `ДКР`.
- [x] Добавить отдельный верхний пункт `Каталог общий`.
- [x] Сгруппировать `График монтажей` внутрь верхнего меню `Графики`.
- [x] Добавить заглушки `График заказов` и `График доставок`.
- [x] Разложить `Рекламации` на `Все` и `ДКР`.
- [x] Оставить `Запчасти` отдельной верхней группой с текущими вкладками.
- [x] Добавить заглушки `Склад -> Наличие` и `Склад -> Заказы`.
- [x] Добавить заглушки `Документация`, `Каталог общий`, `Калькуляции`.
- [x] Проверить, что выбранный год не скрывает и не фильтрует новые модули.
- [x] Переименовать группу `Администрирование` в `Администратор`.
- [x] Проверить отображение меню для основных ролей.

## Этап 2. Адаптация существующих разделов после переноса

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

Задача этапа — проверить существующие рабочие разделы после изменения меню и внести точечные правки без изменения бизнес-логики.

- [x] Проверить, что разделы ДКР открываются из группы `ДКР`.
- [x] Проверить, что каталог ДКР остался внутри группы `ДКР`.
- [x] Проверить, что текущий `График монтажей` открывается из группы `Графики`.
- [x] Проверить, что раздел `Запчасти` работает в новой структуре меню без изменения бизнес-логики.
- [x] Проверить вкладки `Каталог`, `Заказы запчастей`, `Контроль наличия`, `Справочник расшифровок`, `Справка`.
- [x] Проверить, что `Запчасти` используются как общий модуль, включая ДКР.
- [x] Проверить, что меню `Администратор` содержит текущие пункты администрирования.
- [x] Проверить, что `Подрядчики` всегда отображаются внутри группы `Администратор`.
- [x] Проверить доступы для пользователей, ролей и настроек.
- [x] Проверить необходимость новых прав: на этом этапе новые права не потребовались.

## Этап 3. Рекламации: вкладки и тип

Статус: **реализован для текущих рекламаций, ожидает пользовательской проверки**.

Создание рекламации из графика заказов вынесено в отдельный этап, потому что зависит от реализации графика заказов.

- [x] Реализовать отдельные вкладки `Все` и `ДКР`.
- [x] Создать справочник `reclamation_types` и заполнить его типами `ДКР` / `Прочее` через сидер.
- [x] Добавить обязательную связь `reclamations.reclamation_type_id` и перенести существующие записи на тип `ДКР`.
- [x] Реализовать вкладку `ДКР` на текущем списке с обязательным фильтром по типу `dkr`.
- [x] Проверить создание рекламаций по площадкам ДКР.
- [x] Запретить формирование документации для оплаты для рекламаций типа `Прочее`.
- [x] Проверить формирование запросов на запчасти из рекламации.
- [x] Сохранить текущую рабочую логику рекламаций.

## Этап 4. Каталог общий: ядро

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

Пользовательская проверка пройдена для создания и редактирования позиций, импорта и экспорта.

В этот этап не входят внешняя API-интеграция калькуляций и перенос экспорта техописаний. Для них нужны отдельные вводные.

- [x] Зафиксировать, что текущий `catalog.*` относится к каталогу ДКР.
- [x] Спроектировать маршруты с префиксом `common-catalog/...`, таблицы и права с техническим именем `common-catalog`.
- [x] Сверить текущую модель каталога ДКР с требованиями общего каталога как источник паттернов, без смешивания данных.
- [x] Зафиксировать состав и порядок колонок общего каталога.
- [x] Зафиксировать файл `docs/refactor/Каталог общий.xlsx` как актуальный источник колонок и реальных данных общего каталога; старый шаблон оставить историческим референсом.
- [x] Зафиксировать предварительные типы данных по шаблону общего каталога.
- [x] Спроектировать обязательность и валидацию утвержденных полей.
- [x] Использовать текущий файловый механизм для хранения фото и документов позиции.
- [x] Доработать импорт/экспорт позиций.
- [x] Доработать карточку позиции.
- [x] Зафиксировать встраивание `Технич. описание` в карточку общего каталога.
- [x] Добавить в карточку место под будущую кнопку/блок `Калькуляции`.
- [x] Зафиксировать интеграционный ключ `common_catalog_items.id` для будущих связей с графиками, рекламациями и складом наличия; сами связи реализуются в этапах этих модулей.
- [x] Перевести поля, импорт и экспорт на фактический формат `docs/refactor/Каталог общий.xlsx` из 30 колонок и двух строк заголовка.
- [x] Добавить восемь видов цен непосредственно в `common_catalog_items`.
- [x] Скрыть цены по умолчанию от всех ролей, кроме администратора, через field-permissions.
- [x] Ограничить экспорт общего каталога администратором по умолчанию.

## Этап 5. Документация

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

- [x] Реализовать дерево папок.
- [x] Разрешить создание корневых папок только админу.
- [x] Реализовать права чтения и записи на папки для всех, ролей и отдельных пользователей.
- [x] Реализовать наследование прав от родительской папки при создании подпапок.
- [x] Реализовать создание, просмотр, редактирование и удаление документов.
- [x] Отображать иконки файлов по MIME-типу и открывать изображения в защищённом предпросмотре.
- [x] Реализовать версионность документов.
- [x] Реализовать полное удаление отдельных версий.
- [x] Использовать текущий механизм хранения файлов; сами файлы документации хранить на приватном диске и выдавать только после проверки ACL.

## Этап 6. Склад: ядро

Статус: **ядро реализовано и проверено пользователем**.

Ядро склада можно реализовывать после появления позиций общего каталога. PDF-экспорт по шаблону вынесен отдельным подпунктом, потому что точный шаблон еще не согласован.

- [x] Разобрать текущую реализацию `Запчасти` как эталон.
- [x] Зафиксировать соответствие сущностей `Запчасти` -> `Склад`.
- [x] Спроектировать таблицы/модели `stock` для заказов, остатков, броней, списаний и истории.
- [x] Реализовать подвкладку `Наличие`.
- [x] Реализовать подвкладку `Заказы`.
- [x] Реализовать карточку позиции.
- [x] Реализовать бронирование.
- [x] Реализовать списание с конкретных заказов.
- [x] Реализовать отмену брони.
- [x] Реализовать историю движений.
- [x] Реализовать импорт заказов/остатков.
- [x] Настроить права: `Наличие` всем, `Заказы` админу и роли `assistant_head`.
- [x] Покрыть критичную логику расчетов тестами.
- [ ] После согласования шаблона реализовать экспорт наличия в PDF.

## Этап 7. Техническое описание в общем каталоге

Статус: **анализ источника завершён, готово к реализации**.

- [x] Получить и изучить готовый Laravel-модуль техописаний `to.stroyprofit.com`.
- [x] Составить карту данных модуля техописаний.
- [x] Составить карту экспортов и форматов выгрузки.
- [x] Сопоставить данные техописаний с полями `Каталог общий`.
- [x] Решить, что данные техописаний расширяют `common_catalog_items`, а не образуют отдельный модуль каталога.
- [x] Зафиксировать, что техописание не хранит отдельную копию цены, а использует нужный вид цены из `Каталог общий`.
- [ ] Добавить остальные недостающие поля техописаний в `Каталог общий` с безопасной миграцией.
- [ ] Подготовить перенос или обогащение 938 позиций по артикулу в согласованном режиме без потери уже заполненных полей общего каталога.
- [ ] Сопоставить старое одиночное поле цены техописаний с нужным видом цены общего каталога, если оно потребуется при переносе.
- [ ] Перенести изображения через текущий файловый механизм CRM.
- [ ] Встроить просмотр/редактирование техописания в карточку общего каталога.
- [ ] Перенести или адаптировать экспорт из готового Laravel-модуля.
- [ ] Подставлять в DOCX согласованный вид цены из `Каталог общий`, не сохраняя отдельную копию в данных техописания.
- [ ] Реализовать общий DOCX и отдельные DOCX в ZIP через очередь и приватное хранение файлов.
- [ ] Покрыть миграцию данных и варианты экспорта автоматическими тестами.

## Этап 8. Калькуляции

Статус: **исходный Python-модуль изучен, ожидается отдельное ТЗ**.

Текущий `calc.stroyprofit.com` рассматривается как источник предметной модели и экспортов. Финальное решение — перенос расчётного движка в Laravel либо интеграция — принимается после отдельного ТЗ. Формулы источника не считаются согласованными автоматически.

- [x] Добавить пункт меню и страницу-заглушку `Калькуляции`.
- [x] Подготовить место под кнопку `Калькуляция` в карточке общего каталога.
- [x] Изучить код, сущности, связи, формулы и Excel-экспорты `calc.stroyprofit.com`.
- [x] Зафиксировать отсутствие расчётных данных в активной базе источника и нерабочий источник восстановления `backup.sql`.
- [ ] Получить отдельное ТЗ на калькуляции.
- [ ] Найти резервную копию или исходные Excel-файлы материалов, станков, персонала и технологических связей.
- [ ] Согласовать формулы, единицы коэффициентов, ставки, налоги, доставку, накладные расходы и прибыль.
- [ ] Определить, нужны ли версии калькуляций и история изменения нормативов.
- [ ] Выбрать по ТЗ внутреннюю Laravel-реализацию или интеграционный контракт.
- [ ] Спроектировать нормализованную модель данных без общей изменяемой калькуляции на артикул.
- [ ] Реализовать согласованные сценарии, права, импорт и экспорты.
- [ ] Покрыть расчётные формулы и версионность автоматическими тестами.

## Этап 9. Графики заказов и доставок

Статус: **исходная система и обмен с 1С изучены, ожидается отдельное ТЗ**.

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

- [x] Изучить старый `График отгрузок` в `manager.stroyprofit.com`.
- [x] Описать найденный HTTP-обмен с 1С и состав текущего payload.
- [x] Проанализировать существующие статусы, ручные поля, вложения и несколько доставок по заказу.
- [x] Зафиксировать обязательную нормализацию заказов, позиций, доставок и загрузок 1С.
- [ ] Получить и согласовать отдельное ТЗ на `График заказов`.
- [ ] Уточнить стабильный внешний идентификатор заказа и передачу артикула каждой позиции из 1С.
- [ ] Согласовать принадлежность полей источнику или ручному редактированию, чтобы повторная загрузка не уничтожала плановые данные.
- [ ] Спроектировать нормализованные таблицы и связи после получения ТЗ.
- [ ] Спроектировать загрузку данных через 1С.
- [ ] Реализовать безопасный идемпотентный импорт с журналом запусков и ошибок.
- [ ] Реализовать `График заказов` без прямого копирования устаревшей таблицы `graf1`.
- [ ] Подготовить отдельную миграцию исторических данных старого Manager с отчётом о конфликтах и дублях.
- [ ] Добавить карточку заказа с выбором одного или нескольких МАФ.
- [ ] Добавить создание рекламации из заказа через текущую форму.
- [ ] Получить и согласовать требования к `Графику доставок`, если они не войдут в ТЗ графика заказов.
- [ ] Реализовать `График доставок` в виде недельного списка.
- [ ] Добавить ручное планирование занятости водителей.
- [ ] Связать доставки с адресами из графика заказов.
- [ ] Проверить связи монтажей с ДКР-площадками и графиком заказов.

## Этап 10. Рекламации из графика заказов

Статус: **готово после этапа 9**.

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

## Этап 11. Проверка

- [ ] Запустить `make test` внутри контейнеров.
- [ ] Проверить меню в браузере под админом.
- [ ] Проверить меню под пользователем с ограниченными правами.
- [ ] Проверить, что существующие маршруты ДКР работают после перегруппировки меню.
- [ ] Проверить, что текущий каталог доступен внутри ДКР.
- [ ] Проверить, что `Каталог общий` открыт как отдельный рабочий раздел.
- [ ] Проверить, что все новые пункты-заглушки открываются у авторизованных пользователей и не дают 404/403.
- [ ] Проверить, что выбранный год не влияет на новые модули.
- [ ] Зафиксировать результат проверки в этом плане.

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

- [ ] Когда будет передано отдельное ТЗ на `График заказов` и какие новые требования добавит заказчик?
- [ ] Передаёт ли 1С стабильный GUID заказа и артикулы позиций, либо формат обмена нужно расширить?
- [ ] Будет ли отдельное ТЗ на `Калькуляции` и выберет ли оно внутренний расчёт в Laravel или интеграцию?
- [ ] Где находится актуальная резервная копия или исходные Excel-данные `calc.stroyprofit.com`?
- [ ] Какие формулы и нормативы калькулятора подтверждены заказчиком?
- [ ] Нужно ли переносить в общий каталог все 938 записей `to.stroyprofit.com` как исходные или только обогащать совпавшие артикулы?
- [ ] Какой из восьми видов цены общего каталога использовать в DOCX техописания вместо старого одиночного поля `price`?
- [ ] Какой точный PDF-шаблон нужен для экспорта `Склад`?
- [ ] Какие поля, статусы, правила отгрузок и связи с заказами нужны для `График доставок`?