50 KiB
Сервис оценки трудозатрат и стоимости: архитектура
Версия: 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. Приоритет источников (сверху сильнее)
- Аргументы в коде (
init) - Переменные окружения и
.env config/<env>.tomlconfig/default.toml- Значения по умолчанию в моделях секций
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
- API проверяет ключ клиента и валидирует вход.
EstimateServiceвызываетagent.pipeline: уточнение → декомпозиция → оценка O/M/P (с подсказками отrag.retriever) → критик.calibration.coefficientsприменяет коэффициентkпо типу задач.pricing.calculatorсчитает деньги по ставкам изmarket.repositoryактивной версии.market.checkсверяет итог с рынком.infra.auditзаписывает версию конфига, модель, хэши промптов, вход и выход; результат сохраняется сestimate_id.- Возвращаются диапазон, часы, допущения, открытые вопросы и результат сверки с рынком.
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()
Правила для бота (системный промпт и код)
- Цены и часы называет только результат инструмента.
- Всегда показывать диапазон и допущения, а не одну цифру.
- Если инструмент вернул открытые вопросы, сначала задать их клиенту.
- Итоговое КП уходит клиенту после подтверждения человека, пока метрики плана/факта не докажут точность.
- Каждый вызов логируется: версия конфига, входные требования, результат.
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.
| Что | Решение |
|---|---|
| Резерв | Один механизм: 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. Открыто: режим налогообложения продавца (ОСНО или УСН), НДС в источниках ориентиров, предупреждение о падении наценки при фиксированной сумме с НДС.
13.9. Мелкие долги, RAG, схлопнутые миграции
Обновлено: 2 ноября 2026. RAG подробно в ADR-0003.
| Что | Решение |
|---|---|
| Миграции | Схлопнуты в одну 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.
| Что | Решение |
|---|---|
| Образ | Двухэтапная сборка на 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 и тестами структуры файлов.