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. Общий каталог	Реализован и проверен	Создание, редактирование, импорт и экспорт фактического формата Каталог общий.xlsx приняты по результатам пользовательской проверки; добавлены восемь цен и ограничения доступа.
5. Документация	Реализован и проверен	Пользователь проверил дерево папок, работу с документами и версиями; права и приватное хранение дополнительно покрыты автоматическими тестами.
6. Склад: ядро	Реализован и проверен	Ядро склада принято после пользовательской проверки. Цены относятся к общему каталогу; для склада остаётся отдельной задачей только PDF-экспорт после согласования шаблона.
7. Техническое описание	Реализован и проверен	Данные встроены в общий каталог, вид цены выбирается администратором (по умолчанию проект), одиночный DOCX и массовый DOCX/ZIP приняты по результатам пользовательской проверки.
8. Калькуляции	Исходник изучен, ожидается отдельное ТЗ	Восстановлены сущности, формулы и экспорты calc.stroyprofit.com; финальная архитектура, формулы и сценарии не фиксируются до ТЗ. Рабочая база источника сейчас не содержит расчётных данных.
9. Графики заказов и доставок	Ручной контур и XLS реализованы; интеграция в работе	Нормализованное ядро, таблица и карточка заказа по ТЗ, несколько доставок/монтажей, недельный график доставок, файлы, уведомления, документы, экспорт и рекламации приняты пользователем. XLS-импорт реализован и покрыт автотестами; 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 исходных артикулов сопоставлено 907, данные применены к 1033 позициям с учётом вариантов.
• Не переносить старую одиночную цену; вид актуальной цены выбирает администратор в системных настройках, значение по умолчанию — проект.
• Использовать изображения общего каталога; при переносе добавлять исходное изображение только позиции без изображения.
• Встроить просмотр/редактирование техописания в карточку общего каталога.
• Перенести и адаптировать оба DOCX-шаблона готового Laravel-модуля.
• Подставлять в DOCX выбранный администратором вид цены из Каталог общий, не сохраняя отдельную копию в данных техописания.
• Реализовать общий DOCX и отдельные DOCX в ZIP через очередь и приватное хранение файлов.
• Добавить перенос текстов техописаний отдельным листом общего XLSX; изображения переносятся существующим столбцом общего каталога.
• Покрыть перенос данных, настройку цены, права и варианты экспорта автоматическими тестами.

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

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

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

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

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

Статус: ручной контур реализован и проверен пользователем; XLS-импорт реализован и покрыт автотестами; в работе остаются обмен с 1С и перенос истории.

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

Техническая схема

• production_orders — заголовок производственного заказа; не смешивается с ДКР-orders.
• production_order_items — отдельный экземпляр МАФ со ссылкой на common_catalog_items и собственным паспортом.
• production_order_deliveries — неограниченное число доставок с водителем и данными заявки.
• production_order_installations — неограниченное число этапов монтажа с бригадиром.
• production_order_activities — журнал только согласованных значимых событий.
• production_calendar_days — переносы и исключения производственного календаря; базовое правило без исключений — понедельник–пятница.
• Фиксированные статусы и типы исполнения оформляются PHP-enum со строковым значением в БД.
• Номер заказа уникален в пределах календарного года; внешний GUID хранится отдельно и остаётся nullable до согласования 1С.
• Данные доставок, монтажей и другие ручные поля не включаются в payload замены из 1С.

Подэтапы реализации

1. 9.1. Основа данных и права — таблицы, модели, enum, роль driver, permissions и расчёт даты отгрузки.
2. 9.2. Ручной заказ — список с фильтрами, карточка, создание/редактирование, отдельные экземпляры МАФ из общего каталога.
3. 9.3. Доставки и монтажи — несколько записей на заказ, выбор водителя/бригадира, недельный график доставок и связь с графиком монтажей.
4. 9.4. Файлы и коммуникации — документы, фотографии, чат заказа, скан паспорта каждого экземпляра МАФ.
5. 9.5. События и документы — аудит, настраиваемые уведомления, экспорт МАФ, монтажный пакет, заявка на доставку и техдокументация.
6. 9.6. Обмен данными — экспорт списка, XLS-импорт по согласованному формату, API 1С с журналом загрузок и отдельная миграция старых данных.
7. 9.7. Рекламации и приёмка — связь с этапом 10, полные автотесты и пользовательская проверка.

