Init Project Flexly Estimator
This commit is contained in:
@@ -0,0 +1,124 @@
|
||||
# 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`).
|
||||
- В каждой версии теперь хранится снимок вводных, версия растёт на несколько килобайт JSON.
|
||||
- Интерфейс: поле «Как продаём» в форме, переключатель модели на странице оценки, ставки клиента в таблице по ролям, модель рядом с суммой в истории.
|
||||
|
||||
## Отложено
|
||||
|
||||
1. **Гибрид по фазам** (фикс на понятную часть, T&M на неопределённую): потребует признака модели у задачи и раздельного расчёта резерва. Статья называет это основным рабочим сочетанием.
|
||||
2. **Подсказка о модели по признакам** (ясность объёма, вероятность изменений, вовлечённость заказчика): нужны новые поля на шаге уточнения и данные о проектах. Пока решает человек.
|
||||
3. **Эмпирическая калибровка минимума и z:** после 10–15 закрытых проектов заменить 10% и 1,04 квантилем отношения факта к ожидаемым часам (например, 80-м процентилем). Механизм не меняется, меняется источник числа.
|
||||
4. **Разные минимумы для фикса и T&M**, график платежей (30/40/30), потолок на спринт или месяц: не моделируются.
|
||||
5. **Режим целевой маржи** вместо наценки.
|
||||
@@ -0,0 +1,67 @@
|
||||
# ADR-0002: НДС как слой показа поверх цен без НДС
|
||||
|
||||
**Дата:** 31 октября 2026 · **Статус:** принято и реализовано; режим налогообложения продавца не уточнён (см. «Открыто»)
|
||||
**Основание:** вопрос владельца «нужны ли net и gross»; ответ: счёт выставляет компания, зарегистрированная в РФ
|
||||
**Затрагивает:** `pricing/quote.py`, `market/check.py`, `domain/models.py`, API оценок, интерфейс, миграция `0003_vat_rate`
|
||||
**Связано:** [ADR-0001](0001-reserve-policy-and-engagement.md)
|
||||
|
||||
## Контекст
|
||||
|
||||
Калькулятор считает стоимость работ, наценку и резерв. НДС не часть стоимости работ: его ставка зависит от того, кто выставляет счёт, кому и в каком налоговом режиме. При этом клиент платит сумму с НДС, а ориентиры рынка в источниках нередко приведены с НДС без пометки. Если сравнивать нашу цену без НДС с ориентиром с НДС 22%, ошибка почти равна допуску сверки (±25%), и вердикт «выше» или «ниже рынка» может быть ложным.
|
||||
|
||||
## Решение
|
||||
|
||||
1. **Всё считается без НДС (net):** ставки, наценка, резерв, сверка с рынком, история. Калькулятор НДС не знает.
|
||||
2. **НДС это слой показа** над итоговыми суммами. Режимов два: «без НДС» (ставка 0) и «НДС сверху» (ставка из списка). Режима «цена уже включает НДС» нет: цена называется без НДС, к оплате получается `net × (1 + ставка)`.
|
||||
3. **Ставка выбирается на каждую оценку** и хранится в версии (колонка `vat_rate`, как дробь: 0,22 = 22%). Значение по умолчанию берётся из настроек по региону клиента **в момент создания** и дальше не меняется вместе с настройками.
|
||||
4. **Допустимые ставки ограничены списком** из конфигурации (`[pricing.vat] choices` плюс 0 и значения по умолчанию), чтобы опечатка вроде 0,2 вместо 0,22 не попадала в договор. Остальные ставки добавляются правкой конфигурации.
|
||||
5. **Смена ставки у готовой оценки** (`POST /api/estimates/{id}/vat`) это новая версия `reprice` без обращения к модели и без пересчёта, так же как смена модели оплаты. Запрос на то, что уже стоит, версию не создаёт. Модель оплаты и НДС меняются независимо друг от друга через один общий механизм.
|
||||
6. **Сверка с рынком приводит ориентиры к цене без НДС.** У ориентира есть признак `includes_vat` и `vat_rate`; ориентир с НДС делится на `1 + vat_rate`, результат помечается `normalized_from_gross`. Сравнивается всегда цена с резервом без НДС.
|
||||
|
||||
### Значения по умолчанию (настройка `[pricing.vat]`)
|
||||
|
||||
| Клиент | Ставка | Почему |
|
||||
|---|---|---|
|
||||
| РФ | 22% | продавец в РФ, плательщик НДС, общая ставка с 2026 года |
|
||||
| ЕС | 0% (без НДС) | услуга иностранному заказчику не облагается российским НДС |
|
||||
|
||||
Это умолчание, а не правило: правильная ставка зависит от режима продавца. Значения «по региону» меняются в конфигурации (например, `ru = 0.0` для продавца, который НДС не платит).
|
||||
|
||||
### Что проверено на дату решения
|
||||
|
||||
| Факт | Источник |
|
||||
|---|---|
|
||||
| Общая ставка НДС в РФ с 1 января 2026 года 22%; порог дохода для освобождения от НДС на УСН снижен | [buh.ru](https://buh.ru/articles/chto-budet-s-nds-v-2026-godu-povyshenie-stavki-umenshenie-limita-dokhodov-dlya-usn-lgoty-osvobozhden.html) |
|
||||
| На УСН со специальными ставками 5% и 7% входной НДС к вычету не принимается | [ppt.ru, позиция Минфина](https://ppt.ru/obzory/minfin/pozitsiya-minfina-rf-o-nds-dlya-usn-v-2026-godu-kogda-platit-kakie-stavki-i-kto-osvobozhden) |
|
||||
| Место реализации услуг иностранному заказчику за пределами РФ, российский НДС не возникает | [Хабр](https://habr.com/ru/posts/1019948) |
|
||||
|
||||
Ставки НДС страны ЕС для продавцов не из РФ и налоговые льготы для ИТ-компаний не проверялись и не моделируются.
|
||||
|
||||
## Числа (пример из документа с рыночными данными, РФ, шаг округления 1 000 ₽)
|
||||
|
||||
| | Без НДС | НДС 22% | С НДС |
|
||||
|---|---|---|---|
|
||||
| Фиксированная цена | 370 000 ₽ | 81 400 ₽ | **451 400 ₽** |
|
||||
| T&M, ожидаемая стоимость | 336 000 ₽ | 73 920 ₽ | **409 920 ₽** |
|
||||
| T&M, потолок бюджета | 370 000 ₽ | 81 400 ₽ | **451 400 ₽** |
|
||||
|
||||
Ориентир рынка 400–600 тыс. ₽ без НДС. Если бы источник дал 488–732 тыс. ₽ с НДС 22%, то после приведения это те же 400–600 тыс. ₽ без НДС; цена без НДС 340 000 ₽ при этом попадает в рынок (коридор 300–750 тыс. ₽), тогда как без приведения она выглядела бы «ниже рынка» (нижняя граница 366 тыс. ₽).
|
||||
|
||||
## Что намеренно не делается
|
||||
|
||||
- **Налоги самого продавца:** налог на прибыль, УСН, страховые взносы, налоги на зарплату. Взносы уже входят в себестоимость часа, если ставка выведена из зарплаты. Остальное не меняет цену клиента, а лишь определяет, какая наценка нужна продавцу.
|
||||
- **Определение льгот и режима** (освобождения для ИТ, реестр отечественного ПО, УСН с НДС или без): это зависит от предмета договора и статуса компании, решает бухгалтер или юрист. Сервис только позволяет выбрать «Без НДС» или ставку.
|
||||
- **Валюта и расчёты с иностранным клиентом:** в сервис это не входит.
|
||||
|
||||
## Последствия
|
||||
|
||||
- Миграция `0003_vat_rate` добавляет колонку `estimate_versions.vat_rate` (по умолчанию 0).
|
||||
- В ответе API: `vat_rate` у оценки, `quote.vat_rate`, `quote.amount_gross`, `quote.cap_gross`; в бенчмарке `includes_vat`, `vat_rate`; в сверке `normalized_from_gross`.
|
||||
- В справочнике рынка у ориентиров `includes_vat = false` с пометкой: источники не уточняют, считаем без НДС. **Это допущение нужно проверить**, пока оно не подтверждено.
|
||||
- В интерфейсе: поле «НДС» в форме, строка «К оплате с НДС», переключатель ставки на странице оценки, пояснение в карточке сверки.
|
||||
|
||||
## Открыто
|
||||
|
||||
1. **Режим налогообложения продавца** (ОСНО, УСН с НДС 22%, УСН со ставками 5% или 7%, УСН без НДС). От него зависят умолчание «по региону» и то, нужно ли учитывать невозвращаемый входной НДС в себестоимости.
|
||||
2. **Режим «цена фиксирована с НДС».** Если у клиента бюджет задан с НДС, выручка продавца равна `gross / (1 + ставка)`, и наценка фактически падает. Это ограничение стоит показывать как предупреждение (сколько остаётся наценки), но пока не сделано.
|
||||
3. **НДС в ориентирах рынка:** по каждому источнику выяснить, с НДС или без, и проставить флаги.
|
||||
Reference in New Issue
Block a user