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

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

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

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

Модуль `Калькуляции` предназначен для расчёта стоимости изготовления позиции общего каталога, хранения расчётных нормативов и формирования согласованных выгрузок.

Финальный состав модуля будет определён отдельным ТЗ. До его получения нельзя считать утверждённым ни вариант внешнего API, ни полный перенос расчётного движка внутрь CRM.

## 2. Статус

Статус: **исходный Python-модуль изучен, ожидается отдельное ТЗ**.

На первом этапе уже реализованы:

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

Исходный модуль `calc.stroyprofit.com` используется как источник:

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

Код и формулы источника не переносятся без проверки и согласования.

## 3. Результаты анализа источника

В `calc.stroyprofit.com` найдены сущности:

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

Источник рассчитывает:

- материалы;
- станко-часы;
- труд персонала;
- страховые взносы;
- доставку;
- накладные расходы;
- прибыль;
- НДС;
- итоговую стоимость.

Также реализованы:

- ручное изменение коэффициентов;
- подгонка расчёта под целевую цену;
- Excel-калькуляция;
- технологическая карта;
- ZIP с расчётом и подтверждающими документами.

Текущее состояние данных источника:

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

## 4. Архитектурные ограничения

До отдельного ТЗ допускаются два варианта:

1. Реализация расчётного модуля внутри текущего Laravel-приложения.
2. Интеграция с отдельным сервисом по согласованному API.

Независимо от выбранного варианта:

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

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

Сохраняются предварительные требования:

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

Точное поведение кнопки зависит от выбранной архитектуры: переход во внутреннюю карточку расчёта либо запрос к внешнему сервису.

## 6. Что требует отдельного ТЗ

- роли и права;
- состав экранов и справочников;
- утверждённые формулы;
- единицы и смысл технологических коэффициентов;
- источник целевой цены;
- правила подгонки под цену;
- версии нормативов и калькуляций;
- актуальные налоговые и коммерческие ставки;
- импорт исходных данных;
- необходимые варианты Excel, ZIP и подтверждающих документов;
- необходимость внешнего API.

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

- [x] Добавить пункт меню `Калькуляции`.
- [x] Добавить страницу-заглушку.
- [x] Добавить место под кнопку `Калькуляция` в карточке общего каталога.
- [x] Изучить исходный Python-модуль.
- [x] Составить предварительную карту сущностей, связей, формул и экспортов.
- [x] Проверить наличие данных для миграции и зафиксировать их отсутствие в активной базе.
- [ ] Получить отдельное ТЗ.
- [ ] Найти резервную копию или исходные Excel-файлы справочников и связей.
- [ ] Подтвердить формулы и нормативы с заказчиком.
- [ ] Выбрать внутреннюю Laravel-реализацию или интеграционный вариант.
- [ ] Спроектировать нормализованную и версионируемую модель.
- [ ] Реализовать согласованные права, интерфейс, импорт и экспорт.
- [ ] Покрыть критичные расчёты и историю автоматическими тестами.

## 8. Предварительные критерии приемки

Финальные критерии формируются после отдельного ТЗ. Обязательная техническая часть:

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

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

- Будет ли отдельное ТЗ и когда оно будет доступно?
- Расчёт выполняется внутри Laravel или остаётся отдельным сервисом?
- Где находятся актуальные данные старого калькулятора?
- Формула времени — количество, умноженное на коэффициент, или количество, разделённое на производительность?
- Какие проценты, ставки и правила подгонки считаются утверждёнными?
- Требуется ли хранить версии и историю калькуляций?
- Какие роли имеют доступ к просмотру и редактированию?