# ТЗ: Модуль Калькуляции

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

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

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

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

По новым вводным калькуляции не реализуются внутри CRM как самостоятельный расчетный движок. CRM должна отправлять запрос во внешний API по артикулу позиции и отображать возвращенную калькуляцию, если она есть.

## 2. Статус

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

На первом этапе:

- добавить пункт меню;
- добавить страницу-заглушку;
- подготовить кнопку `Калькуляция` в карточке позиции общего каталога.

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

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

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

```text
Калькуляции
```

Также в карточке позиции `Каталог общий` должна быть кнопка `Калькуляция`.

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

На первом этапе:

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

Целевая модель прав определяется после появления платформы калькуляций.

## 5. Интеграция с общим каталогом

Требования:

- карточка позиции общего каталога содержит кнопку `Калькуляция`;
- кнопка выполняет запрос во внешний API калькуляций;
- запрос выполняется по артикулу позиции;
- если API возвращает калькуляцию, CRM должна показать ее пользователю;
- если калькуляции нет, CRM должна показать понятное сообщение.
- выбранный год в CRM не влияет на запрос и отображение калькуляций.

Открыто:

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

## 6. Возможный функционал будущего модуля

Предварительный список:

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

Этот список предварительный и должен быть уточнен после отдельного ТЗ на платформу калькуляций.

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

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

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

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

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

- Пункт `Калькуляции` есть в меню.
- Заглушка открывается.
- В карточке общего каталога предусмотрена кнопка `Калькуляция`.
- После появления API запрос по артикулу работает для конкретной позиции каталога.
- Если калькуляция найдена, пользователь видит результат.
- Если калькуляция не найдена, пользователь видит понятное сообщение.

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

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