Init Project Flexly Estimator
This commit is contained in:
@@ -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. **Режим целевой маржи** вместо наценки.
|
||||
@@ -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. **НДС в ориентирах рынка:** по каждому источнику выяснить, с НДС или без, и проставить флаги.
|
||||
@@ -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 ₽ сдвинется.
|
||||
- **Данные.** Есть ли у вас уже завершённые проекты с фактическими часами, пусть даже по этапам? Это определяет, будет ли калибровка работать со старта или начнётся с нуля.
|
||||
@@ -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. Не подменяет текущую рабочую спецификацию до утверждения решений и миграционного плана.
|
||||
@@ -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`. Открыто: режим налогообложения продавца (ОСНО или УСН), НДС в источниках ориентиров, предупреждение о падении наценки при фиксированной сумме с НДС.
|
||||
|
||||
@@ -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 отдельно ожидаемая стоимость и потолок.
|
||||
- На карточке цены селектор ставки: смена создаёт новую версию без нового расчёта.
|
||||
- Карточка сверки с рынком пишет, что сравнивается цена с резервом без НДС, и помечает ориентиры, приведённые из цен с НДС.
|
||||
|
||||
Reference in New Issue
Block a user