Files
estimator/docs/estimator-architecture-review-v2.md

624 lines
52 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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. Не подменяет текущую рабочую спецификацию до утверждения решений и миграционного плана.