Init Project Flexly Estimator

This commit is contained in:
Alexey Dudin
2026-11-03 09:37:44 +03:00
commit 447464c16c
160 changed files with 12779 additions and 0 deletions
+11
View File
@@ -0,0 +1,11 @@
# Documentation
1. [estimator-architecture.md](estimator-architecture.md): decisions, layers, structure, config, ports, flow, plan
2. [estimator-web-ui.md](estimator-web-ui.md): UI on HTMX + Jinja, in-process API client, screens, security
3. [bot-estimation-market-data.md](bot-estimation-market-data.md): market data collection, sources, analytics (snapshot 2026-10-30), worked examples
Market figures in (3) are starting priors from public, mostly marketing, sources. Replace them with plan/fact data as projects close.
4. [estimator-architecture-review-v2.md](estimator-architecture-review-v2.md): внешнее архитектурное ревью и план развития v2 (Engine + Domain Packs, экономическая модель, неопределённость, RAG и калибровка). Это предложения, не утверждённая спецификация; статусы в нём даны по документам, а не по коду
5. [estimator-architecture-review-v2-response.md](estimator-architecture-review-v2-response.md): разбор этого ревью: что принимаем, что корректируем, что откладываем, порядок работ и два открытых вопроса
6. [adr/0001-reserve-policy-and-engagement.md](adr/0001-reserve-policy-and-engagement.md): решение по резерву, наценке, модели оплаты (фикс или T&M) и снимку вводных, с числами и чувствительностью
7. [adr/0002-vat-layer.md](adr/0002-vat-layer.md): НДС как слой показа поверх цен без НДС, ставки по умолчанию для РФ и ЕС, приведение ориентиров рынка, что проверено и что открыто
@@ -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. **Режим целевой маржи** вместо наценки.
+67
View File
@@ -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. **НДС в ориентирах рынка:** по каждому источнику выяснить, с НДС или без, и проставить флаги.
+552
View File
@@ -0,0 +1,552 @@
# Сервис оценки трудозатрат и стоимости: сбор рыночных данных по разработке ботов
**Версия:** 1.0 · **Дата снимка рынка:** 30 октября 2026 · **Охват:** РФ и ЕС/Великобритания · **Тип работ:** Telegram-боты, боты для сайта, мультиканальные боты, ИИ-агенты
---
## 0. Как читать документ
| Раздел | Что внутри |
|---|---|
| 1 | Принцип: что считает LLM, а что код |
| 2 | Слои данных и откуда их брать |
| 3 | Карта источников РФ и ЕС с оценкой надёжности |
| 4 | Процесс сбора (ETL) шаг за шагом |
| 5 | Схема данных и нормализация |
| 6 | Текущая аналитика рынка (снимок на 30.10.2026) |
| 7 | Сквозные примеры расчёта (РФ и ЕС) |
| 8 | Калибровка, контроль качества, обновление |
| 9 | Юридические риски сбора данных |
| 10 | План внедрения |
| Приложение | Список использованных источников |
**Важное замечание о достоверности.** Все рыночные цифры в разделе 6 взяты из открытых публикаций, найденных 30.10.2026. Большинство из них маркетинговые материалы вендоров и агентств: верхние границы у них завышены, нижние занижены, а методика почти нигде не раскрыта. Поэтому они годятся как стартовые ориентиры (приоры), но не как финальная истина. Реальную цену сервис должен выводить из ваших собственных сделок и план/факта (раздел 8).
---
## 1. Принцип работы
```
ТЗ клиента ─► Агент (LLM): уточнение → декомпозиция → оценка часов (O/M/P) → критик
│
Справочник рынка ◄───┤ (ставки, эталонные задачи, коэффициенты каналов)
▼
Детерминированный код: PERT, ставки, PM, наценка, резерв, налоги, курс валют
▼
Смета: диапазон «от и до», допущения, версия
```
- **LLM** понимает текст: разбивает работу на задачи, оценивает часы, находит аналоги.
- **Код** считает деньги. Расчёт воспроизводим, проверяем и объясним клиенту.
- **Справочник рынка** (этот документ) поставляет ставки, диапазоны цен и коэффициенты для сверки: «наша смета в границах рынка или выбивается».
---
## 2. Какие данные нужны (слои)
| Слой | Что хранить | Зачем | Источники | Надёжность |
|---|---|---|---|---|
| A. Цены проектов | Итоговая цена за типовой проект (бот с одним каналом, ИИ-агент, мультиканал) | Сверка итоговой цифры сметы с рынком | Прайсы агентств, обзоры, публичные закупки, кейсы | Низкая–средняя |
| B. Ставки | Почасовые и дневные ставки по ролям и регионам | Вход для `price()` | Биржи фриланса, вакансии, зарплатные обзоры, агентские прайсы | Средняя |
| C. Трудозатраты | Часы на типовые задачи (RAG, CRM-интеграция, адаптер канала) | Калибровка оценок LLM | Ваша история, открытые кейсы, таймтрекеры | Высокая, если ваши |
| D. Эксплуатация | Хостинг, токены LLM, поддержка, платные API каналов | Строка «run» в смете | Прайсы провайдеров, вендорные калькуляторы | Высокая |
| E. Коэффициенты | Мультиканальность, срочность, комплаенс (GDPR, 152-ФЗ) | Корректировки | Ваша история, экспертные оценки | Средняя |
| F. Курсы и налоги | Курс ЦБ РФ / ECB, НДС, взносы | Пересчёт между РФ и ЕС | ЦБ РФ, ECB (API) | Высокая |
Приоритет по ценности: **C (ваша история) > B > D > A > E**. Слой C всегда должен постепенно вытеснять внешние источники.
---
## 3. Карта источников
### 3.1. Россия
| Источник | Что даёт | Тип | Надёжность | Замечания |
|---|---|---|---|---|
| Обзоры вендоров конструкторов (BotHelp и аналоги) | Градация цен по способам создания, цены по каналам | Маркетинг вендора | Низкая–средняя | Заинтересованы занижать цену конструктора и завышать цену разработки |
| Habr Career (вакансии) | Зарплатные вилки разработчиков ботов | Вакансии | Средняя | Пересчёт зарплаты в ставку: см. 5.3 |
| hh.ru (вакансии, API) | Зарплатные вилки, объём спроса | Вакансии | Средняя | Есть открытое API для вакансий; проверьте текущие условия |
| FL.ru, Kwork, Habr Freelance | Нижний сегмент цен, сроки | Биржи | Средняя для нижнего сегмента | Сильно искажены демпингом |
| Workspace.ru (каталог подрядчиков) | Диапазоны цен и количество специалистов | Каталог | Средняя | Цены заявлены исполнителями |
| Статьи на vc.ru, Sostav, Habr | Кейсы с реальными сметами | Блоги | Низкая–средняя | Часто реклама; ценны конкретные сметы с часами |
| Закупки (zakupki.gov.ru) | Реальные цены контрактов на чат-боты и мини-приложения | Госзакупки | Высокая для своего сегмента | Сегмент не равен коммерческому рынку |
| Ваши КП, договоры, акты | Фактические цены и часы | Внутренние | Максимальная | Главный источник |
### 3.2. ЕС и Великобритания
| Источник | Что даёт | Тип | Надёжность | Замечания |
|---|---|---|---|---|
| Прайсы и блоги агентств (Берлин, Лондон) | Цены запуска и эксплуатации | Маркетинг | Средняя | Часть публикует фиксированные тарифы, это ценно |
| Клатч-подобные каталоги (Clutch, GoodFirms) | Диапазон ставок и бюджетов проектов | Каталоги | Средняя | Самозаявленные данные |
| Фриланс-платформы (Upwork, Fiverr, Malt) | Ставки по сегментам, цена за проект | Биржи | Средняя | Fiverr: цена проекта в нижнем сегменте |
| Зарплатные обзоры (Glassdoor, StepStone, Indeed, Stack Overflow Survey) | Зарплаты, пересчёт в ставку | Опросы | Средняя | Нужна поправка на накладные расходы |
| Eurostat (стоимость рабочей силы) | Макроуровень стоимости труда по странам | Официальная статистика | Высокая | Для коэффициентов между странами |
| Публичные тендеры (TED, национальные порталы, например Hilma в Финляндии) | Фактические цены контрактов | Госзакупки | Высокая для своего сегмента | Крупные проекты, не малый бизнес |
| SaaS-платформы ботов (Intercom, Tidio, Crisp, Zendesk) | Цены подписок и каналов | Прайсы | Высокая | Нужны для строки эксплуатации и сравнения «build vs buy» |
| Прайс WhatsApp Business API (Meta) | Платная часть каналов | Официальный | Высокая | Модель тарификации менялась в 2025–2026, перепроверять каждый квартал |
Порталы и API в таблицах выше названы по моим знаниям, а не проверены в рамках этой сессии: перед внедрением проверьте доступность, условия использования и актуальность.
### 3.3. Как оценивать источник
Каждому источнику присваивайте вес `w ∈ [0, 1]`:
```
w = тип (внутренний 1.0, тендер 0.8, прайс провайдера 0.8, биржа 0.5, агентство 0.5, вендор-маркетинг 0.3)
× свежесть (≤3 мес 1.0, 3–12 мес 0.7, >12 мес 0.4)
× раскрытие (есть состав работ и часы 1.0, только цена 0.6)
```
Агрегация диапазонов идёт взвешенными перцентилями (раздел 5.4), а не простым средним.
---
## 4. Процесс сбора (ETL)
```
1. Поиск → 2. Сбор → 3. Извлечение → 4. Нормализация → 5. Валидация → 6. Хранение → 7. Агрегация → 8. Публикация в конфиг → 9. Обратная связь
```
### Шаг 1. Поиск источников
- Раз в квартал запускайте поисковые запросы по шаблонам: `«стоимость разработки telegram бота 2026»`, `«chatbot development cost 2026 Germany»`, `«AI agent development price EUR»`.
- Для каждого запроса сохраняйте URL, дату, заголовок. Новые домены добавляйте в реестр источников (раздел 5.1).
### Шаг 2. Сбор
- **Ручной сбор** для маркетинговых статей: открыть, выписать таблицы цен.
- **API** там, где оно есть (вакансии, курсы валют ЦБ/ECB).
- **Скрейпинг** только с соблюдением условий сайта и robots.txt (раздел 9). Сохраняйте сырой HTML и дату получения, чтобы можно было перепроверить.
### Шаг 3. Извлечение (LLM со структурированным выводом)
LLM читает страницу и возвращает JSON по схеме. Нельзя давать ему «додумывать»: пустые поля остаются `null`.
```python
from pydantic import BaseModel, Field
from typing import Optional, Literal
class PricePoint(BaseModel):
source_url: str
published: Optional[str] = None # дата публикации, ISO
region: Literal["RU", "EU", "UK", "OTHER"]
segment: str # "tg_single", "multichannel", "ai_agent", "site_bot", "mini_app"
provider_type: Literal["freelance", "constructor_expert", "agency", "custom", "saas"]
currency: str # "RUB", "EUR", "GBP", "USD"
price_min: Optional[float] = None
price_max: Optional[float] = None
unit: Literal["project", "hour", "day", "month"] = "project"
scope_note: Optional[str] = Field(None, description="Что входит в цену, дословно из источника, кратко")
hours_disclosed: Optional[float] = None
quote_verbatim: str = Field(description="Короткая цитата для проверки, до 15 слов")
```
Промпт для извлечения (ключевые правила):
1. Извлекай только то, что явно написано. Не пересчитывай валюты и не усредняй.
2. Если указана вилка, заполни `price_min` и `price_max`.
3. Если цена «от X», заполни `price_min`, `price_max = null`.
4. Различай разовую цену проекта и ежемесячную поддержку.
5. Верни `null`, если данных нет.
### Шаг 4. Нормализация
- Приведите валюту к базовой (например, EUR) по курсу на **дату публикации**, а не на сегодня.
- Приведите единицы: час, день (8 ч), проект.
- Определите, **с НДС или без**, и приведите к «без НДС».
- Приведите сегмент к вашему классификатору (раздел 5.2).
### Шаг 5. Валидация
Автоматические проверки:
- `price_min ≤ price_max`.
- Цена в разумных границах сегмента (например, бот на одном канале за 10 млн ₽ помечается как аномалия).
- Дубликаты (одна цифра переписана в разных блогах): сохраняйте оригинал, копии помечайте как `derived_from`.
- Ручная проверка 10–20% выборки на соответствие цитате.
### Шаг 6. Хранение
Postgres: сырые документы отдельно от нормализованных точек, чтобы можно было переизвлечь при смене схемы.
### Шаг 7. Агрегация
Считайте взвешенные перцентили (P25, P50, P75) по каждому сегменту, региону и типу исполнителя. Подробнее в 5.4.
### Шаг 8. Публикация в конфиг сервиса
Из агрегатов формируется версионируемый `market_config_YYYY_QN.json`: ставки, диапазоны проектов, коэффициенты. Смета ссылается на версию конфига, поэтому её можно воспроизвести.
### Шаг 9. Обратная связь
После каждого проекта фиксируйте план/факт часов и итоговую цену. Эти данные получают вес 1.0 и постепенно заменяют внешние приоры.
---
## 5. Схема данных и нормализация
### 5.1. Таблицы (Postgres)
```sql
CREATE TABLE source (
id SERIAL PRIMARY KEY,
url TEXT UNIQUE NOT NULL,
domain TEXT,
source_type TEXT CHECK (source_type IN
('internal','tender','provider_price','marketplace','agency','vendor_marketing','salary_survey','vacancy')),
region TEXT,
weight_base REAL, -- вес по типу
first_seen DATE,
tos_checked BOOLEAN DEFAULT FALSE
);
CREATE TABLE raw_document (
id SERIAL PRIMARY KEY,
source_id INT REFERENCES source(id),
fetched_at TIMESTAMPTZ,
published DATE,
content_hash TEXT,
body TEXT -- сырой текст или путь к архиву
);
CREATE TABLE price_point (
id SERIAL PRIMARY KEY,
raw_document_id INT REFERENCES raw_document(id),
region TEXT, segment TEXT, provider_type TEXT,
unit TEXT,
price_min NUMERIC, price_max NUMERIC, currency TEXT,
price_min_eur NUMERIC, price_max_eur NUMERIC, -- нормализовано, без НДС
fx_rate NUMERIC, fx_date DATE,
vat_included BOOLEAN,
hours_disclosed NUMERIC,
scope_note TEXT, quote_verbatim TEXT,
weight REAL,
derived_from INT REFERENCES price_point(id)
);
CREATE TABLE rate ( -- ставки по ролям
id SERIAL PRIMARY KEY,
region TEXT, role TEXT, level TEXT,
hourly_eur NUMERIC, basis TEXT, -- 'agency_billing' | 'freelance' | 'salary_derived'
source_id INT, observed DATE
);
CREATE TABLE task_benchmark ( -- эталонные задачи (слой C)
id SERIAL PRIMARY KEY,
task_type TEXT, -- 'tg_core','rag','crm_integration','channel_adapter','qa','deploy'
hours_o NUMERIC, hours_m NUMERIC, hours_p NUMERIC,
actual_hours NUMERIC,
project_id INT, closed_at DATE
);
CREATE TABLE project_actual ( -- план/факт
id SERIAL PRIMARY KEY,
segment TEXT, region TEXT,
est_hours NUMERIC, actual_hours NUMERIC,
est_price_eur NUMERIC, actual_price_eur NUMERIC,
channels INT, has_ai BOOLEAN, has_crm BOOLEAN, closed_at DATE
);
```
### 5.2. Классификатор сегментов
| Код | Описание |
|---|---|
| `tg_single` | Сценарный Telegram-бот, один канал |
| `site_bot` | Бот для сайта (виджет чата) |
| `multichannel` | Два и более канала (Telegram, MAX, ВКонтакте, WhatsApp, сайт) |
| `ai_agent` | Бот с LLM, базой знаний (RAG), интеграциями |
| `mini_app` | Telegram Mini App |
| `run` | Эксплуатация (поддержка, хостинг, токены) |
### 5.3. Пересчёт зарплаты в часовую ставку
Из вилки зарплаты (в месяц) получается себестоимость часа для сметы:
```
ставка_час = зарплата_мес × (1 + взносы_и_налоги_работодателя) × (1 + накладные) / продуктивные_часы_мес
```
- `продуктивные_часы_мес` ≈ 120–130 (не 160: отпуск, встречи, простои). Это допущение, настраивается по вашему таймтрекеру.
- `накладные` 15–30%: офис, лицензии, управление. Допущение, откалибруйте под вашу компанию.
### 5.4. Агрегация
Взвешенный перцентиль по `weight`:
```python
import numpy as np
def weighted_percentile(values, weights, q):
idx = np.argsort(values)
v = np.array(values)[idx]
w = np.array(weights)[idx]
cum = np.cumsum(w) - 0.5 * w
cum /= w.sum()
return float(np.interp(q / 100, cum, v))
```
Если в сегменте меньше 5 точек, показывайте диапазон min–max и пометку «мало данных», а не перцентили.
---
## 6. Текущая аналитика рынка (снимок на 30.10.2026)
> Все цифры из публичных источников (приложение). Валюты не пересчитывались, чтобы не накладывать ошибки курса. Таблицы РФ в рублях, ЕС в EUR/GBP/USD, как в источниках.
### 6.1. Россия: градация по способу создания
| Способ | Срок | Цена |
|---|---|---|
| Конструктор самостоятельно | 1 день | от 0 ₽/мес |
| Конструктор + шаблон | 2–3 часа | от 0 ₽/мес |
| Эксперт на конструкторе | 3–7 дней | 20 000–60 000 ₽ |
| Агентство | 3–6 недель | 80 000–250 000 ₽ (+10–20 тыс. ₽/мес поддержка) |
| Кастомная разработка | 1,5–4 месяца | от 250 000 ₽ |
Источник: обзор BotHelp (обновлён сентябрь 2026). Для сравнения, фрилансерское предложение простого бота на бирже: около 6 500 ₽ за 3 дня.
### 6.2. Россия: цена по каналам при заказе у разработчика
| Канал | Цена |
|---|---|
| Telegram | от 80 000 ₽ |
| ВКонтакте | от 60 000 ₽ |
| MAX | от 80 000 ₽ |
| Все три вместе | от 200 000 ₽ |
Вывод: суммарно по отдельности 220 000 ₽, комплектом 200 000 ₽. Мультиканальность дешевле суммы лишь за счёт общего ядра, но не радикально.
### 6.3. Россия: ИИ-агент и рынок труда
- Кастомный ИИ-бот с подключением к LLM: от 200 000 ₽ за разработку, токены отдельно.
- Вакансия разработчика Telegram-ботов (Habr Career): 200 000–350 000 ₽ в месяц.
### 6.4. ЕС и Великобритания
| Сегмент | Цена | Источник |
|---|---|---|
| B2B-бот поддержки с ИИ и RAG, Берлин | 10 000–30 000 € запуск; FAQ-бот от 10 000 € за 4 недели | Kolonell, 09.2026 |
| Эксплуатация, Берлин | 230–2 000 €/мес при 500–10 000 диалогов/мес | Kolonell, 09.2026 |
| Дневная ставка ИИ-разработчика, Берлин | 500–800 € | Kolonell, 09.2026 |
| SME, Великобритания | 3 000–25 000 £; мультиканальный с CRM 18 000–25 000 £ | Softomate, 2026 |
| Крупное лондонское агентство | 25 000–100 000+ £ | Softomate, 2026 |
| Кастомный разговорный ИИ в Европе (с безопасностью и комплаенсом) | 40 000–150 000 $ и выше | CMARIX, 08.2026 |
| Немецкие агентства, кастомная разработка | 100–200 €/ч | xmethod.de через Qualimero |
### 6.5. Почасовые ставки по регионам (по обзорам агентств)
| Регион | Диапазон | Источники |
|---|---|---|
| Западная Европа | 80–170 $/ч или 90–200 $/ч | Space-O, GMTA |
| Восточная Европа | 40–80 $/ч | Space-O, GMTA |
| Северная Америка | 100–200 $/ч | Space-O |
Один обзор называет для Западной Европы **180–300 $/ч** и для AI-агентств **150–350 $/ч**. Это не ошибка, а другой уровень: расценка агентства «под ключ» (с управлением и маржой) против ставки разработчика. В конфиге обязательно храните поле `basis` (`agency_billing` или `freelance`), иначе ставки смешаются.
### 6.6. Глобальные ориентиры (для контекста)
| Источник | Вилка |
|---|---|
| Fiverr (маркетплейс) | 45–520 $ за проект, 47–315 $/ч |
| Space-O | 3 000 $ (простой) – 300 000+ $ (энтерпрайз) |
| RaftLabs | 4 500–12 000 $ (rule-based) – 72 000–210 000 $ (энтерпрайз-агент) |
| Один AI-агентский калькулятор | 15 000–45 000 $ за чатбот с одним сценарием и RAG |
Расхождения в 10–100 раз между источниками объясняются не ошибкой, а разным сегментом (виджет и энтерпрайз) и типом исполнителя. Поэтому слой `segment × provider_type` обязателен.
### 6.7. Эксплуатация и платный слой каналов
- WhatsApp Business API: у Meta отдельная и менявшаяся модель тарификации, перепроверять каждый квартал.
- SaaS-платформы часто берут за WhatsApp дополнительно несколько десятков евро в месяц (например, 49–99 €/мес у разных вендоров).
- Для кастомных ботов: хостинг (VPS от нескольких сотен рублей), токены LLM, мониторинг, поддержка 10–20 тыс. ₽/мес в РФ.
> **НДС.** Сверка сравнивает цены без НДС. Источники рыночных цен часто не указывают, с НДС ли они; у каждого ориентира в справочнике есть признак `includes_vat` (сейчас везде `false` как допущение, его нужно подтвердить по источникам). Подробности в [ADR-0002](adr/0002-vat-layer.md).
### 6.8. Сводные ориентиры (для сверки итога сметы)
| Сегмент | РФ (разработчик/агентство) | ЕС/Великобритания |
|---|---|---|
| Простой бот, один канал | 20–80 тыс. ₽ (эксперт) – 80+ тыс. ₽ (агентство) | единицы тысяч € (FAQ-бот от ~10 тыс. € у агентства) |
| Мультиканал (3 канала) | от ~200 тыс. ₽ | ~18–25 тыс. £ (с CRM) |
| ИИ-агент с RAG и CRM | от ~200 тыс. ₽ и выше | 10–30 тыс. € (Берлин), 40–150 тыс. $ (комплаенс-уровень) |
| Эксплуатация | 10–20 тыс. ₽/мес (поддержка) | 230–2 000 €/мес |
**Ключевые наблюдения:**
1. Разрыв РФ и ЕС по сопоставимому проекту порядка 5–10 раз, но он зависит от сегмента и типа исполнителя.
2. Цену определяют интеграции (CRM, платежи, RAG) и комплаенс, а не сам бот.
3. Эксплуатация за 2–3 года сопоставима с разработкой, её нужно выводить отдельной строкой.
4. Конструкторы и SaaS радикально снижают цену простых ботов, поэтому в смете нужен вариант «build vs buy».
---
## 7. Сквозные примеры расчёта
> Обновлено 31.10.2026: расчёт резерва и наценки приведён к [ADR-0001](adr/0001-reserve-policy-and-engagement.md). Прежняя версия складывала плоские 10% и запас P85 и давала 397 000 ₽, эта цифра убрана.
### Задача
Мультиканальный ИИ-агент: Telegram + MAX + ВКонтакте, база знаний (RAG), интеграция с amoCRM, тестирование, деплой.
### 7.1. Декомпозиция и оценка часов (результат работы агента)
| # | Задача | Роль | O | M | P | E = (O+4M+P)/6 | σ = (P−O)/6 |
|---|---|---|---|---|---|---|---|
| 1 | Аналитика, ТЗ | analyst | 8 | 12 | 20 | 12,7 | 2 |
| 2 | Ядро бота (Telegram) | backend | 16 | 24 | 40 | 25,3 | 4 |
| 3 | RAG и база знаний | backend | 20 | 32 | 56 | 34,0 | 6 |
| 4 | Интеграция amoCRM | backend | 8 | 16 | 32 | 17,3 | 4 |
| 5 | Адаптер MAX | backend | 8 | 12 | 20 | 12,7 | 2 |
| 6 | Адаптер ВКонтакте | backend | 8 | 12 | 20 | 12,7 | 2 |
| 7 | Тестирование | qa | 12 | 20 | 36 | 21,3 | 4 |
| 8 | Деплой и мониторинг | devops | 4 | 8 | 16 | 8,7 | 2 |
| | **Итого** | | | | | **144,7 ч** | **√Σσ² = 10 ч** |
- Ожидаемые часы: **144,7**.
- Резерв по разбросу оценок (PERT): 1,04 × 10 = **10,4 ч** (7,2%).
- Минимальный резерв: 10% × 144,7 = **14,5 ч**.
- Берётся большее, то есть **14,5 ч**, часы с резервом **159,1**. Это запас по разбросу оценок, а не калиброванный квантиль (подробности в [ADR-0001](adr/0001-reserve-policy-and-engagement.md)).
### 7.2. Расчёт стоимости, профиль РФ
Ставки (иллюстративные допущения, калибруются по вашим данным): analyst 1 500, backend 1 800, qa 1 200, devops 1 800 ₽/ч. PM 15%, риск 10%, маржа 20%.
| Роль | Часы | Ставка | Сумма |
|---|---|---|---|
| analyst | 12,7 | 1 500 | 19 000 |
| backend | 102,0 | 1 800 | 183 600 |
| qa | 21,3 | 1 200 | 25 600 |
| devops | 8,7 | 1 800 | 15 600 |
| **База** | | | **243 800 ₽** |
```
без резерва: 243 800 × 1,15 (PM) × 1,20 (наценка) ≈ 336 444 ≈ 336 000 ₽
с резервом: 336 444 × (1 + 14,5 / 144,7) ≈ 370 088 ≈ 370 000 ₽
```
Для **фиксированной цены** называется 370 000 ₽ (резерв внутри). Для **Time & Materials** называется ожидаемая стоимость 336 000 ₽ и потолок бюджета 370 000 ₽. Наценка 20% даёт маржу 16,7%.
**Сверка с рынком (6.2 и 6.3):** три канала от 200 тыс. ₽ плюс ИИ-агент от 200 тыс. ₽ у разработчика, то есть около 400 тыс. ₽. Смета попадает в рынок.
### 7.3. Расчёт стоимости, профиль ЕС
Те же часы, ставки (допущения в пределах ставок из 6.4 и 6.5): analyst 75, backend 85, qa 60, devops 90 €/ч.
| Роль | Часы | Ставка | Сумма |
|---|---|---|---|
| analyst | 12,7 | 75 | 950 |
| backend | 102,0 | 85 | 8 670 |
| qa | 21,3 | 60 | 1 280 |
| devops | 8,7 | 90 | 780 |
| **База** | | | **11 680 €** |
```
без резерва: 11 680 × 1,15 × 1,20 ≈ 16 118 €
с резервом: 16 118 × (1 + 14,5 / 144,7) ≈ 17 730 €
```
Сверка: Берлин 10–30 тыс. €, Великобритания для мультиканала с CRM 18–25 тыс. £. Смета в границах рынка.
### 7.4. Строка эксплуатации
Для ЕС при 2 000 диалогов/мес: 350–730 €/мес (Берлин). Для РФ: поддержка 10–20 тыс. ₽/мес плюс токены и хостинг. В КП это отдельная строка, а годовая стоимость владения считается как разработка + 12 × эксплуатация.
### 7.5. Код проверки «смета против рынка»
```python
from math import sqrt
def price(tasks, rates, pm=0.15, markup=0.20, floor=0.10, z=1.04):
hours = sum((t["o"] + 4*t["m"] + t["p"]) / 6 for t in tasks)
sigma = sqrt(sum(((t["p"] - t["o"]) / 6) ** 2 for t in tasks))
base = sum(((t["o"] + 4*t["m"] + t["p"]) / 6) * rates[t["role"]] for t in tasks)
expected = base * (1 + pm) * (1 + markup)
reserve = max(z * sigma, floor * hours) # one reserve, added once
return {
"hours": round(hours, 1),
"hours_with_reserve": round(hours + reserve, 1),
"cost_expected": round(expected),
"cost_with_reserve": round(expected * (1 + reserve / hours)),
}
def market_check(cost, bench_min, bench_max, tolerance=0.25):
lo, hi = bench_min * (1 - tolerance), bench_max * (1 + tolerance)
if cost < lo: return "ниже рынка: проверьте, не забыты ли задачи"
if cost > hi: return "выше рынка: проверьте допущения, ставки и маржу"
return "в границах рынка"
```
---
## 8. Калибровка, качество и обновление
### 8.1. Калибровка оценок LLM
LLM систематически занижает интеграции, тестирование и правки. Лечится коэффициентом по типу задачи:
```
k(task_type) = медиана(actual_hours / estimated_hours) по закрытым проектам
итоговая оценка = E × k
```
Пока данных мало (менее 5 закрытых проектов на тип), используйте консервативный `k = 1,2–1,3` на интеграции и QA. Это допущение, замените его статистикой.
### 8.2. Метрики качества сервиса
| Метрика | Формула | Цель |
|---|---|---|
| MAPE по часам | mean(|план − факт| / факт) | < 25% после 20 проектов |
| Покрытие диапазона | доля проектов, где факт попал в [P10, P90] | ≈ 80% |
| Смещение | mean((план − факт) / факт) | около 0 |
Сверка с рынком (доля смет в границах ориентиров) **не является метрикой качества**: если выдавать её за точность, оценки начнут подгонять под чужие прайсы. Она остаётся предупреждением в самой оценке (решение по [разбору ревью](estimator-architecture-review-v2-response.md)).
### 8.3. Расписание обновления
| Данные | Частота | Причина |
|---|---|---|
| Курсы валют | ежедневно (API) | Волатильность |
| Прайсы платных API каналов (WhatsApp, LLM) | ежеквартально | Тарифы меняются |
| Ставки и цены проектов | ежеквартально | Рынок и инфляция |
| Коэффициенты калибровки | после каждого закрытого проекта | Обратная связь |
| Реестр источников | раз в полгода | Источники умирают |
### 8.4. Антипаттерны
- Усреднять цены вендора, агентства и биржи в одну цифру.
- Смешивать ставку разработчика и агентскую расценку (поле `basis`).
- Брать курс на сегодня для старой публикации.
- Показывать клиенту одну цифру без диапазона и допущений.
- Хранить только итог, а не версию конфига и допущения: смета перестаёт воспроизводиться.
---
## 9. Юридические риски сбора данных
Не является юридической консультацией, это контрольный список для проверки.
1. **Условия использования сайтов и robots.txt.** Перед автоматическим сбором проверьте ToS, ведите флаг `tos_checked` в таблице `source`.
2. **Права на базы данных.** В ЕС действует особое (sui generis) право изготовителя базы данных, массовое копирование каталогов может его нарушать. Храните и публикуйте факты (цена, дата, источник), а не копии текстов; цитаты ограничивайте короткими фрагментами.
3. **Персональные данные.** Фрилансеры и сотрудники в вакансиях и профилях это персональные данные. Для ЕС применяется GDPR, для РФ 152-ФЗ (включая локализацию). Храните агрегаты, а персональные поля не собирайте.
4. **Коммерческая тайна и NDA.** Данные ваших проектов и клиентов обезличивайте перед использованием в справочнике.
5. **Достоверность в КП.** Если вы ссылаетесь на «рыночные цены» в предложении клиенту, указывайте источник и дату, чтобы не вводить в заблуждение.
---
## 10. План внедрения
| Этап | Что делаем | Результат |
|---|---|---|
| 1 (1–2 недели) | Реестр источников, ручной сбор 30–50 точек по таблицам раздела 3, схема БД | Первый `market_config` |
| 2 (2–3 недели) | LLM-извлечение в JSON, нормализация валют и НДС, валидация | Автоматизированный конвейер |
| 3 (1–2 недели) | Агрегация, `market_check` в сервисе, версионирование конфигов | Смета со сверкой с рынком |
| 4 (постоянно) | План/факт, калибровка `k`, метрики качества | Точность растёт с каждым проектом |
| 5 (опционально) | Парсеры бирж и вакансий (при наличии API и разрешении ToS), дашборд | Автообновление рынка |
---
## Приложение. Использованные источники (проверены 30.10.2026)
- BotHelp, «Сколько стоит чат-бот в 2026 году: реальные цены», обновлено 03.09.2026. Вендор конструктора, https://bothelp.io/ru/blog/skolko-stoit-razrabotka-chat-bota
- Habr Career, вакансия «Разработчик Telegram-ботов», https://career.habr.com/vacancies/1000103419
- FL.ru, услуга «Создание телеграм ботов», https://www.fl.ru/uslugi-freelancera/11087/sozdanie-telegramm-botov-5.html
- Kolonell, «AI Customer Service Chatbot Cost in Berlin in 2026», 06.09.2026, https://kolonell.com/en/blog/ai-customer-service-chatbot-cost-berlin-2026
- Softomate Solutions, «AI Chatbot Development Cost UK», https://www.softomatesolutions.com/ai-chatbot-development-cost-uk/
- CMARIX, «How Much Does AI Chatbot Development Cost in 2026?», 31.08.2026, https://www.cmarix.com/blog/ai-chatbot-development-cost/
- Qualimero, «Chatbot Costs 2026», https://qualimero.com/en/blog/chatbot-costs
- Space-O Technologies, «How Much Does It Cost to Develop an AI Chatbot in 2026?», https://www.spaceotechnologies.com/blog/ai-chatbot-development-cost/
- GMTA Software, «AI Chatbot Development Cost», https://www.gmtasoftware.com/blog/ai-chatbot-development-cost/
- RaftLabs, «Chatbot development cost in 2026», https://www.raftlabs.com/blog/chatbot-development-cost
- Fiverr, «How Much Does It Cost to Hire a Chatbot Developer in 2026?», 13.02.2026, https://www.fiverr.com/resources/guides/costs/chatbot-developer
- Boei, «10 Chatbot Pricing Plans Compared», https://boei.help/blog/chatbot-pricing-comparison-2026/
- Cost of Hiring an AI Agency 2026 (калькулятор), https://blog-aiagencycalc.pages.dev/cost-of-hiring-an-ai-agency-2026.html
**Напоминание:** источники выше преимущественно маркетинговые. Цифры из них являются стартовыми приорами, которые сервис должен заменять собственными данными по мере накопления закрытых проектов.
@@ -0,0 +1,48 @@
# Разбор архитектурного ревью v2
**Дата:** 31 октября 2026 · **Статус:** позиция по ревью. Вопрос про политику резерва решён ([ADR-0001](adr/0001-reserve-policy-and-engagement.md)), вопрос про данные завершённых проектов открыт
**Относится к:** [estimator-architecture-review-v2.md](estimator-architecture-review-v2.md)
Ниже текст разбора записан как есть, без правок.
---
## Что думаю про ревью
В целом оно полезное и в основном справедливое. Что-то из этого уже было у меня в списке ограничений, но три замечания я бы признал настоящими дефектами.
**Принимаю безоговорочно:**
1. **Наценка и маржа.** В калькуляторе `margin_pct` это множитель `×1.20`, то есть наценка 20%, а фактическая маржа около 16,7%. Название вводит в заблуждение. Исправление небольшое: переименовать в `markup_pct`, при желании добавить режим целевой маржи. Числа в эталонном примере при этом не меняются.
2. **Двойной резерв.** `cost_confident` я считаю как цену, уже включающую 10% риска, умноженную на отношение часов P85 к ожидаемым. Резерв выходит дважды. Плюс подпись «≈P85» обещает вероятность, которую никто не калибровал. Подпись надо смягчить, а политику резерва выбрать одну.
3. **Снимок вводных.** В версии я храню только имя версии справочника (`2026Q4`), а ставки лежат в файле, который можно отредактировать задним числом. Тогда старая оценка перестанет воспроизводиться, а ручная правка пересчитается по изменённым ставкам. Нужно класть в версию снимок ставок и параметров расчёта.
4. **Устаревшие шапки документов.** Исправил: в них стояло «реализация не начата».
**Согласен, но с поправкой:**
- **Domain Packs и каталог работ.** Направление верное, но делать реестр плагинов и композицию возможностей при одном домене и нуле завершённых проектов рано, можно угадать неверную абстракцию. Я бы взял дешёвую часть: вынести то, что сейчас зашито под ботов (тексты промптов, список сегментов, ключи ориентиров), в папку пакета с манифестом, один пакет `bots_ai`, без реестра. Второй домен покажет, чего не хватает.
- **Коды работ.** Самый сильный довод ревью, что RAG и калибровку надо делать после унификации работ. В моём конвейере у задач только свободные названия от модели, поэтому «коэффициент по типу задачи», как я планировал, считать не по чему. Нужно необязательное поле `work_item_code` и факты на уровне задач. Это меняет мой план: до RAG нужен этот шаг.
- **Режимы экспресс и подробная оценка.** Идея хорошая, сейчас её грубо заменяет флаг «продолжить с допущениями». Достаточно пометить результат «предварительная оценка», когда остались допущения.
- **Метрики.** Согласен, что «попадание в рынок» нельзя выдавать за точность, это подталкивает подгонять смету под чужие прайсы. Оставлю как предупреждение, а метрикой сделаю ошибку по часам и смещение. Это моя запись в разделе 8.2 документа с рыночными данными.
**Отложил бы:**
- **Очередь на Postgres.** Нужна только при нескольких репликах, в документах это уже записано как ограничение.
- **Роли `viewer/estimator/approver`, `tenant_id`, Monte Carlo, сценарии «эконом/база/консервативный», экспорт КП.** Всё разумно, но без данных о ваших проектах это проектирование вслепую. Монте-Карло без калибровки только добавит ложной точности, ревью само это признаёт.
- **Девять ADR.** Для вашего масштаба это много. Оформил бы короткие записи только для трёх решений, меняющих модель данных: экономика, снимки, коды работ.
**Чего в ревью не хватает:** нигде не сказано, что без фактических часов все предложенные улучшения (калибровка, рынок по контексту, Monte Carlo) работают на пустых данных. Главный рычаг точности это ввод плана и факта по задачам, и его я бы поставил раньше RAG.
Ещё одна ремарка: в ревью про пользователей UI сказано, что общего ключа мало. Для отдельных пользователей это уже не так (логины, раздельные рабочие пространства). Не хватает только `created_by` в БД: при общем пространстве сейчас не видно, кто создал оценку.
## Что предлагаю дальше
1. Небольшой пакет исправлений без споров: наценка вместо «маржи», один механизм резерва и честные подписи, снимок вводных и `created_by` в версии.
2. Поле `work_item_code` и ввод плана и факта по задачам в интерфейсе.
3. Потом RAG и калибровка.
4. Лёгкая версия пакета домена для ботов.
Нужно ваше решение по двум вопросам:
- **Резерв.** Какую политику берём: ожидаемая цена плюс плоские 10%, или диапазон от ожидаемой до P85 без плоской надбавки? От выбора зависят итоговые цены, у примера из документа 370 000 ₽ сдвинется.
- **Данные.** Есть ли у вас уже завершённые проекты с фактическими часами, пусть даже по этапам? Это определяет, будет ли калибровка работать со старта или начнётся с нуля.
+623
View File
@@ -0,0 +1,623 @@
# Flexly AI Estimator — архитектурное ревью и план развития v2
**Дата:** 30 октября 2026 г.
**Статус:** архитектурные рекомендации / proposal, **не** утверждённая спецификация реализации
**Область:** сервис оценки трудозатрат, стоимости и рисков проектов в экосистеме Flexly AI
**Цель:** эволюция существующего оценщика мультиканальных ботов в универсальный движок оценки программных и интеграционных проектов без переписывания готового ядра.
## 0. Документы и границы ревью
Рассмотрены следующие материалы:
1. [`estimator-architecture.md`](estimator-architecture.md) — архитектура, контракты, конфигурация, pipeline и статус реализации.
2. [`estimator-web-ui.md`](estimator-web-ui.md) — HTMX + Jinja2, UI/API, управление оценками и безопасность.
3. [`bot-estimation-market-data.md`](bot-estimation-market-data.md) — методика сбора рыночных данных, расчёты, PERT, план/факт.
4. [`README.md`](README.md) — состав документации.
**Важно о фактическом состоянии.** Заголовки проектных документов содержат старую формулировку «реализация не начата», но **раздел 13 `estimator-architecture.md` сообщает о завершении этапов 1–5**, тестировании на SQLite и PostgreSQL 16 и наличии 262 тестов. RAG, калибровка, MCP и рыночный ETL отмечены как не начатые. Эти статусы приводятся **со слов документа**: ревью исходного кода и независимый запуск тестов не выполнялись.
**Разделение фактов и предложений:** формулировки «уже реализовано / по документу» описывают имеющуюся документацию; «рекомендуется / предлагается / v2» — новые архитектурные решения, которые требуют принятия ADR и детализации спецификаций.
---
## 1. Executive summary
### Общая оценка
Основа оценщика хорошо подходит для развития. Сильные решения:
- **LLM декомпозирует и предлагает трудозатраты; Python считает деньги.** Денежные расчёты проверяемы и воспроизводимы.
- **Модульный монолит** с разделением `domain`, `agent`, `pricing`, `market`, `calibration`, `services`, `infra`.
- **REST как основной контракт**, MCP — тонкий адаптер к тем же use cases.
- **Immutable-версии смет** и фиксация рыночной конфигурации, модели и промптов.
- **Обучение на план/факте**, а не зависимость исключительно от публичных рыночных оценок.
- **HTMX + Jinja2** достаточно для первого рабочего интерфейса.
**Основная проблема:** предметная область ботов пока проходит через сегменты (`tg_single`, `site_bot`, `multichannel`, `ai_agent`, `mini_app`), коэффициенты каналов, шаблоны работ и рынок. Если расширять эту модель перечислением всё новых комбинированных сегментов, сложность будет расти непропорционально.
**Главная рекомендация:** оставить существующий универсальный `EstimateService`, но выделить **Estimator Engine + Domain Packs + библиотеку переиспользуемых Capabilities/Work Items**. Проект может состоять из возможностей разных доменов, а не принадлежать строго одному типу.
### Приоритетные изменения
| Приоритет | Изменение | Причина |
|---|---|---|
| **P0** | Универсальная предметная модель: `ProjectType`, `Capability`, `DomainPack`, `WorkItem` | Снять привязку к ботам до расширения RAG/БД |
| **P0** | Корректная экономическая модель: себестоимость, наценка, целевая маржа, налоги, внешние расходы | Предотвратить неверное ценообразование |
| **P0** | Пересмотреть учёт неопределённости, корреляций и резерва | Не выдавать неподтверждённый P85 и не учитывать риски дважды |
| **P1** | Каталог типовых работ, кросс-доменные зависимости, дедупликация WBS | Корректная смета смешанного проекта |
| **P1** | Рынок по сопоставимым характеристикам, не только по сегменту | Больше точности и объяснимости |
| **P1** | RAG + калибровка по план/факту с фильтрами контекста и доступа | Получить измеримое улучшение точности |
| **P1** | Надёжная PostgreSQL-очередь задач / worker | Масштабирование и устойчивость к рестартам |
| **P1** | Акторы, tenant scoping и права в UI/API | Подготовка к командной работе и нескольким клиентам |
| **P2** | Дополнительные Domain Packs, сценарии и экспорт КП | Расширение функциональности продукта |
---
## 2. Целевое позиционирование
**Не только «калькулятор цены бота», а движок предварительных технических и коммерческих оценок.**
Возможные потребители:
- Flexly AI Core: получение требований из Telegram, сайта/виджета и других каналов;
- собственный административный интерфейс оценщика;
- менеджер или пресейл-специалист;
- другие приложения по REST и, в перспективе, MCP.
Первоначальные направления специализации:
| Domain Pack | Примеры |
|---|---|
| `bots_ai` | Telegram/сайт/мультиканальность, RAG, LLM-агенты, CRM |
| `web` | лендинги, корпоративные сайты, каталоги, интернет-магазины |
| `software` | backend, личные кабинеты, SaaS, биллинг, API |
| `automation` | CRM/ERP-интеграции, ETL, автоматизация процессов |
Граница применения **первой расширенной версии** — прежде всего IT/цифровая разработка. Оценивание строительства, производства и иных не-IT отраслей потребует дополнительных моделей материалов, закупок, физических ресурсов, нормативов и рисков; текущая архитектура **не гарантирует** их поддержку без дальнейших расширений.
---
## 3. Целевая архитектура: Engine + Domain Packs
```text
Flexly AI channels / Admin UI / external consumers
|
REST API (OpenAPI)
|
EstimateService (use cases)
|
+-----------+-------------+-------------------+
| | |
Intake/Agent Pipeline Domain Registry Estimate Versions
| | |
| +-----------+-----------+ |
| | | | |
| bots_ai web software automation ...
| +-----------+-----------+ |
| | |
+--------- Capability / Work-Item Catalog ----+
|
Deterministic Pricing Engine
|
Market Benchmarks / Risks / RAG / Calibration
|
PostgreSQL + PGVector/BM25 + Audit
```
### 3.1. Что такое Domain Pack
Пакет предметной области — **описание специализации**, а не отдельный микросервис. Он определяет:
1. классификатор типов проектов и функциональных возможностей;
2. каталог типовых задач и зависимостей;
3. уточняющие вопросы и признаки недостаточности требований;
4. правила декомпозиции, полноты и исключения дублей;
5. допустимые роли/ресурсы, источники ставок и эталоны;
6. подсказки и инструкции для агентных шагов;
7. собственную версию и совместимость с общей схемой.
**Не превращать всё сразу в исполняемые Python-плагины.** Предпочтителен декларативный формат (TOML или YAML) с Pydantic-валидацией. Python-хуки разрешать только для предметно-специфичной логики, которой невозможно выразить декларативно. Плагины не должны вносить собственные формулы стоимости в обход `pricing`.
Пример **концептуальной** структуры (не готовая спецификация загрузчика):
```text
src/estimator/
├── domain/ # общее ядро контрактов
├── pricing/ # единая экономика и неопределённость
├── agent/ # универсальный pipeline
├── catalog/ # capabilities, work items, зависимости
├── domains/
│ ├── registry.py # поиск и проверка версий пакетов
│ ├── bots_ai/
│ │ ├── manifest.toml
│ │ ├── capabilities.yaml
│ │ ├── work_items.yaml
│ │ └── prompts/
│ ├── web/
│ ├── software/
│ └── automation/
├── market/ # рыночные данные и сопоставимость
├── calibration/ # фактические часы и статистика
├── rag/ # поиск аналогичных работ/проектов
├── services/
├── infra/
├── api/
├── web/
└── mcp/
```
### 3.2. Композиция возможностей, а не комбинаторика сегментов
Один проект может включать функциональность из нескольких доменов.
```yaml
# Иллюстративная структура входных данных; API v2 пока не утверждён.
project_type: ecommerce
capabilities:
- web.catalog
- web.checkout
- backend.auth
- integration.payment
- integration.crm
- ai.rag
- ai.chat_widget
region: ru
pricing_profile: agency_ru
```
Это лучше, чем заводить отдельные сегменты `ecommerce_with_ai_crm`, `ecommerce_with_ai_and_payments` и т. п.
### 3.3. Как избежать двойного учёта
Каталог должен различать:
- **Capability** — результат/функциональная возможность для заказчика;
- **Work Item** — конкретная работа для создания возможности;
- **Shared Work Item** — общая инфраструктура, аналитика, авторизация, CI/CD и др.;
- **Dependency** — обязательная работа или зависимость между работами;
- **Scope Boundary** — какие работы включены, исключены или уже существуют.
Например, `integration.crm` и `ai.chat_widget` могут использовать одну backend-платформу. Подсчёт выполняется по объединённому WBS с уникальными work items. Общее ядро нельзя суммировать дважды. Аналогично коэффициент за «ещё один канал» нельзя одновременно прибавлять, если адаптер канала уже представлен отдельной задачей — эта защита уже отмечена в текущем документе.
---
## 4. Предлагаемая предметная модель v2
Минимальные сущности и смысловые поля:
| Сущность | Содержание |
|---|---|
| `Project` / `Estimate` | владелец, исходные требования, тип проекта, выбранные capabilities |
| `EstimateVersion` | неизменяемая оценка, статус, снимки вводных и конфигураций |
| `DomainPackRef` | `id`, `version`, `schema_version`, хэш манифеста |
| `Capability` | стабильный код, описание результата, зависимости, критерии применимости |
| `WorkItem` | стабильный код каталога + ID экземпляра, WBS-позиция, роль, тип работы |
| `TaskEstimate` | O/M/P, базовый прогноз, источник эталона, степень неопределённости |
| `RiskEvent` | вероятность, денежное/временное воздействие, затронутые работы, стратегия обработки |
| `PricingProfile` | ставки/ресурсы, способ ценообразования, правила PM/маржи/налогов |
| `MarketBenchmark` | тип и состав проекта, регион, сложность, цена, базис и доказательства |
| `ProjectActual` | фактические часы, расходы, сроки и цена, связь с WBS/версией |
**Важно:** стабильный код шаблона работы (`integration.crm`) и идентификатор конкретной строки сметы (`task_id`) — разные поля. Нужна также связь между версиями строки (`lineage_id`), чтобы после переработки WBS можно было сравнить план/факт и историю исправлений.
Для корректной изоляции в схеме надо предусмотреть `tenant_id`, `created_by`, `approved_by` и действующие права доступа. Отдельная версия сохраняет **снимок** применённых справочников, а не только ссылку на изменяемую запись.
---
## 5. Агентный pipeline v2
Текущий `clarify → decompose → estimate → critic` стоит сохранить как основу. Предлагается расширить его логические этапы:
| # | Шаг | Ответственность |
|---|---|---|
| 1 | **Intake & Classify** | нормализовать требования; определить домены и capabilities |
| 2 | **Clarify** | собрать пробелы, сформировать приоритетные вопросы, зафиксировать допущения |
| 3 | **Decompose** | собрать WBS из каталога + нетиповые работы |
| 4 | **Retrieve Benchmarks** | найти сопоставимые задачи и завершённые проекты |
| 5 | **Estimate** | определить O/M/P, роли/ресурсы, зависимости и основания |
| 6 | **Critic & Validate** | обнаружить пропуски, дубли, неверный scope и несовместимые предположения |
| 7 | **Deterministic Pricing** | рассчитать трудозатраты, ресурсы, риски и финансовые показатели |
| 8 | **Market Check & Approval** | сверить с сопоставимыми предложениями и направить на утверждение при необходимости |
Это **логические** этапы: не требуется восемь отдельных LLM-вызовов. Часть действий выполняется кодом или объединяется в один вызов. Стоимость, задержка и количество токенов — самостоятельные KPI pipeline.
### 5.1. Два режима оценивания
**Rough Estimate (экспресс-оценка):** предварительная вилка на основе частичных требований; короткий список критических вопросов; высокое внимание к допущениям; запрет на выдачу как окончательного фиксированного предложения.
**Detailed Estimate (подробная оценка):** развёрнутая WBS; поиск аналогов; ставки и риски; несколько сценариев; экспертное подтверждение перед отправкой коммерческого предложения.
Режим и полнота данных должны быть явными атрибутами результата. При критически недостающих вводных detailed-оценка остаётся в `needs_input`, а rough-оценка может выдавать осторожный диапазон с предупреждениями.
### 5.2. Ограничения LLM
- LLM не определяет окончательную цену и не может подменять ставки.
- LLM возвращает структурированные кандидаты на задачи, часы, предположения и риски.
- Валидаторы обеспечивают уникальность WBS-элементов, существование ролей, логичность O ≤ M ≤ P, пределы задач и отсутствие дублирования.
- Сбой `critic` не должен скрываться: если расчёт всё же возвращён, он явно получает предупреждение о пропущенной проверке и может требовать подтверждения человеком.
- Клиентские ТЗ, найденные RAG-документы и LLM-ответы считаются **недоверенными входными данными**; структурная схема сама по себе не устраняет prompt injection.
---
## 6. Расчётное ядро: необходимые изменения
### 6.1. Себестоимость, наценка и маржа — разные понятия
В исходном примере из `bot-estimation-market-data.md` применяется:
```text
price = base * 1.15 (PM) * 1.10 (risk) * 1.20 (margin)
```
Последний множитель `1.20` означает **20% наценки**, а не **20% валовой маржи**.
Для себестоимости 100 000 ₽:
| Правило | Итоговая цена | Фактическая валовая маржа |
|---|---:|---:|
| Наценка 20%: `100000 × 1.20` | 120 000 ₽ | ≈16,67% |
| Целевая маржа 20%: `100000 / (1 − 0.20)` | 125 000 ₽ | 20% |
Необходимы разные параметры `markup_pct` и `target_gross_margin_pct` с взаимоисключающими режимами. Формулы должны учитывать точное определение себестоимости (включая прямые/косвенные затраты) и коммерческую политику; налог с продаж/НДС нельзя механически трактовать как прибыль.
Предлагаемая структура результата:
```text
Direct labor cost
+ Project management cost
+ External costs (лицензии, API, закупки, подрядчики)
+ Identified risk allowance / contingency (при наличии)
= Cost basis по правилам PricingProfile
→ Применение выбранной наценки ИЛИ целевой маржи
→ Налоговые правила и валюта
= Customer price, с понятной разбивкой
```
Не нужно одновременно добавлять PM как 15% и включать отдельные PM-задачи в WBS без явного правила исключения дубля. Аналогично эксплуатацию (`run`, TCO) лучше показывать отдельно от разового внедрения.
### 6.2. PERT как первый уровень, а не доказанная вероятность
Базовые формулы из текущего документа полезны:
```text
E_task = (O + 4*M + P) / 6
sigma_task = (P - O) / 6
```
Агрегация `sqrt(sum(sigma_task²))` правомерна как приближение **при независимости** задач и при принятых предположениях о распределении. В реальных проектах один риск может одновременно сдвигать backend, интеграции и QA.
Поэтому:
1. **В v2/MVP:** сохранить PERT, явно фиксировать допущение независимости, не заявлять P85 как гарантированную вероятность без эмпирической калибровки.
2. **В следующем режиме:** моделировать общие факторы риска и корреляции; поддержать Monte Carlo для времени, ресурсов и цены.
3. **Для стоимости:** считать неопределённость с учётом **ставки каждой роли**, а не масштабировать общую стоимость на `hours_p85 / hours_mean`, когда роли существенно отличаются по ставкам.
4. **Для резерва:** развести распределённую неопределённость внутри O/M/P, конкретные рисковые события и коммерческий резерв — иначе риск можно включить дважды.
5. **Для календарного срока:** учитывать зависимости задач, доступную ёмкость команды и параллельное выполнение; общие часы / 8 — это трудоёмкость в человеко-днях, не дата поставки.
Текущая архитектура прямо отмечает приближённость расчёта стоимости по `hours_confident / hours`; доработку следует запланировать как исправление модели, а не только косметическое улучшение отчёта.
### 6.3. Прозрачность оценки
Каждая итоговая цена должна сопровождаться:
- составом работ, включениями и исключениями;
- базой ставок и версией профиля;
- диапазонами времени и стоимости, **с обозначением природы диапазона**;
- факторами риска и допущениями;
- степенью уверенности с опорой на качество исходных данных, а не на самоуверенность LLM;
- отдельными разовыми и регулярными расходами.
---
## 7. Рыночная база и эталонные оценки
### 7.1. Сохранить разделение типов данных
Исходный документ обоснованно различает: цены проектов, почасовые ставки, эталонные трудозатраты, эксплуатационные цены, коэффициенты и валютно-налоговую информацию. Это разделение следует сохранить.
Рыночные данные — **проверка правдоподобия**, а не источник «правильной» цифры. Публичные прайсы/маркетинговые публикации являются слабыми приорами; фактические трудозатраты и сделки компании важнее.
### 7.2. Переход от `segment` к сопоставимому контексту
Рекомендуемые параметры `MarketBenchmark`:
```yaml
# Иллюстративный пример, а не реальная рыночная запись.
domain: software
project_type: ecommerce
capabilities: [web.catalog, web.checkout, integration.crm]
complexity: medium
region: RU
provider_type: agency
price_basis: fixed_project_ex_vat
currency: RUB
observed_at: null
source_type: internal_or_public
sample_size: null
scope: "..."
evidence_quality: unknown
```
Для ставок отдельно хранить `role`, `level`, `basis` (`freelance`, `salary_derived`, `agency_billing` и др.), регион и период наблюдения. Для трудозатрат — технологию, тип работы, сложность, объём, фактические часы и наличие повторного использования компонентов.
Важные правила:
- не смешивать цены подрядчиков разного типа в один агрегат;
- сравнивать предложения только при совместимом scope;
- проверять НДС, валюту, дату курса и единицу измерения;
- сохранять происхождение, первичные документы, признаки дублей и качество свидетельств;
- не складывать «цена мультиканальности» + «цена AI-бота», пока не доказано отсутствие пересечения в составе работ;
- малая выборка должна явно отмечаться, а не выдавать псевдоточные перцентили.
### 7.3. Метрики качества
**Не делать долю «попадания в рынок» основным показателем точности.** Она может побуждать подгонять смету под несопоставимые публикации.
Лучше оценивать:
| Метрика | Интерпретация |
|---|---|
| Ошибка по часам (MAE, WAPE и др.) | Насколько прогноз совпадает с фактической трудоёмкостью |
| Bias / systematic underestimation | Насколько систематически занижаем или завышаем |
| Coverage interval | Как часто факт попадает в обещанный диапазон |
| Ошибка по себестоимости и цене | Точность финансового прогноза отдельно от коммерческой политики |
| Качество scope | Сколько задач пропущено, продублировано, добавлено вручную |
| Human override rate | Насколько часто эксперт исправляет результат агента |
| Time-to-estimate / LLM cost | Цена и время самого оценивания |
MAPE из исходного документа можно оставлять дополнительной метрикой, но она нестабильна на очень малых фактических величинах; полезно сопоставлять её с MAE/WAPE и анализом отдельных доменов.
---
## 8. RAG и калибровка по план/факту
### 8.1. Retrieval
Использовать выбранную для Flexly AI инфраструктуру **PostgreSQL + PGVector/BM25**, без выделения нового search-сервиса на старте. При этом пространство данных оценщика логически и по правам изолировать от пользовательских баз знаний Flexly AI Core.
Поиск аналогов двухступенчатый:
1. структурные фильтры: `tenant_id`, домен/возможности, тип задачи, сложность, технология, период, сопоставимость;
2. гибридный текстово-векторный поиск и ранжирование пригодных кандидатов.
Индексировать не только описание проекта, но и WBS-работы, их предположения, фактические часы, объём и исходную версию оценки. В выдаче хранить `reference_id`, факторы сходства и основания использования. **Не возвращать цены/чувствительные данные чужого tenant.**
### 8.2. Калибровка
Идея исходного документа `k = median(actual_hours / estimated_hours)` разумна как простое первое приближение, но её нужно применять осторожно:
- коэффициент считать по сопоставимым работам/доменам/сложности, а не глобально;
- не подстраивать модель под 1–2 аномальных проекта;
- отмечать число наблюдений и качество данных;
- при малой выборке использовать консервативный prior и постепенное «усиление» собственных данных;
- хранить факт отдельно от прогноза и **не переписывать исторические версии**;
- проверять эффект калибровки на отложенных проектах, а не только на обучающей истории.
Фактические данные желательно собирать **на уровне work item**, а не только проекта: иначе невозможно понять, что регулярно недооценивается — аналитика, QA, CRM-интеграции или эксплуатация.
---
## 9. API, UI, безопасность и интеграция с Flexly AI Core
### 9.1. API
Сохранить существующий контракт `POST /api/estimates`, версии, ответы на вопросы, пересчёт и ручные правки. Расширение вводить совместимо:
- новые поля `project_type`, `capabilities`, `mode`, `pricing_profile_id` — по возможности опционально для существующих клиентов;
- `domain_pack_refs`, `scope`, `risk_register`, `uncertainty`, `cost_breakdown` — в версии результата;
- версия схемы ответа/конфигурации или отдельный API v2 при несовместимом изменении;
- стабильно сохранять `estimate_id`, версии и идемпотентность;
- старые оценки читать и пересчитывать с **их** снимком тарифов и конфигураций, если запрошен исторический повтор.
### 9.2. UI
**HTMX + Jinja2 сохранять** для первого расширенного релиза. Важнее улучшить сценарий работы, чем менять frontend-стек:
- выбор типа проекта и составных возможностей;
- индикатор полноты требований, список вопросов и допущений;
- WBS с ручным редактированием и отображением причин оценки;
- сценарии `economy / base / conservative` (или согласованные аналоги);
- сравнение версий и ручных исправлений;
- отдельные единовременные и ежемесячные расходы;
- экспорт коммерческого предложения (PDF/XLSX — по отдельной задаче);
- план/факт и показатели качества оценщика.
Если появится сложный drag-and-drop редактор WBS, можно добавить точечный JS-компонент, не переводя всё приложение на SPA.
### 9.3. Tenant / user security
Текущий API уже фильтрует сметы по клиенту из `X-API-Key`. Для полноценного UI этого недостаточно, если пользователи одной компании имеют разные права или один UI работает с несколькими организациями.
Рекомендуется:
- идентифицировать **tenant и пользователя** на доверенной стороне;
- управлять ролями `viewer`, `estimator`, `approver`, `admin` (точный перечень — ADR);
- не принимать произвольный `tenant_id` или `X-User-ID` от браузера без проверки доверенного контекста;
- проверять доступ ко **всем** версиям, задачам, рыночным данным и документам;
- ограничить и аудитировать публикацию клиенту/экспорт коммерческого предложения;
- очищать/ограничивать логи и хранилище ТЗ с учётом конфиденциальности.
XSS/CSRF-защита из текущего документа должна остаться. Prompt injection обрабатывать отдельно от XSS: экранирование HTML защищает рендер, а не инструкции для модели.
### 9.4. Конфигурация
Для Flexly AI Core ранее выбран `app_settings` как источник изменяемых настроек моделей, fallback-цепочек и таймаутов. Это **не означает**, что самостоятельный оценщик обязан писать в ту же физическую таблицу.
Разделение:
| Источник | Ответственность |
|---|---|
| `default.toml`, env | технические настройки, секреты, ограничения по умолчанию |
| DB / `app_settings` или собственное конфигурационное API | изменяемые эксплуатационные настройки, маршруты моделей и таймауты |
| `DomainPack` + каталог | предметные правила, коды capabilities и версионируемые шаблоны |
| `PricingProfile` | коммерческая политика, ставки, налоги, наценка/маржа |
| `EstimateVersion` snapshot | точный набор применённых настроек и правил конкретной оценки |
При интеграции с Flexly AI Core возможен поставщик конфигурации через API/адаптер; при отдельном инсталляционном пакете оценщик должен сохранять автономный запуск.
### 9.5. Фоновая обработка
Текущий внутрипроцессный `JobRunner` по документации рассчитан на один экземпляр и требует развития при нескольких репликах.
Рекомендуемый следующий шаг — **PostgreSQL-backed job queue** с отдельным worker, без обязательного RabbitMQ:
- транзакционный захват работ (`FOR UPDATE SKIP LOCKED` там, где применимо);
- lease/heartbeat, контроль timeout, повторный подбор зависших работ;
- идемпотентность `job_id` / `estimate_version_id`;
- лимиты параллелизма и вызовов LLM по tenant/провайдеру;
- политика повторов с учётом сетевых ошибок и риска повторного платного вызова;
- ручное возобновление, отмена, мониторинг, аудит причин сбоя.
SQLite оставить для локальных тестов, но не имитировать на ней продукционные гарантии многопроцессной очереди.
---
## 10. Переход от v1 к v2 без переписывания ядра
### Фаза 0. Зафиксировать базу и устранить несоответствия документации
- Сверить текущий код со статусами раздела 13 `estimator-architecture.md`.
- Обновить шапки документов, где написано «реализация не начата».
- Зафиксировать текущие OpenAPI snapshots, миграции, golden-тесты и эталонные расчёты.
- Зафиксировать поведение существующих `Segment`, рынка и ценового калькулятора как совместимый baseline.
**Готово, когда:** можно продемонстрировать, что старый бот-сценарий и история оценок работают до и после миграции.
### Фаза 1. Универсальное ядро и корректная экономика (**P0**)
- Ввести `DomainPackRef`, `ProjectType`, `Capability`, `WorkItem` и `PricingProfile`.
- Реализовать реестр пакетов и валидацию их схем.
- Представить текущий бот-справочник как первый `bots_ai` pack.
- Развести маржу и наценку, исключить двойной PM и двойной резерв риска.
- Явно маркировать режим расчёта и метод интервала.
**Готово, когда:** текущий бот считается новым ядром без изменения бизнес-смысла старых смет, а финансовые формулы проходят эталонные тесты.
### Фаза 2. Каталог задач и новые домены (**P0/P1**)
- Создать общие work items для аналитики, UI, backend, QA, DevOps, интеграций.
- Добавить `web`, `software`, `automation` как тонкие каталоги.
- Ввести композицию capabilities и проверку дублей.
- Добавить `Intake & Classify`, расширить `Decompose` и `Critic`.
**Готово, когда:** один проект корректно включает работы из нескольких пакетов и не получает повторных общих расходов.
### Фаза 3. Рыночная база, RAG, план/факт (**P1**)
- Перейти от сегмента к контекстным эталонам.
- Добавить гибридный поиск похожих задач с tenant-scoping.
- Собирать факт по work items, строить отчёт bias/coverage.
- Включать калибровку сначала в теневом режиме, затем после подтверждения качества.
**Готово, когда:** улучшение метрик на отложенных проектах измеримо и не приводит к ухудшению отдельных доменов.
### Фаза 4. Эксплуатационная зрелость и интерфейс (**P1/P2**)
- Вынести фоновые расчёты в PostgreSQL worker.
- Ввести user/tenant роли, жизненный цикл согласования сметы.
- Добавить UI выбора capabilities, подробную WBS, сценарии и сравнение версий.
- Реализовать экспорт КП после согласования формата.
- MCP — как тонкий адаптер к стабильному REST/use cases, когда появится реальный потребитель.
**Готово, когда:** параллельные расчёты, рестарты и разграничение доступа воспроизводимо проверяются интеграционными тестами.
---
## 11. Кандидаты ADR
Ниже **предлагаемые** решения, не принятые автоматически:
| ADR | Тема | Рекомендуемое решение |
|---|---|---|
| `ADR-EST-001` | Расширение предметных областей | Engine + декларативные Domain Packs |
| `ADR-EST-002` | Модель состава проекта | Композиция capabilities и единый WBS, а не комбинации сегментов |
| `ADR-EST-003` | Экономическая модель | Отдельные cost basis, markup, target margin, налоги, recurring costs |
| `ADR-EST-004` | Неопределённость и риск | PERT с явными допущениями; позже Monte Carlo с корреляциями |
| `ADR-EST-005` | Хранилище эталонов | SQL-истина + гибридный retrieval для описаний/аналогов |
| `ADR-EST-006` | Калибровка | Work-item plan/fact, версии, отложенная валидация, приоры при малой выборке |
| `ADR-EST-007` | Фоновые задачи | PostgreSQL-backed worker вместо in-process job runner для multi-instance |
| `ADR-EST-008` | Аутентификация UI | Tenant-scoped actor + RBAC, не общий ключ без пользовательского контекста |
| `ADR-EST-009` | Источники конфигурации | TOML/env + DB runtime settings + immutable estimate snapshot |
Каждый ADR должен фиксировать контекст, альтернативы, ограничения, последствия и план миграции с указанием затрагиваемых данных/API.
---
## 12. Тестовая стратегия и критерии готовности
### Контрольные проекты для доказательства универсальности
1. **Мультиканальный AI-бот:** Telegram + сайт + CRM + RAG.
2. **Интернет-магазин:** каталог + оформление заказа + оплата + CRM + AI-консультант.
3. **SaaS-приложение:** кабинет, роли, подписки/биллинг, backend API, администрирование.
Для всех трёх должен работать **один** `EstimateService`, единый pricing engine, единая схема версий и один интерфейс сметы. Специализация должна отличаться данными каталога/пакетов, а не крупными ветками кода `if project_type == ...`.
### Проверки
- Unit/property-based тесты: монотонность стоимости по часам, правила маржи, налоги, валюты, нулевые/аномальные вводные, исключение дублей.
- Golden-тесты: типовые ТЗ разных доменов, полнота WBS, разумные диапазоны, изменения после критика.
- Contract-тесты: совместимость существующих REST-клиентов; версионирование схем.
- Integration: PostgreSQL, concurrent version writes, очередь, retries, tenant isolation.
- Security: XSS, CSRF, prompt injection, разграничение доступа, изоляция RAG и аудита.
- Calibration: сравнение с историческим baseline, временной holdout, bias, coverage, ручные исправления.
- Эксплуатация: продолжительность оценивания, стоимость токенов, частота ошибок/fallback.
**Не стоит задавать универсальные численные пороги точности заранее:** они зависят от накопленной выборки и сложности проектов. Сначала нужен baseline, затем целевые SLA/метрики по доменам.
---
## 13. Открытые вопросы перед утверждением v2
1. **Границы продукта:** только разработка ПО и автоматизация либо намерение оценивать также не-IT работы?
2. **Коммерческая политика:** кто владеет тарифами и ценовыми профилями, нужны ли разные профили для клиентов/команд/регионов?
3. **Роли UI:** внутренний оценщик для команды, сервис для клиентов или оба режима?
4. **Смета vs коммерческое предложение:** когда и кем утверждаются итоговые значения; допускается ли автоматическая публикация предварительной вилки?
5. **Качество исходных данных:** есть ли завершённые проекты с план/фактом на уровне задач?
6. **Правила использования исторических проектов:** можно ли использовать агрегаты между tenants или данные должны быть строго изолированы?
7. **Интеграция с Flexly AI Core:** общий деплой и config provider или автономный сервис с независимой БД?
8. **Стоимость эксплуатации:** нужен ли в v2 полноценный TCO по нагрузочным сценариям (запросы/мес, токены, hosting, поддержка)?
Эти вопросы влияют на ADR и API, но **не мешают** уже сейчас разрабатывать универсальные Domain Packs и исправления расчётной модели.
---
## 14. Рекомендуемое решение
**Принять направление Estimator Engine v2 без переписывания существующих слоёв.**
Сохранить `domain/pricing/agent/market/services/infra`, REST как первичный контракт, HTMX + Jinja2 на первом этапе и историческую версионность оценок. Перед масштабированием на новые рынки и виды проектов:
1. формализовать **Domain Packs + capabilities + work-item catalog**;
2. исправить **финансовую модель и трактовку неопределённости**;
3. обеспечить **композицию WBS без двойного учёта**;
4. затем развивать **RAG, рыночные эталоны и обучение на плане/факте**;
5. отдельно усилить очередь заданий, авторизацию и UI.
**Критерий архитектурного успеха:** новый тип проекта добавляется преимущественно через данные пакета и эталонные тесты, а не через переписывание `pricing.calculator`, `EstimateService`, схемы версий и REST-роутов.
---
## Приложение A. Связь с исходными решениями
| Из исходных документов | Действие в v2 |
|---|---|
| Детерминированная цена | **Сохранить**, уточнить экономику |
| PERT O/M/P | **Сохранить как базовый режим**, не преувеличивать вероятностную интерпретацию |
| `Segment` для ботов | **Обернуть совместимостью**, заменить как главную абстракцию на capabilities |
| TOML рыночные версии | **Сохранить**, добавить метаданные сопоставимости и snapshots |
| `channel_multiplier` | **Не дублировать** с задачами каналов |
| Immutable `estimate_versions` | **Сохранить и расширить** lineage и domain pack refs |
| API + MCP | **Сохранить REST**, MCP подключать по мере реального спроса |
| HTMX + Jinja2 | **Сохранить**, добавлять точечную интерактивность |
| `JobRunner` в процессе | **Оставить на одном инстансе**, перейти на PostgreSQL worker при масштабировании |
| RAG и план/факт | **Реализовать после унификации work items**, иначе усложнится миграция |
## Приложение B. Дополнительные ориентиры
- Исходные локальные документы из раздела 0 — источник описания состояния и принятых решений проекта.
- [GAO Cost Estimating and Assessment Guide (GAO-20-195G)](https://www.gao.gov/products/gao-20-195g) — общие ориентиры по WBS, документированию допущений, анализу неопределённости и актуализации оценок. Руководство рассчитано на крупные программы; принципы следует адаптировать к масштабу Flexly AI.
---
**Статус документа:** рекомендации для архитектурного ревью и постановки ADR. Не подменяет текущую рабочую спецификацию до утверждения решений и миграционного плана.
+681
View File
@@ -0,0 +1,681 @@
# Сервис оценки трудозатрат и стоимости: архитектура
**Версия:** 1.0 · **Дата:** 30 октября 2026 · **Статус:** проект реализован по этапам 1–5 и веб-интерфейсу, актуальное состояние в разделе 13
**Связанный документ:** `bot-estimation-market-data.md` (сбор рыночных данных, аналитика, примеры расчёта)
---
## 1. Принятые решения
| # | Решение | Обоснование |
|---|---|---|
| 1 | Расчёт стоимости это **внешний сервис**, бот вызывает его как инструмент | Деньги считаются детерминированным кодом, а не промптом; один сервис обслуживает несколько потребителей |
| 2 | Сначала **REST** (OpenAPI), затем тонкая **MCP-обёртка** над теми же use cases | Один потребитель не требует MCP; второй потребитель добавляет обёртку без переписывания ядра |
| 3 | **RAG только внутри сервиса** (похожие проекты и эталонные задачи для калибровки часов) | Ставки и коэффициенты это числа, им место в SQL и TOML, а не в векторной базе |
| 4 | Конфигурация **TOML + env**, секции с жёсткой валидацией | Несекретное версионируется в git, секреты приходят из окружения |
| 5 | **Версионируемый справочник рынка** отдельными TOML-файлами, версия записывается в каждую смету | Смета воспроизводима, пересчёт со старой версией даёт старую цену |
| 6 | **Один пакет, один процесс** на старте, чёткие границы модулей | Разделять на сервисы только при реальной нагрузке |
| 7 | Бот **не называет цены сам**, цифры только из результата инструмента | Исключает «придуманные» цены |
---
## 2. Слои и правило зависимостей
```
api/ (REST) mcp/ (обёртка) cli/ (джобы) ← входы
\ | /
services/ (use cases: создать/пересчитать оценку)
/ | | \
agent/ pricing/ market/ calibration/ ← бизнес-модули
\ | | /
domain/ (модели, протоколы) ← чистое ядро
▲
infra/ (llm, db, rag, fx) реализует протоколы из domain/
```
**Правило:** зависимости направлены только вниз, к `domain/`. Модуль `pricing/` не импортирует ничего из `infra/`, поэтому калькулятор тестируется без сети и базы. Провайдера LLM, хранилище или источник курсов можно заменить, не трогая бизнес-логику.
---
## 3. Структура проекта
```
estimator/
├── pyproject.toml
├── README.md
├── .env.example # только секреты и деплой-специфика
├── config/
│ ├── default.toml # все секции с безопасными значениями по умолчанию
│ ├── dev.toml # переопределения для EST_ENV=dev
│ ├── prod.toml
│ └── market/
│ ├── 2026Q4.toml # версионируемый справочник: ставки, коэффициенты, диапазоны
│ └── 2027Q1.toml
├── migrations/ # alembic
├── prompts/
│ ├── clarify.md
│ ├── decompose.md
│ ├── estimate.md
│ └── critic.md
├── src/estimator/
│ ├── config/
│ │ ├── settings.py # Settings: pydantic-settings, toml + env
│ │ └── sections.py # модели секций (AppCfg, LlmCfg, PricingCfg, ...)
│ ├── domain/
│ │ ├── models.py # Requirements, Task, TaskEstimate, Estimate, Assumption
│ │ ├── enums.py # Role, Region, Segment, ProviderType
│ │ ├── ports.py # Protocol: LlmClient, Retriever, MarketRepo, EstimateRepo, FxProvider
│ │ └── errors.py
│ ├── pricing/ # чистый код, без IO
│ │ ├── pert.py # E, σ, перцентили
│ │ ├── calculator.py # price(): ставки, PM, наценка, резерв, налоги
│ │ └── currency.py # конвертация через FxProvider
│ ├── agent/
│ │ ├── pipeline.py # clarify → decompose → estimate → critic
│ │ ├── models.py # PipelineInput, PipelineResult, StepLog
│ │ ├── schemas.py # JSON-схемы structured output
│ │ ├── prompts.py # загрузка prompts/*.md, хэш, защита тегов
│ │ ├── checks.py # структурные предупреждения
│ │ └── steps/
│ │ ├── clarify.py # открытые вопросы по требованиям
│ │ ├── decompose.py # WBS
│ │ ├── estimate.py # O/M/P + допущения и риски
│ │ ├── critic.py # проверка забытых работ, применение правок
│ │ └── common.py
│ ├── market/
│ │ ├── repository.py # загрузка config/market/<version>.toml или БД
│ │ ├── check.py # market_check: смета против рынка
│ │ └── etl/ # сбор рыночных данных
│ │ ├── collect.py
│ │ ├── extract.py # LLM → PricePoint
│ │ └── normalize.py
│ ├── calibration/
│ │ ├── coefficients.py # k по типам задач из плана/факта
│ │ └── feedback.py # приём фактических часов
│ ├── rag/
│ │ ├── indexer.py # индексация прошлых проектов и эталонных задач
│ │ └── retriever.py # поиск похожих задач
│ ├── services/
│ │ ├── estimate_service.py # create / get / update_requirements
│ │ └── market_service.py
│ ├── infra/
│ │ ├── llm/
│ │ │ ├── schema.py # Pydantic → строгая JSON-схема
│ │ │ ├── base.py # HTTP, ретраи, repair-цикл
│ │ │ ├── openai.py # Chat Completions, response_format json_schema
│ │ │ ├── anthropic.py # Messages API, output_config.format
│ │ │ ├── router.py # маршрут по шагам и fallback
│ │ │ └── factory.py # сборка из Settings
│ │ ├── db/
│ │ │ ├── session.py
│ │ │ ├── tables.py
│ │ │ └── repositories.py
│ │ ├── fx/
│ │ │ ├── cbr.py # курсы ЦБ РФ
│ │ │ └── ecb.py
│ │ └── audit.py # журнал вызовов: версии конфига и модели, вход, выход
│ ├── api/
│ │ ├── app.py # FastAPI factory, lifespan
│ │ ├── deps.py # сборка зависимостей из Settings
│ │ ├── auth.py # API-ключи по клиентам
│ │ └── routers/
│ │ ├── estimates.py
│ │ ├── market.py
│ │ └── health.py
│ ├── mcp/
│ │ └── server.py # тонкая обёртка над services/
│ ├── cli.py # typer: migrate, reindex, market-collect, recalibrate
│ └── logging.py
└── tests/
├── unit/
│ ├── pricing/ # эталонные расчёты, property-based
│ └── agent/ # с фейковым LlmClient
├── integration/ # БД, RAG
├── golden/ # набор типовых ТЗ с ожидаемыми диапазонами
└── conftest.py
```
### Ответственность модулей
| Модуль | Отвечает за | Не должен |
|---|---|---|
| `domain` | Модели данных, перечисления, протоколы (порты) | Содержать логику расчёта и импортировать инфраструктуру |
| `pricing` | PERT, ставки, PM, наценка, резерв, налоги, округление | Ходить в сеть, БД и LLM |
| `agent` | Конвейер LLM-шагов со structured output | Считать деньги |
| `market` | Справочник ставок, диапазоны рынка, сверка сметы с рынком, ETL | Знать о HTTP |
| `calibration` | Коэффициенты `k` по плану/факту | Менять смету задним числом |
| `rag` | Индексация и поиск похожих задач | Возвращать цены (только часы и описания) |
| `services` | Сценарии использования, оркестрация модулей | Содержать детали HTTP или SQL |
| `infra` | Реализации портов: LLM, БД, курсы, аудит | Содержать бизнес-правила |
| `api`, `mcp`, `cli` | Входы в систему | Содержать бизнес-логику |
---
## 4. Конфигурация: TOML + env
### 4.1. Приоритет источников (сверху сильнее)
1. Аргументы в коде (`init`)
2. Переменные окружения и `.env`
3. `config/<env>.toml`
4. `config/default.toml`
5. Значения по умолчанию в моделях секций
### 4.2. Правило разделения
| Где | Что |
|---|---|
| **TOML** | Несекретное и версионируемое: параметры расчёта, имена моделей, лимиты, пути, пороги |
| **env** | Секреты и окружение-специфика: ключи API, DSN базы, `EST_ENV` |
| **TOML `market/`** | Справочник рынка: ставки, коэффициенты, диапазоны (отдельная версия на каждый квартал) |
### 4.3. `config/default.toml`
```toml
[app]
name = "estimator"
env = "dev"
log_level = "INFO"
[api]
host = "0.0.0.0"
port = 8000
request_timeout_s = 120
[database]
pool_size = 5
# dsn приходит из env: EST_DATABASE__DSN
[llm]
repair_attempts = 1 # extra calls when JSON fails schema validation
[llm.anthropic]
base_url = "https://api.anthropic.com"
api_version = "2023-06-01"
timeout_s = 90
max_retries = 2
# api_key comes from env: EST_LLM__ANTHROPIC__API_KEY
[llm.openai]
base_url = "https://api.openai.com/v1"
timeout_s = 90
max_retries = 2
# api_key comes from env: EST_LLM__OPENAI__API_KEY
# every pipeline step picks its own provider and model; optional fallback
[llm.steps.critic]
provider = "anthropic"
model = "claude-sonnet-5-5"
max_tokens = 6000
# [llm.steps.critic.fallback]
# provider = "openai"
# model = "<model id>"
[agent]
prompts_dir = "prompts"
max_tasks = 60
max_task_hours = 400
critic_max_change_ratio = 3.0
[rag]
enabled = true
embedding_model = "text-embedding-3-small"
top_k = 5
min_similarity = 0.55
[pricing]
default_region = "ru"
default_currency = "RUB"
default_engagement = "fixed_price" # fixed_price | time_and_materials
pm_pct = 0.15
markup_pct = 0.20 # наценка на себестоимость (маржа = 16,7%)
reserve_floor_pct = 0.10 # минимальный резерв
reserve_z = 1.04 # резерв по PERT = reserve_z × σ, не калиброван
estimate_unit_hours_per_day = 8
[pricing.min_rounding]
step = 1000 # округление итога
[market]
active_version = "2026Q4" # файл config/market/2026Q4.toml
check_tolerance = 0.25
[calibration]
enabled = true
min_samples = 5 # меньше → консервативный коэффициент по умолчанию
default_k = 1.2
[fx]
provider = "cbr"
cache_ttl_s = 3600
[mcp]
enabled = false
transport = "stdio" # stdio | sse
[audit]
store_prompts = true
```
Значения процентов, `default_k` и ставок ниже это стартовые допущения. Их нужно заменять данными из плана/факта.
### 4.4. `config/market/2026Q4.toml` (справочник рынка)
```toml
version = "2026Q4"
published = "2026-10-30"
note = "Стартовые приоры из открытых источников, заменять данными план/факт"
[rates.ru]
currency = "RUB"
basis = "freelance"
[rates.ru.hourly]
analyst = 1500
backend = 1800
qa = 1200
devops = 1800
[rates.eu]
currency = "EUR"
basis = "freelance"
[rates.eu.hourly]
analyst = 75
backend = 85
qa = 60
devops = 90
[channel_coefficient]
first = 1.0
additional = 0.15 # +15% базы за каждый канал после первого (допущение)
[benchmarks.ru.multichannel_ai]
min = 400000
max = 600000
currency = "RUB"
[benchmarks.eu.multichannel_ai]
min = 10000
max = 30000
currency = "EUR"
```
Поле `basis` обязательно: ставка разработчика и расценка агентства «под ключ» различаются в разы, и смешивать их нельзя.
### 4.5. `.env.example`
```bash
EST_ENV=dev
EST_DATABASE__DSN=postgresql+psycopg://user:pass@localhost:5432/estimator
EST_LLM__ANTHROPIC__API_KEY=sk-ant-...
EST_LLM__OPENAI__API_KEY=sk-...
EST_API__KEYS=client_a:key1,client_b:key2
```
Двойное подчёркивание обозначает вложенность: `EST_LLM__ANTHROPIC__API_KEY` попадает в `settings.llm.anthropic.api_key`.
### 4.6. `src/estimator/config/settings.py`
```python
import os
from pydantic_settings import (BaseSettings, SettingsConfigDict,
TomlConfigSettingsSource)
from .sections import (AppCfg, ApiCfg, DatabaseCfg, LlmCfg, RagCfg,
PricingCfg, MarketCfg, CalibrationCfg, FxCfg, McpCfg, AuditCfg)
class Settings(BaseSettings):
model_config = SettingsConfigDict(
env_prefix="EST_",
env_nested_delimiter="__",
env_file=".env",
extra="forbid", # опечатка в TOML = ошибка при старте
)
app: AppCfg = AppCfg()
api: ApiCfg = ApiCfg()
database: DatabaseCfg
llm: LlmCfg
rag: RagCfg = RagCfg()
pricing: PricingCfg = PricingCfg()
market: MarketCfg = MarketCfg()
calibration: CalibrationCfg = CalibrationCfg()
fx: FxCfg = FxCfg()
mcp: McpCfg = McpCfg()
audit: AuditCfg = AuditCfg()
@classmethod
def settings_customise_sources(cls, settings_cls, init_settings, env_settings,
dotenv_settings, file_secret_settings):
files = ["config/default.toml"]
if env := os.getenv("EST_ENV"):
files.append(f"config/{env}.toml")
return (
init_settings,
env_settings,
dotenv_settings,
TomlConfigSettingsSource(settings_cls, toml_file=files),
file_secret_settings,
)
```
В `sections.py` секреты описываются как `SecretStr`, чтобы они не попадали в логи и `repr`:
```python
from pydantic import BaseModel, SecretStr
class ProviderCfg(BaseModel):
base_url: str
api_key: SecretStr | None = None # env only
timeout_s: int = 90
max_retries: int = 2
class RouteCfg(BaseModel):
provider: Literal["anthropic", "openai"] = "anthropic"
model: str = "claude-sonnet-5-5"
temperature: float | None = None # not sent unless set
max_tokens: int = 4000
reasoning_effort: str | None = None # OpenAI only
class StepRouteCfg(RouteCfg):
fallback: RouteCfg | None = None
```
Перед внедрением проверьте установленную версию `pydantic-settings`: поведение `TomlConfigSettingsSource` с несколькими файлами и отсутствующими файлами нужно подтвердить тестом.
---
## 5. Порты (контракты между модулями)
```python
# domain/ports.py
from datetime import date
from typing import Protocol
class LlmClient(Protocol):
async def structured(self, *, system: str, user: str, schema: type, model: str) -> object: ...
class Retriever(Protocol):
async def similar_tasks(self, text: str, k: int) -> list["BenchmarkTask"]: ...
class MarketRepo(Protocol):
def rates(self, region: str) -> "RateCard": ...
def benchmark(self, region: str, segment: str) -> "Benchmark | None": ...
class FxProvider(Protocol):
async def rate(self, src: str, dst: str, on_date: date) -> float: ...
class EstimateRepo(Protocol):
async def save(self, estimate: "Estimate") -> str: ...
async def get(self, estimate_id: str) -> "Estimate": ...
```
Сборка зависимостей находится в `api/deps.py`: читает `Settings`, выбирает реализации (`infra.llm.anthropic` или `infra.llm.openai` по `llm.provider`) и передаёт их в `EstimateService`. Замена провайдера это правка одной строки в TOML.
---
## 6. Сквозной поток `create_estimate`
1. API проверяет ключ клиента и валидирует вход.
2. `EstimateService` вызывает `agent.pipeline`: уточнение → декомпозиция → оценка O/M/P (с подсказками от `rag.retriever`) → критик.
3. `calibration.coefficients` применяет коэффициент `k` по типу задач.
4. `pricing.calculator` считает деньги по ставкам из `market.repository` активной версии.
5. `market.check` сверяет итог с рынком.
6. `infra.audit` записывает версию конфига, модель, хэши промптов, вход и выход; результат сохраняется с `estimate_id`.
7. Возвращаются диапазон, часы, допущения, открытые вопросы и результат сверки с рынком.
---
## 7. Контракт инструментов для бота
Инструменты крупные, а не набор мелких калькуляторов.
| Инструмент | Назначение |
|---|---|
| `create_estimate(requirements, region, currency)` | Создаёт оценку, возвращает `estimate_id`, диапазон, часы, допущения. Для долгих расчётов асинхронно со статусом |
| `get_estimate(estimate_id)` | Итог и разбивка |
| `update_requirements(estimate_id, changes)` | Пересчёт при изменении требований, новая версия без ручной правки |
| `list_open_questions(estimate_id)` | Вопросы, на которые нужен ответ клиента |
| `market_check(estimate_id)` | Сверка с рынком |
Эскиз MCP-обёртки:
```python
from mcp.server.fastmcp import FastMCP
import httpx
mcp = FastMCP("estimation")
API = "http://estimation-service:8000"
@mcp.tool()
async def create_estimate(requirements: str, region: str = "EU", currency: str = "EUR") -> dict:
"""Создать оценку трудозатрат и стоимости по описанию задачи."""
async with httpx.AsyncClient(timeout=120) as c:
r = await c.post(f"{API}/estimates", json={
"requirements": requirements, "region": region, "currency": currency})
r.raise_for_status()
return r.json()
if __name__ == "__main__":
mcp.run()
```
### Правила для бота (системный промпт и код)
1. Цены и часы называет только результат инструмента.
2. Всегда показывать диапазон и допущения, а не одну цифру.
3. Если инструмент вернул открытые вопросы, сначала задать их клиенту.
4. Итоговое КП уходит клиенту после подтверждения человека, пока метрики плана/факта не докажут точность.
5. Каждый вызов логируется: версия конфига, входные требования, результат.
---
## 8. Сквозные требования к сервису
| Требование | Реализация |
|---|---|
| Версионирование | `estimate_id` + `config_version` + `market_version` + `model_version`; пересчёт создаёт новую версию, старая остаётся |
| Идемпотентность | Повторный вызов с теми же требованиями не создаёт дубль (ключ идемпотентности) |
| Авторизация и мультиарендность | Ключ на бота или клиента, сметы разных заказчиков не пересекаются |
| Персональные данные | В сервис передаются только требования, без контактов клиента |
| Аудит | Версии конфига и модели, хэши промптов, вход и выход |
| Тесты расчёта | Фиксированные наборы задач с эталонным результатом, чтобы правка ставок не ломала расчёт незаметно |
| Golden-тесты агента | 10–20 типовых ТЗ с ожидаемыми вилками часов, ловят дрейф после смены модели или промпта |
| Промпты | Файлы `prompts/*.md` в git, хэш промпта пишется в аудит |
| Валидация конфига | `extra="forbid"` на всех секциях: ошибка конфигурации падает при старте |
---
## 9. Тестовая стратегия
| Уровень | Что проверяем | Инструменты |
|---|---|---|
| Unit: `pricing` | PERT, ставки, округление, граничные случаи; свойства (стоимость монотонна по часам) | pytest, hypothesis |
| Unit: `agent` | Шаги конвейера с фейковым `LlmClient` и записанными ответами | pytest |
| Integration | БД, RAG, репозитории | pytest + testcontainers (Postgres с pgvector) |
| Golden | Типовые ТЗ → ожидаемые диапазоны часов и стоимости | Набор фикстур, запуск при смене модели или промпта |
| Contract | Схема OpenAPI и MCP-инструментов не ломается | schemathesis или снапшот схемы |
---
## 10. План реализации
| Этап | Содержимое | Результат |
|---|---|---|
| 1 | `pyproject.toml`, `config/` (settings + sections), `/health`, CI с линтером и тестами | Проект запускается с пустым API и валидацией конфига |
| 2 | `domain/` + `pricing/` с эталонными тестами | Детерминированный калькулятор |
| 3 | `market/repository` + `config/market/2026Q4.toml` + `market/check` | Ставки и сверка с рынком |
| 4 | `infra/llm` + `agent/pipeline` + prompts + golden-тесты | Оценка из ТЗ в JSON |
| 5 | `infra/db` + alembic + `services/estimate_service` + REST | Сохранение, версии, аудит |
| 6 | `rag/` + индексация прошлых проектов | Калибровка часов по аналогам |
| 7 | `calibration/` + приём план/факт | Коэффициенты `k` по статистике |
| 8 | `mcp/server.py` | Подключение для второго потребителя |
| 9 | `market/etl/` | Автоматизированное обновление справочника рынка |
Порядок отражает зависимости: сначала то, что не требует LLM и сети (этапы 1–3), затем агент, затем хранение и обучение на данных.
---
## 11. Открытые вопросы
| Вопрос | Влияет на |
|---|---|
| Чем реализован оркестратор текущего бота (свой на Python или готовая платформа) | Прямой function calling или сразу MCP |
| Нужны ли налоги и НДС в расчёте, для каких юрисдикций | `pricing/calculator`, секция `[pricing]` |
| Нужна ли мультитенантность с первого дня | `api/auth`, схема БД |
| Где хранить справочник рынка: TOML в git или БД | `market/repository`; на старте TOML, при частых правках БД |
| Объём исторических данных для RAG и калибровки | Этапы 6–7 |
---
## 13. Статус реализации и отклонения от проекта
Обновлено: 30 октября 2026.
### 13.1. Статус по плану (раздел 10)
| Этап | Статус |
|---|---|
| 1. Каркас, конфигурация, `/health` | готово |
| 2. `domain/` + `pricing/` с эталонными тестами | готово |
| 3. `market/repository`, справочник, `market/check` | готово (плюс эндпоинты `/api/market/*` и авторизация по ключу) |
| 4. LLM-клиент (OpenAI, Anthropic) и конвейер агента | готово на фейковых и мокнутых ответах, на реальных провайдерах не проверено |
| 5. БД, миграции, `estimate_service`, REST оценок | готово, проверено на SQLite и PostgreSQL 16 |
| 6. RAG | не начато |
| 7. Калибровка | не начато |
| 8. MCP-обёртка | не начато |
| 9. ETL рыночных данных | не начато |
### 13.2. Отклонения и уточнения
| Что | Как в проекте | Как реализовано | Причина |
|---|---|---|---|
| Путь к конфигам | Жёстко `config/` | Переменная `EST_CONFIG_DIR` (по умолчанию `config` от текущей папки) | Тесты и деплой не зависят от места запуска |
| Ключи API | Не детализировано | `EST_API__KEYS` хранится строкой `client:key,...`, словарь строится свойством `api.key_map` | pydantic-settings разбирает `dict` из env как JSON |
| Авторизация | Этап 5 | Уже в этапе 3: `X-API-Key`, сравнение через `secrets.compare_digest`, без ключей доступ закрыт | Справочник содержит внутренние ставки, открывать его нельзя |
| Сегмент `multichannel_ai` | Не было в классификаторе | Добавлен в `Segment` | Рыночный ориентир сформирован для составного сегмента |
| Порт `MarketRepo` | `rates()`, `benchmark()` | `version`, `rates()`, `currency()`, `benchmark()`, `channel_multiplier()` | Нужны валюта и версия для сверки и аудита |
| Валидация справочника | Общие слова | Pydantic со `extra="forbid"`, имя файла должно совпадать с `version`, ставки > 0, `min <= max`, роли только из `Role` | Опечатка в справочнике не должна молча менять цены |
| Версия рынка из API | Не описано | Версия проверяется regex `^[0-9A-Za-z_-]{1,32}$` до обращения к диску | Защита от обхода путей |
| Запуск | Не описано | Активная версия рынка загружается и валидируется при старте, ошибка останавливает приложение | Fail fast |
| `channel_multiplier` | Коэффициент канала | Только для быстрой оценки и масштабирования ориентиров, в расчёт по задачам не применяется | В расчёте по задачам адаптеры каналов уже отдельные задачи, иначе двойной учёт |
| Сверка с рынком | `market_check` | Границы `[min*(1-tol), max*(1+tol)]` включительно, при разных валютах `CurrencyMismatchError` (без тихой конвертации) | Конвертация появится вместе с `FxProvider` |
### 13.3. Известные ограничения текущей версии
- Доверительная стоимость считается как `cost * (hours_confident / hours)`, то есть при том же составе ролей. Для проектов с сильно разной неопределённостью по ролям это приближение.
- Справочник читается с диска один раз на версию и кэшируется в памяти процесса. Для смены версии нужен перезапуск.
- Сверка сравнивает точечную стоимость с границами рынка, диапазон `cost_confident` в сверке пока не участвует.
- Курсы валют и пересчёт между РФ и ЕС не реализованы.
### 13.4. Этап 4: LLM-слой и конвейер агента
Обновлено: 30 октября 2026.
| Что | Решение | Причина |
|---|---|---|
| Провайдеры | Свои клиенты на `httpx` для OpenAI Chat Completions и Anthropic Messages, без SDK | Меньше зависимостей, весь HTTP тестируется через `MockTransport` |
| Structured output OpenAI | `response_format: json_schema` со `strict: true`, лимит через `max_completion_tokens` | Формат Chat Completions |
| Structured output Anthropic | `output_config.format` с `type: json_schema`, ответ в текстовом блоке | Принудительный `tool_choice` отклоняется текущими моделями Claude (Opus 5.5, Sonnet 5.5, Fable 5.1, Mythos 5.1) |
| Схема | Pydantic → строгая схема: `$ref` раскрыты, у каждого объекта `additionalProperties: false` и все поля обязательны, неподдерживаемые ключевые слова убраны | Строгие режимы обоих провайдеров; диапазоны проверяет Pydantic после ответа |
| `temperature` | Не отправляется, пока не задан в конфиге | Часть моделей рассуждения его отвергает |
| Маршрутизация | Провайдер и модель на каждый шаг, опциональный `fallback` | Критика может идти у другого вендора |
| Fallback | При сбое провайдера, авторизации, отказе, битом ответе; не при 4xx-ошибке запроса | Ошибка запроса наша, другой провайдер её не исправит |
| Ключи | Нужны только провайдерам, на которые ссылаются шаги; проверка при старте | Лишние ключи не требуются |
| Битый JSON | Одна повторная попытка с текстом ошибки (`repair_attempts`) | Дёшево и обычно помогает |
| Семантические ошибки | Одна повторная попытка с перечнем проблем (пропущенные id, слишком много задач) | Схема этого не ловит |
| Идентификаторы задач | Назначаются кодом (`t1`, `t2`), модель их не придумывает | Исключает расхождение id между шагами |
| Критик | Лучшее усилие: при сбое смета остаётся с предупреждением. Правка likely сильнее чем в `critic_max_change_ratio` раз отклоняется | Сбой проверки не должен терять оценку, критик не должен раздувать её |
| Защита от инъекций | Текст клиента и сгенерированные названия в тегах, наши теги в тексте экранируются, промпты называют это данными | Клиентский текст не должен управлять конвейером |
| Аудит | `StepLog`: провайдер, модель, хэш промпта, токены, признак fallback | Воспроизводимость |
Модель по умолчанию `claude-sonnet-5-5` взята из перечня актуальных моделей Anthropic. Идентификаторы моделей OpenAI в конфиг не вписаны (закомментированный пример), их нужно сверить с документацией провайдера перед использованием.
Не проверено на реальных провайдерах: все тесты идут на подменённом HTTP. Для проверки есть `tests/integration/test_llm_live.py` (запуск с `EST_LIVE_LLM=1` и ключами).
### 13.5. Этап 5: хранилище, сервис оценок, REST
Обновлено: 30 октября 2026.
**Модель данных.** Оценка состоит из идентичности (`estimates`) и неизменяемого списка версий (`estimate_versions`). Любое изменение (ответы на вопросы, пересчёт, ручная правка) это новая версия, старые остаются доступными (`GET /api/estimates/{id}?version=N`). В версии хранятся вход, статус, результат агента, расчёт стоимости, результат сверки с рынком, версия справочника рынка и ошибка.
| Что | Решение | Причина |
|---|---|---|
| СУБД | PostgreSQL в проде (JSONB), SQLite для разработки и тестов, одна схема | Один код, тесты без сервера |
| DSN | `postgresql://` и `sqlite://` приводятся к асинхронным драйверам (`psycopg`, `aiosqlite`) | Удобство конфигурации |
| Миграции | Alembic, `python -m estimator migrate`; тест сверяет миграцию с моделями (нет расхождений) и проверяет откат | Схема не дрейфует |
| Запуск без схемы | Приложение не стартует, сообщение с подсказкой про `migrate` | Fail fast |
| Номер версии | Атомарный `UPDATE ... RETURNING` с проверкой владельца в `WHERE` | Конкурентные версии получают разные номера, в SQLite нет взаимной блокировки |
| Идемпотентность | Заголовок `Idempotency-Key` + хэш запроса: повтор возвращает оригинал, другой запрос с тем же ключом даёт 409, гонка обрабатывается ограничением уникальности | Безопасные повторы от бота |
| Изоляция | Все запросы фильтруются по клиенту из ключа API, чужая оценка даёт 404 | Мультитенантность |
| Фоновые расчёты | `JobRunner` в процессе с лимитом параллелизма (`[jobs] max_concurrent`) и таймаутом на расчёт (`timeout_s`) | Расчёт идёт десятки секунд, API отвечает 202 |
| Перезапуск | `pending` ставятся в очередь заново, `running` помечаются `failed/interrupted` и не запускаются сами | Не сжигать токены в цикле падений |
| Остановка сервиса | Незавершённые расчёты отменяются после `shutdown_grace_s` и помечаются `interrupted` | Нет вечных `running` |
| Прогресс | Поле `step` обновляется в БД по ходу конвейера (`clarify`, `decompose`, `estimate`, `critic`, `pricing`) | Интерфейс показывает прогресс |
| Роли | Модель может использовать только роли, для которых есть ставка в справочнике рынка; нарушение даёт повторный запрос и затем ошибку | Нельзя дойти до конца и упасть на расчёте |
| Валюта | Определяется регионом справочника; другая валюта в запросе даёт 422 | Конвертации нет (нужен `FxProvider`) |
| Ручная правка | `PATCH /api/estimates/{id}/tasks/{task_id}` создаёт версию `manual_edit`, пересчитывает по версии справочника исходной оценки | Правка часов не должна менять ставки |
| Ошибки в API | Коды `llm_unavailable`, `llm_auth`, `llm_refusal`, `llm_bad_output`, `pipeline_invalid`, `missing_rate`, `timeout`, `interrupted`, `internal` с безопасным текстом | Ключи и детали провайдера клиенту не отдаются |
| Аудит | Журнал шагов (провайдер, модель, хэш промпта, токены) хранится в результате версии в БД и в API не отдаётся | Воспроизводимость без утечки внутренностей |
**Эндпоинты** (все под `X-API-Key`):
| Метод и путь | Назначение |
|---|---|
| `POST /api/estimates` | Создать оценку, ответ `202` |
| `GET /api/estimates/{id}?version=N` | Статус и результат |
| `GET /api/estimates?status=&limit=&cursor=` | Список, новые первыми, курсорная пагинация |
| `POST /api/estimates/{id}/answers` | Ответы на открытые вопросы, новая версия |
| `POST /api/estimates/{id}/recalculate` | Пересчёт (можно с новыми требованиями), новая версия |
| `PATCH /api/estimates/{id}/tasks/{task_id}` | Ручная правка часов, новая версия |
**Проверено:** 262 теста на SQLite и PostgreSQL 16 (репозиторий, миграции, весь REST-сценарий, перезапуск, остановка, лимит параллелизма), живой запуск `uvicorn` на реальном Postgres.
**Ограничения.**
- Фоновые задачи живут в процессе: сервис рассчитан на один экземпляр. При нескольких репликах перезапуск одной поставит в очередь `pending`-расчёты других. Для масштабирования нужна внешняя очередь.
- Нет срока хранения и очистки старых оценок.
- Нет лимита частоты запросов на клиента.
- Ключ API определяет клиента, отдельных пользователей внутри клиента нет.
- Калибровка (этап 7) и RAG (этап 6) не подключены: `Retriever` в сервис не передаётся.
### 13.6. Веб-интерфейс
Обновлено: 31 октября 2026. Подробности и отклонения в разделе 13 `estimator-web-ui.md`.
Интерфейс на HTMX + Jinja подключается тем же приложением (`[web] enabled = true`), без Node, обращается к REST API внутри процесса через `httpx.ASGITransport` и случайные токены на процесс. Вход по пользователям из `EST_WEB__USERS`, сессия в подписанной cookie, CSRF на всех изменяющих запросах, строгий CSP. В API добавлены поля `requirements` и `answers` в ответ оценки (нужны интерфейсу для пересчёта).
Проверено: 363 теста на SQLite и PostgreSQL 16, включая 57 тестов интерфейса (вход, CSRF, XSS, изоляция, полный сценарий), плюс прогон настоящего htmx в jsdom на живом сервере.
### 13.7. Политика резерва, наценка и модель оплаты
Обновлено: 31 октября 2026. Решение и обоснование: [ADR-0001](adr/0001-reserve-policy-and-engagement.md).
| Что | Решение |
|---|---|
| Резерв | Один механизм: `max(1,04 × σ, 10% от ожидаемых часов)`, добавляется один раз. Плоский «риск 10%» и «P85» убраны |
| Наценка и маржа | `markup_pct` (20%) вместо `margin_pct`; маржа 16,7% показывается отдельно |
| Результат расчёта | `cost_expected` (без резерва), `cost_with_reserve`, резерв в часах, доле и деньгах, его основание (`pert` или `floor`), ставки клиента по ролям |
| Модель оплаты | Выбор на каждую оценку: фиксированная цена (называется цена с резервом) или T&M (ожидаемая стоимость и потолок бюджета). Меняет подачу, не часы |
| Смена модели | `POST /api/estimates/{id}/engagement`: новая версия `reprice` без вызова LLM |
| Снимок вводных | `price.inputs` хранит ставки и параметры расчёта; ручная правка пересчитывает по снимку, а не по текущим файлам |
| Миграция | `0002_engagement`: колонка `estimate_versions.engagement` |
Эталонный пример (РФ): 336 000 ₽ без резерва, 370 000 ₽ с резервом, резерв 14,5 ч (10%, основание «минимум»). Проверено: 422 теста на SQLite и PostgreSQL 16.
Ломающее изменение API: поля `price.cost` и `price.cost_confident` заменены (см. ADR). Старых развёртываний нет.
### 13.8. НДС
Обновлено: 31 октября 2026. Решение и обоснование: [ADR-0002](adr/0002-vat-layer.md).
| Что | Решение |
|---|---|
| Расчёт | Только без НДС: ставки, наценка, резерв, сверка с рынком, история |
| Показ | НДС сверху на итоговые суммы (`quote.amount_gross`, `cap_gross`); режимы «без НДС» и «сверху», режима «включён» нет |
| Ставка | На каждую оценку, хранится в версии (`vat_rate`, миграция `0003`), умолчание по региону клиента из `[pricing.vat]`: РФ 22%, ЕС без НДС |
| Допустимые ставки | Только из списка конфигурации (защита от опечаток), остальные добавляются конфигом |
| Смена ставки | `POST /api/estimates/{id}/vat`: новая версия `reprice` без LLM, общий механизм со сменой модели оплаты |
| Рынок | У ориентира `includes_vat` и `vat_rate`; ориентир с НДС приводится к цене без НДС перед сверкой |
Проверено: тесты на SQLite и PostgreSQL 16, включая миграцию `0003`. Открыто: режим налогообложения продавца (ОСНО или УСН), НДС в источниках ориентиров, предупреждение о падении наценки при фиксированной сумме с НДС.
+410
View File
@@ -0,0 +1,410 @@
# Сервис оценки: веб-интерфейс на HTMX + Jinja
**Версия:** 1.0 · **Дата:** 30 октября 2026 · **Статус:** реализовано (экраны 1–4, история, справочник), состояние и отклонения в разделе 13
**Связанные документы:** `estimator-architecture.md` (архитектура и конфигурация), `bot-estimation-market-data.md` (рыночные данные)
Документ дополняет архитектуру разделом про интерфейс. Он не меняет ядро: `web/` добавляется как ещё один вход рядом с `api/`, `mcp/` и `cli/`.
---
## 1. Принятые решения
| # | Решение | Обоснование |
|---|---|---|
| 1 | Интерфейс на **HTMX + Jinja2**, без Node в зависимостях | Экраны это формы, таблицы, статусы и справочники; сборка фронтенда не нужна |
| 2 | UI использует **REST API** как любой другой клиент (вариант B) | Один контракт для бота и интерфейса, UI ежедневно проверяет API, возможен отдельный деплой |
| 3 | Вызов API **in-process** через `httpx.ASGITransport`, без сети | Контракт соблюдается, накладных расходов нет |
| 4 | Маршруты `/ui/*` отдают только HTML-фрагменты, `/api/*` только JSON | Контракт API не засоряется `HX-Request`-ветками |
| 5 | Долгие расчёты через **асинхронное создание + опрос статуса** (`hx-trigger="every 2s"`) | Оценка идёт десятки секунд (несколько вызовов LLM) |
| 6 | JS и CSS **лежат в репозитории**, без CDN | Проще CSP и работа в закрытом контуре |
| 7 | Текст от LLM считается **недоверенным**: автоэкранирование Jinja включено, `\|safe` не используется | Защита от XSS и prompt injection через допущения и названия задач |
---
## 2. Сравнение вариантов интеграции UI и API
| Вариант | Как работает | Плюсы | Минусы | Выбор |
|---|---|---|---|---|
| A. UI вызывает `services/` напрямую | `web/` рядом с `api/` | Проще и быстрее | UI может обойти контракт, расхождения заметны поздно | нет |
| **B. UI ходит в API через клиент** | `web/` вызывает REST | Единый контракт, можно вынести в отдельный сервис | Нужен клиент и решение по аутентификации | **да** |
Клиент для in-process режима:
```python
# web/client.py
import httpx
def make_api_client(api_app, key: str) -> httpx.AsyncClient:
return httpx.AsyncClient(
transport=httpx.ASGITransport(app=api_app),
base_url="http://api",
headers={"X-API-Key": key},
)
```
Для отдельного деплоя в TOML задаётся `[web] api_base_url`, и клиент создаётся с обычным транспортом. Код маршрутов не меняется.
Нюанс: `ASGITransport` не запускает lifespan приложения. Зависимости API (БД, LLM-клиент) должны инициализироваться в общем lifespan основного приложения, а не только внутри sub-app, иначе первый вызов упадёт. Это нужно подтвердить тестом на раннем этапе.
---
## 3. Структура модуля
```
src/estimator/web/
├── router.py # подключается как /ui, отдельно от /api
├── client.py # клиент API
├── deps.py # сессия, CSRF, текущий пользователь, get_api
├── routes/
│ ├── estimates.py # список, форма, результат, статус, ответы на вопросы
│ ├── market.py # справочник рынка, версии
│ ├── feedback.py # ввод план/факт
│ └── calibration.py # коэффициенты k
├── templates/
│ ├── base.html
│ ├── components/ # макросы: таблица, бейдж, диапазон, пагинация
│ ├── estimates/
│ │ ├── list.html
│ │ ├── new.html
│ │ ├── detail.html
│ │ ├── _status.html # фрагмент опроса
│ │ ├── _result.html
│ │ ├── _task_row.html # одна строка таблицы задач
│ │ └── _questions.html # открытые вопросы
│ ├── market/
│ │ └── index.html
│ └── feedback/
│ └── form.html
└── static/
├── htmx.min.js # зафиксированная версия, не из CDN
├── app.css
├── VENDOR.md # версии и хэши вендорных файлов
└── alpine.min.js # опционально
```
Правило зависимостей прежнее: бизнес-модули ничего не знают об HTML, `web/` зависит только от API-клиента и собственных шаблонов.
### Секция конфигурации (в `default.toml`)
```toml
[web]
enabled = true
api_base_url = "" # пусто = in-process через ASGITransport
session_ttl_s = 28800
page_size = 20
poll_interval_s = 2
# из env: EST_WEB__SESSION_SECRET, EST_WEB__INTERNAL_API_KEY
```
Секрет сессии и внутренний ключ API приходят только из окружения и в браузер не попадают.
---
## 4. Контракт API, нужный интерфейсу
Реализован на этапе 5 (см. раздел 13.5 `estimator-architecture.md`). Интерфейс опирается на асинхронную модель с версиями:
| Метод | Назначение | Ответ |
|---|---|---|
| `POST /api/estimates` | Создать оценку (`Idempotency-Key` необязателен, `engagement` необязателен) | `202` + оценка со статусом `pending` |
| `POST /api/estimates/{id}/engagement` | Показать готовую оценку как фикс или T&M | `200`, новая версия `reprice` без вызова модели |
| `POST /api/estimates/{id}/vat` | Сменить ставку НДС на готовой оценке (`vat_rate`, доля) | `200`, новая версия `reprice` без пересчёта |
| `GET /api/estimates/{id}?version=N` | Статус и результат | `{id, version, latest_version, status, step, open_questions, result, error, ...}` |
| `GET /api/estimates?status=&limit=&cursor=` | Список | `{items, next_cursor}` |
| `POST /api/estimates/{id}/answers` | Ответы на открытые вопросы (`question_id`, `answer`) | `202`, новая версия |
| `POST /api/estimates/{id}/recalculate` | Пересчёт | `202`, новая версия |
| `PATCH /api/estimates/{id}/tasks/{task_id}` | Правка часов задачи | `200`, новая версия с итогом |
| `GET /api/market/versions`, `GET /api/market/{version}` | Справочник рынка | JSON |
| `POST /api/projects/{id}/actuals` | Ввод факта | этап 7, пока нет |
| `GET /api/calibration` | Коэффициенты `k` и число наблюдений | этап 7, пока нет |
Статусы: `pending`, `running`, `needs_input`, `done`, `failed`. Поле `step` содержит текущий шаг конвейера (`clarify`, `decompose`, `estimate`, `critic`, `pricing`). При `failed` поле `error` содержит `code` и безопасный текст. Идентификаторы задач (`t1`, `t2`, ...) стабильны внутри версии и используются в правках.
---
## 5. Экраны первой версии
| # | Экран | Содержимое |
|---|---|---|
| 1 | Новая оценка | Форма: описание, регион, валюта → статус → результат |
| 2 | Результат | Таблица задач (O/M/P, часы, роль), итоговый диапазон, допущения и риски, бейдж «сверка с рынком», блок открытых вопросов с формой ответа, кнопка «пересчитать» |
| 3 | История | Список оценок, версии, фильтры по региону и статусу |
| 4 | Справочник рынка | Активная версия, ставки, диапазоны (только просмотр) |
| 5 | План/факт | Форма ввода фактических часов по закрытому проекту |
| 6 | Калибровка | Таблица коэффициентов `k` по типам задач и числу наблюдений |
Правка отдельной задачи делается построчно: `hx-put`/`hx-patch` на строку, подмена только этой строки, пересчёт итога приходит следующим фрагментом (`hx-swap-oob`).
---
## 6. Рабочий скелет
### 6.1. Подключение
```python
# web/router.py
from pathlib import Path
from fastapi import APIRouter
from fastapi.staticfiles import StaticFiles
from fastapi.templating import Jinja2Templates
BASE = Path(__file__).parent
templates = Jinja2Templates(directory=BASE / "templates")
router = APIRouter(prefix="/ui")
# в app.py:
# app.include_router(web_router)
# app.mount("/ui/static", StaticFiles(directory=BASE / "static"), name="ui-static")
```
### 6.2. Маршрут создания оценки
```python
# web/routes/estimates.py
from fastapi import Depends, Form, Request
from fastapi.responses import HTMLResponse
from ..router import router, templates
from ..deps import get_api, check_csrf
@router.post("/estimates", response_class=HTMLResponse, dependencies=[Depends(check_csrf)])
async def create(request: Request, requirements: str = Form(...),
region: str = Form("ru"), currency: str = Form("RUB"),
api=Depends(get_api)):
r = await api.post("/api/estimates", json={
"requirements": requirements, "region": region, "currency": currency})
r.raise_for_status()
return templates.TemplateResponse(request, "estimates/_status.html", {"est": r.json()})
@router.get("/estimates/{est_id}/status", response_class=HTMLResponse)
async def status(request: Request, est_id: str, api=Depends(get_api)):
r = await api.get(f"/api/estimates/{est_id}")
r.raise_for_status()
return templates.TemplateResponse(request, "estimates/_status.html", {"est": r.json()})
```
### 6.3. `base.html`
```html
<!doctype html>
<html lang="ru">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{% block title %}Оценка работ{% endblock %}</title>
<link rel="stylesheet" href="/ui/static/app.css">
<script src="/ui/static/htmx.min.js" defer></script>
<meta name="csrf-token" content="{{ csrf_token }}">
</head>
<body hx-headers='{"X-CSRF-Token": "{{ csrf_token }}"}'>
<nav>
<a href="/ui/estimates/new">Новая оценка</a>
<a href="/ui/estimates">История</a>
<a href="/ui/market">Рынок</a>
<a href="/ui/calibration">Калибровка</a>
</nav>
<main>{% block content %}{% endblock %}</main>
</body>
</html>
```
### 6.4. `estimates/new.html`
```html
{% extends "base.html" %}
{% block content %}
<form hx-post="/ui/estimates" hx-target="#result" hx-swap="innerHTML">
<label>Описание задачи
<textarea name="requirements" rows="8" required></textarea>
</label>
<label>Регион
<select name="region">
<option value="ru">РФ</option>
<option value="eu">ЕС</option>
</select>
</label>
<label>Валюта
<select name="currency">
<option>RUB</option>
<option>EUR</option>
</select>
</label>
<button type="submit">Рассчитать</button>
</form>
<section id="result"></section>
{% endblock %}
```
### 6.5. `estimates/_status.html` (опрос останавливается сам)
```html
<div id="est-{{ est.id }}"
{% if est.status in ("pending", "running") %}
hx-get="/ui/estimates/{{ est.id }}/status"
hx-trigger="every 2s"
hx-swap="outerHTML"
{% endif %}>
{% if est.status == "done" %}
{% include "estimates/_result.html" %}
{% elif est.status == "needs_input" %}
{% include "estimates/_questions.html" %}
{% elif est.status == "failed" %}
<p class="error">Не удалось выполнить расчёт. Повторите попытку.</p>
{% else %}
<p>Считаю… {{ est.step or "" }}</p>
{% endif %}
</div>
```
Когда статус становится `done`, сервер возвращает фрагмент без `hx-get` и `hx-trigger`, и опрос прекращается. Если понадобится живой прогресс по шагам, подключается SSE-расширение HTMX, но на старте опроса достаточно.
### 6.6. CSRF и сессия (эскиз)
```python
# web/deps.py
import secrets
from fastapi import HTTPException, Request
def csrf_token(request: Request) -> str:
token = request.session.get("csrf")
if not token:
token = secrets.token_urlsafe(32)
request.session["csrf"] = token
return token
async def check_csrf(request: Request):
sent = request.headers.get("X-CSRF-Token")
if not sent or not secrets.compare_digest(sent, request.session.get("csrf", "")):
raise HTTPException(403, "CSRF")
```
`SessionMiddleware` подключается с секретом из `EST_WEB__SESSION_SECRET`, cookie с флагами `HttpOnly`, `Secure` (вне dev) и `SameSite=Lax`.
---
## 7. Статика без Node
| Задача | Решение |
|---|---|
| Стили | Классless-CSS (Pico или Simple.css) одним файлом, либо Tailwind standalone CLI (один бинарник, не Node, запускается только при разработке) |
| Графики | Серверный SVG из Jinja или вендорный Chart.js в `static/`; для калибровки на старте достаточно таблиц |
| Мелкая интерактивность | Нативные `<details>` и `<dialog>`, при необходимости Alpine.js одним файлом |
| Вендорные файлы | Версии и контрольные суммы записываются в `static/VENDOR.md`, обновление вручную по решению |
---
## 8. Безопасность
| Риск | Мера |
|---|---|
| XSS через текст от LLM (допущения, риски, названия задач) | Автоэкранирование Jinja включено (проверить, что оно действует для всех `.html`-шаблонов), `\|safe` на таких полях запрещён, код-ревью и тест на экранирование |
| Утечка внутреннего ключа API | Ключ только на сервере, браузер получает сессионную cookie |
| CSRF | Токен в сессии, заголовок `X-CSRF-Token` через `hx-headers` |
| Кража сессии | `HttpOnly`, `Secure`, `SameSite=Lax`, короткий TTL (`session_ttl_s`) |
| Подмена клиента | UI использует отдельный внутренний ключ с ограниченными правами |
| Утечка чужих смет | Все запросы фильтруются по клиенту/пользователю на стороне API |
| Prompt injection через требования клиента | Текст требований передаётся в LLM как данные, результат шагов валидируется схемой, отображается экранированным |
| Лишние данные в логах | В логи UI не пишется текст требований и персональные поля |
---
## 9. Тестирование
| Уровень | Что проверяем |
|---|---|
| Контракт API | OpenAPI-схема, коды ответов и статусы, snapshot схемы |
| Фрагменты UI | `TestClient`: ключевые элементы в HTML, остановка опроса после `done`, отсутствие `hx-trigger` в конечных статусах |
| Безопасность | Экранирование: оценка с `<script>` в допущениях не исполняется и выводится как текст; запрос без CSRF-токена получает 403 |
| In-process клиент | Запуск API через `ASGITransport` с инициализированными зависимостями |
| Доступ | Один пользователь не видит чужие оценки |
Браузерные тесты (Playwright) добавляются, только если экранов станет много.
---
## 10. Ограничения подхода
HTMX хорошо подходит для форм, таблиц, статусов и построчного редактирования. Если понадобится визуальный редактор декомпозиции (WBS) с перетаскиванием и зависимостями, лучше выделить для него точечную Alpine-компоненту или небольшой остров на ванильном JS, по-прежнему без Node. Для текущего набора экранов этого не требуется.
---
## 11. План реализации
| Этап | Содержимое | Зависит от |
|---|---|---|
| 1 | Каркас `web/`: router, статика, `base.html`, сессия, CSRF, `get_api` через ASGITransport | Каркас API и конфига (этап 1 архитектуры) |
| 2 | Справочник рынка (просмотр) | `market/repository` |
| 3 | Новая оценка + опрос статуса + результат | Асинхронный `POST /api/estimates` и конвейер агента |
| 4 | Открытые вопросы и пересчёт, правка задач построчно | Эндпоинты `answers`, `tasks`, `recalculate` |
| 5 | История и фильтры | Хранилище оценок |
| 6 | Ввод план/факт и экран калибровки | Модуль `calibration` |
Этапы 1 и 2 можно делать сразу после каркаса API, ещё без LLM: так проверяются сессия, CSRF и in-process клиент на простых экранах.
---
## 12. Открытые вопросы
| Вопрос | Влияет на |
|---|---|
| Кто пользователи UI: только вы, команда или клиенты | Модель аутентификации (сессия, вход через reverse proxy, роли) |
| Нужна ли привязка оценки к пользователю UI, а не только к клиенту API | Схема БД, заголовок «от имени» при вызове API |
| Нужен ли экспорт сметы (PDF, XLSX) из интерфейса | Дополнительные эндпоинты и шаблоны, вывод в КП |
| Нужен ли русско-английский интерфейс | i18n в Jinja (gettext) с первого дня или позже |
| Единый деплой или UI отдельным контейнером | `[web] api_base_url`, транспорт клиента |
---
## 13. Статус реализации и отклонения от проекта
Обновлено: 31 октября 2026.
Реализованы экраны 1–4 из раздела 5 и история: вход, новая оценка, результат со статусом и опросом, открытые вопросы, пересчёт, правка задачи в строке, список с пагинацией и справочник рынка. **Не реализованы** ввод план/факт и калибровка: их API появится на этапе 7. Экспорт сметы (PDF, XLSX) и двуязычность не делались.
### 13.1. Что сделано иначе, чем в проекте
| Что | В проекте | Реализовано | Причина |
|---|---|---|---|
| Создание оценки | `hx-post` и подмена фрагмента | Обычная форма `POST` с редиректом 303 на страницу оценки, опрос идёт уже на ней | Работает и без JavaScript, один путь для всех |
| Вызов API из UI | Один внутренний ключ `EST_WEB__INTERNAL_API_KEY` | Случайные токены на процесс, по одному на рабочее пространство, живут только в памяти. Ключ из env нужен только в режиме внешнего API (`api_base_url`) | Нечему утекать в конфиг и логи, токен недоступен браузеру |
| Аутентификация | Открытый вопрос | Пользователи в `EST_WEB__USERS` (`имя:хэш`), пароли PBKDF2-HMAC-SHA256 (600 000 итераций), хэш создаёт `python -m estimator hash-password`, подписанная cookie-сессия | Нет БД пользователей, пароли в открытом виде не хранятся |
| Рабочее пространство | Не описано | `workspace = "shared"` (все видят общие оценки) или `"per_user"` | Команда или изолированные пользователи, переключается конфигом |
| Отзыв сессии | Не описано | Подписанная cookie не отзывается, поэтому пользователь перепроверяется по конфигу на каждом запросе: удалили из `EST_WEB__USERS`, доступ пропал сразу | Cookie без серверного хранилища |
| Защита входа | Не описано | Не более `login_max_attempts` неудач за `login_window_s` на пару (адрес, пользователь), на адрес в четыре раза больше; одинаковый ответ и одинаковое время для неизвестного пользователя | Подбор паролей |
| Заголовки | CSP упомянут | `default-src 'none'; script-src 'self'; style-src 'self'; frame-ancestors 'none'`, `nosniff`, `no-store`; в шаблонах нет инлайн-скриптов и стилей | Тест это проверяет |
| htmx | Вендорный файл | 2.0.11 из npm, целостность сверена с реестром, хэш в `static/VENDOR.md`; в конфиге `allowEval=false`, `allowScriptTags=false`, `selfRequestsOnly=true`; ответы 4xx подставляются в `#flash`, 5xx нет | Ужесточение и показ ошибок валидации |
| Сообщения об ошибках | Не описано | Сообщения API переводятся на русский, ошибки 5xx не показываются (общий текст), 404 всегда «Не найдено» | Внутренности не уходят в браузер |
| Время | UTC | `[web] timezone`, по умолчанию UTC | Часовой пояс пользователя |
### 13.2. Найдено при тестировании
- Макрос Jinja, импортированный без контекста, не видел переменную `csrf_token`: форма входа отправляла пустой токен. Теперь токен передаётся макросу параметром, тест на CSRF это ловит.
- Проверка поведения htmx выполнена в jsdom с настоящим `htmx.min.js` на живом сервере: опрос обновляет панель и останавливается после готовности, строка правки подменяется формой, ошибка валидации попадает в `#flash`, успешная правка доходит с CSRF-токеном и `HX-Redirect`. Для jsdom пришлось подменить XPath-выражение, которым htmx ищет атрибуты `hx-on:*` (в проекте они не используются, в браузерах это работает).
### 13.3. Не проверено и ограничения
- **В настоящем браузере интерфейс не открывался.** jsdom не применяет CSP и не умеет переходить по `HX-Redirect`, вёрстка и тёмная тема не проверялись глазами.
- Ограничитель входа живёт в памяти процесса и сбрасывается при перезапуске. За обратным прокси нужен `uvicorn --proxy-headers`, иначе все запросы приходят с адреса прокси.
- Сессии нельзя отозвать по одной, только удалением пользователя или сменой `EST_WEB__SESSION_SECRET` (разлогинит всех).
- Правка строки поддерживается только для последней версии, старые версии показываются без действий.
- В режиме `per_user` оценки, созданные через API ботами, в интерфейсе не видны (отдельное пространство клиента).
### 13.4. Модель оплаты в интерфейсе (31.10.2026)
Подробности в [ADR-0001](adr/0001-reserve-policy-and-engagement.md).
- В форме новой оценки поле «Как продаём» (значение по умолчанию из `[pricing] default_engagement`).
- На странице оценки карточка показывает цену по выбранной модели. Фикс: цена с резервом, отдельно без резерва и сам резерв. T&M: ожидаемая стоимость, потолок бюджета и совет закрепить его в договоре.
- Переключатель «Показать как Time & Materials» и обратно создаёт новую версию без нового расчёта.
- В таблице по ролям добавлена ставка клиента (себестоимость × (1 + управление) × (1 + наценка)), по ней считается T&M.
- Карточка показывает основание резерва (по PERT или минимум), наценку и маржу.
- В истории рядом с суммой указана модель.
### 13.5. НДС в интерфейсе (31.10.2026)
Подробности в [ADR-0002](adr/0002-vat-layer.md).
- В форме новой оценки поле «НДС»: по региону клиента (РФ 22%, ЕС без НДС), «Без НДС» или ставка из списка конфигурации.
- Все цены на странице без НДС. Под ценой строка «К оплате с НДС X%» с суммой и размером НДС; для T&M отдельно ожидаемая стоимость и потолок.
- На карточке цены селектор ставки: смена создаёт новую версию без нового расчёта.
- Карточка сверки с рынком пишет, что сравнивается цена с резервом без НДС, и помечает ориентиры, приведённые из цен с НДС.