52 KiB
Flexly AI Estimator — архитектурное ревью и план развития v2
Дата: 30 октября 2026 г.
Статус: архитектурные рекомендации / proposal, не утверждённая спецификация реализации
Область: сервис оценки трудозатрат, стоимости и рисков проектов в экосистеме Flexly AI
Цель: эволюция существующего оценщика мультиканальных ботов в универсальный движок оценки программных и интеграционных проектов без переписывания готового ядра.
0. Документы и границы ревью
Рассмотрены следующие материалы:
estimator-architecture.md— архитектура, контракты, конфигурация, pipeline и статус реализации.estimator-web-ui.md— HTMX + Jinja2, UI/API, управление оценками и безопасность.bot-estimation-market-data.md— методика сбора рыночных данных, расчёты, PERT, план/факт.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
Пакет предметной области — описание специализации, а не отдельный микросервис. Он определяет:
- классификатор типов проектов и функциональных возможностей;
- каталог типовых задач и зависимостей;
- уточняющие вопросы и признаки недостаточности требований;
- правила декомпозиции, полноты и исключения дублей;
- допустимые роли/ресурсы, источники ставок и эталоны;
- подсказки и инструкции для агентных шагов;
- собственную версию и совместимость с общей схемой.
Не превращать всё сразу в исполняемые 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.
Поэтому:
- В v2/MVP: сохранить PERT, явно фиксировать допущение независимости, не заявлять P85 как гарантированную вероятность без эмпирической калибровки.
- В следующем режиме: моделировать общие факторы риска и корреляции; поддержать Monte Carlo для времени, ресурсов и цены.
- Для стоимости: считать неопределённость с учётом ставки каждой роли, а не масштабировать общую стоимость на
hours_p85 / hours_mean, когда роли существенно отличаются по ставкам. - Для резерва: развести распределённую неопределённость внутри O/M/P, конкретные рисковые события и коммерческий резерв — иначе риск можно включить дважды.
- Для календарного срока: учитывать зависимости задач, доступную ёмкость команды и параллельное выполнение; общие часы / 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.
Поиск аналогов двухступенчатый:
- структурные фильтры:
tenant_id, домен/возможности, тип задачи, сложность, технология, период, сопоставимость; - гибридный текстово-векторный поиск и ранжирование пригодных кандидатов.
Индексировать не только описание проекта, но и 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_aipack. - Развести маржу и наценку, исключить двойной 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. Тестовая стратегия и критерии готовности
Контрольные проекты для доказательства универсальности
- Мультиканальный AI-бот: Telegram + сайт + CRM + RAG.
- Интернет-магазин: каталог + оформление заказа + оплата + CRM + AI-консультант.
- 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
- Границы продукта: только разработка ПО и автоматизация либо намерение оценивать также не-IT работы?
- Коммерческая политика: кто владеет тарифами и ценовыми профилями, нужны ли разные профили для клиентов/команд/регионов?
- Роли UI: внутренний оценщик для команды, сервис для клиентов или оба режима?
- Смета vs коммерческое предложение: когда и кем утверждаются итоговые значения; допускается ли автоматическая публикация предварительной вилки?
- Качество исходных данных: есть ли завершённые проекты с план/фактом на уровне задач?
- Правила использования исторических проектов: можно ли использовать агрегаты между tenants или данные должны быть строго изолированы?
- Интеграция с Flexly AI Core: общий деплой и config provider или автономный сервис с независимой БД?
- Стоимость эксплуатации: нужен ли в v2 полноценный TCO по нагрузочным сценариям (запросы/мес, токены, hosting, поддержка)?
Эти вопросы влияют на ADR и API, но не мешают уже сейчас разрабатывать универсальные Domain Packs и исправления расчётной модели.
14. Рекомендуемое решение
Принять направление Estimator Engine v2 без переписывания существующих слоёв.
Сохранить domain/pricing/agent/market/services/infra, REST как первичный контракт, HTMX + Jinja2 на первом этапе и историческую версионность оценок. Перед масштабированием на новые рынки и виды проектов:
- формализовать Domain Packs + capabilities + work-item catalog;
- исправить финансовую модель и трактовку неопределённости;
- обеспечить композицию WBS без двойного учёта;
- затем развивать RAG, рыночные эталоны и обучение на плане/факте;
- отдельно усилить очередь заданий, авторизацию и 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. Не подменяет текущую рабочую спецификацию до утверждения решений и миграционного плана.