krona-staff/docs/REQ-001-PAYROLL.md

REQ-001: Универсальный расчёт заработной платы

• Статус: утверждено владельцем 2026-09-23, реализуется
• Контур: управленческий учёт. Официальный расчёт (НДФЛ, страховые взносы, МРОТ, кадровые документы) — следующий этап, схема данных готовится под него заранее
• Проверочный пример: таблица владельца «Доходы и расходы 2026 год», листы «График» и «Расчет ЗП с доп. поваром»

1. Задача

Модуль считает переменную часть зарплаты для любой организации, а не для одного кафе. Главный сценарий — переход с Excel: основная масса малого бизнеса ведёт расчёт в таблицах со своими формулами, и продукт обязан принять эти формулы, а не навязать свои.

Отсюда три обязательных свойства:

1. Формулу задаёт клиент. Правило оплаты — не код, а настройка: собирается в визуальном конструкторе из блоков, хранится как структура, показывается человеку словами.
2. Переход без потерь. Историю из таблицы можно загрузить, сверить с расчётом модуля и убедиться, что суммы совпадают, прежде чем отказываться от Excel.
3. Формулы меняются со временем. Изменение ставки или правила создаёт новую версию; прошлые ведомости пересчёту не подлежат и воспроизводятся в точности.

Остальное — учёт смен (факт из терминала плюс подтверждение управляющего), ведомость, выплаты, остатки, мониторинг и кабинет сотрудника в мобильном приложении.

2. Словарь

Термин	Значение
Подразделение (OrganizationUnit)	Точка, цех, магазин, участок. К нему привязаны показатели дня и смены
Показатель дня	Числовая величина подразделения за день: выручка, число чеков, объём производства. Состав определяет клиент
Позиция	Оплачиваемая строка дня сотрудника: заказ, доставка, услуга, партия. Имеет атрибуты: сумма, дальность, тип клиента
Смена (WorkSession)	Факт работы сотрудника в подразделении за операционный день
Правило оплаты (PayRule)	Дерево блоков, по которому считается начисление. Версионируется
Параметр сотрудника	Значение, которое правило подставляет для конкретного человека: ставка, процент, надбавка, гарантия, план
Фонд дня	Сумма, которую участники смены делят между собой. Задаётся правилом подразделения
Ведомость (PayrollRun)	Расчёт за период со строками по сотруднику и дню
Остаток	Начислено минус выплачено нарастающим итогом. Плюс — долг перед сотрудником

3. Конструктор правил

Правило собирается из блоков. Набор покрывает схемы, которые встречаются на практике:

Блок	Назначение
Показатель, параметр, часы, число участников	Источники значений
Сложение, вычитание, умножение, деление	Арифметика
Процент от значения	Процент от выручки, от продаж, от суммы заказов
Доля из фонда	Командная схема: фонд делится между участниками смены
Сумма и количество позиций с фильтром	Сдельщина: «сумма заказов дешевле 5000», «количество доставок»
За каждую позицию	Оплата за единицу, в том числе по шкале от атрибута позиции
Шкала по ступеням	Ставка выбирается по достигнутому уровню и применяется ко всей сумме
Прогрессивная шкала	Каждая ступень применяется к своему слою: 3% до 100 тыс, 5% дальше
Условие	Премия при выполнении условий: выручка выше порога и на смене не меньше трёх человек
Наибольшее, наименьшее	Гарантированный минимум и потолок выплаты
Округление	Шаг округления строки начисления
Ночные, сверхурочные, праздничные часы	Доплаты, обязательные по ТК РФ: 20% за ночные, 1,5 и 2 за переработку, двойная за праздник
Окно агрегации	Показатель или позиции берутся за смену, день, неделю, декаду или месяц: фонд считается на дне, а прогрессивная шкала обычно на месяце

Полный разбор отраслевых схем — в справочнике схем; ограничения, которые нельзя нарушать, — в правовых ограничениях.

Примеры правил, которые из этого собираются:

Повар в команде:      доля из фонда + ставка × часы + надбавка
Администратор:        наибольшее(процент от выручки + ставка × часы; гарантия смены)
Продавец:             оплата смены + прогрессивный процент от личных продаж
Курьер:               ставка × часы
                      + процент от суммы заказов дешевле 5000 ₽
                      + за каждый заказ дороже 5000 ₽: по шкале дальности (250 или 500 ₽)
Мастер услуг:         наибольшее(50% своих клиентов + 35% клиентов салона; гарантия смены)
Премия за выручку:    если выручка ≥ порога и участников ≥ 3, добавить премию

Каждое правило движок умеет пересказать словами — этот же текст показывается сотруднику в расшифровке суммы.

3.1 Фонд и неполная смена

