strprfcrm/docs/refactor/tz-calculations.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. Этапы реализации

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

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

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

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

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

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