Files
estimator/docs/estimator-architecture.md
T

46 KiB
Raw Blame History

Сервис оценки трудозатрат и стоимости: архитектура

Версия: 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/<version>.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/<env>.toml
  4. config/default.toml
  5. Значения по умолчанию в моделях секций

4.2. Правило разделения

Где Что
TOML Несекретное и версионируемое: параметры расчёта, имена моделей, лимиты, пути, пороги
env Секреты и окружение-специфика: ключи API, DSN базы, EST_ENV
TOML market/ Справочник рынка: ставки, коэффициенты, диапазоны (отдельная версия на каждый квартал)

4.3. config/default.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 = "<model id>"

[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 (справочник рынка)

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

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

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:

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. Порты (контракты между модулями)

# 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-обёртки:

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 не начато
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.

Что Решение
Резерв Один механизм: 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.

Что Решение
Расчёт Только без НДС: ставки, наценка, резерв, сверка с рынком, история
Показ НДС сверху на итоговые суммы (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. Открыто: режим налогообложения продавца (ОСНО или УСН), НДС в источниках ориентиров, предупреждение о падении наценки при фиксированной сумме с НДС.