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

52 KiB
Raw Permalink Blame History

Flexly AI Estimator — архитектурное ревью и план развития v2

Дата: 30 октября 2026 г.
Статус: архитектурные рекомендации / proposal, не утверждённая спецификация реализации
Область: сервис оценки трудозатрат, стоимости и рисков проектов в экосистеме Flexly AI
Цель: эволюция существующего оценщика мультиканальных ботов в универсальный движок оценки программных и интеграционных проектов без переписывания готового ядра.

0. Документы и границы ревью

Рассмотрены следующие материалы:

  1. estimator-architecture.md — архитектура, контракты, конфигурация, pipeline и статус реализации.
  2. estimator-web-ui.md — HTMX + Jinja2, UI/API, управление оценками и безопасность.
  3. bot-estimation-market-data.md — методика сбора рыночных данных, расчёты, PERT, план/факт.
  4. 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

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.

Пример концептуальной структуры (не готовая спецификация загрузчика):

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. Композиция возможностей, а не комбинаторика сегментов

Один проект может включать функциональность из нескольких доменов.

# Иллюстративная структура входных данных; 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 применяется:

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 с взаимоисключающими режимами. Формулы должны учитывать точное определение себестоимости (включая прямые/косвенные затраты) и коммерческую политику; налог с продаж/НДС нельзя механически трактовать как прибыль.

Предлагаемая структура результата:

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 как первый уровень, а не доказанная вероятность

Базовые формулы из текущего документа полезны:

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:

# Иллюстративный пример, а не реальная рыночная запись.
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) — общие ориентиры по WBS, документированию допущений, анализу неопределённости и актуализации оценок. Руководство рассчитано на крупные программы; принципы следует адаптировать к масштабу Flexly AI.

Статус документа: рекомендации для архитектурного ревью и постановки ADR. Не подменяет текущую рабочую спецификацию до утверждения решений и миграционного плана.