Фонд подразделения за день задаётся отдельным правилом (например, 11% от выручки). Он распределяется по времени присутствия: в каждый отрезок смены фонд делится между теми, кто в этот момент работал. Если участник ушёл раньше, он получает долю только за свои часы, а остальные забирают оставшуюся часть. При равных сменах это в точности «фонд ÷ число участников». Вес участника настраивается: полный участник, половина (например, дополнительный сотрудник) или без участия.

3.2 Округление и хранение

Каждая строка начисления округляется с настраиваемым шагом, по умолчанию до рубля. Остаток от округления остаётся в фонде и не приписывается сотруднику. Суммы хранятся в копейках (BIGINT), валюта — ISO 4217.

3.3 Версии правил

Правило и его параметры не редактируются на месте: правка создаёт следующую версию с датой начала действия. Ведомость хранит ссылку на версию и полный след расчёта (входные показатели, фонд, доля, параметры, текст правила), поэтому любую сумму можно объяснить и воспроизвести спустя год.

4. Периоды, ведомость, выплаты

• Период настраивается: неделя (в том числе начиная с четверга, как в таблице владельца), две недели, месяц.
• Статусы ведомости: draft → calculated → approved → paid. После approved строки не пересчитываются; исправление — отдельной корректировкой.
• Выплаты вводятся фактической суммой; разница с начисленным автоматически становится остатком и переносится дальше.
• Реестр начислений и выплат — только на добавление, на уровне прав базы данных.

5. Учёт часов

• Источник — события терминала (check_in / check_out) с идемпотентным ключом.
• Смена попадает в расчёт только после подтверждения управляющим.
• Корректировка часов не меняет исходные события: правка хранится отдельно с причиной.
• Незакрытая смена помечается аномалией после нормы плюс два часа.

6. Переход с Excel

1. Загрузка таблицы. Клиент загружает свой файл; мастер определяет листы и колонки: сотрудник, дата, подразделение, часы, сумма, показатели дня.
2. Подбор формулы. Система предлагает пресет отрасли и подбирает параметры сотрудников по истории, после чего показывает, на скольких днях расчёт совпал с таблицей и где разошёлся.
3. Разбор расхождений. По каждому расхождению видно, из чего сложилась сумма модуля и какая сумма стоит в таблице. Обычно расхождения — это ручные правки в Excel или изменение ставки, не отражённое в формуле.
4. Параллельный период. Клиент неделю ведёт расчёт и в таблице, и в модуле, сверяет итоги и после совпадения отключает таблицу.

Проверка метода на реальной таблице владельца: правило «фонд 11% ÷ участники + 100 ₽/ч + личная надбавка» воспроизводит суммы поваров точно; администраторы считаются как «процент от выручки + почасовая, но не ниже 3000 ₽». Расхождения объясняются изменением ставок в течение года и ручными правками — что и подтверждает необходимость версий и режима сверки.

7. Мониторинг

Ежедневный экран по подразделению: показатели дня, кто на смене, фонд, начислено, доля фонда оплаты в выручке, неподтверждённые и незакрытые смены, дни без введённых показателей. Недельный и месячный итог — по ведомости.

8. Доступ

Роль	Права
Владелец	всё, включая утверждение ведомостей, правил и мониторинг по всем подразделениям
Управляющий	показатели, подтверждение смен, расчёт и выплаты по своему подразделению
Сотрудник	только свои смены, начисления, выплаты, остаток и расшифровка сумм

Сотрудник получает доступ по record-level правам платформы (scope: own). Данные других сотрудников недоступны ни в API, ни в приложении.

9. Границы этапа

Входит: подразделения, сотрудники, показатели и позиции, конструктор правил с версиями, пресеты отраслей, приём отметок терминала, смены и подтверждение, расчёт, ведомость, выплаты, остатки, импорт из Excel и сверка, API для мобильного приложения, мониторинг.

Не входит: НДФЛ и страховые взносы, кадровые документы, отпуска и больничные, планирование графиков, выгрузка в 1С, официальный табель Т-13, автоматическая интеграция с кассой (предусмотрена точка расширения — показатель с источником «модуль»).

10. Вопросы, которые остаются к владельцу по его пресету

1. Дополнительный сотрудник и стажёр считаются в делителе фонда как половина участника? В таблице встречаются оба варианта.
2. Гарантия администратора (3000 ₽) — за смену любой длительности или пропорционально часам?
3. Премия за выручку: при каком пороге и какая сумма, и зависит ли она от числа участников смены?
4. Перенос остатка: бессрочно или закрывается в конце месяца?
5. Выплаты: только наличные или бывают переводы, и нужно ли фиксировать, кто выдал деньги?