Init Project Flexly Estimator

This commit is contained in:
Alexey Dudin
2026-11-03 09:37:44 +03:00
commit 447464c16c
160 changed files with 12779 additions and 0 deletions
+623
View File
@@ -0,0 +1,623 @@
# Flexly AI Estimator — архитектурное ревью и план развития v2
**Дата:** 30 октября 2026 г.
**Статус:** архитектурные рекомендации / proposal, **не** утверждённая спецификация реализации
**Область:** сервис оценки трудозатрат, стоимости и рисков проектов в экосистеме Flexly AI
**Цель:** эволюция существующего оценщика мультиканальных ботов в универсальный движок оценки программных и интеграционных проектов без переписывания готового ядра.
## 0. Документы и границы ревью
Рассмотрены следующие материалы:
1. [`estimator-architecture.md`](estimator-architecture.md) — архитектура, контракты, конфигурация, pipeline и статус реализации.
2. [`estimator-web-ui.md`](estimator-web-ui.md) — HTMX + Jinja2, UI/API, управление оценками и безопасность.
3. [`bot-estimation-market-data.md`](bot-estimation-market-data.md) — методика сбора рыночных данных, расчёты, PERT, план/факт.
4. [`README.md`](README.md) — состав документации.
**Важно о фактическом состоянии.** Заголовки проектных документов содержат старую формулировку «реализация не начата», но **раздел 13 `estimator-architecture.md` сообщает о завершении этапов 1–5**, тестировании на SQLite и PostgreSQL 16 и наличии 262 тестов. RAG, калибровка, MCP и рыночный ETL отмечены как не начатые. Эти статусы приводятся **со слов документа**: ревью исходного кода и независимый запуск тестов не выполнялись.
**Разделение фактов и предложений:** формулировки «уже реализовано / по документу» описывают имеющуюся документацию; «рекомендуется / предлагается / v2» — новые архитектурные решения, которые требуют принятия ADR и детализации спецификаций.
---
## 1. Executive summary
### Общая оценка
Основа оценщика хорошо подходит для развития. Сильные решения:
- **LLM декомпозирует и предлагает трудозатраты; Python считает деньги.** Денежные расчёты проверяемы и воспроизводимы.
- **Модульный монолит** с разделением `domain`, `agent`, `pricing`, `market`, `calibration`, `services`, `infra`.
- **REST как основной контракт**, MCP — тонкий адаптер к тем же use cases.
- **Immutable-версии смет** и фиксация рыночной конфигурации, модели и промптов.
- **Обучение на план/факте**, а не зависимость исключительно от публичных рыночных оценок.
- **HTMX + Jinja2** достаточно для первого рабочего интерфейса.
**Основная проблема:** предметная область ботов пока проходит через сегменты (`tg_single`, `site_bot`, `multichannel`, `ai_agent`, `mini_app`), коэффициенты каналов, шаблоны работ и рынок. Если расширять эту модель перечислением всё новых комбинированных сегментов, сложность будет расти непропорционально.
**Главная рекомендация:** оставить существующий универсальный `EstimateService`, но выделить **Estimator Engine + Domain Packs + библиотеку переиспользуемых Capabilities/Work Items**. Проект может состоять из возможностей разных доменов, а не принадлежать строго одному типу.
### Приоритетные изменения
| Приоритет | Изменение | Причина |
|---|---|---|
| **P0** | Универсальная предметная модель: `ProjectType`, `Capability`, `DomainPack`, `WorkItem` | Снять привязку к ботам до расширения RAG/БД |
| **P0** | Корректная экономическая модель: себестоимость, наценка, целевая маржа, налоги, внешние расходы | Предотвратить неверное ценообразование |
| **P0** | Пересмотреть учёт неопределённости, корреляций и резерва | Не выдавать неподтверждённый P85 и не учитывать риски дважды |
| **P1** | Каталог типовых работ, кросс-доменные зависимости, дедупликация WBS | Корректная смета смешанного проекта |
| **P1** | Рынок по сопоставимым характеристикам, не только по сегменту | Больше точности и объяснимости |
| **P1** | RAG + калибровка по план/факту с фильтрами контекста и доступа | Получить измеримое улучшение точности |
| **P1** | Надёжная PostgreSQL-очередь задач / worker | Масштабирование и устойчивость к рестартам |
| **P1** | Акторы, tenant scoping и права в UI/API | Подготовка к командной работе и нескольким клиентам |
| **P2** | Дополнительные Domain Packs, сценарии и экспорт КП | Расширение функциональности продукта |
---
## 2. Целевое позиционирование
**Не только «калькулятор цены бота», а движок предварительных технических и коммерческих оценок.**
Возможные потребители:
- Flexly AI Core: получение требований из Telegram, сайта/виджета и других каналов;
- собственный административный интерфейс оценщика;
- менеджер или пресейл-специалист;
- другие приложения по REST и, в перспективе, MCP.
Первоначальные направления специализации:
| Domain Pack | Примеры |
|---|---|
| `bots_ai` | Telegram/сайт/мультиканальность, RAG, LLM-агенты, CRM |
| `web` | лендинги, корпоративные сайты, каталоги, интернет-магазины |
| `software` | backend, личные кабинеты, SaaS, биллинг, API |
| `automation` | CRM/ERP-интеграции, ETL, автоматизация процессов |
Граница применения **первой расширенной версии** — прежде всего IT/цифровая разработка. Оценивание строительства, производства и иных не-IT отраслей потребует дополнительных моделей материалов, закупок, физических ресурсов, нормативов и рисков; текущая архитектура **не гарантирует** их поддержку без дальнейших расширений.
---
## 3. Целевая архитектура: Engine + Domain Packs
```text
Flexly AI channels / Admin UI / external consumers
|
REST API (OpenAPI)
|
EstimateService (use cases)
|
+-----------+-------------+-------------------+
| | |
Intake/Agent Pipeline Domain Registry Estimate Versions
| | |
| +-----------+-----------+ |
| | | | |
| bots_ai web software automation ...
| +-----------+-----------+ |
| | |
+--------- Capability / Work-Item Catalog ----+
|
Deterministic Pricing Engine
|
Market Benchmarks / Risks / RAG / Calibration
|
PostgreSQL + PGVector/BM25 + Audit
```
### 3.1. Что такое Domain Pack
Пакет предметной области — **описание специализации**, а не отдельный микросервис. Он определяет:
1. классификатор типов проектов и функциональных возможностей;
2. каталог типовых задач и зависимостей;
3. уточняющие вопросы и признаки недостаточности требований;
4. правила декомпозиции, полноты и исключения дублей;
5. допустимые роли/ресурсы, источники ставок и эталоны;
6. подсказки и инструкции для агентных шагов;
7. собственную версию и совместимость с общей схемой.
**Не превращать всё сразу в исполняемые Python-плагины.** Предпочтителен декларативный формат (TOML или YAML) с Pydantic-валидацией. Python-хуки разрешать только для предметно-специфичной логики, которой невозможно выразить декларативно. Плагины не должны вносить собственные формулы стоимости в обход `pricing`.
Пример **концептуальной** структуры (не готовая спецификация загрузчика):
```text
src/estimator/
├── domain/ # общее ядро контрактов
├── pricing/ # единая экономика и неопределённость
├── agent/ # универсальный pipeline
├── catalog/ # capabilities, work items, зависимости
├── domains/
│ ├── registry.py # поиск и проверка версий пакетов
│ ├── bots_ai/
│ │ ├── manifest.toml
│ │ ├── capabilities.yaml
│ │ ├── work_items.yaml
│ │ └── prompts/
│ ├── web/
│ ├── software/
│ └── automation/
├── market/ # рыночные данные и сопоставимость
├── calibration/ # фактические часы и статистика
├── rag/ # поиск аналогичных работ/проектов
├── services/
├── infra/
├── api/
├── web/
└── mcp/
```
### 3.2. Композиция возможностей, а не комбинаторика сегментов
Один проект может включать функциональность из нескольких доменов.
```yaml
# Иллюстративная структура входных данных; API v2 пока не утверждён.
project_type: ecommerce
capabilities:
- web.catalog
- web.checkout
- backend.auth
- integration.payment
- integration.crm
- ai.rag
- ai.chat_widget
region: ru
pricing_profile: agency_ru
```
Это лучше, чем заводить отдельные сегменты `ecommerce_with_ai_crm`, `ecommerce_with_ai_and_payments` и т. п.
### 3.3. Как избежать двойного учёта
Каталог должен различать:
- **Capability** — результат/функциональная возможность для заказчика;
- **Work Item** — конкретная работа для создания возможности;
- **Shared Work Item** — общая инфраструктура, аналитика, авторизация, CI/CD и др.;
- **Dependency** — обязательная работа или зависимость между работами;
- **Scope Boundary** — какие работы включены, исключены или уже существуют.
Например, `integration.crm` и `ai.chat_widget` могут использовать одну backend-платформу. Подсчёт выполняется по объединённому WBS с уникальными work items. Общее ядро нельзя суммировать дважды. Аналогично коэффициент за «ещё один канал» нельзя одновременно прибавлять, если адаптер канала уже представлен отдельной задачей — эта защита уже отмечена в текущем документе.
---
## 4. Предлагаемая предметная модель v2
Минимальные сущности и смысловые поля:
| Сущность | Содержание |
|---|---|
| `Project` / `Estimate` | владелец, исходные требования, тип проекта, выбранные capabilities |
| `EstimateVersion` | неизменяемая оценка, статус, снимки вводных и конфигураций |
| `DomainPackRef` | `id`, `version`, `schema_version`, хэш манифеста |
| `Capability` | стабильный код, описание результата, зависимости, критерии применимости |
| `WorkItem` | стабильный код каталога + ID экземпляра, WBS-позиция, роль, тип работы |
| `TaskEstimate` | O/M/P, базовый прогноз, источник эталона, степень неопределённости |
| `RiskEvent` | вероятность, денежное/временное воздействие, затронутые работы, стратегия обработки |
| `PricingProfile` | ставки/ресурсы, способ ценообразования, правила PM/маржи/налогов |
| `MarketBenchmark` | тип и состав проекта, регион, сложность, цена, базис и доказательства |
| `ProjectActual` | фактические часы, расходы, сроки и цена, связь с WBS/версией |
**Важно:** стабильный код шаблона работы (`integration.crm`) и идентификатор конкретной строки сметы (`task_id`) — разные поля. Нужна также связь между версиями строки (`lineage_id`), чтобы после переработки WBS можно было сравнить план/факт и историю исправлений.
Для корректной изоляции в схеме надо предусмотреть `tenant_id`, `created_by`, `approved_by` и действующие права доступа. Отдельная версия сохраняет **снимок** применённых справочников, а не только ссылку на изменяемую запись.
---
## 5. Агентный pipeline v2
Текущий `clarify → decompose → estimate → critic` стоит сохранить как основу. Предлагается расширить его логические этапы:
| # | Шаг | Ответственность |
|---|---|---|
| 1 | **Intake & Classify** | нормализовать требования; определить домены и capabilities |
| 2 | **Clarify** | собрать пробелы, сформировать приоритетные вопросы, зафиксировать допущения |
| 3 | **Decompose** | собрать WBS из каталога + нетиповые работы |
| 4 | **Retrieve Benchmarks** | найти сопоставимые задачи и завершённые проекты |
| 5 | **Estimate** | определить O/M/P, роли/ресурсы, зависимости и основания |
| 6 | **Critic & Validate** | обнаружить пропуски, дубли, неверный scope и несовместимые предположения |
| 7 | **Deterministic Pricing** | рассчитать трудозатраты, ресурсы, риски и финансовые показатели |
| 8 | **Market Check & Approval** | сверить с сопоставимыми предложениями и направить на утверждение при необходимости |
Это **логические** этапы: не требуется восемь отдельных LLM-вызовов. Часть действий выполняется кодом или объединяется в один вызов. Стоимость, задержка и количество токенов — самостоятельные KPI pipeline.
### 5.1. Два режима оценивания
**Rough Estimate (экспресс-оценка):** предварительная вилка на основе частичных требований; короткий список критических вопросов; высокое внимание к допущениям; запрет на выдачу как окончательного фиксированного предложения.
**Detailed Estimate (подробная оценка):** развёрнутая WBS; поиск аналогов; ставки и риски; несколько сценариев; экспертное подтверждение перед отправкой коммерческого предложения.
Режим и полнота данных должны быть явными атрибутами результата. При критически недостающих вводных detailed-оценка остаётся в `needs_input`, а rough-оценка может выдавать осторожный диапазон с предупреждениями.
### 5.2. Ограничения LLM
- LLM не определяет окончательную цену и не может подменять ставки.
- LLM возвращает структурированные кандидаты на задачи, часы, предположения и риски.
- Валидаторы обеспечивают уникальность WBS-элементов, существование ролей, логичность O ≤ M ≤ P, пределы задач и отсутствие дублирования.
- Сбой `critic` не должен скрываться: если расчёт всё же возвращён, он явно получает предупреждение о пропущенной проверке и может требовать подтверждения человеком.
- Клиентские ТЗ, найденные RAG-документы и LLM-ответы считаются **недоверенными входными данными**; структурная схема сама по себе не устраняет prompt injection.
---
## 6. Расчётное ядро: необходимые изменения
### 6.1. Себестоимость, наценка и маржа — разные понятия
В исходном примере из `bot-estimation-market-data.md` применяется:
```text
price = base * 1.15 (PM) * 1.10 (risk) * 1.20 (margin)
```
Последний множитель `1.20` означает **20% наценки**, а не **20% валовой маржи**.
Для себестоимости 100 000 ₽:
| Правило | Итоговая цена | Фактическая валовая маржа |
|---|---:|---:|
| Наценка 20%: `100000 × 1.20` | 120 000 ₽ | ≈16,67% |
| Целевая маржа 20%: `100000 / (1 − 0.20)` | 125 000 ₽ | 20% |
Необходимы разные параметры `markup_pct` и `target_gross_margin_pct` с взаимоисключающими режимами. Формулы должны учитывать точное определение себестоимости (включая прямые/косвенные затраты) и коммерческую политику; налог с продаж/НДС нельзя механически трактовать как прибыль.
Предлагаемая структура результата:
```text
Direct labor cost
+ Project management cost
+ External costs (лицензии, API, закупки, подрядчики)
+ Identified risk allowance / contingency (при наличии)
= Cost basis по правилам PricingProfile
→ Применение выбранной наценки ИЛИ целевой маржи
→ Налоговые правила и валюта
= Customer price, с понятной разбивкой
```
Не нужно одновременно добавлять PM как 15% и включать отдельные PM-задачи в WBS без явного правила исключения дубля. Аналогично эксплуатацию (`run`, TCO) лучше показывать отдельно от разового внедрения.
### 6.2. PERT как первый уровень, а не доказанная вероятность
Базовые формулы из текущего документа полезны:
```text
E_task = (O + 4*M + P) / 6
sigma_task = (P - O) / 6
```
Агрегация `sqrt(sum(sigma_task²))` правомерна как приближение **при независимости** задач и при принятых предположениях о распределении. В реальных проектах один риск может одновременно сдвигать backend, интеграции и QA.
Поэтому:
1. **В v2/MVP:** сохранить PERT, явно фиксировать допущение независимости, не заявлять P85 как гарантированную вероятность без эмпирической калибровки.
2. **В следующем режиме:** моделировать общие факторы риска и корреляции; поддержать Monte Carlo для времени, ресурсов и цены.
3. **Для стоимости:** считать неопределённость с учётом **ставки каждой роли**, а не масштабировать общую стоимость на `hours_p85 / hours_mean`, когда роли существенно отличаются по ставкам.
4. **Для резерва:** развести распределённую неопределённость внутри O/M/P, конкретные рисковые события и коммерческий резерв — иначе риск можно включить дважды.
5. **Для календарного срока:** учитывать зависимости задач, доступную ёмкость команды и параллельное выполнение; общие часы / 8 — это трудоёмкость в человеко-днях, не дата поставки.
Текущая архитектура прямо отмечает приближённость расчёта стоимости по `hours_confident / hours`; доработку следует запланировать как исправление модели, а не только косметическое улучшение отчёта.
### 6.3. Прозрачность оценки
Каждая итоговая цена должна сопровождаться:
- составом работ, включениями и исключениями;
- базой ставок и версией профиля;
- диапазонами времени и стоимости, **с обозначением природы диапазона**;
- факторами риска и допущениями;
- степенью уверенности с опорой на качество исходных данных, а не на самоуверенность LLM;
- отдельными разовыми и регулярными расходами.
---
## 7. Рыночная база и эталонные оценки
### 7.1. Сохранить разделение типов данных
Исходный документ обоснованно различает: цены проектов, почасовые ставки, эталонные трудозатраты, эксплуатационные цены, коэффициенты и валютно-налоговую информацию. Это разделение следует сохранить.
Рыночные данные — **проверка правдоподобия**, а не источник «правильной» цифры. Публичные прайсы/маркетинговые публикации являются слабыми приорами; фактические трудозатраты и сделки компании важнее.
### 7.2. Переход от `segment` к сопоставимому контексту
Рекомендуемые параметры `MarketBenchmark`:
```yaml
# Иллюстративный пример, а не реальная рыночная запись.
domain: software
project_type: ecommerce
capabilities: [web.catalog, web.checkout, integration.crm]
complexity: medium
region: RU
provider_type: agency
price_basis: fixed_project_ex_vat
currency: RUB
observed_at: null
source_type: internal_or_public
sample_size: null
scope: "..."
evidence_quality: unknown
```
Для ставок отдельно хранить `role`, `level`, `basis` (`freelance`, `salary_derived`, `agency_billing` и др.), регион и период наблюдения. Для трудозатрат — технологию, тип работы, сложность, объём, фактические часы и наличие повторного использования компонентов.
Важные правила:
- не смешивать цены подрядчиков разного типа в один агрегат;
- сравнивать предложения только при совместимом scope;
- проверять НДС, валюту, дату курса и единицу измерения;
- сохранять происхождение, первичные документы, признаки дублей и качество свидетельств;
- не складывать «цена мультиканальности» + «цена AI-бота», пока не доказано отсутствие пересечения в составе работ;
- малая выборка должна явно отмечаться, а не выдавать псевдоточные перцентили.
### 7.3. Метрики качества
**Не делать долю «попадания в рынок» основным показателем точности.** Она может побуждать подгонять смету под несопоставимые публикации.
Лучше оценивать:
| Метрика | Интерпретация |
|---|---|
| Ошибка по часам (MAE, WAPE и др.) | Насколько прогноз совпадает с фактической трудоёмкостью |
| Bias / systematic underestimation | Насколько систематически занижаем или завышаем |
| Coverage interval | Как часто факт попадает в обещанный диапазон |
| Ошибка по себестоимости и цене | Точность финансового прогноза отдельно от коммерческой политики |
| Качество scope | Сколько задач пропущено, продублировано, добавлено вручную |
| Human override rate | Насколько часто эксперт исправляет результат агента |
| Time-to-estimate / LLM cost | Цена и время самого оценивания |
MAPE из исходного документа можно оставлять дополнительной метрикой, но она нестабильна на очень малых фактических величинах; полезно сопоставлять её с MAE/WAPE и анализом отдельных доменов.
---
## 8. RAG и калибровка по план/факту
### 8.1. Retrieval
Использовать выбранную для Flexly AI инфраструктуру **PostgreSQL + PGVector/BM25**, без выделения нового search-сервиса на старте. При этом пространство данных оценщика логически и по правам изолировать от пользовательских баз знаний Flexly AI Core.
Поиск аналогов двухступенчатый:
1. структурные фильтры: `tenant_id`, домен/возможности, тип задачи, сложность, технология, период, сопоставимость;
2. гибридный текстово-векторный поиск и ранжирование пригодных кандидатов.
Индексировать не только описание проекта, но и WBS-работы, их предположения, фактические часы, объём и исходную версию оценки. В выдаче хранить `reference_id`, факторы сходства и основания использования. **Не возвращать цены/чувствительные данные чужого tenant.**
### 8.2. Калибровка
Идея исходного документа `k = median(actual_hours / estimated_hours)` разумна как простое первое приближение, но её нужно применять осторожно:
- коэффициент считать по сопоставимым работам/доменам/сложности, а не глобально;
- не подстраивать модель под 1–2 аномальных проекта;
- отмечать число наблюдений и качество данных;
- при малой выборке использовать консервативный prior и постепенное «усиление» собственных данных;
- хранить факт отдельно от прогноза и **не переписывать исторические версии**;
- проверять эффект калибровки на отложенных проектах, а не только на обучающей истории.
Фактические данные желательно собирать **на уровне work item**, а не только проекта: иначе невозможно понять, что регулярно недооценивается — аналитика, QA, CRM-интеграции или эксплуатация.
---
## 9. API, UI, безопасность и интеграция с Flexly AI Core
### 9.1. API
Сохранить существующий контракт `POST /api/estimates`, версии, ответы на вопросы, пересчёт и ручные правки. Расширение вводить совместимо:
- новые поля `project_type`, `capabilities`, `mode`, `pricing_profile_id` — по возможности опционально для существующих клиентов;
- `domain_pack_refs`, `scope`, `risk_register`, `uncertainty`, `cost_breakdown` — в версии результата;
- версия схемы ответа/конфигурации или отдельный API v2 при несовместимом изменении;
- стабильно сохранять `estimate_id`, версии и идемпотентность;
- старые оценки читать и пересчитывать с **их** снимком тарифов и конфигураций, если запрошен исторический повтор.
### 9.2. UI
**HTMX + Jinja2 сохранять** для первого расширенного релиза. Важнее улучшить сценарий работы, чем менять frontend-стек:
- выбор типа проекта и составных возможностей;
- индикатор полноты требований, список вопросов и допущений;
- WBS с ручным редактированием и отображением причин оценки;
- сценарии `economy / base / conservative` (или согласованные аналоги);
- сравнение версий и ручных исправлений;
- отдельные единовременные и ежемесячные расходы;
- экспорт коммерческого предложения (PDF/XLSX — по отдельной задаче);
- план/факт и показатели качества оценщика.
Если появится сложный drag-and-drop редактор WBS, можно добавить точечный JS-компонент, не переводя всё приложение на SPA.
### 9.3. Tenant / user security
Текущий API уже фильтрует сметы по клиенту из `X-API-Key`. Для полноценного UI этого недостаточно, если пользователи одной компании имеют разные права или один UI работает с несколькими организациями.
Рекомендуется:
- идентифицировать **tenant и пользователя** на доверенной стороне;
- управлять ролями `viewer`, `estimator`, `approver`, `admin` (точный перечень — ADR);
- не принимать произвольный `tenant_id` или `X-User-ID` от браузера без проверки доверенного контекста;
- проверять доступ ко **всем** версиям, задачам, рыночным данным и документам;
- ограничить и аудитировать публикацию клиенту/экспорт коммерческого предложения;
- очищать/ограничивать логи и хранилище ТЗ с учётом конфиденциальности.
XSS/CSRF-защита из текущего документа должна остаться. Prompt injection обрабатывать отдельно от XSS: экранирование HTML защищает рендер, а не инструкции для модели.
### 9.4. Конфигурация
Для Flexly AI Core ранее выбран `app_settings` как источник изменяемых настроек моделей, fallback-цепочек и таймаутов. Это **не означает**, что самостоятельный оценщик обязан писать в ту же физическую таблицу.
Разделение:
| Источник | Ответственность |
|---|---|
| `default.toml`, env | технические настройки, секреты, ограничения по умолчанию |
| DB / `app_settings` или собственное конфигурационное API | изменяемые эксплуатационные настройки, маршруты моделей и таймауты |
| `DomainPack` + каталог | предметные правила, коды capabilities и версионируемые шаблоны |
| `PricingProfile` | коммерческая политика, ставки, налоги, наценка/маржа |
| `EstimateVersion` snapshot | точный набор применённых настроек и правил конкретной оценки |
При интеграции с Flexly AI Core возможен поставщик конфигурации через API/адаптер; при отдельном инсталляционном пакете оценщик должен сохранять автономный запуск.
### 9.5. Фоновая обработка
Текущий внутрипроцессный `JobRunner` по документации рассчитан на один экземпляр и требует развития при нескольких репликах.
Рекомендуемый следующий шаг — **PostgreSQL-backed job queue** с отдельным worker, без обязательного RabbitMQ:
- транзакционный захват работ (`FOR UPDATE SKIP LOCKED` там, где применимо);
- lease/heartbeat, контроль timeout, повторный подбор зависших работ;
- идемпотентность `job_id` / `estimate_version_id`;
- лимиты параллелизма и вызовов LLM по tenant/провайдеру;
- политика повторов с учётом сетевых ошибок и риска повторного платного вызова;
- ручное возобновление, отмена, мониторинг, аудит причин сбоя.
SQLite оставить для локальных тестов, но не имитировать на ней продукционные гарантии многопроцессной очереди.
---
## 10. Переход от v1 к v2 без переписывания ядра
### Фаза 0. Зафиксировать базу и устранить несоответствия документации
- Сверить текущий код со статусами раздела 13 `estimator-architecture.md`.
- Обновить шапки документов, где написано «реализация не начата».
- Зафиксировать текущие OpenAPI snapshots, миграции, golden-тесты и эталонные расчёты.
- Зафиксировать поведение существующих `Segment`, рынка и ценового калькулятора как совместимый baseline.
**Готово, когда:** можно продемонстрировать, что старый бот-сценарий и история оценок работают до и после миграции.
### Фаза 1. Универсальное ядро и корректная экономика (**P0**)
- Ввести `DomainPackRef`, `ProjectType`, `Capability`, `WorkItem` и `PricingProfile`.
- Реализовать реестр пакетов и валидацию их схем.
- Представить текущий бот-справочник как первый `bots_ai` pack.
- Развести маржу и наценку, исключить двойной PM и двойной резерв риска.
- Явно маркировать режим расчёта и метод интервала.
**Готово, когда:** текущий бот считается новым ядром без изменения бизнес-смысла старых смет, а финансовые формулы проходят эталонные тесты.
### Фаза 2. Каталог задач и новые домены (**P0/P1**)
- Создать общие work items для аналитики, UI, backend, QA, DevOps, интеграций.
- Добавить `web`, `software`, `automation` как тонкие каталоги.
- Ввести композицию capabilities и проверку дублей.
- Добавить `Intake & Classify`, расширить `Decompose` и `Critic`.
**Готово, когда:** один проект корректно включает работы из нескольких пакетов и не получает повторных общих расходов.
### Фаза 3. Рыночная база, RAG, план/факт (**P1**)
- Перейти от сегмента к контекстным эталонам.
- Добавить гибридный поиск похожих задач с tenant-scoping.
- Собирать факт по work items, строить отчёт bias/coverage.
- Включать калибровку сначала в теневом режиме, затем после подтверждения качества.
**Готово, когда:** улучшение метрик на отложенных проектах измеримо и не приводит к ухудшению отдельных доменов.
### Фаза 4. Эксплуатационная зрелость и интерфейс (**P1/P2**)
- Вынести фоновые расчёты в PostgreSQL worker.
- Ввести user/tenant роли, жизненный цикл согласования сметы.
- Добавить UI выбора capabilities, подробную WBS, сценарии и сравнение версий.
- Реализовать экспорт КП после согласования формата.
- MCP — как тонкий адаптер к стабильному REST/use cases, когда появится реальный потребитель.
**Готово, когда:** параллельные расчёты, рестарты и разграничение доступа воспроизводимо проверяются интеграционными тестами.
---
## 11. Кандидаты ADR
Ниже **предлагаемые** решения, не принятые автоматически:
| ADR | Тема | Рекомендуемое решение |
|---|---|---|
| `ADR-EST-001` | Расширение предметных областей | Engine + декларативные Domain Packs |
| `ADR-EST-002` | Модель состава проекта | Композиция capabilities и единый WBS, а не комбинации сегментов |
| `ADR-EST-003` | Экономическая модель | Отдельные cost basis, markup, target margin, налоги, recurring costs |
| `ADR-EST-004` | Неопределённость и риск | PERT с явными допущениями; позже Monte Carlo с корреляциями |
| `ADR-EST-005` | Хранилище эталонов | SQL-истина + гибридный retrieval для описаний/аналогов |
| `ADR-EST-006` | Калибровка | Work-item plan/fact, версии, отложенная валидация, приоры при малой выборке |
| `ADR-EST-007` | Фоновые задачи | PostgreSQL-backed worker вместо in-process job runner для multi-instance |
| `ADR-EST-008` | Аутентификация UI | Tenant-scoped actor + RBAC, не общий ключ без пользовательского контекста |
| `ADR-EST-009` | Источники конфигурации | TOML/env + DB runtime settings + immutable estimate snapshot |
Каждый ADR должен фиксировать контекст, альтернативы, ограничения, последствия и план миграции с указанием затрагиваемых данных/API.
---
## 12. Тестовая стратегия и критерии готовности
### Контрольные проекты для доказательства универсальности
1. **Мультиканальный AI-бот:** Telegram + сайт + CRM + RAG.
2. **Интернет-магазин:** каталог + оформление заказа + оплата + CRM + AI-консультант.
3. **SaaS-приложение:** кабинет, роли, подписки/биллинг, backend API, администрирование.
Для всех трёх должен работать **один** `EstimateService`, единый pricing engine, единая схема версий и один интерфейс сметы. Специализация должна отличаться данными каталога/пакетов, а не крупными ветками кода `if project_type == ...`.
### Проверки
- Unit/property-based тесты: монотонность стоимости по часам, правила маржи, налоги, валюты, нулевые/аномальные вводные, исключение дублей.
- Golden-тесты: типовые ТЗ разных доменов, полнота WBS, разумные диапазоны, изменения после критика.
- Contract-тесты: совместимость существующих REST-клиентов; версионирование схем.
- Integration: PostgreSQL, concurrent version writes, очередь, retries, tenant isolation.
- Security: XSS, CSRF, prompt injection, разграничение доступа, изоляция RAG и аудита.
- Calibration: сравнение с историческим baseline, временной holdout, bias, coverage, ручные исправления.
- Эксплуатация: продолжительность оценивания, стоимость токенов, частота ошибок/fallback.
**Не стоит задавать универсальные численные пороги точности заранее:** они зависят от накопленной выборки и сложности проектов. Сначала нужен baseline, затем целевые SLA/метрики по доменам.
---
## 13. Открытые вопросы перед утверждением v2
1. **Границы продукта:** только разработка ПО и автоматизация либо намерение оценивать также не-IT работы?
2. **Коммерческая политика:** кто владеет тарифами и ценовыми профилями, нужны ли разные профили для клиентов/команд/регионов?
3. **Роли UI:** внутренний оценщик для команды, сервис для клиентов или оба режима?
4. **Смета vs коммерческое предложение:** когда и кем утверждаются итоговые значения; допускается ли автоматическая публикация предварительной вилки?
5. **Качество исходных данных:** есть ли завершённые проекты с план/фактом на уровне задач?
6. **Правила использования исторических проектов:** можно ли использовать агрегаты между tenants или данные должны быть строго изолированы?
7. **Интеграция с Flexly AI Core:** общий деплой и config provider или автономный сервис с независимой БД?
8. **Стоимость эксплуатации:** нужен ли в v2 полноценный TCO по нагрузочным сценариям (запросы/мес, токены, hosting, поддержка)?
Эти вопросы влияют на ADR и API, но **не мешают** уже сейчас разрабатывать универсальные Domain Packs и исправления расчётной модели.
---
## 14. Рекомендуемое решение
**Принять направление Estimator Engine v2 без переписывания существующих слоёв.**
Сохранить `domain/pricing/agent/market/services/infra`, REST как первичный контракт, HTMX + Jinja2 на первом этапе и историческую версионность оценок. Перед масштабированием на новые рынки и виды проектов:
1. формализовать **Domain Packs + capabilities + work-item catalog**;
2. исправить **финансовую модель и трактовку неопределённости**;
3. обеспечить **композицию WBS без двойного учёта**;
4. затем развивать **RAG, рыночные эталоны и обучение на плане/факте**;
5. отдельно усилить очередь заданий, авторизацию и UI.
**Критерий архитектурного успеха:** новый тип проекта добавляется преимущественно через данные пакета и эталонные тесты, а не через переписывание `pricing.calculator`, `EstimateService`, схемы версий и REST-роутов.
---
## Приложение A. Связь с исходными решениями
| Из исходных документов | Действие в v2 |
|---|---|
| Детерминированная цена | **Сохранить**, уточнить экономику |
| PERT O/M/P | **Сохранить как базовый режим**, не преувеличивать вероятностную интерпретацию |
| `Segment` для ботов | **Обернуть совместимостью**, заменить как главную абстракцию на capabilities |
| TOML рыночные версии | **Сохранить**, добавить метаданные сопоставимости и snapshots |
| `channel_multiplier` | **Не дублировать** с задачами каналов |
| Immutable `estimate_versions` | **Сохранить и расширить** lineage и domain pack refs |
| API + MCP | **Сохранить REST**, MCP подключать по мере реального спроса |
| HTMX + Jinja2 | **Сохранить**, добавлять точечную интерактивность |
| `JobRunner` в процессе | **Оставить на одном инстансе**, перейти на PostgreSQL worker при масштабировании |
| RAG и план/факт | **Реализовать после унификации work items**, иначе усложнится миграция |
## Приложение B. Дополнительные ориентиры
- Исходные локальные документы из раздела 0 — источник описания состояния и принятых решений проекта.
- [GAO Cost Estimating and Assessment Guide (GAO-20-195G)](https://www.gao.gov/products/gao-20-195g) — общие ориентиры по WBS, документированию допущений, анализу неопределённости и актуализации оценок. Руководство рассчитано на крупные программы; принципы следует адаптировать к масштабу Flexly AI.
---
**Статус документа:** рекомендации для архитектурного ревью и постановки ADR. Не подменяет текущую рабочую спецификацию до утверждения решений и миграционного плана.