# ТЗ: Модуль Рекламации

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

- [План реорганизации](plan.md)
- [Карта нового меню](menu.md)
- [Исходное ТЗ](source-tz.md)
- [ТЗ: Модуль ДКР](tz-dkr.md)
- [ТЗ: Графики](tz-schedules.md)
- [ТЗ: Запчасти](tz-spare-parts.md)

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

Модуль `Рекламации` предназначен для ведения клиентских рекламаций Manager 2.0.

В новом формате раздел должен сохранить текущую рабочую логику рекламаций и получить структуру:

```text
Рекламации
├── Все
└── ДКР
```

Рекламации имеют два типа:

- `ДКР` — рекламации по программе ДКР;
- `Прочее` — остальные рекламации.

## 2. Статус

Статус модуля: **реализован для текущих рекламаций, ожидает пользовательской проверки**.

В текущей CRM уже есть:

- список рекламаций;
- карточка рекламации;
- маршрут списка: `reclamations.index`;
- маршрут карточки: `reclamations.show`;
- контроллер: `ReclamationController`;
- модель: `Reclamation`;
- связь с площадкой/заказом;
- документы и фото до/после;
- генерация пакетов документов;
- связь с запчастями и резервами;
- создание записи в графике монтажей из рекламации.

Текущая бизнес-логика рекламаций сохранена, добавлены типы и явное разделение интерфейса на вкладки `Все` / `ДКР`. Создание рекламаций типа `Прочее` из графика заказов остается отложенным до реализации самого графика.

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

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

```text
Рекламации
├── Все
└── ДКР
```

Требования:

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

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

На первом этапе оставляем текущие права.

| Действие | Permission |
|---|---|
| Просмотр рекламаций | `reclamations.view` |
| Создание/редактирование | Использовать текущие права рекламаций |
| Экспорт | Использовать текущие права рекламаций |

Требования:

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

## 5. Справочник типов рекламаций

Тип рекламации должен храниться не строковым полем, а ссылкой на отдельный системный справочник.

### 5.1. Таблица типов

Создать таблицу `reclamation_types` со следующими полями:

| Поле | Тип | Требование |
|---|---|---|
| `id` | `bigint` | Первичный ключ. |
| `code` | `string` | Уникальный стабильный код типа. |
| `name` | `string` | Отображаемое название типа. |
| `created_at`, `updated_at` | `timestamps` | Служебные даты. |

Начальные записи справочника:

| `code` | `name` |
|---|---|
| `dkr` | `ДКР` |
| `other` | `Прочее` |

Требования:

- создать модель `ReclamationType`;
- определить в модели константы кодов `CODE_DKR = 'dkr'` и `CODE_OTHER = 'other'`;
- создать сидер `ReclamationTypeSeeder`;
- сидер должен идемпотентно создавать или обновлять типы по полю `code`;
- зарегистрировать `ReclamationTypeSeeder` в общем процессе заполнения БД;
- системные коды `dkr` и `other` использовать в бизнес-логике вместо сравнения отображаемых названий;
- на текущем этапе отдельный интерфейс управления справочником не требуется;
- удаление используемого типа рекламации должно быть запрещено внешним ключом (`restrictOnDelete`).

### 5.2. Связь с рекламацией

В таблицу `reclamations` добавить обязательное поле `reclamation_type_id`:

- внешний ключ на `reclamation_types.id`;
- индекс для фильтрации списков;
- связь `Reclamation::reclamationType()`;
- обратная связь `ReclamationType::reclamations()`;
- существующим рекламациям при переносе данных назначить тип с кодом `dkr`;
- после заполнения существующих записей поле не должно допускать `null`.

Тип назначается сервером по сценарию создания:

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

## 6. Подраздел `Все`

Назначение:

- общий список всех рекламаций независимо от типа.

Функционал:

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

Текущая основа:

- `reclamations.index`.

## 7. Подраздел `ДКР`

Назначение:

- список рекламаций типа `ДКР`;
- работа с рекламациями, созданными по площадкам ДКР.

Функционал:

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

Принятое решение:

- отдельный URL для списка `ДКР` не обязателен;
- в интерфейсе обязательно отдельное разделение на вкладки `Все` и `ДКР`;
- вкладка `ДКР` использует текущий список с обязательным фильтром по `reclamation_type_id` типа с кодом `dkr`;
- тип рекламации определяется через справочник `reclamation_types`;
- при создании рекламации из площадки назначается тип `dkr` (`ДКР`);
- при создании рекламации не из площадки, включая создание из графика заказов, назначается тип `other` (`Прочее`);
- рекламации типа `Прочее` не выводятся во вкладке `ДКР`;
- формирование документации для оплаты разрешено только для рекламаций типа `ДКР`.

## 8. Карточка рекламации

Карточка должна сохранить текущий функционал:

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

