Init Project Flexly Estimator
This commit is contained in:
@@ -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`. Открыто: режим налогообложения продавца (ОСНО или УСН), НДС в источниках ориентиров, предупреждение о падении наценки при фиксированной сумме с НДС.
|
||||
|
||||
Reference in New Issue
Block a user