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

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

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

## 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. Список позиций

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

Функционал:

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

Источник полей: файл [Шаблон Каталог ощий.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. Связи с другими модулями

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

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

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

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

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

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

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

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

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

- Какой точный формат API калькуляций: endpoint, параметры, авторизация, структура ответа?