# ТЗ: Модуль Каталог общий

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

- [План реорганизации](plan.md)
- [Карта нового меню](menu.md)
- [ТЗ: Модуль ДКР](tz-dkr.md)
- [Шаблон каталога](Шаблон%20Каталог%20ощий.xlsx)

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

`Каталог общий` — центральный справочник позиций платформы Manager 2.0.

Он является базовым источником данных для модулей:

- `Графики`;
- `Рекламации`;
- `Склад`;
- `Технич. описание`;
- `Калькуляции`.

`Каталог общий` и каталог ДКР — разные сущности. Текущий каталог ДКР остается внутри модуля `ДКР`; общий каталог проектируется отдельно.

## 2. Статус

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

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

Реализация использует ключ модуля, маршрутов и прав `common-catalog`. Физические
SQL-таблицы названы `common_catalog_items` и `common_catalog_item_documents` по
принятому в Laravel соглашению snake_case.

В текущей CRM уже есть раздел `Каталог` ДКР:

- маршрут списка: `catalog.index`;
- маршрут карточки: `catalog.show`;
- контроллер: `ProductController`;
- модель: `Product`;
- загрузка изображения/thumbnail;
- загрузка сертификата/документа;
- экспорт каталога.

Эта реализация относится к каталогу ДКР и не становится автоматически `Каталогом общим`. Ее можно использовать как источник UI/технических паттернов, но данные и назначение общего каталога должны быть отделены.

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

Целевое меню:

```text
Каталог общий
├── Позиции
└── Карточка позиции
```

Требования:

- пункт `Каталог общий` должен быть отдельным верхним пунктом меню;
- пункт `Каталог` должен остаться внутри меню `ДКР`;
- текущие маршруты `catalog.index` и `catalog.show` остаются маршрутами каталога ДКР;
- маршруты `Каталог общий` должны использовать префикс `common-catalog/...`;
- таблицы и права `Каталог общий` должны использовать техническое имя `common-catalog`;
- выбранный год в CRM не влияет на отображение и данные общего каталога;
- реорганизация меню выполняется сразу общей для всей платформы Manager 2.0.

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

На первом этапе для заглушки используем доступ для всех авторизованных пользователей.

| Действие | Permission |
|---|---|
| Просмотр заглушки | Любой авторизованный пользователь |
| Просмотр общего каталога после реализации | `common-catalog.view` |
| Создание/редактирование/удаление | Права с префиксом `common-catalog.*` |
| Импорт/экспорт | Права с префиксом `common-catalog.*` |

Требования:

- не переиспользовать `catalog.view` автоматически, потому что это право относится к каталогу ДКР;
- новые права общего каталога использовать с техническим именем `common-catalog`;
- заглушку `Каталог общий` показывать всем авторизованным пользователям.

## 5. Основные сущности

Базовая сущность: позиция каталога.

Возможная техническая основа для анализа:

- модель `Product`;
- карточка позиции через `catalog.show`;
- связи с МАФ/SKU через текущую модель данных.

Эти сущности относятся к каталогу ДКР и не должны смешиваться с общим каталогом без отдельной миграции или синхронизации.

Целевая роль позиции:

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

## 6. Список позиций

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

Функционал:

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

Источник полей: файл [Шаблон Каталог ощий.xlsx](Шаблон%20Каталог%20ощий.xlsx), лист 1, строка 1. В строке 3 шаблона есть пример заполнения.

Колонки:

1. `ID`;
2. `Внешний вид`;
3. `Артикул`;
4. `Наименование по калькулятору`;
5. `Вид`;
6. `Габаритные размеры`;
7. `Высота падения`;
8. `Дополнительные сведения`;
9. `Единица измерения габаритов`;
10. `Вес, кг.`;
11. `Объем, м3`;
12. `Места`;
13. `Состав`;
14. `Возрастная группа`;
15. `Макс.кол-во пользователей`;
16. `Ед.`;
17. `Серия`;
18. `ТМ`;
19. `Примечание`.

