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

125 lines
14 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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. **Режим целевой маржи** вместо наценки.