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

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

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

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

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

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

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

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

## 2. Статус

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

В текущей 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. Список позиций

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

Функционал:

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

Колонки:

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

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

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

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

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

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

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

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

Фото:

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

Документы:

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

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

Требования:

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

Открытая доработка:

- отдельно сверить шаблон калькулятора и текущие поля каталога ДКР как референс.

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

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

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

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

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

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

- [ ] Проверить текущие маршруты `catalog.*`.
- [ ] Зафиксировать, что текущие маршруты `catalog.*` относятся к каталогу ДКР.
- [ ] Использовать префикс маршрутов `common-catalog/...` для `Каталог общий`.
- [ ] Использовать техническое имя `common-catalog` для таблиц и прав общего каталога.
- [ ] Добавить верхний пункт `Каталог общий`.
- [ ] Добавить страницу-заглушку `Каталог общий`.
- [ ] Спроектировать карточку позиции общего каталога.
- [ ] Проверить загрузку фото позиции.
- [ ] Спроектировать загрузку документов позиции через текущий файловый механизм.
- [ ] Составить список текущих полей каталога ДКР как источник для анализа.
- [ ] Сверить поля с шаблоном калькулятора.
- [ ] Описать недостающие поля для доработки.
- [ ] Подготовить расширение блока документов до набора файлов, если нужно.
- [ ] Определить, включается ли `Технич. описание` внутрь карточки общего каталога.
- [ ] Добавить в карточку место под API-запрос `Калькуляции`.
- [ ] Проверить связи с модулями, которым нужен общий каталог.
- [ ] Проверить, что заглушка `Каталог общий` видна всем авторизованным пользователям.

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

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

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

- Какие точные колонки должны быть добавлены по шаблону калькулятора?
- Как именно включить готовый Laravel-модуль техописаний в общий каталог и какие экспорты оттуда переносить?
- Какой точный формат API калькуляций: endpoint, параметры, авторизация, структура ответа?