Текущий подэтап: 9.6. Обмен данными; фоновый экспорт списка и атомарный XLS-импорт реализованы, а 1С и перенос истории ожидают согласования контракта. Подэтап 9.7 реализован и принят пользователем.

• 9.1. Основа данных и права: добавлены нормализованные таблицы и модели, enum статусов/типов, производственный календарь, роль driver, действия и permissions отдельных полей.
• 9.2. Ручной заказ: реализованы список с фильтрами, цветовой статус, карточка, создание/редактирование, расчёт договорной даты отгрузки и отдельные экземпляры МАФ из общего каталога.
• 9.3. Доставки и монтажи: реализованы несколько доставок/монтажей на заказ, выбор водителя/бригадира, недельный график доставок и синхронизация с действующим графиком монтажей.
• 9.4. Файлы и коммуникации: реализованы документы, фотографии, чат и скан паспорта каждого экземпляра МАФ; для файлов используются MIME-иконки и просмотр изображений.
• 9.5. События и документы: реализованы согласованный аудит, настраиваемые уведомления, экспорт МАФ, заявка на доставку, монтажный пакет и архив техдокументации.
• 9.6. Обмен данными: реализовать согласованную часть XLS/1С и отдельный перенос истории.

• [x] 9.7. Рекламации и автопроверка: этап 10 связан с заказами, полный набор автоматических тестов пройден, интерфейс принят пользователем.

• [x] Изучить старый График отгрузок в manager.stroyprofit.com.

• [x] Описать найденный HTTP-обмен с 1С и состав текущего payload.

• [x] Проанализировать существующие статусы, ручные поля, вложения и несколько доставок по заказу.

• [x] Зафиксировать обязательную нормализацию заказов, позиций, доставок и загрузок 1С.

• [x] Получить отдельное ТЗ на График заказов.

• [x] Конвертировать ТЗ в tz-order-schedule.md, сохранить значимый референс карточки и сопоставить требования с планом и текущим кодом.

• [x] Получить и конвертировать ответы заказчика в tz-order-schedule-answers.md.

• [x] Получить и разобрать шаблон заявки на доставку templates/DeliveryRequest.xls.

• [x] Согласовать даты отгрузки, производственный календарь, несколько доставок/монтажей, роль водителя, права, уведомления и аудит.

• [ ] Согласовать со специалистом 1С оставшиеся вопросы интеграции.

• [ ] Уточнить стабильный внешний идентификатор заказа и передачу артикула каждой позиции из 1С.

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

• [x] Согласовать календарь рабочих дней и значения полей дат отгрузки.

• [x] Зафиксировать Водитель как отдельную роль в ролевой модели.

• [x] Спроектировать нормализованные таблицы и связи после получения ТЗ.

• [ ] Спроектировать загрузку данных через 1С.

• [ ] Реализовать безопасный идемпотентный импорт с журналом запусков и ошибок.

• [x] Реализовать График заказов без прямого копирования устаревшей таблицы graf1.

• [ ] Подготовить отдельную миграцию исторических данных старого Manager с отчётом о конфликтах и дублях.

• [x] Добавить карточку заказа с выбором одного или нескольких МАФ.

• [x] Добавить ручное создание заказа, файлы, фотографии, чат, паспорт каждого МАФ и журнал согласованных действий.

• [x] Добавить статусы, типы исполнения, цветовую индикацию и настраиваемые уведомления.

• [x] Реализовать экспорт списка заказов с активными фильтрами и экспорт МАФ одного заказа.

• [x] Реализовать ручной XLS-импорт: обновление по ID, создание при пустом ID, ошибка при неизвестном ID; экземпляры МАФ принимать с отдельного листа.

• [x] Реализовать пакеты документов для монтажа, доставки и технической документации.

• [x] Добавить создание рекламации из заказа через текущую форму.

• [x] Получить базовые требования и шаблон заявки для Графика доставок.

• [x] Реализовать График доставок в виде недельного списка.

• [x] Добавить ручное планирование занятости водителей.

• [x] Связать доставки с адресами из графика заказов.

• [x] Проверить связи монтажей с ДКР-площадками и графиком заказов.

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

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

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

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

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

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

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