Files
estimator/docs/adr/0001-reserve-policy-and-engagement.md
T
2026-11-09 08:43:30 +03:00

14 KiB
Raw Blame History

ADR-0001: политика резерва, наценка и модель оплаты (фикс или T&M)

Дата: 31 октября 2026 · Статус: принято и реализовано Основание: разбор ревью v2, замечания 1 и 2 (наценка и маржа, двойной резерв), пункт про снимок вводных; решение владельца продукта от 31.10.2026 Затрагивает: pricing/, domain/models.py, API оценок, интерфейс, миграция 0002_engagement

Контекст

В первой версии калькулятора были три проблемы.

  1. Двойной резерв. Цена считалась как база × (1 + PM) × (1 + риск 10%) × (1 + маржа 20%), а «цена с запасом» получалась умножением этого числа на отношение часов P85 к ожидаемым. Резерв учитывался дважды: плоские 10% и ещё запас по PERT. Подпись «≈P85» к тому же обещала вероятность, которую никто не калибровал.
  2. Название «маржа». Параметр margin_pct = 0,20 это множитель ×1,20, то есть наценка на себестоимость. Маржа при такой наценке 16,7%.
  3. Вводные не сохранялись. В версии хранилось только имя справочника рынка (2026Q4), ставки читались из файла. Правка файла задним числом меняла результат ручной правки и пересчёта.

Отдельно нужно было решить, как продавать работу: по фиксированной цене или Time & Materials. По словам владельца, малые и понятные проекты проще вести по фиксу, а проекты, где всё может поменяться много раз, и сложные заказчики лучше подходят для T&M. Поэтому выбор должен быть настройкой, а не зашитым правилом.

Решение

1. Один механизм резерва

ожидаемые часы        H  = Σ E (PERT)
разброс               σ  = √Σσᵢ²
резерв по PERT        Rp = z × σ                (z = 1,04, не калиброван)
минимальный резерв    Rf = floor × H            (floor = 10%)
резерв, часы          R  = max(Rp, Rf)
стоимость без резерва   = Σ(часы × ставка) × (1 + PM) × (1 + наценка)
стоимость с резервом    = стоимость без резерва × (1 + R / H)
  • Резерв добавляется один раз. Плоской надбавки «риск 10%» больше нет, её роль выполняет минимум.
  • Минимум страхует от того, что трёхточечная оценка не видит: смены объёма, переделок по замечаниям, слишком узких O и P (их разброс задан промптом, а не измерен) и того, что задачи ошибаются вместе, хотя σ считается как для независимых.
  • Стоимость резерва считается при том же составе ролей, что и основная работа (приближение).
  • Подпись «≈P85» убрана. Показывается честная формулировка: «резерв по разбросу оценок (PERT)» или «минимальный резерв», с обеими частями.
  • Результат содержит оба слагаемых (pert_reserve_hours, floor_reserve_hours), итоговый резерв, его долю и основание (reserve_basis: pert или floor).

2. Наценка вместо маржи

margin_pct переименован в markup_pct (значение 20% прежнее). Результат содержит implied_margin_pct = markup / (1 + markup) (16,7%), интерфейс показывает «наценка 20% (маржа 16,7%)». Режим целевой маржи не добавлялся.

3. Параметры

Параметр Значение по умолчанию Смысл
pm_pct 0,15 управление проектом, процент к себестоимости работ
markup_pct 0,20 наценка на себестоимость
reserve_floor_pct 0,10 минимальный резерв от ожидаемых часов
reserve_z 1,04 коэффициент при σ для резерва по PERT
default_engagement fixed_price модель оплаты по умолчанию

Прежние ключи risk_pct, margin_pct, confidence_z удалены. Конфигурация строгая, старый ключ в TOML вызывает ошибку при запуске, а не молча игнорируется.

4. Модель оплаты как выбор на каждую оценку

Модель выбирается при создании оценки (поле в форме и в API, значение по умолчанию из конфига) и хранится в версии. Она меняет подачу, а не трудозатраты: обе суммы всегда считаются из одних чисел.

Фиксированная цена Time & Materials
Что называем клиенту cost_with_reserve cost_expected
Резерв внутри цены, риск на подрядчике потолок бюджета (cap = cost_with_reserve), его стоит закрепить в договоре
Часы в заголовке с резервом ожидаемые, потолок в часах отдельно
Ставки не нужны ставка клиента по ролям: ставка × (1 + PM) × (1 + наценка)
  • Смена модели у готовой оценки это POST /api/estimates/{id}/engagement: новая версия с источником reprice, без обращения к модели, числа не пересчитываются. Повтор той же модели новой версии не создаёт.
  • Ответы на вопросы, пересчёт и ручная правка сохраняют модель; пересчёт может сменить её явно.
  • Сверка с рынком всегда сравнивает цену с резервом: ориентиры рынка это итоговые цены проектов.

