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

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

- [План реорганизации](plan.md)
- [Карта нового меню](menu.md)
- [Исходное ТЗ](source-tz.md)
- [ТЗ: Каталог общий](tz-catalog-common.md)

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

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

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

## 2. Статус

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

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

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

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

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

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

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

Требования:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## 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`.