# 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. Не подменяет текущую рабочую спецификацию до утверждения решений и миграционного плана.