strprfcrm/docs/refactor/plan.md

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

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

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

• Исходное ТЗ
• Карта нового меню
• ТЗ: ДКР
• ТЗ: Каталог общий
• ТЗ: Графики
• ТЗ: Рекламации
• ТЗ: Запчасти
• ТЗ: Склад
• ТЗ: Документация
• ТЗ: Технич. описание
• ТЗ: Калькуляции
• ТЗ: Администратор

Цель

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

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

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

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

• Изучить ТЗ Manager 2.0 и схему зависимостей.
• Составить карту нового меню.
• Перенести карту меню в docs/refactor/menu.md.
• Создать общий план реализации в docs/refactor/plan.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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Изучить старый График отгрузок в manager.stroyprofit.com.
• Описать найденный HTTP-обмен с 1С и состав текущего payload.
• Проанализировать существующие статусы, ручные поля, вложения и несколько доставок по заказу.
• Зафиксировать обязательную нормализацию заказов, позиций, доставок и загрузок 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-шаблон нужен для экспорта Склад?
• Какие поля, статусы, правила отгрузок и связи с заказами нужны для График доставок?