strprfcrm/docs/refactor/tz-technical-description.md

ТЗ: Технич. описание

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

• План реорганизации
• Карта нового меню
• Исходное ТЗ
• ТЗ: Каталог общий

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

Технич. описание описывает технические данные позиции общего каталога и выгрузки этих данных в заданном формате.

По новым вводным это не отдельный самостоятельный модуль, а часть модуля Каталог общий: по сути это те же данные позиции, только представленные и выгружаемые в определенном формате.

2. Статус

Статус: реализовано в модуле Каталог общий и проверено пользователем.

Laravel-модуль to.stroyprofit.com изучен и используется как источник:

• структуры данных технического описания;
• правил формирования выгрузок;
• шаблонов/форматов экспорта;
• возможных UI-решений, если они применимы к текущей CRM.

В источнике находятся 938 позиций из 24 серий. Для всех позиций заполнены цена, характеристики, полное и краткое техническое описание, группа, название для формы и изображение. Наличие одиночной цены в старом модуле зафиксировано как факт анализа; в новой CRM цены хранятся у позиции общего каталога по восьми отдельным видам.

Для переноса между окружениями экспорт общего каталога содержит необязательный лист Техописания с текстовыми полями. Импорт понимает как системный экспорт с этим листом, так и исходный 30-колоночный файл без него. Изображение техописания является изображением позиции общего каталога и переносится существующим столбцом Внешний вид.

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

Отдельный пункт меню Технич. описание не нужен. Целевая модель:

Каталог общий
└── Карточка позиции
    └── Технич. описание / экспорт

Требования:

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

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

Отдельная заглушка для техописания не требуется, потому что функциональность встраивается в карточку общего каталога.

Целевая модель:

• просмотр техописания наследует доступ к позиции общего каталога;
• экспорт техописания наследует доступ к позиции общего каталога;
• редактирование данных техописания наследует права редактирования позиции общего каталога.

5. Функциональные требования

Целевой функционал:

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

6. Что не переносим из готового модуля

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

7. Результаты анализа

Источник хранит:

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

Экспорт поддерживает:

• выбор нескольких позиций;
• общий DOCX;
• отдельный DOCX для каждой позиции в ZIP;
• выбор полного, краткого или комбинированного описания;
• отдельный и массовый DOCX-шаблоны.

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

Техописание не хранит собственную копию цены. При формировании DOCX оно читает выбранный администратором вид цены непосредственно из позиции Каталог общий. По умолчанию используется поле project_price (проект). Старое одиночное поле price не переносится.

Экспорт доступен только пользователю, имеющему право просмотра выбранного ценового поля. Поэтому DOCX не позволяет обойти действующее ограничение видимости цен.

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

• Получить и изучить готовый Laravel-модуль техописаний.
• Составить карту данных модуля техописаний.
• Составить карту экспортов и форматов выгрузки.
• Сопоставить данные техописаний с полями Каталог общий.
• Решить, что данные хранятся в карточке общего каталога, а не в отдельном модуле.
• Исключить отдельную копию цены из модели техописания; владельцем цен является общий каталог.
• Добавить остальные недостающие поля общего каталога.
• Перенести данные по артикулу с защитой уже заполненных полей.
• Заменить старое поле price выбором актуального ценового поля в системных настройках.
• Переносить исходное изображение через файловый механизм CRM только при отсутствии изображения общего каталога.
• Встроить просмотр/редактирование техописания в карточку общего каталога.
• Перенести и адаптировать экспорт из готового Laravel-модуля.
• Подставлять в экспорт выбранный вид цены из Каталог общий.
• Выполнять массовые экспорты через очередь и выдавать результат из приватного хранилища.
• Не добавлять отдельный пункт меню Технич. описание в финальную навигацию.

9. Критерии приемки

• Техническое описание доступно из карточки позиции общего каталога.
• Данные техописания не дублируют общий каталог без необходимости.
• Цена не дублируется в техописании и берётся из позиции общего каталога.
• Экспорт техописания работает в согласованном формате.
• Готовый Laravel-модуль использован как источник экспортной логики.
• Права просмотра/редактирования согласованы с правами общего каталога.

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

• Использовать безопасное обогащение существующего общего каталога; отсутствующие позиции автоматически не создавать.
• Сохранить оба текущих DOCX-шаблона без визуальных изменений.
• Нужна ли история изменения текстов технического описания?
• Вид цены выбирается администратором; значение по умолчанию — проект.

11. Результат фактического переноса

• источник: 938 позиций, 24 серии, 938 изображений;
• найдено в общем каталоге: 907 исходных артикулов;
• обогащено: 1033 позиции общего каталога с учётом вариантов одного артикула;
• уже заполненные поля и изображения не перезаписывались;
• 31 отсутствующий артикул оставлен для отдельного решения: K5320, E2002, Е4015, Е4016, Е4017, Е4019, Е4022, Е6306, 5002, 5008, 5011, 6502, 6503, 6504, 0001-1, VR0001, VR0002, VR0007, VR0008, VR0009, VR0010, VR0011, VR0012, VR0013, VR0014, VR0015, 10020, У001, У002, МК001, ЕК-001.