125 lines
14 KiB
Markdown
125 lines
14 KiB
Markdown
# ADR-0001: политика резерва, наценка и модель оплаты (фикс или T&M)
|
||
|
||
**Дата:** 31 октября 2026 · **Статус:** принято и реализовано
|
||
**Основание:** [разбор ревью v2](../estimator-architecture-review-v2-response.md), замечания 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](https://fittin.ru/blog/tm-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. **Режим целевой маржи** вместо наценки.
|