# Сервис оценки трудозатрат и стоимости: архитектура **Версия:** 1.0 · **Дата:** 30 октября 2026 · **Статус:** проект реализован по этапам 1–5 и веб-интерфейсу, актуальное состояние в разделе 13 **Связанный документ:** `bot-estimation-market-data.md` (сбор рыночных данных, аналитика, примеры расчёта) --- ## 1. Принятые решения | # | Решение | Обоснование | |---|---|---| | 1 | Расчёт стоимости это **внешний сервис**, бот вызывает его как инструмент | Деньги считаются детерминированным кодом, а не промптом; один сервис обслуживает несколько потребителей | | 2 | Сначала **REST** (OpenAPI), затем тонкая **MCP-обёртка** над теми же use cases | Один потребитель не требует MCP; второй потребитель добавляет обёртку без переписывания ядра | | 3 | **RAG только внутри сервиса** (похожие проекты и эталонные задачи для калибровки часов) | Ставки и коэффициенты это числа, им место в SQL и TOML, а не в векторной базе | | 4 | Конфигурация **TOML + env**, секции с жёсткой валидацией | Несекретное версионируется в git, секреты приходят из окружения | | 5 | **Версионируемый справочник рынка** отдельными TOML-файлами, версия записывается в каждую смету | Смета воспроизводима, пересчёт со старой версией даёт старую цену | | 6 | **Один пакет, один процесс** на старте, чёткие границы модулей | Разделять на сервисы только при реальной нагрузке | | 7 | Бот **не называет цены сам**, цифры только из результата инструмента | Исключает «придуманные» цены | --- ## 2. Слои и правило зависимостей ``` api/ (REST) mcp/ (обёртка) cli/ (джобы) ← входы \ | / services/ (use cases: создать/пересчитать оценку) / | | \ agent/ pricing/ market/ calibration/ ← бизнес-модули \ | | / domain/ (модели, протоколы) ← чистое ядро ▲ infra/ (llm, db, rag, fx) реализует протоколы из domain/ ``` **Правило:** зависимости направлены только вниз, к `domain/`. Модуль `pricing/` не импортирует ничего из `infra/`, поэтому калькулятор тестируется без сети и базы. Провайдера LLM, хранилище или источник курсов можно заменить, не трогая бизнес-логику. --- ## 3. Структура проекта ``` estimator/ ├── pyproject.toml ├── README.md ├── .env.example # только секреты и деплой-специфика ├── config/ │ ├── default.toml # все секции с безопасными значениями по умолчанию │ ├── dev.toml # переопределения для EST_ENV=dev │ ├── prod.toml │ └── market/ │ ├── 2026Q4.toml # версионируемый справочник: ставки, коэффициенты, диапазоны │ └── 2027Q1.toml ├── migrations/ # alembic ├── prompts/ │ ├── clarify.md │ ├── decompose.md │ ├── estimate.md │ └── critic.md ├── src/estimator/ │ ├── config/ │ │ ├── settings.py # Settings: pydantic-settings, toml + env │ │ └── sections.py # модели секций (AppCfg, LlmCfg, PricingCfg, ...) │ ├── domain/ │ │ ├── models.py # Requirements, Task, TaskEstimate, Estimate, Assumption │ │ ├── enums.py # Role, Region, Segment, ProviderType │ │ ├── ports.py # Protocol: LlmClient, Retriever, MarketRepo, EstimateRepo, FxProvider │ │ └── errors.py │ ├── pricing/ # чистый код, без IO │ │ ├── pert.py # E, σ, перцентили │ │ ├── calculator.py # price(): ставки, PM, наценка, резерв, налоги │ │ └── currency.py # конвертация через FxProvider │ ├── agent/ │ │ ├── pipeline.py # clarify → decompose → estimate → critic │ │ ├── models.py # PipelineInput, PipelineResult, StepLog │ │ ├── schemas.py # JSON-схемы structured output │ │ ├── prompts.py # загрузка prompts/*.md, хэш, защита тегов │ │ ├── checks.py # структурные предупреждения │ │ └── steps/ │ │ ├── clarify.py # открытые вопросы по требованиям │ │ ├── decompose.py # WBS │ │ ├── estimate.py # O/M/P + допущения и риски │ │ ├── critic.py # проверка забытых работ, применение правок │ │ └── common.py │ ├── market/ │ │ ├── repository.py # загрузка config/market/.toml или БД │ │ ├── check.py # market_check: смета против рынка │ │ └── etl/ # сбор рыночных данных │ │ ├── collect.py │ │ ├── extract.py # LLM → PricePoint │ │ └── normalize.py │ ├── calibration/ │ │ ├── coefficients.py # k по типам задач из плана/факта │ │ └── feedback.py # приём фактических часов │ ├── rag/ │ │ ├── indexer.py # индексация прошлых проектов и эталонных задач │ │ └── retriever.py # поиск похожих задач │ ├── services/ │ │ ├── estimate_service.py # create / get / update_requirements │ │ └── market_service.py │ ├── infra/ │ │ ├── llm/ │ │ │ ├── schema.py # Pydantic → строгая JSON-схема │ │ │ ├── base.py # HTTP, ретраи, repair-цикл │ │ │ ├── openai.py # Chat Completions, response_format json_schema │ │ │ ├── anthropic.py # Messages API, output_config.format │ │ │ ├── router.py # маршрут по шагам и fallback │ │ │ └── factory.py # сборка из Settings │ │ ├── db/ │ │ │ ├── session.py │ │ │ ├── tables.py │ │ │ └── repositories.py │ │ ├── fx/ │ │ │ ├── cbr.py # курсы ЦБ РФ │ │ │ └── ecb.py │ │ └── audit.py # журнал вызовов: версии конфига и модели, вход, выход │ ├── api/ │ │ ├── app.py # FastAPI factory, lifespan │ │ ├── deps.py # сборка зависимостей из Settings │ │ ├── auth.py # API-ключи по клиентам │ │ └── routers/ │ │ ├── estimates.py │ │ ├── market.py │ │ └── health.py │ ├── mcp/ │ │ └── server.py # тонкая обёртка над services/ │ ├── cli.py # typer: migrate, reindex, market-collect, recalibrate │ └── logging.py └── tests/ ├── unit/ │ ├── pricing/ # эталонные расчёты, property-based │ └── agent/ # с фейковым LlmClient ├── integration/ # БД, RAG ├── golden/ # набор типовых ТЗ с ожидаемыми диапазонами └── conftest.py ``` ### Ответственность модулей | Модуль | Отвечает за | Не должен | |---|---|---| | `domain` | Модели данных, перечисления, протоколы (порты) | Содержать логику расчёта и импортировать инфраструктуру | | `pricing` | PERT, ставки, PM, наценка, резерв, налоги, округление | Ходить в сеть, БД и LLM | | `agent` | Конвейер LLM-шагов со structured output | Считать деньги | | `market` | Справочник ставок, диапазоны рынка, сверка сметы с рынком, ETL | Знать о HTTP | | `calibration` | Коэффициенты `k` по плану/факту | Менять смету задним числом | | `rag` | Индексация и поиск похожих задач | Возвращать цены (только часы и описания) | | `services` | Сценарии использования, оркестрация модулей | Содержать детали HTTP или SQL | | `infra` | Реализации портов: LLM, БД, курсы, аудит | Содержать бизнес-правила | | `api`, `mcp`, `cli` | Входы в систему | Содержать бизнес-логику | --- ## 4. Конфигурация: TOML + env ### 4.1. Приоритет источников (сверху сильнее) 1. Аргументы в коде (`init`) 2. Переменные окружения и `.env` 3. `config/.toml` 4. `config/default.toml` 5. Значения по умолчанию в моделях секций ### 4.2. Правило разделения | Где | Что | |---|---| | **TOML** | Несекретное и версионируемое: параметры расчёта, имена моделей, лимиты, пути, пороги | | **env** | Секреты и окружение-специфика: ключи API, DSN базы, `EST_ENV` | | **TOML `market/`** | Справочник рынка: ставки, коэффициенты, диапазоны (отдельная версия на каждый квартал) | ### 4.3. `config/default.toml` ```toml [app] name = "estimator" env = "dev" log_level = "INFO" [api] host = "0.0.0.0" port = 8000 request_timeout_s = 120 [database] pool_size = 5 # dsn приходит из env: EST_DATABASE__DSN [llm] repair_attempts = 1 # extra calls when JSON fails schema validation [llm.anthropic] base_url = "https://api.anthropic.com" api_version = "2023-06-01" timeout_s = 90 max_retries = 2 # api_key comes from env: EST_LLM__ANTHROPIC__API_KEY [llm.openai] base_url = "https://api.openai.com/v1" timeout_s = 90 max_retries = 2 # api_key comes from env: EST_LLM__OPENAI__API_KEY # every pipeline step picks its own provider and model; optional fallback [llm.steps.critic] provider = "anthropic" model = "claude-sonnet-5-5" max_tokens = 6000 # [llm.steps.critic.fallback] # provider = "openai" # model = "" [agent] prompts_dir = "prompts" max_tasks = 60 max_task_hours = 400 critic_max_change_ratio = 3.0 [rag] enabled = true embedding_model = "text-embedding-3-small" top_k = 5 min_similarity = 0.55 [pricing] default_region = "ru" default_currency = "RUB" default_engagement = "fixed_price" # fixed_price | time_and_materials pm_pct = 0.15 markup_pct = 0.20 # наценка на себестоимость (маржа = 16,7%) reserve_floor_pct = 0.10 # минимальный резерв reserve_z = 1.04 # резерв по PERT = reserve_z × σ, не калиброван estimate_unit_hours_per_day = 8 [pricing.min_rounding] step = 1000 # округление итога [market] active_version = "2026Q4" # файл config/market/2026Q4.toml check_tolerance = 0.25 [calibration] enabled = true min_samples = 5 # меньше → консервативный коэффициент по умолчанию default_k = 1.2 [fx] provider = "cbr" cache_ttl_s = 3600 [mcp] enabled = false transport = "stdio" # stdio | sse [audit] store_prompts = true ``` Значения процентов, `default_k` и ставок ниже это стартовые допущения. Их нужно заменять данными из плана/факта. ### 4.4. `config/market/2026Q4.toml` (справочник рынка) ```toml version = "2026Q4" published = "2026-10-30" note = "Стартовые приоры из открытых источников, заменять данными план/факт" [rates.ru] currency = "RUB" basis = "freelance" [rates.ru.hourly] analyst = 1500 backend = 1800 qa = 1200 devops = 1800 [rates.eu] currency = "EUR" basis = "freelance" [rates.eu.hourly] analyst = 75 backend = 85 qa = 60 devops = 90 [channel_coefficient] first = 1.0 additional = 0.15 # +15% базы за каждый канал после первого (допущение) [benchmarks.ru.multichannel_ai] min = 400000 max = 600000 currency = "RUB" [benchmarks.eu.multichannel_ai] min = 10000 max = 30000 currency = "EUR" ``` Поле `basis` обязательно: ставка разработчика и расценка агентства «под ключ» различаются в разы, и смешивать их нельзя. ### 4.5. `.env.example` ```bash EST_ENV=dev EST_DATABASE__DSN=postgresql+psycopg://user:pass@localhost:5432/estimator EST_LLM__ANTHROPIC__API_KEY=sk-ant-... EST_LLM__OPENAI__API_KEY=sk-... EST_API__KEYS=client_a:key1,client_b:key2 ``` Двойное подчёркивание обозначает вложенность: `EST_LLM__ANTHROPIC__API_KEY` попадает в `settings.llm.anthropic.api_key`. ### 4.6. `src/estimator/config/settings.py` ```python import os from pydantic_settings import (BaseSettings, SettingsConfigDict, TomlConfigSettingsSource) from .sections import (AppCfg, ApiCfg, DatabaseCfg, LlmCfg, RagCfg, PricingCfg, MarketCfg, CalibrationCfg, FxCfg, McpCfg, AuditCfg) class Settings(BaseSettings): model_config = SettingsConfigDict( env_prefix="EST_", env_nested_delimiter="__", env_file=".env", extra="forbid", # опечатка в TOML = ошибка при старте ) app: AppCfg = AppCfg() api: ApiCfg = ApiCfg() database: DatabaseCfg llm: LlmCfg rag: RagCfg = RagCfg() pricing: PricingCfg = PricingCfg() market: MarketCfg = MarketCfg() calibration: CalibrationCfg = CalibrationCfg() fx: FxCfg = FxCfg() mcp: McpCfg = McpCfg() audit: AuditCfg = AuditCfg() @classmethod def settings_customise_sources(cls, settings_cls, init_settings, env_settings, dotenv_settings, file_secret_settings): files = ["config/default.toml"] if env := os.getenv("EST_ENV"): files.append(f"config/{env}.toml") return ( init_settings, env_settings, dotenv_settings, TomlConfigSettingsSource(settings_cls, toml_file=files), file_secret_settings, ) ``` В `sections.py` секреты описываются как `SecretStr`, чтобы они не попадали в логи и `repr`: ```python from pydantic import BaseModel, SecretStr class ProviderCfg(BaseModel): base_url: str api_key: SecretStr | None = None # env only timeout_s: int = 90 max_retries: int = 2 class RouteCfg(BaseModel): provider: Literal["anthropic", "openai"] = "anthropic" model: str = "claude-sonnet-5-5" temperature: float | None = None # not sent unless set max_tokens: int = 4000 reasoning_effort: str | None = None # OpenAI only class StepRouteCfg(RouteCfg): fallback: RouteCfg | None = None ``` Перед внедрением проверьте установленную версию `pydantic-settings`: поведение `TomlConfigSettingsSource` с несколькими файлами и отсутствующими файлами нужно подтвердить тестом. --- ## 5. Порты (контракты между модулями) ```python # domain/ports.py from datetime import date from typing import Protocol class LlmClient(Protocol): async def structured(self, *, system: str, user: str, schema: type, model: str) -> object: ... class Retriever(Protocol): async def similar_tasks(self, text: str, k: int) -> list["BenchmarkTask"]: ... class MarketRepo(Protocol): def rates(self, region: str) -> "RateCard": ... def benchmark(self, region: str, segment: str) -> "Benchmark | None": ... class FxProvider(Protocol): async def rate(self, src: str, dst: str, on_date: date) -> float: ... class EstimateRepo(Protocol): async def save(self, estimate: "Estimate") -> str: ... async def get(self, estimate_id: str) -> "Estimate": ... ``` Сборка зависимостей находится в `api/deps.py`: читает `Settings`, выбирает реализации (`infra.llm.anthropic` или `infra.llm.openai` по `llm.provider`) и передаёт их в `EstimateService`. Замена провайдера это правка одной строки в TOML. --- ## 6. Сквозной поток `create_estimate` 1. API проверяет ключ клиента и валидирует вход. 2. `EstimateService` вызывает `agent.pipeline`: уточнение → декомпозиция → оценка O/M/P (с подсказками от `rag.retriever`) → критик. 3. `calibration.coefficients` применяет коэффициент `k` по типу задач. 4. `pricing.calculator` считает деньги по ставкам из `market.repository` активной версии. 5. `market.check` сверяет итог с рынком. 6. `infra.audit` записывает версию конфига, модель, хэши промптов, вход и выход; результат сохраняется с `estimate_id`. 7. Возвращаются диапазон, часы, допущения, открытые вопросы и результат сверки с рынком. --- ## 7. Контракт инструментов для бота Инструменты крупные, а не набор мелких калькуляторов. | Инструмент | Назначение | |---|---| | `create_estimate(requirements, region, currency)` | Создаёт оценку, возвращает `estimate_id`, диапазон, часы, допущения. Для долгих расчётов асинхронно со статусом | | `get_estimate(estimate_id)` | Итог и разбивка | | `update_requirements(estimate_id, changes)` | Пересчёт при изменении требований, новая версия без ручной правки | | `list_open_questions(estimate_id)` | Вопросы, на которые нужен ответ клиента | | `market_check(estimate_id)` | Сверка с рынком | Эскиз MCP-обёртки: ```python from mcp.server.fastmcp import FastMCP import httpx mcp = FastMCP("estimation") API = "http://estimation-service:8000" @mcp.tool() async def create_estimate(requirements: str, region: str = "EU", currency: str = "EUR") -> dict: """Создать оценку трудозатрат и стоимости по описанию задачи.""" async with httpx.AsyncClient(timeout=120) as c: r = await c.post(f"{API}/estimates", json={ "requirements": requirements, "region": region, "currency": currency}) r.raise_for_status() return r.json() if __name__ == "__main__": mcp.run() ``` ### Правила для бота (системный промпт и код) 1. Цены и часы называет только результат инструмента. 2. Всегда показывать диапазон и допущения, а не одну цифру. 3. Если инструмент вернул открытые вопросы, сначала задать их клиенту. 4. Итоговое КП уходит клиенту после подтверждения человека, пока метрики плана/факта не докажут точность. 5. Каждый вызов логируется: версия конфига, входные требования, результат. --- ## 8. Сквозные требования к сервису | Требование | Реализация | |---|---| | Версионирование | `estimate_id` + `config_version` + `market_version` + `model_version`; пересчёт создаёт новую версию, старая остаётся | | Идемпотентность | Повторный вызов с теми же требованиями не создаёт дубль (ключ идемпотентности) | | Авторизация и мультиарендность | Ключ на бота или клиента, сметы разных заказчиков не пересекаются | | Персональные данные | В сервис передаются только требования, без контактов клиента | | Аудит | Версии конфига и модели, хэши промптов, вход и выход | | Тесты расчёта | Фиксированные наборы задач с эталонным результатом, чтобы правка ставок не ломала расчёт незаметно | | Golden-тесты агента | 10–20 типовых ТЗ с ожидаемыми вилками часов, ловят дрейф после смены модели или промпта | | Промпты | Файлы `prompts/*.md` в git, хэш промпта пишется в аудит | | Валидация конфига | `extra="forbid"` на всех секциях: ошибка конфигурации падает при старте | --- ## 9. Тестовая стратегия | Уровень | Что проверяем | Инструменты | |---|---|---| | Unit: `pricing` | PERT, ставки, округление, граничные случаи; свойства (стоимость монотонна по часам) | pytest, hypothesis | | Unit: `agent` | Шаги конвейера с фейковым `LlmClient` и записанными ответами | pytest | | Integration | БД, RAG, репозитории | pytest + testcontainers (Postgres с pgvector) | | Golden | Типовые ТЗ → ожидаемые диапазоны часов и стоимости | Набор фикстур, запуск при смене модели или промпта | | Contract | Схема OpenAPI и MCP-инструментов не ломается | schemathesis или снапшот схемы | --- ## 10. План реализации | Этап | Содержимое | Результат | |---|---|---| | 1 | `pyproject.toml`, `config/` (settings + sections), `/health`, CI с линтером и тестами | Проект запускается с пустым API и валидацией конфига | | 2 | `domain/` + `pricing/` с эталонными тестами | Детерминированный калькулятор | | 3 | `market/repository` + `config/market/2026Q4.toml` + `market/check` | Ставки и сверка с рынком | | 4 | `infra/llm` + `agent/pipeline` + prompts + golden-тесты | Оценка из ТЗ в JSON | | 5 | `infra/db` + alembic + `services/estimate_service` + REST | Сохранение, версии, аудит | | 6 | `rag/` + индексация прошлых проектов | Калибровка часов по аналогам | | 7 | `calibration/` + приём план/факт | Коэффициенты `k` по статистике | | 8 | `mcp/server.py` | Подключение для второго потребителя | | 9 | `market/etl/` | Автоматизированное обновление справочника рынка | Порядок отражает зависимости: сначала то, что не требует LLM и сети (этапы 1–3), затем агент, затем хранение и обучение на данных. --- ## 11. Открытые вопросы | Вопрос | Влияет на | |---|---| | Чем реализован оркестратор текущего бота (свой на Python или готовая платформа) | Прямой function calling или сразу MCP | | Нужны ли налоги и НДС в расчёте, для каких юрисдикций | `pricing/calculator`, секция `[pricing]` | | Нужна ли мультитенантность с первого дня | `api/auth`, схема БД | | Где хранить справочник рынка: TOML в git или БД | `market/repository`; на старте TOML, при частых правках БД | | Объём исторических данных для RAG и калибровки | Этапы 6–7 | --- ## 13. Статус реализации и отклонения от проекта Обновлено: 30 октября 2026. ### 13.1. Статус по плану (раздел 10) | Этап | Статус | |---|---| | 1. Каркас, конфигурация, `/health` | готово | | 2. `domain/` + `pricing/` с эталонными тестами | готово | | 3. `market/repository`, справочник, `market/check` | готово (плюс эндпоинты `/api/market/*` и авторизация по ключу) | | 4. LLM-клиент (OpenAI, Anthropic) и конвейер агента | готово на фейковых и мокнутых ответах, на реальных провайдерах не проверено | | 5. БД, миграции, `estimate_service`, REST оценок | готово, проверено на SQLite и PostgreSQL 16 | | 6. RAG | основная часть готова (ADR-0003), корпус пуст, на реальных эмбеддингах не проверено | | 7. Калибровка | не начато | | 8. MCP-обёртка | не начато | | 9. ETL рыночных данных | не начато | ### 13.2. Отклонения и уточнения | Что | Как в проекте | Как реализовано | Причина | |---|---|---|---| | Путь к конфигам | Жёстко `config/` | Переменная `EST_CONFIG_DIR` (по умолчанию `config` от текущей папки) | Тесты и деплой не зависят от места запуска | | Ключи API | Не детализировано | `EST_API__KEYS` хранится строкой `client:key,...`, словарь строится свойством `api.key_map` | pydantic-settings разбирает `dict` из env как JSON | | Авторизация | Этап 5 | Уже в этапе 3: `X-API-Key`, сравнение через `secrets.compare_digest`, без ключей доступ закрыт | Справочник содержит внутренние ставки, открывать его нельзя | | Сегмент `multichannel_ai` | Не было в классификаторе | Добавлен в `Segment` | Рыночный ориентир сформирован для составного сегмента | | Порт `MarketRepo` | `rates()`, `benchmark()` | `version`, `rates()`, `currency()`, `benchmark()`, `channel_multiplier()` | Нужны валюта и версия для сверки и аудита | | Валидация справочника | Общие слова | Pydantic со `extra="forbid"`, имя файла должно совпадать с `version`, ставки > 0, `min <= max`, роли только из `Role` | Опечатка в справочнике не должна молча менять цены | | Версия рынка из API | Не описано | Версия проверяется regex `^[0-9A-Za-z_-]{1,32}$` до обращения к диску | Защита от обхода путей | | Запуск | Не описано | Активная версия рынка загружается и валидируется при старте, ошибка останавливает приложение | Fail fast | | `channel_multiplier` | Коэффициент канала | Только для быстрой оценки и масштабирования ориентиров, в расчёт по задачам не применяется | В расчёте по задачам адаптеры каналов уже отдельные задачи, иначе двойной учёт | | Сверка с рынком | `market_check` | Границы `[min*(1-tol), max*(1+tol)]` включительно, при разных валютах `CurrencyMismatchError` (без тихой конвертации) | Конвертация появится вместе с `FxProvider` | ### 13.3. Известные ограничения текущей версии - Доверительная стоимость считается как `cost * (hours_confident / hours)`, то есть при том же составе ролей. Для проектов с сильно разной неопределённостью по ролям это приближение. - Справочник читается с диска один раз на версию и кэшируется в памяти процесса. Для смены версии нужен перезапуск. - Сверка сравнивает точечную стоимость с границами рынка, диапазон `cost_confident` в сверке пока не участвует. - Курсы валют и пересчёт между РФ и ЕС не реализованы. ### 13.4. Этап 4: LLM-слой и конвейер агента Обновлено: 30 октября 2026. | Что | Решение | Причина | |---|---|---| | Провайдеры | Свои клиенты на `httpx` для OpenAI Chat Completions и Anthropic Messages, без SDK | Меньше зависимостей, весь HTTP тестируется через `MockTransport` | | Structured output OpenAI | `response_format: json_schema` со `strict: true`, лимит через `max_completion_tokens` | Формат Chat Completions | | Structured output Anthropic | `output_config.format` с `type: json_schema`, ответ в текстовом блоке | Принудительный `tool_choice` отклоняется текущими моделями Claude (Opus 5.5, Sonnet 5.5, Fable 5.1, Mythos 5.1) | | Схема | Pydantic → строгая схема: `$ref` раскрыты, у каждого объекта `additionalProperties: false` и все поля обязательны, неподдерживаемые ключевые слова убраны | Строгие режимы обоих провайдеров; диапазоны проверяет Pydantic после ответа | | `temperature` | Не отправляется, пока не задан в конфиге | Часть моделей рассуждения его отвергает | | Маршрутизация | Провайдер и модель на каждый шаг, опциональный `fallback` | Критика может идти у другого вендора | | Fallback | При сбое провайдера, авторизации, отказе, битом ответе; не при 4xx-ошибке запроса | Ошибка запроса наша, другой провайдер её не исправит | | Ключи | Нужны только провайдерам, на которые ссылаются шаги; проверка при старте | Лишние ключи не требуются | | Битый JSON | Одна повторная попытка с текстом ошибки (`repair_attempts`) | Дёшево и обычно помогает | | Семантические ошибки | Одна повторная попытка с перечнем проблем (пропущенные id, слишком много задач) | Схема этого не ловит | | Идентификаторы задач | Назначаются кодом (`t1`, `t2`), модель их не придумывает | Исключает расхождение id между шагами | | Критик | Лучшее усилие: при сбое смета остаётся с предупреждением. Правка likely сильнее чем в `critic_max_change_ratio` раз отклоняется | Сбой проверки не должен терять оценку, критик не должен раздувать её | | Защита от инъекций | Текст клиента и сгенерированные названия в тегах, наши теги в тексте экранируются, промпты называют это данными | Клиентский текст не должен управлять конвейером | | Аудит | `StepLog`: провайдер, модель, хэш промпта, токены, признак fallback | Воспроизводимость | Модель по умолчанию `claude-sonnet-5-5` взята из перечня актуальных моделей Anthropic. Идентификаторы моделей OpenAI в конфиг не вписаны (закомментированный пример), их нужно сверить с документацией провайдера перед использованием. Не проверено на реальных провайдерах: все тесты идут на подменённом HTTP. Для проверки есть `tests/integration/test_llm_live.py` (запуск с `EST_LIVE_LLM=1` и ключами). ### 13.5. Этап 5: хранилище, сервис оценок, REST Обновлено: 30 октября 2026. **Модель данных.** Оценка состоит из идентичности (`estimates`) и неизменяемого списка версий (`estimate_versions`). Любое изменение (ответы на вопросы, пересчёт, ручная правка) это новая версия, старые остаются доступными (`GET /api/estimates/{id}?version=N`). В версии хранятся вход, статус, результат агента, расчёт стоимости, результат сверки с рынком, версия справочника рынка и ошибка. | Что | Решение | Причина | |---|---|---| | СУБД | PostgreSQL в проде (JSONB), SQLite для разработки и тестов, одна схема | Один код, тесты без сервера | | DSN | `postgresql://` и `sqlite://` приводятся к асинхронным драйверам (`psycopg`, `aiosqlite`) | Удобство конфигурации | | Миграции | Alembic, `python -m estimator migrate`; тест сверяет миграцию с моделями (нет расхождений) и проверяет откат | Схема не дрейфует | | Запуск без схемы | Приложение не стартует, сообщение с подсказкой про `migrate` | Fail fast | | Номер версии | Атомарный `UPDATE ... RETURNING` с проверкой владельца в `WHERE` | Конкурентные версии получают разные номера, в SQLite нет взаимной блокировки | | Идемпотентность | Заголовок `Idempotency-Key` + хэш запроса: повтор возвращает оригинал, другой запрос с тем же ключом даёт 409, гонка обрабатывается ограничением уникальности | Безопасные повторы от бота | | Изоляция | Все запросы фильтруются по клиенту из ключа API, чужая оценка даёт 404 | Мультитенантность | | Фоновые расчёты | `JobRunner` в процессе с лимитом параллелизма (`[jobs] max_concurrent`) и таймаутом на расчёт (`timeout_s`) | Расчёт идёт десятки секунд, API отвечает 202 | | Перезапуск | `pending` ставятся в очередь заново, `running` помечаются `failed/interrupted` и не запускаются сами | Не сжигать токены в цикле падений | | Остановка сервиса | Незавершённые расчёты отменяются после `shutdown_grace_s` и помечаются `interrupted` | Нет вечных `running` | | Прогресс | Поле `step` обновляется в БД по ходу конвейера (`clarify`, `decompose`, `estimate`, `critic`, `pricing`) | Интерфейс показывает прогресс | | Роли | Модель может использовать только роли, для которых есть ставка в справочнике рынка; нарушение даёт повторный запрос и затем ошибку | Нельзя дойти до конца и упасть на расчёте | | Валюта | Определяется регионом справочника; другая валюта в запросе даёт 422 | Конвертации нет (нужен `FxProvider`) | | Ручная правка | `PATCH /api/estimates/{id}/tasks/{task_id}` создаёт версию `manual_edit`, пересчитывает по версии справочника исходной оценки | Правка часов не должна менять ставки | | Ошибки в API | Коды `llm_unavailable`, `llm_auth`, `llm_refusal`, `llm_bad_output`, `pipeline_invalid`, `missing_rate`, `timeout`, `interrupted`, `internal` с безопасным текстом | Ключи и детали провайдера клиенту не отдаются | | Аудит | Журнал шагов (провайдер, модель, хэш промпта, токены) хранится в результате версии в БД и в API не отдаётся | Воспроизводимость без утечки внутренностей | **Эндпоинты** (все под `X-API-Key`): | Метод и путь | Назначение | |---|---| | `POST /api/estimates` | Создать оценку, ответ `202` | | `GET /api/estimates/{id}?version=N` | Статус и результат | | `GET /api/estimates?status=&limit=&cursor=` | Список, новые первыми, курсорная пагинация | | `POST /api/estimates/{id}/answers` | Ответы на открытые вопросы, новая версия | | `POST /api/estimates/{id}/recalculate` | Пересчёт (можно с новыми требованиями), новая версия | | `PATCH /api/estimates/{id}/tasks/{task_id}` | Ручная правка часов, новая версия | **Проверено:** 262 теста на SQLite и PostgreSQL 16 (репозиторий, миграции, весь REST-сценарий, перезапуск, остановка, лимит параллелизма), живой запуск `uvicorn` на реальном Postgres. **Ограничения.** - Фоновые задачи живут в процессе: сервис рассчитан на один экземпляр. При нескольких репликах перезапуск одной поставит в очередь `pending`-расчёты других. Для масштабирования нужна внешняя очередь. - Нет срока хранения и очистки старых оценок. - Нет лимита частоты запросов на клиента. - Ключ API определяет клиента, отдельных пользователей внутри клиента нет. - Калибровка (этап 7) и RAG (этап 6) не подключены: `Retriever` в сервис не передаётся. ### 13.6. Веб-интерфейс Обновлено: 31 октября 2026. Подробности и отклонения в разделе 13 `estimator-web-ui.md`. Интерфейс на HTMX + Jinja подключается тем же приложением (`[web] enabled = true`), без Node, обращается к REST API внутри процесса через `httpx.ASGITransport` и случайные токены на процесс. Вход по пользователям из `EST_WEB__USERS`, сессия в подписанной cookie, CSRF на всех изменяющих запросах, строгий CSP. В API добавлены поля `requirements` и `answers` в ответ оценки (нужны интерфейсу для пересчёта). Проверено: 363 теста на SQLite и PostgreSQL 16, включая 57 тестов интерфейса (вход, CSRF, XSS, изоляция, полный сценарий), плюс прогон настоящего htmx в jsdom на живом сервере. ### 13.7. Политика резерва, наценка и модель оплаты Обновлено: 31 октября 2026. Решение и обоснование: [ADR-0001](adr/0001-reserve-policy-and-engagement.md). | Что | Решение | |---|---| | Резерв | Один механизм: `max(1,04 × σ, 10% от ожидаемых часов)`, добавляется один раз. Плоский «риск 10%» и «P85» убраны | | Наценка и маржа | `markup_pct` (20%) вместо `margin_pct`; маржа 16,7% показывается отдельно | | Результат расчёта | `cost_expected` (без резерва), `cost_with_reserve`, резерв в часах, доле и деньгах, его основание (`pert` или `floor`), ставки клиента по ролям | | Модель оплаты | Выбор на каждую оценку: фиксированная цена (называется цена с резервом) или T&M (ожидаемая стоимость и потолок бюджета). Меняет подачу, не часы | | Смена модели | `POST /api/estimates/{id}/engagement`: новая версия `reprice` без вызова LLM | | Снимок вводных | `price.inputs` хранит ставки и параметры расчёта; ручная правка пересчитывает по снимку, а не по текущим файлам | | Миграция | `0002_engagement`: колонка `estimate_versions.engagement` | Эталонный пример (РФ): 336 000 ₽ без резерва, 370 000 ₽ с резервом, резерв 14,5 ч (10%, основание «минимум»). Проверено: 422 теста на SQLite и PostgreSQL 16. Ломающее изменение API: поля `price.cost` и `price.cost_confident` заменены (см. ADR). Старых развёртываний нет. ### 13.8. НДС Обновлено: 31 октября 2026. Решение и обоснование: [ADR-0002](adr/0002-vat-layer.md). | Что | Решение | |---|---| | Расчёт | Только без НДС: ставки, наценка, резерв, сверка с рынком, история | | Показ | НДС сверху на итоговые суммы (`quote.amount_gross`, `cap_gross`); режимы «без НДС» и «сверху», режима «включён» нет | | Ставка | На каждую оценку, хранится в версии (`vat_rate`, миграция `0003`), умолчание по региону клиента из `[pricing.vat]`: РФ 22%, ЕС без НДС | | Допустимые ставки | Только из списка конфигурации (защита от опечаток), остальные добавляются конфигом | | Смена ставки | `POST /api/estimates/{id}/vat`: новая версия `reprice` без LLM, общий механизм со сменой модели оплаты | | Рынок | У ориентира `includes_vat` и `vat_rate`; ориентир с НДС приводится к цене без НДС перед сверкой | Проверено: тесты на SQLite и PostgreSQL 16, включая миграцию `0003`. Открыто: режим налогообложения продавца (ОСНО или УСН), НДС в источниках ориентиров, предупреждение о падении наценки при фиксированной сумме с НДС. ### 13.9. Мелкие долги, RAG, схлопнутые миграции Обновлено: 2 ноября 2026. RAG подробно в [ADR-0003](adr/0003-rag-reference-tasks.md). | Что | Решение | |---|---| | Миграции | Схлопнуты в одну `0001_initial` (ревизии `0002_engagement`, `0003_vat_rate` и упоминания о них в ADR-0001 и ADR-0002 исторические). Пока нигде нет установленной базы, схему можно править в этом файле; после первой установки только новые ревизии | | Автор версий | У оценки `created_by` (кто начал), у каждой версии свой `created_by` (кто сделал). Для ключа API это имя клиента, для интерфейса имя человека (токены UI теперь на пользователя, а не на рабочее пространство). Изоляция данных по-прежнему идёт по клиенту | | «Предварительная оценка» | `result.preliminary` и причины, если оценка опирается на допущения по неуточнённым вопросам; в интерфейсе плашка и пометка в истории. Ручная правка и смена модели оплаты статус не меняют | | Роли | В справочник рынка добавлены ставки `frontend` и `designer`. **Это допущения без источника** (frontend равен backend, designer условный), помечены в файле и ждут реальных значений | | RAG | Таблица `reference_tasks` (pgvector и HNSW на PostgreSQL, JSON и Python на SQLite), эмбеддинги OpenAI-совместимые или офлайн `hash`, поиск аналогов по каждой задаче, загрузка через CLI `rag`, аналоги видны в интерфейсе и сохраняются в результате | | Конфигурация | `[rag]`: `enabled=false` по умолчанию, `provider`, `model`, `base_url`, `top_k`, `min_similarity`, `batch_size`; `agent.reference_k` удалён (заменён на `rag.top_k`) | Проверено: 599 тестов на SQLite и PostgreSQL 16 с pgvector 0.6.0, прогон настоящего htmx в jsdom. ### 13.10. Docker и запуск Обновлено: 2 ноября 2026. Подробности в [deployment.md](deployment.md). | Что | Решение | |---|---| | Образ | Двухэтапная сборка на `python:3.12-slim`, запуск не от root, `config/`, `prompts/`, `migrations/` и `alembic.ini` лежат в `/app` (сервис читает их относительно рабочего каталога) | | Миграции | Отдельное разовое задание `migrate` в compose; сервис стартует только после его успешного завершения. Для одного контейнера есть `MIGRATE_ON_START=true` | | База | `pgvector/pgvector:pg16`, готовность проверяется по TCP | | Новые команды | `python -m estimator wait-db [--timeout N]`; настройки `[api] proxy_headers` и `forwarded_allow_ips` | | `.env` | Читаются только ключи с префиксом `EST_`: переменные compose в том же файле сервису не мешают, а опечатка с префиксом по-прежнему вызывает ошибку | | Зависимости | Добавлен пропущенный `pgvector`; тест сверяет все импортируемые пакеты с `pyproject.toml` | Образ в среде разработки не собирался (нет Docker); проверка выполнена имитацией на PostgreSQL 16 с pgvector и тестами структуры файлов.