Init Project Flexly Estimator

This commit is contained in:
Alexey Dudin
2026-11-03 09:37:44 +03:00
commit 447464c16c
160 changed files with 12779 additions and 0 deletions
+681
View File
@@ -0,0 +1,681 @@
# Сервис оценки трудозатрат и стоимости: архитектура
**Версия:** 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 | не начато |
| 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`. Открыто: режим налогообложения продавца (ОСНО или УСН), НДС в источниках ориентиров, предупреждение о падении наценки при фиксированной сумме с НДС.