Files
estimator/docs/estimator-architecture.md
T
2026-11-09 08:43:30 +03:00

712 lines
50 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Сервис оценки трудозатрат и стоимости: архитектура
**Версия:** 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`
```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` (справочник рынка)
```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 и тестами структуры файлов.