# 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 за переработку, двойная за праздник                                             |
| Окно агрегации                               | Показатель или позиции берутся за смену, день, неделю, декаду или месяц: фонд считается на дне, а прогрессивная шкала обычно на месяце |

Полный разбор отраслевых схем — в [справочнике схем](PAYROLL-SCHEMES-CATALOGUE.md); ограничения, которые нельзя нарушать, — в [правовых ограничениях](PAYROLL-LEGAL-LIMITS.md).

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

```
Повар в команде:      доля из фонда + ставка × часы + надбавка
Администратор:        наибольшее(процент от выручки + ставка × часы; гарантия смены)
Продавец:             оплата смены + прогрессивный процент от личных продаж
Курьер:               ставка × часы
                      + процент от суммы заказов дешевле 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. Выплаты: только наличные или бывают переводы, и нужно ли фиксировать, кто выдал деньги?