5. Снимок вводных

В результат расчёта (price.inputs) записываются ставки по ролям, pm_pct, markup_pct, reserve_floor_pct, reserve_z и шаг округления. Ручная правка пересчитывает цену по этому снимку (price_with), а не по текущему файлу ставок и не по текущим настройкам. Сверка с рынком при этом использует ориентир и допуск из прежней сверки. Тест это проверяет: после смены наценки в настройках правка старой оценки сохраняет прежнюю наценку, а новая оценка берёт новую.

Числа

Пример из документа с рыночными данными (РФ, шаг округления 1 000 ₽):

Было Стало
Без резерва не показывалось 336 000 ₽
Цена с резервом 370 000 ₽ (плоские 10%) 370 000 ₽ (минимум 10%)
«С запасом P85» 397 000 ₽ (резерв дважды) убрано
Маржа при наценке 20% называлась «маржа 20%» 16,7%

Чувствительность к минимальному резерву (тот же проект, σ = 10 ч, резерв по PERT 7,2%):

Минимум Цена с резервом Основание
0% 361 000 ₽ PERT
10% 370 000 ₽ минимум
15% 387 000 ₽ минимум
20% 404 000 ₽ минимум
25% 421 000 ₽ минимум

Более неопределённый проект (те же вероятные часы, пессимистичные оценки в 4 раза выше): ожидаемые часы 195,3, σ = 29,5 ч, резерв по PERT 15,7% выше минимума и становится основанием; без резерва 454 000 ₽, с резервом 526 000 ₽.

Что взято из статьи FITTIN

Прислана владельцем: Time & Material vs Fix Price: что выбрать в 2026, 3 июня 2026. Это маркетинговый материал подрядчика с собственной платформой: его цены и тарифы нигде не использованы. Учтены только общие рассуждения.

Мысль статьи Что сделано
Выбор зависит от зрелости описания работ: фикс требует зрелого ТЗ, T&M требует вовлечённого заказчика Выбор оставлен человеку и вынесен в настройку; подсказка по признакам отложена (см. ниже)
Типичная ошибка T&M: нет потолка бюджета В T&M показывается потолок и совет закрепить его в договоре
В T&M договор содержит ставки по ролям, оценку задач и отчёт по часам Таблица ставок клиента по ролям и оценка по задачам в часах
Лучше всего работает гибрид: фикс на понятный запуск, T&M на развитие и эксперименты Не реализовано, записано как следующий шаг
Буфер на риск в фиксе у них 15–25%, выше при неясном ТЗ Это данные одного подрядчика. Наш минимум 10% не менялся, но параметр reserve_floor_pct позволяет поднять его без правки кода (таблица выше)
Fixed Price и T&M для типовых аудитов и ТЗ, T&M для исследований и MVP с открытым составом Войдёт в подсказку по признакам

Последствия

  • Ломающее изменение API: поля price.cost и price.cost_confident заменены на cost_expected, cost_with_reserve, reserve_cost и другие; добавлены engagement, result.quote, price.inputs. Старых развёртываний нет, поэтому миграция данных не писалась: результаты, сохранённые прежней версией, новый код не прочитает.
  • Миграция 0002_engagement добавляет колонку estimate_versions.engagement (по умолчанию fixed_price). Позже, до первой установки, миграция схлопнута в 0001_initial (см. раздел 13.9 архитектуры).
  • В каждой версии теперь хранится снимок вводных, версия растёт на несколько килобайт JSON.
  • Интерфейс: поле «Как продаём» в форме, переключатель модели на странице оценки, ставки клиента в таблице по ролям, модель рядом с суммой в истории.

Отложено

  1. Гибрид по фазам (фикс на понятную часть, T&M на неопределённую): потребует признака модели у задачи и раздельного расчёта резерва. Статья называет это основным рабочим сочетанием.
  2. Подсказка о модели по признакам (ясность объёма, вероятность изменений, вовлечённость заказчика): нужны новые поля на шаге уточнения и данные о проектах. Пока решает человек.
  3. Эмпирическая калибровка минимума и z: после 10–15 закрытых проектов заменить 10% и 1,04 квантилем отношения факта к ожидаемым часам (например, 80-м процентилем). Механизм не меняется, меняется источник числа.
  4. Разные минимумы для фикса и T&M, график платежей (30/40/30), потолок на спринт или месяц: не моделируются.
  5. Режим целевой маржи вместо наценки.