Изменения на первом этапе:

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

## 9. Создание из графика заказов

Сценарий:

1. Пользователь открывает заказ в `График заказов`.
2. Пользователь выбирает один или несколько МАФ заказа.
3. Пользователь нажимает `Добавить рекламацию`.
4. Открывается текущая форма создания рекламации.
5. В форму передаются заказ и выбранные МАФ.
6. Пользователь заполняет форму по текущему процессу и сохраняет рекламацию.

Требования:

- использовать существующую форму создания рекламации;
- поддержать выбор одного или нескольких МАФ;
- привязать созданную рекламацию к заказу и выбранным МАФ;
- назначить созданной рекламации тип `other` (`Прочее`);
- созданная рекламация отображается во вкладке `Все`;
- созданная рекламация не отображается во вкладке `ДКР`;
- для нее недоступно формирование документации для оплаты;
- остальные функции карточки рекламации работают по текущим правилам.

## 10. Связи

| Модуль | Связь | Требование |
|---|---|---|
| ДКР / Площадки | Используется при создании рекламации типа `ДКР` | Сохранить текущую связь. |
| Каталог общий | Данные по позициям | Использовать общий каталог как источник номенклатуры. |
| График заказов | Из заказа создается рекламация по одному или нескольким МАФ | Открывать текущую форму создания с предзаполненным заказом и выбранными МАФ; назначать тип `other` (`Прочее`). |
| График монтажей | Рекламация может попасть в монтажный график | Сохранить текущую связь. |
| Запчасти | Из рекламации формируется запрос на запчасть | Сохранить текущую связь и резервы. |

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

- изменение текущих маршрутов `reclamations.*`;
- переработка модели `Reclamation` сверх добавления типа рекламации и связей с заказом/выбранными МАФ;
- изменение логики резервов запчастей;
- изменение состава и шаблонов документации для оплаты;
- разработка графика заказов;
- внедрение новых прав доступа.

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

- [x] Проверить текущие маршруты `reclamations.*`.
- [x] Проверить текущие permissions рекламаций.
- [x] Добавить верхнюю группу меню `Рекламации`.
- [x] Добавить отдельные вкладки `Все` и `ДКР`.
- [x] Создать таблицу `reclamation_types` и модель `ReclamationType`.
- [x] Создать и зарегистрировать `ReclamationTypeSeeder` с типами `dkr` (`ДКР`) и `other` (`Прочее`).
- [x] Добавить `reclamations.reclamation_type_id`, внешний ключ, индекс и связи моделей.
- [x] Назначить существующим рекламациям тип `dkr` и сделать поле типа обязательным.
- [x] Реализовать вкладку `ДКР` на текущем списке с обязательным фильтром по типу `dkr`.
- [x] Проверить открытие карточки рекламации.
- [x] Проверить создание рекламации по площадке ДКР.
- [ ] Реализовать создание рекламации из графика заказов с выбором одного или нескольких МАФ.
- [ ] Передавать заказ и выбранные МАФ в текущую форму создания рекламации.
- [ ] Автоматически назначать тип рекламации в зависимости от сценария создания.
- [x] Запретить формирование документации для оплаты для типа `Прочее`.
- [x] Проверить связь с графиком монтажей.
- [x] Проверить блок запчастей и резервов.
- [x] Проверить экспорт рекламаций.

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

- В меню есть группа `Рекламации`.
- Внутри есть отдельные вкладки `Все` и `ДКР`.
- `Все` открывает текущий общий список рекламаций.
- Текущие маршруты рекламаций сохранены.
- Пользователи с прежним доступом сохраняют доступ.
- Рекламации типа `ДКР` связаны с площадками ДКР.
- Типы рекламаций хранятся в отдельной таблице `reclamation_types`.
- Сидер создает типы `dkr` (`ДКР`) и `other` (`Прочее`) без дублирования при повторном запуске.
- Каждая рекламация имеет обязательную ссылку `reclamation_type_id` на справочник типов.
- Существующие рекламации после миграции имеют тип `ДКР`.
- При создании рекламации из площадки автоматически назначается тип `dkr` (`ДКР`).
- При создании рекламации не из площадки назначается тип `other` (`Прочее`).
- Вкладка `ДКР` открывает текущий список с обязательным фильтром по типу `dkr`.
- Рекламации из графика заказов не попадают во вкладку `ДКР`.
- Из графика заказов можно выбрать один или несколько МАФ и открыть текущую форму создания рекламации.
- Созданная из графика заказов рекламация привязана к заказу и выбранным МАФ.
- Документация для оплаты формируется только для рекламаций типа `ДКР`.
- Для рекламаций типа `Прочее` действие формирования платежных документов отсутствует и блокируется на сервере.
- Из рекламации по-прежнему можно работать с запчастями.
- Перенос рекламации в график монтажей работает как раньше.