Требования к колонкам:

- указанный перечень и порядок являются целевым форматом общего каталога;
- при импорте принимать заголовок `Единица измерения габаритов` в формате шаблона с переносом строки между словами `измерения` и `габаритов`;
- поле `Артикул` хранить строкой, чтобы сохранять ведущие нули;
- `Внешний вид` отображает фото позиции;
- состав полей общего каталога не зависит от состава полей каталога ДКР;
- цена не является полем общего каталога: её единственным владельцем является модуль `Склад`;
- обязательность заполнения и правила валидации полей уточняются при проектировании модели данных.

Предварительная модель полей по шаблону:

| Колонка | Поле | Тип данных | Примечание |
|---|---|---|---|
| A | `ID` | integer | Внутренний идентификатор/номер строки каталога. |
| B | `Внешний вид` | image/file | Фото позиции; в шаблоне есть встроенное изображение. |
| C | `Артикул` | string | Сохранять ведущие нули, пример: `0254`. |
| D | `Наименование по калькулятору` | text | Может содержать переносы строк. |
| E | `Вид` | string | Категория/вид позиции. |
| F | `Габаритные размеры` | text | Может содержать текст и единицы измерения. |
| G | `Высота падения` | decimal | Числовое значение, допускается `0`. |
| H | `Дополнительные сведения` | text nullable | Дополнительное описание. |
| I | `Единица измерения габаритов` | string | В шаблоне заголовок разбит переносом строки. |
| J | `Вес, кг.` | decimal | Вес в килограммах. |
| K | `Объем, м3` | decimal | Объем в кубических метрах. |
| L | `Места` | integer | Количество мест. |
| M | `Состав` | text nullable | Состав комплекта/позиции. |
| N | `Возрастная группа` | string | Пример: `0+`. |
| O | `Макс.кол-во пользователей` | integer | Максимальное количество пользователей. |
| P | `Ед.` | string | Единица учета, пример: `шт.`. |
| Q | `Серия` | string | Серия позиции. |
| R | `ТМ` | string | Торговая марка. |
| S | `Примечание` | text nullable | Свободное примечание. |

## 7. Карточка позиции

Карточка позиции должна стать центральной карточкой товара/МАФ.

Функционал карточки:

- просмотр и редактирование полей позиции общего каталога;
- загрузка фото МАФ/позиции;
- хранение сопутствующих документов;
- блок/выгрузка технического описания, встроенные в карточку общего каталога;
- переход в `Калькуляции`;
- отображение связанных МАФ/SKU, если это потребуется для новой логики;
- сохранение привычных действий карточки каталога ДКР только как UI-паттерна, без смешивания данных.

Текущие возможности каталога ДКР, которые можно использовать как паттерн:

- `catalog.upload-thumbnail` — использовать как основу загрузки фото;
- `catalog.upload-certificate` — использовать как основу загрузки документов, но расширить модель до нескольких произвольных документов, если текущая реализация ограничена сертификатом.

## 8. Фото и документы

Фото:

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

Документы:

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

## 9. Импорт и экспорт

Требования:

- спроектировать импорт и экспорт общего каталога;
- использовать текущий импорт/экспорт каталога ДКР как технический референс, если это ускорит реализацию;
- использовать утвержденные колонки общего каталога в заданном порядке;
- использовать [Шаблон Каталог ощий.xlsx](Шаблон%20Каталог%20ощий.xlsx) как целевой шаблон импорта/экспорта общего каталога;
- при импорте обновлять существующие позиции по стабильному ключу;
- ошибки импорта должны быть понятны пользователю.

## 10. Связи с другими модулями

