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