| Модуль | Связь | Требование |
|---|---|---|
| ДКР | Имеет собственный каталог | Не смешивать каталог ДКР с общим каталогом. |
| Склад | Использует картинку, артикул, наименование, характеристики, ед. изм.; хранит актуальную цену | Склад берёт справочные поля из общего каталога, но является единственным источником цены. |
| Графики | Используют данные по позициям | При разработке графиков опираться на общий каталог. |
| Рекламации | Используют данные по позициям | Сохранить/добавить связь рекламаций с позициями общего каталога. |
| Технич. описание | Является частью общего каталога | Источник `to.stroyprofit.com` изучен; описательные поля и DOCX-экспорты переносятся в карточку, а цена читается из `Склад`. |
| Калькуляции | Открываются из карточки позиции | Финальное поведение кнопки и способ реализации определяются отдельным ТЗ; исходный `calc.stroyprofit.com` используется как референс. |

## 11. Что не входит в первый этап

В первый этап общего каталога не входит:

- переименование текущих маршрутов `catalog.*`;
- полная переработка модели `Product`;
- внедрение новых прав доступа;
- разработка модуля `Склад`;
- отдельный модуль `Технич. описание`;
- разработка калькуляций до получения отдельного ТЗ и согласования архитектуры;
- изменение бизнес-логики ДКР.

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

- [x] Проверить текущие маршруты `catalog.*`.
- [x] Зафиксировать, что текущие маршруты `catalog.*` относятся к каталогу ДКР.
- [x] Использовать префикс маршрутов `common-catalog/...` для `Каталог общий`.
- [x] Использовать техническое имя `common-catalog` для модуля и прав, SQL-префикс `common_catalog` — для таблиц.
- [x] Добавить верхний пункт `Каталог общий`.
- [x] Заменить страницу-заглушку рабочим списком `Каталог общий`.
- [x] Спроектировать и реализовать карточку позиции общего каталога.
- [x] Проверить загрузку фото позиции.
- [x] Реализовать загрузку документов позиции через текущий файловый механизм.
- [x] Зафиксировать состав и порядок колонок общего каталога.
- [x] Зафиксировать шаблон общего каталога как источник колонок.
- [x] Зафиксировать предварительные типы данных по шаблону общего каталога.
- [x] Спроектировать обязательность и валидацию утвержденных полей: обязательны артикул и наименование по калькулятору; числовые значения неотрицательны; остальные поля допускают постепенное заполнение.
- [x] Реализовать утвержденные поля в списке и карточке позиции.
- [x] Реализовать фоновый импорт/экспорт по утвержденным 19 колонкам с обновлением по артикулу и поддержкой встроенных изображений.
- [x] Реализовать блок документов как набор файлов.
- [x] Зафиксировать, что `Технич. описание` включается внутрь карточки общего каталога.
- [x] Добавить в карточку место под будущий модуль `Калькуляции`.
- [x] Зафиксировать `common_catalog_items.id` как внешний ключ для будущих связей модулей; добавление связей выполняется вместе с соответствующими модулями.
- [x] Настроить `common-catalog.view` для основных авторизованных ролей и отдельные права на изменение, файлы, импорт и экспорт.

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

- В верхнем меню есть пункт `Каталог общий`.
- В меню `ДКР` остается пункт `Каталог`.
- Текущие маршруты `catalog.index` и `catalog.show` сохранены как маршруты каталога ДКР.
- Рабочий раздел `Каталог общий` доступен основным авторизованным ролям через право `common-catalog.view`.
- После реализации общий каталог не смешивает данные с каталогом ДКР без отдельной миграции/синхронизации.
- Список, импорт и экспорт общего каталога используют утвержденный состав и порядок колонок из файла `docs/refactor/Шаблон Каталог ощий.xlsx`.
- Карточка позиции общего каталога поддерживает фото и набор документов; места интеграции техописания и калькуляции подготовлены до реализации соответствующих этапов.
- ДКР продолжает использовать свой каталог без поломки существующих связей.
- Реорганизация меню выполнена как часть общей структуры Manager 2.0.

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

- Какие дополнительные поля техописания добавляются напрямую в `common_catalog_items` после переноса источника?
- Какое поведение кнопки калькуляции будет утверждено отдельным ТЗ?