From 447464c16c457cf20b3f9c871154285fa1173b06 Mon Sep 17 00:00:00 2001 From: Alexey Dudin Date: Tue, 3 Nov 2026 09:37:44 +0300 Subject: [PATCH] Init Project Flexly Estimator --- .env.example | 7 + .gitignore | 9 + Makefile | 16 + README.md | 123 +++ alembic.ini | 38 + config/default.toml | 138 +++ config/dev.toml | 2 + config/market/2026Q4.toml | 39 + config/prod.toml | 5 + docs/README.md | 11 + .../adr/0001-reserve-policy-and-engagement.md | 124 +++ docs/adr/0002-vat-layer.md | 67 ++ docs/bot-estimation-market-data.md | 552 ++++++++++++ ...timator-architecture-review-v2-response.md | 48 ++ docs/estimator-architecture-review-v2.md | 623 ++++++++++++++ docs/estimator-architecture.md | 681 +++++++++++++++ docs/estimator-web-ui.md | 410 +++++++++ migrations/env.py | 58 ++ migrations/script.py.mako | 22 + migrations/versions/0001_initial.py | 67 ++ migrations/versions/0002_engagement.py | 25 + migrations/versions/0003_vat_rate.py | 23 + prompts/.gitkeep | 0 prompts/clarify.md | 24 + prompts/critic.md | 10 + prompts/decompose.md | 16 + prompts/estimate.md | 16 + pyproject.toml | 47 ++ src/estimator/__init__.py | 1 + src/estimator/__main__.py | 57 ++ src/estimator/agent/__init__.py | 5 + src/estimator/agent/checks.py | 24 + src/estimator/agent/models.py | 53 ++ src/estimator/agent/pipeline.py | 197 +++++ src/estimator/agent/prompts.py | 43 + src/estimator/agent/schemas.py | 71 ++ src/estimator/agent/steps/__init__.py | 0 src/estimator/agent/steps/clarify.py | 34 + src/estimator/agent/steps/common.py | 24 + src/estimator/agent/steps/critic.py | 105 +++ src/estimator/agent/steps/decompose.py | 64 ++ src/estimator/agent/steps/estimate.py | 61 ++ src/estimator/api/__init__.py | 0 src/estimator/api/app.py | 91 ++ src/estimator/api/auth.py | 19 + src/estimator/api/deps.py | 17 + src/estimator/api/routers/__init__.py | 0 src/estimator/api/routers/estimates.py | 176 ++++ src/estimator/api/routers/health.py | 10 + src/estimator/api/routers/market.py | 51 ++ src/estimator/calibration/__init__.py | 1 + src/estimator/config/__init__.py | 3 + src/estimator/config/sections.py | 262 ++++++ src/estimator/config/settings.py | 105 +++ src/estimator/domain/__init__.py | 0 src/estimator/domain/enums.py | 39 + src/estimator/domain/errors.py | 109 +++ src/estimator/domain/estimates.py | 100 +++ src/estimator/domain/llm.py | 28 + src/estimator/domain/models.py | 128 +++ src/estimator/domain/ports.py | 81 ++ src/estimator/infra/__init__.py | 0 src/estimator/infra/db/__init__.py | 5 + src/estimator/infra/db/repositories.py | 274 ++++++ src/estimator/infra/db/session.py | 27 + src/estimator/infra/db/tables.py | 68 ++ src/estimator/infra/db/types.py | 31 + src/estimator/infra/llm/__init__.py | 6 + src/estimator/infra/llm/anthropic.py | 64 ++ src/estimator/infra/llm/base.py | 194 +++++ src/estimator/infra/llm/factory.py | 36 + src/estimator/infra/llm/openai.py | 65 ++ src/estimator/infra/llm/router.py | 64 ++ src/estimator/infra/llm/schema.py | 54 ++ src/estimator/logging.py | 8 + src/estimator/market/__init__.py | 4 + src/estimator/market/check.py | 53 ++ src/estimator/market/models.py | 48 ++ src/estimator/market/repository.py | 109 +++ src/estimator/mcp/__init__.py | 1 + src/estimator/passwords.py | 55 ++ src/estimator/pricing/__init__.py | 5 + src/estimator/pricing/calculator.py | 121 +++ src/estimator/pricing/pert.py | 16 + src/estimator/pricing/quote.py | 31 + src/estimator/rag/__init__.py | 1 + src/estimator/services/__init__.py | 4 + src/estimator/services/estimate_service.py | 467 +++++++++++ src/estimator/services/jobs.py | 45 + src/estimator/services/views.py | 125 +++ src/estimator/web/__init__.py | 3 + src/estimator/web/client.py | 134 +++ src/estimator/web/deps.py | 82 ++ src/estimator/web/format.py | 111 +++ src/estimator/web/mount.py | 103 +++ src/estimator/web/routes/__init__.py | 0 src/estimator/web/routes/auth.py | 61 ++ src/estimator/web/routes/estimates.py | 230 +++++ src/estimator/web/routes/market.py | 15 + src/estimator/web/security.py | 89 ++ src/estimator/web/static/VENDOR.md | 8 + src/estimator/web/static/app.css | 63 ++ src/estimator/web/static/htmx.min.js | 1 + src/estimator/web/templates/base.html | 34 + .../web/templates/components/macros.html | 9 + src/estimator/web/templates/error.html | 9 + .../web/templates/estimates/_panel.html | 47 ++ .../web/templates/estimates/_questions.html | 22 + .../web/templates/estimates/_result.html | 133 +++ .../web/templates/estimates/_rows.html | 18 + .../templates/estimates/_task_edit_row.html | 18 + .../web/templates/estimates/_task_row.html | 22 + .../web/templates/estimates/detail.html | 6 + .../web/templates/estimates/list.html | 21 + .../web/templates/estimates/new.html | 44 + src/estimator/web/templates/login.html | 20 + src/estimator/web/templates/market/index.html | 41 + src/estimator/web/templating.py | 50 ++ tests/__init__.py | 0 tests/conftest.py | 40 + tests/factories.py | 19 + tests/fakes.py | 52 ++ tests/golden/.gitkeep | 0 tests/helpers.py | 20 + tests/integration/.gitkeep | 0 tests/integration/__init__.py | 0 tests/integration/db/__init__.py | 0 tests/integration/db/test_migrations.py | 79 ++ tests/integration/db/test_repository.py | 226 +++++ tests/integration/test_llm_live.py | 50 ++ tests/integration/test_pipeline_over_http.py | 170 ++++ tests/unit/__init__.py | 0 tests/unit/agent/__init__.py | 0 tests/unit/agent/conftest.py | 109 +++ tests/unit/agent/test_pipeline.py | 374 +++++++++ tests/unit/agent/test_prompts_and_schemas.py | 80 ++ tests/unit/api/__init__.py | 0 tests/unit/api/test_estimates_api.py | 591 +++++++++++++ tests/unit/api/test_lifecycle.py | 101 +++ tests/unit/api/test_market_api.py | 105 +++ tests/unit/config/__init__.py | 0 tests/unit/config/test_market_toml.py | 15 + tests/unit/config/test_settings.py | 162 ++++ tests/unit/llm/__init__.py | 0 tests/unit/llm/conftest.py | 70 ++ tests/unit/llm/test_anthropic.py | 114 +++ tests/unit/llm/test_openai.py | 160 ++++ tests/unit/llm/test_router.py | 152 ++++ tests/unit/llm/test_schema.py | 69 ++ tests/unit/market/__init__.py | 0 tests/unit/market/test_check.py | 70 ++ tests/unit/market/test_repository.py | 135 +++ tests/unit/pricing/__init__.py | 0 tests/unit/pricing/test_calculator.py | 226 +++++ tests/unit/pricing/test_pert.py | 19 + tests/unit/test_health.py | 13 + tests/unit/test_jobs.py | 65 ++ tests/unit/web/__init__.py | 0 tests/unit/web/test_ui.py | 792 ++++++++++++++++++ tests/unit/web/test_units.py | 166 ++++ 160 files changed, 12779 insertions(+) create mode 100644 .env.example create mode 100644 .gitignore create mode 100644 Makefile create mode 100644 README.md create mode 100644 alembic.ini create mode 100644 config/default.toml create mode 100644 config/dev.toml create mode 100644 config/market/2026Q4.toml create mode 100644 config/prod.toml create mode 100644 docs/README.md create mode 100644 docs/adr/0001-reserve-policy-and-engagement.md create mode 100644 docs/adr/0002-vat-layer.md create mode 100644 docs/bot-estimation-market-data.md create mode 100644 docs/estimator-architecture-review-v2-response.md create mode 100644 docs/estimator-architecture-review-v2.md create mode 100644 docs/estimator-architecture.md create mode 100644 docs/estimator-web-ui.md create mode 100644 migrations/env.py create mode 100644 migrations/script.py.mako create mode 100644 migrations/versions/0001_initial.py create mode 100644 migrations/versions/0002_engagement.py create mode 100644 migrations/versions/0003_vat_rate.py create mode 100644 prompts/.gitkeep create mode 100644 prompts/clarify.md create mode 100644 prompts/critic.md create mode 100644 prompts/decompose.md create mode 100644 prompts/estimate.md create mode 100644 pyproject.toml create mode 100644 src/estimator/__init__.py create mode 100644 src/estimator/__main__.py create mode 100644 src/estimator/agent/__init__.py create mode 100644 src/estimator/agent/checks.py create mode 100644 src/estimator/agent/models.py create mode 100644 src/estimator/agent/pipeline.py create mode 100644 src/estimator/agent/prompts.py create mode 100644 src/estimator/agent/schemas.py create mode 100644 src/estimator/agent/steps/__init__.py create mode 100644 src/estimator/agent/steps/clarify.py create mode 100644 src/estimator/agent/steps/common.py create mode 100644 src/estimator/agent/steps/critic.py create mode 100644 src/estimator/agent/steps/decompose.py create mode 100644 src/estimator/agent/steps/estimate.py create mode 100644 src/estimator/api/__init__.py create mode 100644 src/estimator/api/app.py create mode 100644 src/estimator/api/auth.py create mode 100644 src/estimator/api/deps.py create mode 100644 src/estimator/api/routers/__init__.py create mode 100644 src/estimator/api/routers/estimates.py create mode 100644 src/estimator/api/routers/health.py create mode 100644 src/estimator/api/routers/market.py create mode 100644 src/estimator/calibration/__init__.py create mode 100644 src/estimator/config/__init__.py create mode 100644 src/estimator/config/sections.py create mode 100644 src/estimator/config/settings.py create mode 100644 src/estimator/domain/__init__.py create mode 100644 src/estimator/domain/enums.py create mode 100644 src/estimator/domain/errors.py create mode 100644 src/estimator/domain/estimates.py create mode 100644 src/estimator/domain/llm.py create mode 100644 src/estimator/domain/models.py create mode 100644 src/estimator/domain/ports.py create mode 100644 src/estimator/infra/__init__.py create mode 100644 src/estimator/infra/db/__init__.py create mode 100644 src/estimator/infra/db/repositories.py create mode 100644 src/estimator/infra/db/session.py create mode 100644 src/estimator/infra/db/tables.py create mode 100644 src/estimator/infra/db/types.py create mode 100644 src/estimator/infra/llm/__init__.py create mode 100644 src/estimator/infra/llm/anthropic.py create mode 100644 src/estimator/infra/llm/base.py create mode 100644 src/estimator/infra/llm/factory.py create mode 100644 src/estimator/infra/llm/openai.py create mode 100644 src/estimator/infra/llm/router.py create mode 100644 src/estimator/infra/llm/schema.py create mode 100644 src/estimator/logging.py create mode 100644 src/estimator/market/__init__.py create mode 100644 src/estimator/market/check.py create mode 100644 src/estimator/market/models.py create mode 100644 src/estimator/market/repository.py create mode 100644 src/estimator/mcp/__init__.py create mode 100644 src/estimator/passwords.py create mode 100644 src/estimator/pricing/__init__.py create mode 100644 src/estimator/pricing/calculator.py create mode 100644 src/estimator/pricing/pert.py create mode 100644 src/estimator/pricing/quote.py create mode 100644 src/estimator/rag/__init__.py create mode 100644 src/estimator/services/__init__.py create mode 100644 src/estimator/services/estimate_service.py create mode 100644 src/estimator/services/jobs.py create mode 100644 src/estimator/services/views.py create mode 100644 src/estimator/web/__init__.py create mode 100644 src/estimator/web/client.py create mode 100644 src/estimator/web/deps.py create mode 100644 src/estimator/web/format.py create mode 100644 src/estimator/web/mount.py create mode 100644 src/estimator/web/routes/__init__.py create mode 100644 src/estimator/web/routes/auth.py create mode 100644 src/estimator/web/routes/estimates.py create mode 100644 src/estimator/web/routes/market.py create mode 100644 src/estimator/web/security.py create mode 100644 src/estimator/web/static/VENDOR.md create mode 100644 src/estimator/web/static/app.css create mode 100644 src/estimator/web/static/htmx.min.js create mode 100644 src/estimator/web/templates/base.html create mode 100644 src/estimator/web/templates/components/macros.html create mode 100644 src/estimator/web/templates/error.html create mode 100644 src/estimator/web/templates/estimates/_panel.html create mode 100644 src/estimator/web/templates/estimates/_questions.html create mode 100644 src/estimator/web/templates/estimates/_result.html create mode 100644 src/estimator/web/templates/estimates/_rows.html create mode 100644 src/estimator/web/templates/estimates/_task_edit_row.html create mode 100644 src/estimator/web/templates/estimates/_task_row.html create mode 100644 src/estimator/web/templates/estimates/detail.html create mode 100644 src/estimator/web/templates/estimates/list.html create mode 100644 src/estimator/web/templates/estimates/new.html create mode 100644 src/estimator/web/templates/login.html create mode 100644 src/estimator/web/templates/market/index.html create mode 100644 src/estimator/web/templating.py create mode 100644 tests/__init__.py create mode 100644 tests/conftest.py create mode 100644 tests/factories.py create mode 100644 tests/fakes.py create mode 100644 tests/golden/.gitkeep create mode 100644 tests/helpers.py create mode 100644 tests/integration/.gitkeep create mode 100644 tests/integration/__init__.py create mode 100644 tests/integration/db/__init__.py create mode 100644 tests/integration/db/test_migrations.py create mode 100644 tests/integration/db/test_repository.py create mode 100644 tests/integration/test_llm_live.py create mode 100644 tests/integration/test_pipeline_over_http.py create mode 100644 tests/unit/__init__.py create mode 100644 tests/unit/agent/__init__.py create mode 100644 tests/unit/agent/conftest.py create mode 100644 tests/unit/agent/test_pipeline.py create mode 100644 tests/unit/agent/test_prompts_and_schemas.py create mode 100644 tests/unit/api/__init__.py create mode 100644 tests/unit/api/test_estimates_api.py create mode 100644 tests/unit/api/test_lifecycle.py create mode 100644 tests/unit/api/test_market_api.py create mode 100644 tests/unit/config/__init__.py create mode 100644 tests/unit/config/test_market_toml.py create mode 100644 tests/unit/config/test_settings.py create mode 100644 tests/unit/llm/__init__.py create mode 100644 tests/unit/llm/conftest.py create mode 100644 tests/unit/llm/test_anthropic.py create mode 100644 tests/unit/llm/test_openai.py create mode 100644 tests/unit/llm/test_router.py create mode 100644 tests/unit/llm/test_schema.py create mode 100644 tests/unit/market/__init__.py create mode 100644 tests/unit/market/test_check.py create mode 100644 tests/unit/market/test_repository.py create mode 100644 tests/unit/pricing/__init__.py create mode 100644 tests/unit/pricing/test_calculator.py create mode 100644 tests/unit/pricing/test_pert.py create mode 100644 tests/unit/test_health.py create mode 100644 tests/unit/test_jobs.py create mode 100644 tests/unit/web/__init__.py create mode 100644 tests/unit/web/test_ui.py create mode 100644 tests/unit/web/test_units.py diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..61067f4 --- /dev/null +++ b/.env.example @@ -0,0 +1,7 @@ +EST_ENV=dev +EST_DATABASE__DSN=postgresql+psycopg://user:pass@localhost:5432/estimator +# Keys are needed only for providers that some step actually uses +EST_LLM__ANTHROPIC__API_KEY=sk-ant-... +EST_LLM__OPENAI__API_KEY=sk-... +EST_API__KEYS=client_a:key1,client_b:key2 +# EST_CONFIG_DIR=config diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a6ee5f2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +__pycache__/ +*.pyc +.venv/ +.env +.pytest_cache/ +.ruff_cache/ +*.egg-info/ +dist/ +build/ diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..574301f --- /dev/null +++ b/Makefile @@ -0,0 +1,16 @@ +.PHONY: install run test lint fmt + +install: + pip install -e ".[dev]" + +run: + python -m estimator + +test: + pytest + +lint: + ruff check . + +fmt: + ruff format . diff --git a/README.md b/README.md new file mode 100644 index 0000000..9a4f53d --- /dev/null +++ b/README.md @@ -0,0 +1,123 @@ +# estimator + +Service for estimating labor effort and cost of work. An agent decomposes and estimates the work +(LLM, structured output); a deterministic calculator turns hours into money. + +Status: stages 1-5 of the plan are done (config, domain, pricing, versioned market data with market +check, API-key auth, multi-provider LLM layer, agent pipeline, PostgreSQL/SQLite storage with +migrations, background jobs and the REST API for estimates). +The HTMX web UI is built too (see below). Next: RAG and calibration, then the MCP wrapper. +See section 13 of docs/estimator-architecture.md for status and deviations from the design. + +## Docs + +| File | What it covers | +|---|---| +| [docs/estimator-architecture.md](docs/estimator-architecture.md) | Layers, project structure, TOML + env config, ports, flow | +| [docs/estimator-web-ui.md](docs/estimator-web-ui.md) | HTMX + Jinja interface that talks to the API | +| [docs/bot-estimation-market-data.md](docs/bot-estimation-market-data.md) | Market data sources, ETL, analytics snapshot, worked examples | + +## Quick start + +```bash +python -m venv .venv && . .venv/bin/activate +pip install -e ".[dev]" +cp .env.example .env # fill in secrets (a key per provider that a step uses) +python -m estimator migrate # create the database schema +python -m estimator # http://localhost:8000/health (docs at /docs) +pytest +ruff check . +``` + +## Configuration + +- Non-secret settings: `config/default.toml`, overridden by `config/.toml`. +- Secrets and environment-specific values: env vars with prefix `EST_`, nested with `__` + (for example `EST_LLM__API_KEY`). +- `EST_CONFIG_DIR` points to another config directory (default `config`, relative to the working dir). +- Market reference data (rates, benchmarks) is versioned in `config/market/.toml`. +- Unknown keys in any section fail at startup. + +Priority, highest first: init args, env and `.env`, `config/.toml`, `config/default.toml`, +defaults in `config/sections.py`. + +## LLM providers + +OpenAI (Chat Completions) and Anthropic (Messages) are supported. Each pipeline step has its own +route in `[llm.steps.]`: provider, model, `max_tokens`, optional `temperature` and +`reasoning_effort` (OpenAI), and an optional `[llm.steps..fallback]`. API keys come from +`EST_LLM__ANTHROPIC__API_KEY` and `EST_LLM__OPENAI__API_KEY`; only providers that a step uses need one. + +Live check against the real APIs (skipped by default): + +```bash +EST_LIVE_LLM=1 EST_LIVE_OPENAI_MODEL= pytest tests/integration/test_llm_live.py -s +``` + +Prompts are in `prompts/*.md`; their hash is written to the audit log of every step. + +## Database + +`EST_DATABASE__DSN` accepts `postgresql://...` (production, JSONB) or `sqlite:///path.db` (development). +Apply migrations with `python -m estimator migrate`; the service refuses to start without a schema. +Each estimate is an append-only list of versions: answers, recalculation and manual edits create a new +version and keep the old ones. + +## API in short + +```bash +curl -s -X POST localhost:8000/api/estimates -H "X-API-Key: " -H "Idempotency-Key: job-42" \ + -H "Content-Type: application/json" \ + -d '{"requirements": "Telegram bot with a knowledge base and amoCRM", "region": "ru"}' +# -> 202 {"id": "...", "status": "pending", ...} then poll GET /api/estimates/{id} +``` + +Statuses: `pending`, `running`, `needs_input` (answer via `/answers`), `done`, `failed`. +The service runs background jobs inside the process, so run a single instance for now. + +## Tests + +```bash +pytest # SQLite +TEST_PG_DSN=postgresql://user@host:5432/testdb pytest # SQLite and PostgreSQL (drops the tables in testdb) +``` + +## Web UI + +Off by default. To enable it: + +```bash +python -m estimator hash-password # asks for a password (12+ characters), prints a hash +export EST_WEB__ENABLED=true +export EST_WEB__SESSION_SECRET=$(python -c "import secrets; print(secrets.token_urlsafe(48))") +export EST_WEB__USERS="alex:,bob:" +python -m estimator # http://localhost:8000/ui/ +``` + +Settings are in `[web]` of `config/default.toml`: `workspace` (`shared` or `per_user`), `timezone`, +`poll_interval_s`, `cookie_secure` (set it behind HTTPS; `prod.toml` already does), login throttling. +Behind a reverse proxy start uvicorn with `--proxy-headers`. The UI has no Node dependency; htmx is +vendored in `src/estimator/web/static/` (see `VENDOR.md`). + +## Pricing in short + +``` +without reserve = sum(hours x rate) x (1 + PM) x (1 + markup) # a markup: 20% markup = 16.7% margin +reserve hours = max(1.04 x sigma, 10% of expected hours) # one reserve, added once +with reserve = without reserve x (1 + reserve hours / expected hours) +``` + +Each estimate is sold either as **fixed price** (the price with the reserve is quoted) or as **time and +materials** (the expected cost is quoted, the reserve becomes a budget ceiling, and client hourly rates +per role are shown). Choose it per estimate in the UI or with `engagement` in the API, default in +`[pricing] default_engagement`; switching a finished estimate creates a new version without a model call. +The rates and parameters used are stored with every result, so repricing never depends on today's files. +Reasoning and numbers: `docs/adr/0001-reserve-policy-and-engagement.md`. + +## VAT + +Everything is calculated without VAT; VAT is added on top when quoting. The rate is chosen per +estimate (default by the client's region in `[pricing.vat]`: Russian client 22%, EU client none) and +stored with the version; changing it creates a new version without recalculation. Market benchmarks +carry `includes_vat`/`vat_rate` and are converted to prices without VAT before the check. See +`docs/adr/0002-vat-layer.md`. diff --git a/alembic.ini b/alembic.ini new file mode 100644 index 0000000..935b0d8 --- /dev/null +++ b/alembic.ini @@ -0,0 +1,38 @@ +[alembic] +script_location = migrations +prepend_sys_path = src +path_separator = os +# the database URL comes from EST_DATABASE__DSN (see migrations/env.py) + +[loggers] +keys = root,sqlalchemy,alembic + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = WARNING +handlers = console +qualname = + +[logger_sqlalchemy] +level = WARNING +handlers = +qualname = sqlalchemy.engine + +[logger_alembic] +level = INFO +handlers = +qualname = alembic + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(levelname)-5.5s [%(name)s] %(message)s diff --git a/config/default.toml b/config/default.toml new file mode 100644 index 0000000..e9201dc --- /dev/null +++ b/config/default.toml @@ -0,0 +1,138 @@ +[app] +name = "estimator" +env = "dev" +log_level = "INFO" + +[api] +host = "0.0.0.0" +port = 8000 +request_timeout_s = 120 + +[database] +pool_size = 5 +echo = false +# dsn comes from 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 + +# Each pipeline step picks its own provider and model. +# temperature is omitted unless set (some reasoning models reject it). +[llm.steps.clarify] +provider = "anthropic" +model = "claude-sonnet-5-5" +max_tokens = 3000 + +[llm.steps.decompose] +provider = "anthropic" +model = "claude-sonnet-5-5" +max_tokens = 8000 + +[llm.steps.estimate] +provider = "anthropic" +model = "claude-sonnet-5-5" +max_tokens = 8000 + +[llm.steps.critic] +provider = "anthropic" +model = "claude-sonnet-5-5" +max_tokens = 6000 + +# Example: critic on another vendor, with the first vendor as fallback. +# Check the model ID in the provider docs before use. +# [llm.steps.critic] +# provider = "openai" +# model = "gpt-6.1-sol" +# reasoning_effort = "low" +# max_tokens = 6000 +# [llm.steps.critic.fallback] +# provider = "anthropic" +# model = "claude-sonnet-5-5" +# max_tokens = 6000 + +[agent] +prompts_dir = "prompts" +max_requirements_chars = 20000 +max_questions = 7 +max_tasks = 60 +max_task_hours = 400 +max_critic_new_tasks = 10 +critic_max_change_ratio = 3.0 +reference_k = 5 + +[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, chosen per estimate in the UI/API +pm_pct = 0.15 +markup_pct = 0.20 # markup on cost; the implied margin is markup / (1 + markup) +reserve_floor_pct = 0.10 # minimum reserve; the PERT reserve is used when it is larger +reserve_z = 1.04 # PERT reserve = reserve_z x sigma of the estimate, not a calibrated quantile +estimate_unit_hours_per_day = 8 + +[pricing.vat] +# VAT is shown on top of prices that are calculated without it. Defaults by the client's region: +# Russian client: 22% (the general rate since 2026, for a seller that charges VAT); EU client: none, +# services to a foreign client are outside Russian VAT. Override per estimate in the UI or API. +default_rates = { ru = 0.22, eu = 0.0 } +choices = [0.22, 0.10, 0.07, 0.05] # other rates offered besides "no VAT" + +[pricing.min_rounding] +step = 1000 + +[market] +active_version = "2026Q4" +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" + +[web] +enabled = false +api_base_url = "" # empty = call the API inside this process +session_ttl_s = 28800 +page_size = 20 +poll_interval_s = 2 +workspace = "shared" # shared | per_user +timezone = "UTC" +cookie_secure = false # true behind HTTPS +login_max_attempts = 5 +login_window_s = 300 +# secrets come from env: EST_WEB__SESSION_SECRET, EST_WEB__USERS, EST_WEB__INTERNAL_API_KEY + +[audit] +store_prompts = true + +[jobs] +max_concurrent = 4 +timeout_s = 300 +shutdown_grace_s = 10 diff --git a/config/dev.toml b/config/dev.toml new file mode 100644 index 0000000..99448d1 --- /dev/null +++ b/config/dev.toml @@ -0,0 +1,2 @@ +[app] +log_level = "DEBUG" diff --git a/config/market/2026Q4.toml b/config/market/2026Q4.toml new file mode 100644 index 0000000..dedc64b --- /dev/null +++ b/config/market/2026Q4.toml @@ -0,0 +1,39 @@ +version = "2026Q4" +published = "2026-10-30" +note = "Starting priors from public sources; replace with plan/fact data" + +[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 # assumption: +15% of base per extra channel + +[benchmarks.ru.multichannel_ai] +min = 400000 +max = 600000 +currency = "RUB" +includes_vat = false # the sources do not say; assumed to be without VAT, to be checked + +[benchmarks.eu.multichannel_ai] +min = 10000 +max = 30000 +currency = "EUR" +includes_vat = false # the sources do not say; assumed to be without VAT, to be checked diff --git a/config/prod.toml b/config/prod.toml new file mode 100644 index 0000000..a6491ee --- /dev/null +++ b/config/prod.toml @@ -0,0 +1,5 @@ +[app] +log_level = "INFO" + +[web] +cookie_secure = true diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..2b5d821 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,11 @@ +# Documentation + +1. [estimator-architecture.md](estimator-architecture.md): decisions, layers, structure, config, ports, flow, plan +2. [estimator-web-ui.md](estimator-web-ui.md): UI on HTMX + Jinja, in-process API client, screens, security +3. [bot-estimation-market-data.md](bot-estimation-market-data.md): market data collection, sources, analytics (snapshot 2026-10-30), worked examples + +Market figures in (3) are starting priors from public, mostly marketing, sources. Replace them with plan/fact data as projects close. +4. [estimator-architecture-review-v2.md](estimator-architecture-review-v2.md): внешнее архитектурное ревью и план развития v2 (Engine + Domain Packs, экономическая модель, неопределённость, RAG и калибровка). Это предложения, не утверждённая спецификация; статусы в нём даны по документам, а не по коду +5. [estimator-architecture-review-v2-response.md](estimator-architecture-review-v2-response.md): разбор этого ревью: что принимаем, что корректируем, что откладываем, порядок работ и два открытых вопроса +6. [adr/0001-reserve-policy-and-engagement.md](adr/0001-reserve-policy-and-engagement.md): решение по резерву, наценке, модели оплаты (фикс или T&M) и снимку вводных, с числами и чувствительностью +7. [adr/0002-vat-layer.md](adr/0002-vat-layer.md): НДС как слой показа поверх цен без НДС, ставки по умолчанию для РФ и ЕС, приведение ориентиров рынка, что проверено и что открыто diff --git a/docs/adr/0001-reserve-policy-and-engagement.md b/docs/adr/0001-reserve-policy-and-engagement.md new file mode 100644 index 0000000..a129d7b --- /dev/null +++ b/docs/adr/0001-reserve-policy-and-engagement.md @@ -0,0 +1,124 @@ +# ADR-0001: политика резерва, наценка и модель оплаты (фикс или T&M) + +**Дата:** 31 октября 2026 · **Статус:** принято и реализовано +**Основание:** [разбор ревью v2](../estimator-architecture-review-v2-response.md), замечания 1 и 2 (наценка и маржа, двойной резерв), пункт про снимок вводных; решение владельца продукта от 31.10.2026 +**Затрагивает:** `pricing/`, `domain/models.py`, API оценок, интерфейс, миграция `0002_engagement` + +## Контекст + +В первой версии калькулятора были три проблемы. + +1. **Двойной резерв.** Цена считалась как `база × (1 + PM) × (1 + риск 10%) × (1 + маржа 20%)`, а «цена с запасом» получалась умножением этого числа на отношение часов P85 к ожидаемым. Резерв учитывался дважды: плоские 10% и ещё запас по PERT. Подпись «≈P85» к тому же обещала вероятность, которую никто не калибровал. +2. **Название «маржа».** Параметр `margin_pct = 0,20` это множитель `×1,20`, то есть **наценка** на себестоимость. Маржа при такой наценке 16,7%. +3. **Вводные не сохранялись.** В версии хранилось только имя справочника рынка (`2026Q4`), ставки читались из файла. Правка файла задним числом меняла результат ручной правки и пересчёта. + +Отдельно нужно было решить, как продавать работу: по фиксированной цене или Time & Materials. По словам владельца, малые и понятные проекты проще вести по фиксу, а проекты, где всё может поменяться много раз, и сложные заказчики лучше подходят для T&M. Поэтому выбор должен быть настройкой, а не зашитым правилом. + +## Решение + +### 1. Один механизм резерва + +``` +ожидаемые часы H = Σ E (PERT) +разброс σ = √Σσᵢ² +резерв по PERT Rp = z × σ (z = 1,04, не калиброван) +минимальный резерв Rf = floor × H (floor = 10%) +резерв, часы R = max(Rp, Rf) +``` + +``` +стоимость без резерва = Σ(часы × ставка) × (1 + PM) × (1 + наценка) +стоимость с резервом = стоимость без резерва × (1 + R / H) +``` + +- Резерв добавляется **один раз**. Плоской надбавки «риск 10%» больше нет, её роль выполняет минимум. +- Минимум страхует от того, что трёхточечная оценка не видит: смены объёма, переделок по замечаниям, слишком узких O и P (их разброс задан промптом, а не измерен) и того, что задачи ошибаются вместе, хотя `σ` считается как для независимых. +- Стоимость резерва считается при том же составе ролей, что и основная работа (приближение). +- Подпись «≈P85» убрана. Показывается честная формулировка: «резерв по разбросу оценок (PERT)» или «минимальный резерв», с обеими частями. +- Результат содержит оба слагаемых (`pert_reserve_hours`, `floor_reserve_hours`), итоговый резерв, его долю и основание (`reserve_basis`: `pert` или `floor`). + +### 2. Наценка вместо маржи + +`margin_pct` переименован в `markup_pct` (значение 20% прежнее). Результат содержит `implied_margin_pct = markup / (1 + markup)` (16,7%), интерфейс показывает «наценка 20% (маржа 16,7%)». Режим целевой маржи не добавлялся. + +### 3. Параметры + +| Параметр | Значение по умолчанию | Смысл | +|---|---|---| +| `pm_pct` | 0,15 | управление проектом, процент к себестоимости работ | +| `markup_pct` | 0,20 | наценка на себестоимость | +| `reserve_floor_pct` | 0,10 | минимальный резерв от ожидаемых часов | +| `reserve_z` | 1,04 | коэффициент при σ для резерва по PERT | +| `default_engagement` | `fixed_price` | модель оплаты по умолчанию | + +Прежние ключи `risk_pct`, `margin_pct`, `confidence_z` удалены. Конфигурация строгая, старый ключ в TOML вызывает ошибку при запуске, а не молча игнорируется. + +### 4. Модель оплаты как выбор на каждую оценку + +Модель выбирается при создании оценки (поле в форме и в API, значение по умолчанию из конфига) и хранится в версии. Она **меняет подачу, а не трудозатраты**: обе суммы всегда считаются из одних чисел. + +| | Фиксированная цена | Time & Materials | +|---|---|---| +| Что называем клиенту | `cost_with_reserve` | `cost_expected` | +| Резерв | внутри цены, риск на подрядчике | потолок бюджета (`cap` = `cost_with_reserve`), его стоит закрепить в договоре | +| Часы в заголовке | с резервом | ожидаемые, потолок в часах отдельно | +| Ставки | не нужны | ставка клиента по ролям: `ставка × (1 + PM) × (1 + наценка)` | + +- Смена модели у готовой оценки это `POST /api/estimates/{id}/engagement`: **новая версия с источником `reprice`, без обращения к модели**, числа не пересчитываются. Повтор той же модели новой версии не создаёт. +- Ответы на вопросы, пересчёт и ручная правка сохраняют модель; пересчёт может сменить её явно. +- Сверка с рынком всегда сравнивает **цену с резервом**: ориентиры рынка это итоговые цены проектов. + +### 5. Снимок вводных + +В результат расчёта (`price.inputs`) записываются ставки по ролям, `pm_pct`, `markup_pct`, `reserve_floor_pct`, `reserve_z` и шаг округления. Ручная правка пересчитывает цену **по этому снимку** (`price_with`), а не по текущему файлу ставок и не по текущим настройкам. Сверка с рынком при этом использует ориентир и допуск из прежней сверки. Тест это проверяет: после смены наценки в настройках правка старой оценки сохраняет прежнюю наценку, а новая оценка берёт новую. + +## Числа + +Пример из документа с рыночными данными (РФ, шаг округления 1 000 ₽): + +| | Было | Стало | +|---|---|---| +| Без резерва | не показывалось | **336 000 ₽** | +| Цена с резервом | 370 000 ₽ (плоские 10%) | **370 000 ₽** (минимум 10%) | +| «С запасом P85» | 397 000 ₽ (резерв дважды) | убрано | +| Маржа при наценке 20% | называлась «маржа 20%» | 16,7% | + +Чувствительность к минимальному резерву (тот же проект, σ = 10 ч, резерв по PERT 7,2%): + +| Минимум | Цена с резервом | Основание | +|---|---|---| +| 0% | 361 000 ₽ | PERT | +| **10%** | **370 000 ₽** | минимум | +| 15% | 387 000 ₽ | минимум | +| 20% | 404 000 ₽ | минимум | +| 25% | 421 000 ₽ | минимум | + +Более неопределённый проект (те же вероятные часы, пессимистичные оценки в 4 раза выше): ожидаемые часы 195,3, σ = 29,5 ч, резерв по PERT 15,7% выше минимума и становится основанием; без резерва 454 000 ₽, с резервом 526 000 ₽. + +## Что взято из статьи FITTIN + +Прислана владельцем: [Time & Material vs Fix Price: что выбрать в 2026](https://fittin.ru/blog/tm-vs-fix-price-2026), 3 июня 2026. Это маркетинговый материал подрядчика с собственной платформой: его цены и тарифы нигде не использованы. Учтены только общие рассуждения. + +| Мысль статьи | Что сделано | +|---|---| +| Выбор зависит от зрелости описания работ: фикс требует зрелого ТЗ, T&M требует вовлечённого заказчика | Выбор оставлен человеку и вынесен в настройку; подсказка по признакам отложена (см. ниже) | +| Типичная ошибка T&M: нет потолка бюджета | В T&M показывается потолок и совет закрепить его в договоре | +| В T&M договор содержит ставки по ролям, оценку задач и отчёт по часам | Таблица ставок клиента по ролям и оценка по задачам в часах | +| Лучше всего работает гибрид: фикс на понятный запуск, T&M на развитие и эксперименты | Не реализовано, записано как следующий шаг | +| Буфер на риск в фиксе у них 15–25%, выше при неясном ТЗ | Это данные одного подрядчика. Наш минимум 10% не менялся, но параметр `reserve_floor_pct` позволяет поднять его без правки кода (таблица выше) | +| Fixed Price и T&M для типовых аудитов и ТЗ, T&M для исследований и MVP с открытым составом | Войдёт в подсказку по признакам | + +## Последствия + +- **Ломающее изменение API:** поля `price.cost` и `price.cost_confident` заменены на `cost_expected`, `cost_with_reserve`, `reserve_cost` и другие; добавлены `engagement`, `result.quote`, `price.inputs`. Старых развёртываний нет, поэтому миграция данных не писалась: результаты, сохранённые прежней версией, новый код не прочитает. +- **Миграция `0002_engagement`** добавляет колонку `estimate_versions.engagement` (по умолчанию `fixed_price`). +- В каждой версии теперь хранится снимок вводных, версия растёт на несколько килобайт JSON. +- Интерфейс: поле «Как продаём» в форме, переключатель модели на странице оценки, ставки клиента в таблице по ролям, модель рядом с суммой в истории. + +## Отложено + +1. **Гибрид по фазам** (фикс на понятную часть, T&M на неопределённую): потребует признака модели у задачи и раздельного расчёта резерва. Статья называет это основным рабочим сочетанием. +2. **Подсказка о модели по признакам** (ясность объёма, вероятность изменений, вовлечённость заказчика): нужны новые поля на шаге уточнения и данные о проектах. Пока решает человек. +3. **Эмпирическая калибровка минимума и z:** после 10–15 закрытых проектов заменить 10% и 1,04 квантилем отношения факта к ожидаемым часам (например, 80-м процентилем). Механизм не меняется, меняется источник числа. +4. **Разные минимумы для фикса и T&M**, график платежей (30/40/30), потолок на спринт или месяц: не моделируются. +5. **Режим целевой маржи** вместо наценки. diff --git a/docs/adr/0002-vat-layer.md b/docs/adr/0002-vat-layer.md new file mode 100644 index 0000000..620c689 --- /dev/null +++ b/docs/adr/0002-vat-layer.md @@ -0,0 +1,67 @@ +# ADR-0002: НДС как слой показа поверх цен без НДС + +**Дата:** 31 октября 2026 · **Статус:** принято и реализовано; режим налогообложения продавца не уточнён (см. «Открыто») +**Основание:** вопрос владельца «нужны ли net и gross»; ответ: счёт выставляет компания, зарегистрированная в РФ +**Затрагивает:** `pricing/quote.py`, `market/check.py`, `domain/models.py`, API оценок, интерфейс, миграция `0003_vat_rate` +**Связано:** [ADR-0001](0001-reserve-policy-and-engagement.md) + +## Контекст + +Калькулятор считает стоимость работ, наценку и резерв. НДС не часть стоимости работ: его ставка зависит от того, кто выставляет счёт, кому и в каком налоговом режиме. При этом клиент платит сумму с НДС, а ориентиры рынка в источниках нередко приведены с НДС без пометки. Если сравнивать нашу цену без НДС с ориентиром с НДС 22%, ошибка почти равна допуску сверки (±25%), и вердикт «выше» или «ниже рынка» может быть ложным. + +## Решение + +1. **Всё считается без НДС (net):** ставки, наценка, резерв, сверка с рынком, история. Калькулятор НДС не знает. +2. **НДС это слой показа** над итоговыми суммами. Режимов два: «без НДС» (ставка 0) и «НДС сверху» (ставка из списка). Режима «цена уже включает НДС» нет: цена называется без НДС, к оплате получается `net × (1 + ставка)`. +3. **Ставка выбирается на каждую оценку** и хранится в версии (колонка `vat_rate`, как дробь: 0,22 = 22%). Значение по умолчанию берётся из настроек по региону клиента **в момент создания** и дальше не меняется вместе с настройками. +4. **Допустимые ставки ограничены списком** из конфигурации (`[pricing.vat] choices` плюс 0 и значения по умолчанию), чтобы опечатка вроде 0,2 вместо 0,22 не попадала в договор. Остальные ставки добавляются правкой конфигурации. +5. **Смена ставки у готовой оценки** (`POST /api/estimates/{id}/vat`) это новая версия `reprice` без обращения к модели и без пересчёта, так же как смена модели оплаты. Запрос на то, что уже стоит, версию не создаёт. Модель оплаты и НДС меняются независимо друг от друга через один общий механизм. +6. **Сверка с рынком приводит ориентиры к цене без НДС.** У ориентира есть признак `includes_vat` и `vat_rate`; ориентир с НДС делится на `1 + vat_rate`, результат помечается `normalized_from_gross`. Сравнивается всегда цена с резервом без НДС. + +### Значения по умолчанию (настройка `[pricing.vat]`) + +| Клиент | Ставка | Почему | +|---|---|---| +| РФ | 22% | продавец в РФ, плательщик НДС, общая ставка с 2026 года | +| ЕС | 0% (без НДС) | услуга иностранному заказчику не облагается российским НДС | + +Это умолчание, а не правило: правильная ставка зависит от режима продавца. Значения «по региону» меняются в конфигурации (например, `ru = 0.0` для продавца, который НДС не платит). + +### Что проверено на дату решения + +| Факт | Источник | +|---|---| +| Общая ставка НДС в РФ с 1 января 2026 года 22%; порог дохода для освобождения от НДС на УСН снижен | [buh.ru](https://buh.ru/articles/chto-budet-s-nds-v-2026-godu-povyshenie-stavki-umenshenie-limita-dokhodov-dlya-usn-lgoty-osvobozhden.html) | +| На УСН со специальными ставками 5% и 7% входной НДС к вычету не принимается | [ppt.ru, позиция Минфина](https://ppt.ru/obzory/minfin/pozitsiya-minfina-rf-o-nds-dlya-usn-v-2026-godu-kogda-platit-kakie-stavki-i-kto-osvobozhden) | +| Место реализации услуг иностранному заказчику за пределами РФ, российский НДС не возникает | [Хабр](https://habr.com/ru/posts/1019948) | + +Ставки НДС страны ЕС для продавцов не из РФ и налоговые льготы для ИТ-компаний не проверялись и не моделируются. + +## Числа (пример из документа с рыночными данными, РФ, шаг округления 1 000 ₽) + +| | Без НДС | НДС 22% | С НДС | +|---|---|---|---| +| Фиксированная цена | 370 000 ₽ | 81 400 ₽ | **451 400 ₽** | +| T&M, ожидаемая стоимость | 336 000 ₽ | 73 920 ₽ | **409 920 ₽** | +| T&M, потолок бюджета | 370 000 ₽ | 81 400 ₽ | **451 400 ₽** | + +Ориентир рынка 400–600 тыс. ₽ без НДС. Если бы источник дал 488–732 тыс. ₽ с НДС 22%, то после приведения это те же 400–600 тыс. ₽ без НДС; цена без НДС 340 000 ₽ при этом попадает в рынок (коридор 300–750 тыс. ₽), тогда как без приведения она выглядела бы «ниже рынка» (нижняя граница 366 тыс. ₽). + +## Что намеренно не делается + +- **Налоги самого продавца:** налог на прибыль, УСН, страховые взносы, налоги на зарплату. Взносы уже входят в себестоимость часа, если ставка выведена из зарплаты. Остальное не меняет цену клиента, а лишь определяет, какая наценка нужна продавцу. +- **Определение льгот и режима** (освобождения для ИТ, реестр отечественного ПО, УСН с НДС или без): это зависит от предмета договора и статуса компании, решает бухгалтер или юрист. Сервис только позволяет выбрать «Без НДС» или ставку. +- **Валюта и расчёты с иностранным клиентом:** в сервис это не входит. + +## Последствия + +- Миграция `0003_vat_rate` добавляет колонку `estimate_versions.vat_rate` (по умолчанию 0). +- В ответе API: `vat_rate` у оценки, `quote.vat_rate`, `quote.amount_gross`, `quote.cap_gross`; в бенчмарке `includes_vat`, `vat_rate`; в сверке `normalized_from_gross`. +- В справочнике рынка у ориентиров `includes_vat = false` с пометкой: источники не уточняют, считаем без НДС. **Это допущение нужно проверить**, пока оно не подтверждено. +- В интерфейсе: поле «НДС» в форме, строка «К оплате с НДС», переключатель ставки на странице оценки, пояснение в карточке сверки. + +## Открыто + +1. **Режим налогообложения продавца** (ОСНО, УСН с НДС 22%, УСН со ставками 5% или 7%, УСН без НДС). От него зависят умолчание «по региону» и то, нужно ли учитывать невозвращаемый входной НДС в себестоимости. +2. **Режим «цена фиксирована с НДС».** Если у клиента бюджет задан с НДС, выручка продавца равна `gross / (1 + ставка)`, и наценка фактически падает. Это ограничение стоит показывать как предупреждение (сколько остаётся наценки), но пока не сделано. +3. **НДС в ориентирах рынка:** по каждому источнику выяснить, с НДС или без, и проставить флаги. diff --git a/docs/bot-estimation-market-data.md b/docs/bot-estimation-market-data.md new file mode 100644 index 0000000..46f7104 --- /dev/null +++ b/docs/bot-estimation-market-data.md @@ -0,0 +1,552 @@ +# Сервис оценки трудозатрат и стоимости: сбор рыночных данных по разработке ботов + +**Версия:** 1.0 · **Дата снимка рынка:** 30 октября 2026 · **Охват:** РФ и ЕС/Великобритания · **Тип работ:** Telegram-боты, боты для сайта, мультиканальные боты, ИИ-агенты + +--- + +## 0. Как читать документ + +| Раздел | Что внутри | +|---|---| +| 1 | Принцип: что считает LLM, а что код | +| 2 | Слои данных и откуда их брать | +| 3 | Карта источников РФ и ЕС с оценкой надёжности | +| 4 | Процесс сбора (ETL) шаг за шагом | +| 5 | Схема данных и нормализация | +| 6 | Текущая аналитика рынка (снимок на 30.10.2026) | +| 7 | Сквозные примеры расчёта (РФ и ЕС) | +| 8 | Калибровка, контроль качества, обновление | +| 9 | Юридические риски сбора данных | +| 10 | План внедрения | +| Приложение | Список использованных источников | + +**Важное замечание о достоверности.** Все рыночные цифры в разделе 6 взяты из открытых публикаций, найденных 30.10.2026. Большинство из них маркетинговые материалы вендоров и агентств: верхние границы у них завышены, нижние занижены, а методика почти нигде не раскрыта. Поэтому они годятся как стартовые ориентиры (приоры), но не как финальная истина. Реальную цену сервис должен выводить из ваших собственных сделок и план/факта (раздел 8). + +--- + +## 1. Принцип работы + +``` +ТЗ клиента ─► Агент (LLM): уточнение → декомпозиция → оценка часов (O/M/P) → критик + │ + Справочник рынка ◄───┤ (ставки, эталонные задачи, коэффициенты каналов) + ▼ + Детерминированный код: PERT, ставки, PM, наценка, резерв, налоги, курс валют + ▼ + Смета: диапазон «от и до», допущения, версия +``` + +- **LLM** понимает текст: разбивает работу на задачи, оценивает часы, находит аналоги. +- **Код** считает деньги. Расчёт воспроизводим, проверяем и объясним клиенту. +- **Справочник рынка** (этот документ) поставляет ставки, диапазоны цен и коэффициенты для сверки: «наша смета в границах рынка или выбивается». + +--- + +## 2. Какие данные нужны (слои) + +| Слой | Что хранить | Зачем | Источники | Надёжность | +|---|---|---|---|---| +| A. Цены проектов | Итоговая цена за типовой проект (бот с одним каналом, ИИ-агент, мультиканал) | Сверка итоговой цифры сметы с рынком | Прайсы агентств, обзоры, публичные закупки, кейсы | Низкая–средняя | +| B. Ставки | Почасовые и дневные ставки по ролям и регионам | Вход для `price()` | Биржи фриланса, вакансии, зарплатные обзоры, агентские прайсы | Средняя | +| C. Трудозатраты | Часы на типовые задачи (RAG, CRM-интеграция, адаптер канала) | Калибровка оценок LLM | Ваша история, открытые кейсы, таймтрекеры | Высокая, если ваши | +| D. Эксплуатация | Хостинг, токены LLM, поддержка, платные API каналов | Строка «run» в смете | Прайсы провайдеров, вендорные калькуляторы | Высокая | +| E. Коэффициенты | Мультиканальность, срочность, комплаенс (GDPR, 152-ФЗ) | Корректировки | Ваша история, экспертные оценки | Средняя | +| F. Курсы и налоги | Курс ЦБ РФ / ECB, НДС, взносы | Пересчёт между РФ и ЕС | ЦБ РФ, ECB (API) | Высокая | + +Приоритет по ценности: **C (ваша история) > B > D > A > E**. Слой C всегда должен постепенно вытеснять внешние источники. + +--- + +## 3. Карта источников + +### 3.1. Россия + +| Источник | Что даёт | Тип | Надёжность | Замечания | +|---|---|---|---|---| +| Обзоры вендоров конструкторов (BotHelp и аналоги) | Градация цен по способам создания, цены по каналам | Маркетинг вендора | Низкая–средняя | Заинтересованы занижать цену конструктора и завышать цену разработки | +| Habr Career (вакансии) | Зарплатные вилки разработчиков ботов | Вакансии | Средняя | Пересчёт зарплаты в ставку: см. 5.3 | +| hh.ru (вакансии, API) | Зарплатные вилки, объём спроса | Вакансии | Средняя | Есть открытое API для вакансий; проверьте текущие условия | +| FL.ru, Kwork, Habr Freelance | Нижний сегмент цен, сроки | Биржи | Средняя для нижнего сегмента | Сильно искажены демпингом | +| Workspace.ru (каталог подрядчиков) | Диапазоны цен и количество специалистов | Каталог | Средняя | Цены заявлены исполнителями | +| Статьи на vc.ru, Sostav, Habr | Кейсы с реальными сметами | Блоги | Низкая–средняя | Часто реклама; ценны конкретные сметы с часами | +| Закупки (zakupki.gov.ru) | Реальные цены контрактов на чат-боты и мини-приложения | Госзакупки | Высокая для своего сегмента | Сегмент не равен коммерческому рынку | +| Ваши КП, договоры, акты | Фактические цены и часы | Внутренние | Максимальная | Главный источник | + +### 3.2. ЕС и Великобритания + +| Источник | Что даёт | Тип | Надёжность | Замечания | +|---|---|---|---|---| +| Прайсы и блоги агентств (Берлин, Лондон) | Цены запуска и эксплуатации | Маркетинг | Средняя | Часть публикует фиксированные тарифы, это ценно | +| Клатч-подобные каталоги (Clutch, GoodFirms) | Диапазон ставок и бюджетов проектов | Каталоги | Средняя | Самозаявленные данные | +| Фриланс-платформы (Upwork, Fiverr, Malt) | Ставки по сегментам, цена за проект | Биржи | Средняя | Fiverr: цена проекта в нижнем сегменте | +| Зарплатные обзоры (Glassdoor, StepStone, Indeed, Stack Overflow Survey) | Зарплаты, пересчёт в ставку | Опросы | Средняя | Нужна поправка на накладные расходы | +| Eurostat (стоимость рабочей силы) | Макроуровень стоимости труда по странам | Официальная статистика | Высокая | Для коэффициентов между странами | +| Публичные тендеры (TED, национальные порталы, например Hilma в Финляндии) | Фактические цены контрактов | Госзакупки | Высокая для своего сегмента | Крупные проекты, не малый бизнес | +| SaaS-платформы ботов (Intercom, Tidio, Crisp, Zendesk) | Цены подписок и каналов | Прайсы | Высокая | Нужны для строки эксплуатации и сравнения «build vs buy» | +| Прайс WhatsApp Business API (Meta) | Платная часть каналов | Официальный | Высокая | Модель тарификации менялась в 2025–2026, перепроверять каждый квартал | + +Порталы и API в таблицах выше названы по моим знаниям, а не проверены в рамках этой сессии: перед внедрением проверьте доступность, условия использования и актуальность. + +### 3.3. Как оценивать источник + +Каждому источнику присваивайте вес `w ∈ [0, 1]`: + +``` +w = тип (внутренний 1.0, тендер 0.8, прайс провайдера 0.8, биржа 0.5, агентство 0.5, вендор-маркетинг 0.3) + × свежесть (≤3 мес 1.0, 3–12 мес 0.7, >12 мес 0.4) + × раскрытие (есть состав работ и часы 1.0, только цена 0.6) +``` + +Агрегация диапазонов идёт взвешенными перцентилями (раздел 5.4), а не простым средним. + +--- + +## 4. Процесс сбора (ETL) + +``` +1. Поиск → 2. Сбор → 3. Извлечение → 4. Нормализация → 5. Валидация → 6. Хранение → 7. Агрегация → 8. Публикация в конфиг → 9. Обратная связь +``` + +### Шаг 1. Поиск источников +- Раз в квартал запускайте поисковые запросы по шаблонам: `«стоимость разработки telegram бота 2026»`, `«chatbot development cost 2026 Germany»`, `«AI agent development price EUR»`. +- Для каждого запроса сохраняйте URL, дату, заголовок. Новые домены добавляйте в реестр источников (раздел 5.1). + +### Шаг 2. Сбор +- **Ручной сбор** для маркетинговых статей: открыть, выписать таблицы цен. +- **API** там, где оно есть (вакансии, курсы валют ЦБ/ECB). +- **Скрейпинг** только с соблюдением условий сайта и robots.txt (раздел 9). Сохраняйте сырой HTML и дату получения, чтобы можно было перепроверить. + +### Шаг 3. Извлечение (LLM со структурированным выводом) +LLM читает страницу и возвращает JSON по схеме. Нельзя давать ему «додумывать»: пустые поля остаются `null`. + +```python +from pydantic import BaseModel, Field +from typing import Optional, Literal + +class PricePoint(BaseModel): + source_url: str + published: Optional[str] = None # дата публикации, ISO + region: Literal["RU", "EU", "UK", "OTHER"] + segment: str # "tg_single", "multichannel", "ai_agent", "site_bot", "mini_app" + provider_type: Literal["freelance", "constructor_expert", "agency", "custom", "saas"] + currency: str # "RUB", "EUR", "GBP", "USD" + price_min: Optional[float] = None + price_max: Optional[float] = None + unit: Literal["project", "hour", "day", "month"] = "project" + scope_note: Optional[str] = Field(None, description="Что входит в цену, дословно из источника, кратко") + hours_disclosed: Optional[float] = None + quote_verbatim: str = Field(description="Короткая цитата для проверки, до 15 слов") +``` + +Промпт для извлечения (ключевые правила): +1. Извлекай только то, что явно написано. Не пересчитывай валюты и не усредняй. +2. Если указана вилка, заполни `price_min` и `price_max`. +3. Если цена «от X», заполни `price_min`, `price_max = null`. +4. Различай разовую цену проекта и ежемесячную поддержку. +5. Верни `null`, если данных нет. + +### Шаг 4. Нормализация +- Приведите валюту к базовой (например, EUR) по курсу на **дату публикации**, а не на сегодня. +- Приведите единицы: час, день (8 ч), проект. +- Определите, **с НДС или без**, и приведите к «без НДС». +- Приведите сегмент к вашему классификатору (раздел 5.2). + +### Шаг 5. Валидация +Автоматические проверки: +- `price_min ≤ price_max`. +- Цена в разумных границах сегмента (например, бот на одном канале за 10 млн ₽ помечается как аномалия). +- Дубликаты (одна цифра переписана в разных блогах): сохраняйте оригинал, копии помечайте как `derived_from`. +- Ручная проверка 10–20% выборки на соответствие цитате. + +### Шаг 6. Хранение +Postgres: сырые документы отдельно от нормализованных точек, чтобы можно было переизвлечь при смене схемы. + +### Шаг 7. Агрегация +Считайте взвешенные перцентили (P25, P50, P75) по каждому сегменту, региону и типу исполнителя. Подробнее в 5.4. + +### Шаг 8. Публикация в конфиг сервиса +Из агрегатов формируется версионируемый `market_config_YYYY_QN.json`: ставки, диапазоны проектов, коэффициенты. Смета ссылается на версию конфига, поэтому её можно воспроизвести. + +### Шаг 9. Обратная связь +После каждого проекта фиксируйте план/факт часов и итоговую цену. Эти данные получают вес 1.0 и постепенно заменяют внешние приоры. + +--- + +## 5. Схема данных и нормализация + +### 5.1. Таблицы (Postgres) + +```sql +CREATE TABLE source ( + id SERIAL PRIMARY KEY, + url TEXT UNIQUE NOT NULL, + domain TEXT, + source_type TEXT CHECK (source_type IN + ('internal','tender','provider_price','marketplace','agency','vendor_marketing','salary_survey','vacancy')), + region TEXT, + weight_base REAL, -- вес по типу + first_seen DATE, + tos_checked BOOLEAN DEFAULT FALSE +); + +CREATE TABLE raw_document ( + id SERIAL PRIMARY KEY, + source_id INT REFERENCES source(id), + fetched_at TIMESTAMPTZ, + published DATE, + content_hash TEXT, + body TEXT -- сырой текст или путь к архиву +); + +CREATE TABLE price_point ( + id SERIAL PRIMARY KEY, + raw_document_id INT REFERENCES raw_document(id), + region TEXT, segment TEXT, provider_type TEXT, + unit TEXT, + price_min NUMERIC, price_max NUMERIC, currency TEXT, + price_min_eur NUMERIC, price_max_eur NUMERIC, -- нормализовано, без НДС + fx_rate NUMERIC, fx_date DATE, + vat_included BOOLEAN, + hours_disclosed NUMERIC, + scope_note TEXT, quote_verbatim TEXT, + weight REAL, + derived_from INT REFERENCES price_point(id) +); + +CREATE TABLE rate ( -- ставки по ролям + id SERIAL PRIMARY KEY, + region TEXT, role TEXT, level TEXT, + hourly_eur NUMERIC, basis TEXT, -- 'agency_billing' | 'freelance' | 'salary_derived' + source_id INT, observed DATE +); + +CREATE TABLE task_benchmark ( -- эталонные задачи (слой C) + id SERIAL PRIMARY KEY, + task_type TEXT, -- 'tg_core','rag','crm_integration','channel_adapter','qa','deploy' + hours_o NUMERIC, hours_m NUMERIC, hours_p NUMERIC, + actual_hours NUMERIC, + project_id INT, closed_at DATE +); + +CREATE TABLE project_actual ( -- план/факт + id SERIAL PRIMARY KEY, + segment TEXT, region TEXT, + est_hours NUMERIC, actual_hours NUMERIC, + est_price_eur NUMERIC, actual_price_eur NUMERIC, + channels INT, has_ai BOOLEAN, has_crm BOOLEAN, closed_at DATE +); +``` + +### 5.2. Классификатор сегментов + +| Код | Описание | +|---|---| +| `tg_single` | Сценарный Telegram-бот, один канал | +| `site_bot` | Бот для сайта (виджет чата) | +| `multichannel` | Два и более канала (Telegram, MAX, ВКонтакте, WhatsApp, сайт) | +| `ai_agent` | Бот с LLM, базой знаний (RAG), интеграциями | +| `mini_app` | Telegram Mini App | +| `run` | Эксплуатация (поддержка, хостинг, токены) | + +### 5.3. Пересчёт зарплаты в часовую ставку + +Из вилки зарплаты (в месяц) получается себестоимость часа для сметы: + +``` +ставка_час = зарплата_мес × (1 + взносы_и_налоги_работодателя) × (1 + накладные) / продуктивные_часы_мес +``` + +- `продуктивные_часы_мес` ≈ 120–130 (не 160: отпуск, встречи, простои). Это допущение, настраивается по вашему таймтрекеру. +- `накладные` 15–30%: офис, лицензии, управление. Допущение, откалибруйте под вашу компанию. + +### 5.4. Агрегация + +Взвешенный перцентиль по `weight`: + +```python +import numpy as np + +def weighted_percentile(values, weights, q): + idx = np.argsort(values) + v = np.array(values)[idx] + w = np.array(weights)[idx] + cum = np.cumsum(w) - 0.5 * w + cum /= w.sum() + return float(np.interp(q / 100, cum, v)) +``` + +Если в сегменте меньше 5 точек, показывайте диапазон min–max и пометку «мало данных», а не перцентили. + +--- + +## 6. Текущая аналитика рынка (снимок на 30.10.2026) + +> Все цифры из публичных источников (приложение). Валюты не пересчитывались, чтобы не накладывать ошибки курса. Таблицы РФ в рублях, ЕС в EUR/GBP/USD, как в источниках. + +### 6.1. Россия: градация по способу создания + +| Способ | Срок | Цена | +|---|---|---| +| Конструктор самостоятельно | 1 день | от 0 ₽/мес | +| Конструктор + шаблон | 2–3 часа | от 0 ₽/мес | +| Эксперт на конструкторе | 3–7 дней | 20 000–60 000 ₽ | +| Агентство | 3–6 недель | 80 000–250 000 ₽ (+10–20 тыс. ₽/мес поддержка) | +| Кастомная разработка | 1,5–4 месяца | от 250 000 ₽ | + +Источник: обзор BotHelp (обновлён сентябрь 2026). Для сравнения, фрилансерское предложение простого бота на бирже: около 6 500 ₽ за 3 дня. + +### 6.2. Россия: цена по каналам при заказе у разработчика + +| Канал | Цена | +|---|---| +| Telegram | от 80 000 ₽ | +| ВКонтакте | от 60 000 ₽ | +| MAX | от 80 000 ₽ | +| Все три вместе | от 200 000 ₽ | + +Вывод: суммарно по отдельности 220 000 ₽, комплектом 200 000 ₽. Мультиканальность дешевле суммы лишь за счёт общего ядра, но не радикально. + +### 6.3. Россия: ИИ-агент и рынок труда + +- Кастомный ИИ-бот с подключением к LLM: от 200 000 ₽ за разработку, токены отдельно. +- Вакансия разработчика Telegram-ботов (Habr Career): 200 000–350 000 ₽ в месяц. + +### 6.4. ЕС и Великобритания + +| Сегмент | Цена | Источник | +|---|---|---| +| B2B-бот поддержки с ИИ и RAG, Берлин | 10 000–30 000 € запуск; FAQ-бот от 10 000 € за 4 недели | Kolonell, 09.2026 | +| Эксплуатация, Берлин | 230–2 000 €/мес при 500–10 000 диалогов/мес | Kolonell, 09.2026 | +| Дневная ставка ИИ-разработчика, Берлин | 500–800 € | Kolonell, 09.2026 | +| SME, Великобритания | 3 000–25 000 £; мультиканальный с CRM 18 000–25 000 £ | Softomate, 2026 | +| Крупное лондонское агентство | 25 000–100 000+ £ | Softomate, 2026 | +| Кастомный разговорный ИИ в Европе (с безопасностью и комплаенсом) | 40 000–150 000 $ и выше | CMARIX, 08.2026 | +| Немецкие агентства, кастомная разработка | 100–200 €/ч | xmethod.de через Qualimero | + +### 6.5. Почасовые ставки по регионам (по обзорам агентств) + +| Регион | Диапазон | Источники | +|---|---|---| +| Западная Европа | 80–170 $/ч или 90–200 $/ч | Space-O, GMTA | +| Восточная Европа | 40–80 $/ч | Space-O, GMTA | +| Северная Америка | 100–200 $/ч | Space-O | + +Один обзор называет для Западной Европы **180–300 $/ч** и для AI-агентств **150–350 $/ч**. Это не ошибка, а другой уровень: расценка агентства «под ключ» (с управлением и маржой) против ставки разработчика. В конфиге обязательно храните поле `basis` (`agency_billing` или `freelance`), иначе ставки смешаются. + +### 6.6. Глобальные ориентиры (для контекста) + +| Источник | Вилка | +|---|---| +| Fiverr (маркетплейс) | 45–520 $ за проект, 47–315 $/ч | +| Space-O | 3 000 $ (простой) – 300 000+ $ (энтерпрайз) | +| RaftLabs | 4 500–12 000 $ (rule-based) – 72 000–210 000 $ (энтерпрайз-агент) | +| Один AI-агентский калькулятор | 15 000–45 000 $ за чатбот с одним сценарием и RAG | + +Расхождения в 10–100 раз между источниками объясняются не ошибкой, а разным сегментом (виджет и энтерпрайз) и типом исполнителя. Поэтому слой `segment × provider_type` обязателен. + +### 6.7. Эксплуатация и платный слой каналов + +- WhatsApp Business API: у Meta отдельная и менявшаяся модель тарификации, перепроверять каждый квартал. +- SaaS-платформы часто берут за WhatsApp дополнительно несколько десятков евро в месяц (например, 49–99 €/мес у разных вендоров). +- Для кастомных ботов: хостинг (VPS от нескольких сотен рублей), токены LLM, мониторинг, поддержка 10–20 тыс. ₽/мес в РФ. + +> **НДС.** Сверка сравнивает цены без НДС. Источники рыночных цен часто не указывают, с НДС ли они; у каждого ориентира в справочнике есть признак `includes_vat` (сейчас везде `false` как допущение, его нужно подтвердить по источникам). Подробности в [ADR-0002](adr/0002-vat-layer.md). + +### 6.8. Сводные ориентиры (для сверки итога сметы) + +| Сегмент | РФ (разработчик/агентство) | ЕС/Великобритания | +|---|---|---| +| Простой бот, один канал | 20–80 тыс. ₽ (эксперт) – 80+ тыс. ₽ (агентство) | единицы тысяч € (FAQ-бот от ~10 тыс. € у агентства) | +| Мультиканал (3 канала) | от ~200 тыс. ₽ | ~18–25 тыс. £ (с CRM) | +| ИИ-агент с RAG и CRM | от ~200 тыс. ₽ и выше | 10–30 тыс. € (Берлин), 40–150 тыс. $ (комплаенс-уровень) | +| Эксплуатация | 10–20 тыс. ₽/мес (поддержка) | 230–2 000 €/мес | + +**Ключевые наблюдения:** +1. Разрыв РФ и ЕС по сопоставимому проекту порядка 5–10 раз, но он зависит от сегмента и типа исполнителя. +2. Цену определяют интеграции (CRM, платежи, RAG) и комплаенс, а не сам бот. +3. Эксплуатация за 2–3 года сопоставима с разработкой, её нужно выводить отдельной строкой. +4. Конструкторы и SaaS радикально снижают цену простых ботов, поэтому в смете нужен вариант «build vs buy». + +--- + +## 7. Сквозные примеры расчёта + +> Обновлено 31.10.2026: расчёт резерва и наценки приведён к [ADR-0001](adr/0001-reserve-policy-and-engagement.md). Прежняя версия складывала плоские 10% и запас P85 и давала 397 000 ₽, эта цифра убрана. + +### Задача +Мультиканальный ИИ-агент: Telegram + MAX + ВКонтакте, база знаний (RAG), интеграция с amoCRM, тестирование, деплой. + +### 7.1. Декомпозиция и оценка часов (результат работы агента) + +| # | Задача | Роль | O | M | P | E = (O+4M+P)/6 | σ = (P−O)/6 | +|---|---|---|---|---|---|---|---| +| 1 | Аналитика, ТЗ | analyst | 8 | 12 | 20 | 12,7 | 2 | +| 2 | Ядро бота (Telegram) | backend | 16 | 24 | 40 | 25,3 | 4 | +| 3 | RAG и база знаний | backend | 20 | 32 | 56 | 34,0 | 6 | +| 4 | Интеграция amoCRM | backend | 8 | 16 | 32 | 17,3 | 4 | +| 5 | Адаптер MAX | backend | 8 | 12 | 20 | 12,7 | 2 | +| 6 | Адаптер ВКонтакте | backend | 8 | 12 | 20 | 12,7 | 2 | +| 7 | Тестирование | qa | 12 | 20 | 36 | 21,3 | 4 | +| 8 | Деплой и мониторинг | devops | 4 | 8 | 16 | 8,7 | 2 | +| | **Итого** | | | | | **144,7 ч** | **√Σσ² = 10 ч** | + +- Ожидаемые часы: **144,7**. +- Резерв по разбросу оценок (PERT): 1,04 × 10 = **10,4 ч** (7,2%). +- Минимальный резерв: 10% × 144,7 = **14,5 ч**. +- Берётся большее, то есть **14,5 ч**, часы с резервом **159,1**. Это запас по разбросу оценок, а не калиброванный квантиль (подробности в [ADR-0001](adr/0001-reserve-policy-and-engagement.md)). + +### 7.2. Расчёт стоимости, профиль РФ + +Ставки (иллюстративные допущения, калибруются по вашим данным): analyst 1 500, backend 1 800, qa 1 200, devops 1 800 ₽/ч. PM 15%, риск 10%, маржа 20%. + +| Роль | Часы | Ставка | Сумма | +|---|---|---|---| +| analyst | 12,7 | 1 500 | 19 000 | +| backend | 102,0 | 1 800 | 183 600 | +| qa | 21,3 | 1 200 | 25 600 | +| devops | 8,7 | 1 800 | 15 600 | +| **База** | | | **243 800 ₽** | + +``` +без резерва: 243 800 × 1,15 (PM) × 1,20 (наценка) ≈ 336 444 ≈ 336 000 ₽ +с резервом: 336 444 × (1 + 14,5 / 144,7) ≈ 370 088 ≈ 370 000 ₽ +``` + +Для **фиксированной цены** называется 370 000 ₽ (резерв внутри). Для **Time & Materials** называется ожидаемая стоимость 336 000 ₽ и потолок бюджета 370 000 ₽. Наценка 20% даёт маржу 16,7%. + +**Сверка с рынком (6.2 и 6.3):** три канала от 200 тыс. ₽ плюс ИИ-агент от 200 тыс. ₽ у разработчика, то есть около 400 тыс. ₽. Смета попадает в рынок. + +### 7.3. Расчёт стоимости, профиль ЕС + +Те же часы, ставки (допущения в пределах ставок из 6.4 и 6.5): analyst 75, backend 85, qa 60, devops 90 €/ч. + +| Роль | Часы | Ставка | Сумма | +|---|---|---|---| +| analyst | 12,7 | 75 | 950 | +| backend | 102,0 | 85 | 8 670 | +| qa | 21,3 | 60 | 1 280 | +| devops | 8,7 | 90 | 780 | +| **База** | | | **11 680 €** | + +``` +без резерва: 11 680 × 1,15 × 1,20 ≈ 16 118 € +с резервом: 16 118 × (1 + 14,5 / 144,7) ≈ 17 730 € +``` + +Сверка: Берлин 10–30 тыс. €, Великобритания для мультиканала с CRM 18–25 тыс. £. Смета в границах рынка. + +### 7.4. Строка эксплуатации + +Для ЕС при 2 000 диалогов/мес: 350–730 €/мес (Берлин). Для РФ: поддержка 10–20 тыс. ₽/мес плюс токены и хостинг. В КП это отдельная строка, а годовая стоимость владения считается как разработка + 12 × эксплуатация. + +### 7.5. Код проверки «смета против рынка» + +```python +from math import sqrt + +def price(tasks, rates, pm=0.15, markup=0.20, floor=0.10, z=1.04): + hours = sum((t["o"] + 4*t["m"] + t["p"]) / 6 for t in tasks) + sigma = sqrt(sum(((t["p"] - t["o"]) / 6) ** 2 for t in tasks)) + base = sum(((t["o"] + 4*t["m"] + t["p"]) / 6) * rates[t["role"]] for t in tasks) + expected = base * (1 + pm) * (1 + markup) + reserve = max(z * sigma, floor * hours) # one reserve, added once + return { + "hours": round(hours, 1), + "hours_with_reserve": round(hours + reserve, 1), + "cost_expected": round(expected), + "cost_with_reserve": round(expected * (1 + reserve / hours)), + } + +def market_check(cost, bench_min, bench_max, tolerance=0.25): + lo, hi = bench_min * (1 - tolerance), bench_max * (1 + tolerance) + if cost < lo: return "ниже рынка: проверьте, не забыты ли задачи" + if cost > hi: return "выше рынка: проверьте допущения, ставки и маржу" + return "в границах рынка" +``` + +--- + +## 8. Калибровка, качество и обновление + +### 8.1. Калибровка оценок LLM + +LLM систематически занижает интеграции, тестирование и правки. Лечится коэффициентом по типу задачи: + +``` +k(task_type) = медиана(actual_hours / estimated_hours) по закрытым проектам +итоговая оценка = E × k +``` + +Пока данных мало (менее 5 закрытых проектов на тип), используйте консервативный `k = 1,2–1,3` на интеграции и QA. Это допущение, замените его статистикой. + +### 8.2. Метрики качества сервиса + +| Метрика | Формула | Цель | +|---|---|---| +| MAPE по часам | mean(|план − факт| / факт) | < 25% после 20 проектов | +| Покрытие диапазона | доля проектов, где факт попал в [P10, P90] | ≈ 80% | +| Смещение | mean((план − факт) / факт) | около 0 | + +Сверка с рынком (доля смет в границах ориентиров) **не является метрикой качества**: если выдавать её за точность, оценки начнут подгонять под чужие прайсы. Она остаётся предупреждением в самой оценке (решение по [разбору ревью](estimator-architecture-review-v2-response.md)). + +### 8.3. Расписание обновления + +| Данные | Частота | Причина | +|---|---|---| +| Курсы валют | ежедневно (API) | Волатильность | +| Прайсы платных API каналов (WhatsApp, LLM) | ежеквартально | Тарифы меняются | +| Ставки и цены проектов | ежеквартально | Рынок и инфляция | +| Коэффициенты калибровки | после каждого закрытого проекта | Обратная связь | +| Реестр источников | раз в полгода | Источники умирают | + +### 8.4. Антипаттерны + +- Усреднять цены вендора, агентства и биржи в одну цифру. +- Смешивать ставку разработчика и агентскую расценку (поле `basis`). +- Брать курс на сегодня для старой публикации. +- Показывать клиенту одну цифру без диапазона и допущений. +- Хранить только итог, а не версию конфига и допущения: смета перестаёт воспроизводиться. + +--- + +## 9. Юридические риски сбора данных + +Не является юридической консультацией, это контрольный список для проверки. + +1. **Условия использования сайтов и robots.txt.** Перед автоматическим сбором проверьте ToS, ведите флаг `tos_checked` в таблице `source`. +2. **Права на базы данных.** В ЕС действует особое (sui generis) право изготовителя базы данных, массовое копирование каталогов может его нарушать. Храните и публикуйте факты (цена, дата, источник), а не копии текстов; цитаты ограничивайте короткими фрагментами. +3. **Персональные данные.** Фрилансеры и сотрудники в вакансиях и профилях это персональные данные. Для ЕС применяется GDPR, для РФ 152-ФЗ (включая локализацию). Храните агрегаты, а персональные поля не собирайте. +4. **Коммерческая тайна и NDA.** Данные ваших проектов и клиентов обезличивайте перед использованием в справочнике. +5. **Достоверность в КП.** Если вы ссылаетесь на «рыночные цены» в предложении клиенту, указывайте источник и дату, чтобы не вводить в заблуждение. + +--- + +## 10. План внедрения + +| Этап | Что делаем | Результат | +|---|---|---| +| 1 (1–2 недели) | Реестр источников, ручной сбор 30–50 точек по таблицам раздела 3, схема БД | Первый `market_config` | +| 2 (2–3 недели) | LLM-извлечение в JSON, нормализация валют и НДС, валидация | Автоматизированный конвейер | +| 3 (1–2 недели) | Агрегация, `market_check` в сервисе, версионирование конфигов | Смета со сверкой с рынком | +| 4 (постоянно) | План/факт, калибровка `k`, метрики качества | Точность растёт с каждым проектом | +| 5 (опционально) | Парсеры бирж и вакансий (при наличии API и разрешении ToS), дашборд | Автообновление рынка | + +--- + +## Приложение. Использованные источники (проверены 30.10.2026) + +- BotHelp, «Сколько стоит чат-бот в 2026 году: реальные цены», обновлено 03.09.2026. Вендор конструктора, https://bothelp.io/ru/blog/skolko-stoit-razrabotka-chat-bota +- Habr Career, вакансия «Разработчик Telegram-ботов», https://career.habr.com/vacancies/1000103419 +- FL.ru, услуга «Создание телеграм ботов», https://www.fl.ru/uslugi-freelancera/11087/sozdanie-telegramm-botov-5.html +- Kolonell, «AI Customer Service Chatbot Cost in Berlin in 2026», 06.09.2026, https://kolonell.com/en/blog/ai-customer-service-chatbot-cost-berlin-2026 +- Softomate Solutions, «AI Chatbot Development Cost UK», https://www.softomatesolutions.com/ai-chatbot-development-cost-uk/ +- CMARIX, «How Much Does AI Chatbot Development Cost in 2026?», 31.08.2026, https://www.cmarix.com/blog/ai-chatbot-development-cost/ +- Qualimero, «Chatbot Costs 2026», https://qualimero.com/en/blog/chatbot-costs +- Space-O Technologies, «How Much Does It Cost to Develop an AI Chatbot in 2026?», https://www.spaceotechnologies.com/blog/ai-chatbot-development-cost/ +- GMTA Software, «AI Chatbot Development Cost», https://www.gmtasoftware.com/blog/ai-chatbot-development-cost/ +- RaftLabs, «Chatbot development cost in 2026», https://www.raftlabs.com/blog/chatbot-development-cost +- Fiverr, «How Much Does It Cost to Hire a Chatbot Developer in 2026?», 13.02.2026, https://www.fiverr.com/resources/guides/costs/chatbot-developer +- Boei, «10 Chatbot Pricing Plans Compared», https://boei.help/blog/chatbot-pricing-comparison-2026/ +- Cost of Hiring an AI Agency 2026 (калькулятор), https://blog-aiagencycalc.pages.dev/cost-of-hiring-an-ai-agency-2026.html + +**Напоминание:** источники выше преимущественно маркетинговые. Цифры из них являются стартовыми приорами, которые сервис должен заменять собственными данными по мере накопления закрытых проектов. diff --git a/docs/estimator-architecture-review-v2-response.md b/docs/estimator-architecture-review-v2-response.md new file mode 100644 index 0000000..08b6c94 --- /dev/null +++ b/docs/estimator-architecture-review-v2-response.md @@ -0,0 +1,48 @@ +# Разбор архитектурного ревью v2 + +**Дата:** 31 октября 2026 · **Статус:** позиция по ревью. Вопрос про политику резерва решён ([ADR-0001](adr/0001-reserve-policy-and-engagement.md)), вопрос про данные завершённых проектов открыт +**Относится к:** [estimator-architecture-review-v2.md](estimator-architecture-review-v2.md) + +Ниже текст разбора записан как есть, без правок. + +--- + +## Что думаю про ревью + +В целом оно полезное и в основном справедливое. Что-то из этого уже было у меня в списке ограничений, но три замечания я бы признал настоящими дефектами. + +**Принимаю безоговорочно:** + +1. **Наценка и маржа.** В калькуляторе `margin_pct` это множитель `×1.20`, то есть наценка 20%, а фактическая маржа около 16,7%. Название вводит в заблуждение. Исправление небольшое: переименовать в `markup_pct`, при желании добавить режим целевой маржи. Числа в эталонном примере при этом не меняются. +2. **Двойной резерв.** `cost_confident` я считаю как цену, уже включающую 10% риска, умноженную на отношение часов P85 к ожидаемым. Резерв выходит дважды. Плюс подпись «≈P85» обещает вероятность, которую никто не калибровал. Подпись надо смягчить, а политику резерва выбрать одну. +3. **Снимок вводных.** В версии я храню только имя версии справочника (`2026Q4`), а ставки лежат в файле, который можно отредактировать задним числом. Тогда старая оценка перестанет воспроизводиться, а ручная правка пересчитается по изменённым ставкам. Нужно класть в версию снимок ставок и параметров расчёта. +4. **Устаревшие шапки документов.** Исправил: в них стояло «реализация не начата». + +**Согласен, но с поправкой:** + +- **Domain Packs и каталог работ.** Направление верное, но делать реестр плагинов и композицию возможностей при одном домене и нуле завершённых проектов рано, можно угадать неверную абстракцию. Я бы взял дешёвую часть: вынести то, что сейчас зашито под ботов (тексты промптов, список сегментов, ключи ориентиров), в папку пакета с манифестом, один пакет `bots_ai`, без реестра. Второй домен покажет, чего не хватает. +- **Коды работ.** Самый сильный довод ревью, что RAG и калибровку надо делать после унификации работ. В моём конвейере у задач только свободные названия от модели, поэтому «коэффициент по типу задачи», как я планировал, считать не по чему. Нужно необязательное поле `work_item_code` и факты на уровне задач. Это меняет мой план: до RAG нужен этот шаг. +- **Режимы экспресс и подробная оценка.** Идея хорошая, сейчас её грубо заменяет флаг «продолжить с допущениями». Достаточно пометить результат «предварительная оценка», когда остались допущения. +- **Метрики.** Согласен, что «попадание в рынок» нельзя выдавать за точность, это подталкивает подгонять смету под чужие прайсы. Оставлю как предупреждение, а метрикой сделаю ошибку по часам и смещение. Это моя запись в разделе 8.2 документа с рыночными данными. + +**Отложил бы:** + +- **Очередь на Postgres.** Нужна только при нескольких репликах, в документах это уже записано как ограничение. +- **Роли `viewer/estimator/approver`, `tenant_id`, Monte Carlo, сценарии «эконом/база/консервативный», экспорт КП.** Всё разумно, но без данных о ваших проектах это проектирование вслепую. Монте-Карло без калибровки только добавит ложной точности, ревью само это признаёт. +- **Девять ADR.** Для вашего масштаба это много. Оформил бы короткие записи только для трёх решений, меняющих модель данных: экономика, снимки, коды работ. + +**Чего в ревью не хватает:** нигде не сказано, что без фактических часов все предложенные улучшения (калибровка, рынок по контексту, Monte Carlo) работают на пустых данных. Главный рычаг точности это ввод плана и факта по задачам, и его я бы поставил раньше RAG. + +Ещё одна ремарка: в ревью про пользователей UI сказано, что общего ключа мало. Для отдельных пользователей это уже не так (логины, раздельные рабочие пространства). Не хватает только `created_by` в БД: при общем пространстве сейчас не видно, кто создал оценку. + +## Что предлагаю дальше + +1. Небольшой пакет исправлений без споров: наценка вместо «маржи», один механизм резерва и честные подписи, снимок вводных и `created_by` в версии. +2. Поле `work_item_code` и ввод плана и факта по задачам в интерфейсе. +3. Потом RAG и калибровка. +4. Лёгкая версия пакета домена для ботов. + +Нужно ваше решение по двум вопросам: + +- **Резерв.** Какую политику берём: ожидаемая цена плюс плоские 10%, или диапазон от ожидаемой до P85 без плоской надбавки? От выбора зависят итоговые цены, у примера из документа 370 000 ₽ сдвинется. +- **Данные.** Есть ли у вас уже завершённые проекты с фактическими часами, пусть даже по этапам? Это определяет, будет ли калибровка работать со старта или начнётся с нуля. diff --git a/docs/estimator-architecture-review-v2.md b/docs/estimator-architecture-review-v2.md new file mode 100644 index 0000000..0ac1eed --- /dev/null +++ b/docs/estimator-architecture-review-v2.md @@ -0,0 +1,623 @@ +# Flexly AI Estimator — архитектурное ревью и план развития v2 + +**Дата:** 30 октября 2026 г. +**Статус:** архитектурные рекомендации / proposal, **не** утверждённая спецификация реализации +**Область:** сервис оценки трудозатрат, стоимости и рисков проектов в экосистеме Flexly AI +**Цель:** эволюция существующего оценщика мультиканальных ботов в универсальный движок оценки программных и интеграционных проектов без переписывания готового ядра. + +## 0. Документы и границы ревью + +Рассмотрены следующие материалы: + +1. [`estimator-architecture.md`](estimator-architecture.md) — архитектура, контракты, конфигурация, pipeline и статус реализации. +2. [`estimator-web-ui.md`](estimator-web-ui.md) — HTMX + Jinja2, UI/API, управление оценками и безопасность. +3. [`bot-estimation-market-data.md`](bot-estimation-market-data.md) — методика сбора рыночных данных, расчёты, PERT, план/факт. +4. [`README.md`](README.md) — состав документации. + +**Важно о фактическом состоянии.** Заголовки проектных документов содержат старую формулировку «реализация не начата», но **раздел 13 `estimator-architecture.md` сообщает о завершении этапов 1–5**, тестировании на SQLite и PostgreSQL 16 и наличии 262 тестов. RAG, калибровка, MCP и рыночный ETL отмечены как не начатые. Эти статусы приводятся **со слов документа**: ревью исходного кода и независимый запуск тестов не выполнялись. + +**Разделение фактов и предложений:** формулировки «уже реализовано / по документу» описывают имеющуюся документацию; «рекомендуется / предлагается / v2» — новые архитектурные решения, которые требуют принятия ADR и детализации спецификаций. + +--- + +## 1. Executive summary + +### Общая оценка + +Основа оценщика хорошо подходит для развития. Сильные решения: + +- **LLM декомпозирует и предлагает трудозатраты; Python считает деньги.** Денежные расчёты проверяемы и воспроизводимы. +- **Модульный монолит** с разделением `domain`, `agent`, `pricing`, `market`, `calibration`, `services`, `infra`. +- **REST как основной контракт**, MCP — тонкий адаптер к тем же use cases. +- **Immutable-версии смет** и фиксация рыночной конфигурации, модели и промптов. +- **Обучение на план/факте**, а не зависимость исключительно от публичных рыночных оценок. +- **HTMX + Jinja2** достаточно для первого рабочего интерфейса. + +**Основная проблема:** предметная область ботов пока проходит через сегменты (`tg_single`, `site_bot`, `multichannel`, `ai_agent`, `mini_app`), коэффициенты каналов, шаблоны работ и рынок. Если расширять эту модель перечислением всё новых комбинированных сегментов, сложность будет расти непропорционально. + +**Главная рекомендация:** оставить существующий универсальный `EstimateService`, но выделить **Estimator Engine + Domain Packs + библиотеку переиспользуемых Capabilities/Work Items**. Проект может состоять из возможностей разных доменов, а не принадлежать строго одному типу. + +### Приоритетные изменения + +| Приоритет | Изменение | Причина | +|---|---|---| +| **P0** | Универсальная предметная модель: `ProjectType`, `Capability`, `DomainPack`, `WorkItem` | Снять привязку к ботам до расширения RAG/БД | +| **P0** | Корректная экономическая модель: себестоимость, наценка, целевая маржа, налоги, внешние расходы | Предотвратить неверное ценообразование | +| **P0** | Пересмотреть учёт неопределённости, корреляций и резерва | Не выдавать неподтверждённый P85 и не учитывать риски дважды | +| **P1** | Каталог типовых работ, кросс-доменные зависимости, дедупликация WBS | Корректная смета смешанного проекта | +| **P1** | Рынок по сопоставимым характеристикам, не только по сегменту | Больше точности и объяснимости | +| **P1** | RAG + калибровка по план/факту с фильтрами контекста и доступа | Получить измеримое улучшение точности | +| **P1** | Надёжная PostgreSQL-очередь задач / worker | Масштабирование и устойчивость к рестартам | +| **P1** | Акторы, tenant scoping и права в UI/API | Подготовка к командной работе и нескольким клиентам | +| **P2** | Дополнительные Domain Packs, сценарии и экспорт КП | Расширение функциональности продукта | + +--- + +## 2. Целевое позиционирование + +**Не только «калькулятор цены бота», а движок предварительных технических и коммерческих оценок.** + +Возможные потребители: + +- Flexly AI Core: получение требований из Telegram, сайта/виджета и других каналов; +- собственный административный интерфейс оценщика; +- менеджер или пресейл-специалист; +- другие приложения по REST и, в перспективе, MCP. + +Первоначальные направления специализации: + +| Domain Pack | Примеры | +|---|---| +| `bots_ai` | Telegram/сайт/мультиканальность, RAG, LLM-агенты, CRM | +| `web` | лендинги, корпоративные сайты, каталоги, интернет-магазины | +| `software` | backend, личные кабинеты, SaaS, биллинг, API | +| `automation` | CRM/ERP-интеграции, ETL, автоматизация процессов | + +Граница применения **первой расширенной версии** — прежде всего IT/цифровая разработка. Оценивание строительства, производства и иных не-IT отраслей потребует дополнительных моделей материалов, закупок, физических ресурсов, нормативов и рисков; текущая архитектура **не гарантирует** их поддержку без дальнейших расширений. + +--- + +## 3. Целевая архитектура: Engine + Domain Packs + +```text +Flexly AI channels / Admin UI / external consumers + | + REST API (OpenAPI) + | + EstimateService (use cases) + | + +-----------+-------------+-------------------+ + | | | +Intake/Agent Pipeline Domain Registry Estimate Versions + | | | + | +-----------+-----------+ | + | | | | | + | bots_ai web software automation ... + | +-----------+-----------+ | + | | | + +--------- Capability / Work-Item Catalog ----+ + | + Deterministic Pricing Engine + | + Market Benchmarks / Risks / RAG / Calibration + | + PostgreSQL + PGVector/BM25 + Audit +``` + +### 3.1. Что такое Domain Pack + +Пакет предметной области — **описание специализации**, а не отдельный микросервис. Он определяет: + +1. классификатор типов проектов и функциональных возможностей; +2. каталог типовых задач и зависимостей; +3. уточняющие вопросы и признаки недостаточности требований; +4. правила декомпозиции, полноты и исключения дублей; +5. допустимые роли/ресурсы, источники ставок и эталоны; +6. подсказки и инструкции для агентных шагов; +7. собственную версию и совместимость с общей схемой. + +**Не превращать всё сразу в исполняемые Python-плагины.** Предпочтителен декларативный формат (TOML или YAML) с Pydantic-валидацией. Python-хуки разрешать только для предметно-специфичной логики, которой невозможно выразить декларативно. Плагины не должны вносить собственные формулы стоимости в обход `pricing`. + +Пример **концептуальной** структуры (не готовая спецификация загрузчика): + +```text +src/estimator/ +├── domain/ # общее ядро контрактов +├── pricing/ # единая экономика и неопределённость +├── agent/ # универсальный pipeline +├── catalog/ # capabilities, work items, зависимости +├── domains/ +│ ├── registry.py # поиск и проверка версий пакетов +│ ├── bots_ai/ +│ │ ├── manifest.toml +│ │ ├── capabilities.yaml +│ │ ├── work_items.yaml +│ │ └── prompts/ +│ ├── web/ +│ ├── software/ +│ └── automation/ +├── market/ # рыночные данные и сопоставимость +├── calibration/ # фактические часы и статистика +├── rag/ # поиск аналогичных работ/проектов +├── services/ +├── infra/ +├── api/ +├── web/ +└── mcp/ +``` + +### 3.2. Композиция возможностей, а не комбинаторика сегментов + +Один проект может включать функциональность из нескольких доменов. + +```yaml +# Иллюстративная структура входных данных; API v2 пока не утверждён. +project_type: ecommerce +capabilities: + - web.catalog + - web.checkout + - backend.auth + - integration.payment + - integration.crm + - ai.rag + - ai.chat_widget +region: ru +pricing_profile: agency_ru +``` + +Это лучше, чем заводить отдельные сегменты `ecommerce_with_ai_crm`, `ecommerce_with_ai_and_payments` и т. п. + +### 3.3. Как избежать двойного учёта + +Каталог должен различать: + +- **Capability** — результат/функциональная возможность для заказчика; +- **Work Item** — конкретная работа для создания возможности; +- **Shared Work Item** — общая инфраструктура, аналитика, авторизация, CI/CD и др.; +- **Dependency** — обязательная работа или зависимость между работами; +- **Scope Boundary** — какие работы включены, исключены или уже существуют. + +Например, `integration.crm` и `ai.chat_widget` могут использовать одну backend-платформу. Подсчёт выполняется по объединённому WBS с уникальными work items. Общее ядро нельзя суммировать дважды. Аналогично коэффициент за «ещё один канал» нельзя одновременно прибавлять, если адаптер канала уже представлен отдельной задачей — эта защита уже отмечена в текущем документе. + +--- + +## 4. Предлагаемая предметная модель v2 + +Минимальные сущности и смысловые поля: + +| Сущность | Содержание | +|---|---| +| `Project` / `Estimate` | владелец, исходные требования, тип проекта, выбранные capabilities | +| `EstimateVersion` | неизменяемая оценка, статус, снимки вводных и конфигураций | +| `DomainPackRef` | `id`, `version`, `schema_version`, хэш манифеста | +| `Capability` | стабильный код, описание результата, зависимости, критерии применимости | +| `WorkItem` | стабильный код каталога + ID экземпляра, WBS-позиция, роль, тип работы | +| `TaskEstimate` | O/M/P, базовый прогноз, источник эталона, степень неопределённости | +| `RiskEvent` | вероятность, денежное/временное воздействие, затронутые работы, стратегия обработки | +| `PricingProfile` | ставки/ресурсы, способ ценообразования, правила PM/маржи/налогов | +| `MarketBenchmark` | тип и состав проекта, регион, сложность, цена, базис и доказательства | +| `ProjectActual` | фактические часы, расходы, сроки и цена, связь с WBS/версией | + +**Важно:** стабильный код шаблона работы (`integration.crm`) и идентификатор конкретной строки сметы (`task_id`) — разные поля. Нужна также связь между версиями строки (`lineage_id`), чтобы после переработки WBS можно было сравнить план/факт и историю исправлений. + +Для корректной изоляции в схеме надо предусмотреть `tenant_id`, `created_by`, `approved_by` и действующие права доступа. Отдельная версия сохраняет **снимок** применённых справочников, а не только ссылку на изменяемую запись. + +--- + +## 5. Агентный pipeline v2 + +Текущий `clarify → decompose → estimate → critic` стоит сохранить как основу. Предлагается расширить его логические этапы: + +| # | Шаг | Ответственность | +|---|---|---| +| 1 | **Intake & Classify** | нормализовать требования; определить домены и capabilities | +| 2 | **Clarify** | собрать пробелы, сформировать приоритетные вопросы, зафиксировать допущения | +| 3 | **Decompose** | собрать WBS из каталога + нетиповые работы | +| 4 | **Retrieve Benchmarks** | найти сопоставимые задачи и завершённые проекты | +| 5 | **Estimate** | определить O/M/P, роли/ресурсы, зависимости и основания | +| 6 | **Critic & Validate** | обнаружить пропуски, дубли, неверный scope и несовместимые предположения | +| 7 | **Deterministic Pricing** | рассчитать трудозатраты, ресурсы, риски и финансовые показатели | +| 8 | **Market Check & Approval** | сверить с сопоставимыми предложениями и направить на утверждение при необходимости | + +Это **логические** этапы: не требуется восемь отдельных LLM-вызовов. Часть действий выполняется кодом или объединяется в один вызов. Стоимость, задержка и количество токенов — самостоятельные KPI pipeline. + +### 5.1. Два режима оценивания + +**Rough Estimate (экспресс-оценка):** предварительная вилка на основе частичных требований; короткий список критических вопросов; высокое внимание к допущениям; запрет на выдачу как окончательного фиксированного предложения. + +**Detailed Estimate (подробная оценка):** развёрнутая WBS; поиск аналогов; ставки и риски; несколько сценариев; экспертное подтверждение перед отправкой коммерческого предложения. + +Режим и полнота данных должны быть явными атрибутами результата. При критически недостающих вводных detailed-оценка остаётся в `needs_input`, а rough-оценка может выдавать осторожный диапазон с предупреждениями. + +### 5.2. Ограничения LLM + +- LLM не определяет окончательную цену и не может подменять ставки. +- LLM возвращает структурированные кандидаты на задачи, часы, предположения и риски. +- Валидаторы обеспечивают уникальность WBS-элементов, существование ролей, логичность O ≤ M ≤ P, пределы задач и отсутствие дублирования. +- Сбой `critic` не должен скрываться: если расчёт всё же возвращён, он явно получает предупреждение о пропущенной проверке и может требовать подтверждения человеком. +- Клиентские ТЗ, найденные RAG-документы и LLM-ответы считаются **недоверенными входными данными**; структурная схема сама по себе не устраняет prompt injection. + +--- + +## 6. Расчётное ядро: необходимые изменения + +### 6.1. Себестоимость, наценка и маржа — разные понятия + +В исходном примере из `bot-estimation-market-data.md` применяется: + +```text +price = base * 1.15 (PM) * 1.10 (risk) * 1.20 (margin) +``` + +Последний множитель `1.20` означает **20% наценки**, а не **20% валовой маржи**. + +Для себестоимости 100 000 ₽: + +| Правило | Итоговая цена | Фактическая валовая маржа | +|---|---:|---:| +| Наценка 20%: `100000 × 1.20` | 120 000 ₽ | ≈16,67% | +| Целевая маржа 20%: `100000 / (1 − 0.20)` | 125 000 ₽ | 20% | + +Необходимы разные параметры `markup_pct` и `target_gross_margin_pct` с взаимоисключающими режимами. Формулы должны учитывать точное определение себестоимости (включая прямые/косвенные затраты) и коммерческую политику; налог с продаж/НДС нельзя механически трактовать как прибыль. + +Предлагаемая структура результата: + +```text +Direct labor cost ++ Project management cost ++ External costs (лицензии, API, закупки, подрядчики) ++ Identified risk allowance / contingency (при наличии) += Cost basis по правилам PricingProfile +→ Применение выбранной наценки ИЛИ целевой маржи +→ Налоговые правила и валюта += Customer price, с понятной разбивкой +``` + +Не нужно одновременно добавлять PM как 15% и включать отдельные PM-задачи в WBS без явного правила исключения дубля. Аналогично эксплуатацию (`run`, TCO) лучше показывать отдельно от разового внедрения. + +### 6.2. PERT как первый уровень, а не доказанная вероятность + +Базовые формулы из текущего документа полезны: + +```text +E_task = (O + 4*M + P) / 6 +sigma_task = (P - O) / 6 +``` + +Агрегация `sqrt(sum(sigma_task²))` правомерна как приближение **при независимости** задач и при принятых предположениях о распределении. В реальных проектах один риск может одновременно сдвигать backend, интеграции и QA. + +Поэтому: + +1. **В v2/MVP:** сохранить PERT, явно фиксировать допущение независимости, не заявлять P85 как гарантированную вероятность без эмпирической калибровки. +2. **В следующем режиме:** моделировать общие факторы риска и корреляции; поддержать Monte Carlo для времени, ресурсов и цены. +3. **Для стоимости:** считать неопределённость с учётом **ставки каждой роли**, а не масштабировать общую стоимость на `hours_p85 / hours_mean`, когда роли существенно отличаются по ставкам. +4. **Для резерва:** развести распределённую неопределённость внутри O/M/P, конкретные рисковые события и коммерческий резерв — иначе риск можно включить дважды. +5. **Для календарного срока:** учитывать зависимости задач, доступную ёмкость команды и параллельное выполнение; общие часы / 8 — это трудоёмкость в человеко-днях, не дата поставки. + +Текущая архитектура прямо отмечает приближённость расчёта стоимости по `hours_confident / hours`; доработку следует запланировать как исправление модели, а не только косметическое улучшение отчёта. + +### 6.3. Прозрачность оценки + +Каждая итоговая цена должна сопровождаться: + +- составом работ, включениями и исключениями; +- базой ставок и версией профиля; +- диапазонами времени и стоимости, **с обозначением природы диапазона**; +- факторами риска и допущениями; +- степенью уверенности с опорой на качество исходных данных, а не на самоуверенность LLM; +- отдельными разовыми и регулярными расходами. + +--- + +## 7. Рыночная база и эталонные оценки + +### 7.1. Сохранить разделение типов данных + +Исходный документ обоснованно различает: цены проектов, почасовые ставки, эталонные трудозатраты, эксплуатационные цены, коэффициенты и валютно-налоговую информацию. Это разделение следует сохранить. + +Рыночные данные — **проверка правдоподобия**, а не источник «правильной» цифры. Публичные прайсы/маркетинговые публикации являются слабыми приорами; фактические трудозатраты и сделки компании важнее. + +### 7.2. Переход от `segment` к сопоставимому контексту + +Рекомендуемые параметры `MarketBenchmark`: + +```yaml +# Иллюстративный пример, а не реальная рыночная запись. +domain: software +project_type: ecommerce +capabilities: [web.catalog, web.checkout, integration.crm] +complexity: medium +region: RU +provider_type: agency +price_basis: fixed_project_ex_vat +currency: RUB +observed_at: null +source_type: internal_or_public +sample_size: null +scope: "..." +evidence_quality: unknown +``` + +Для ставок отдельно хранить `role`, `level`, `basis` (`freelance`, `salary_derived`, `agency_billing` и др.), регион и период наблюдения. Для трудозатрат — технологию, тип работы, сложность, объём, фактические часы и наличие повторного использования компонентов. + +Важные правила: + +- не смешивать цены подрядчиков разного типа в один агрегат; +- сравнивать предложения только при совместимом scope; +- проверять НДС, валюту, дату курса и единицу измерения; +- сохранять происхождение, первичные документы, признаки дублей и качество свидетельств; +- не складывать «цена мультиканальности» + «цена AI-бота», пока не доказано отсутствие пересечения в составе работ; +- малая выборка должна явно отмечаться, а не выдавать псевдоточные перцентили. + +### 7.3. Метрики качества + +**Не делать долю «попадания в рынок» основным показателем точности.** Она может побуждать подгонять смету под несопоставимые публикации. + +Лучше оценивать: + +| Метрика | Интерпретация | +|---|---| +| Ошибка по часам (MAE, WAPE и др.) | Насколько прогноз совпадает с фактической трудоёмкостью | +| Bias / systematic underestimation | Насколько систематически занижаем или завышаем | +| Coverage interval | Как часто факт попадает в обещанный диапазон | +| Ошибка по себестоимости и цене | Точность финансового прогноза отдельно от коммерческой политики | +| Качество scope | Сколько задач пропущено, продублировано, добавлено вручную | +| Human override rate | Насколько часто эксперт исправляет результат агента | +| Time-to-estimate / LLM cost | Цена и время самого оценивания | + +MAPE из исходного документа можно оставлять дополнительной метрикой, но она нестабильна на очень малых фактических величинах; полезно сопоставлять её с MAE/WAPE и анализом отдельных доменов. + +--- + +## 8. RAG и калибровка по план/факту + +### 8.1. Retrieval + +Использовать выбранную для Flexly AI инфраструктуру **PostgreSQL + PGVector/BM25**, без выделения нового search-сервиса на старте. При этом пространство данных оценщика логически и по правам изолировать от пользовательских баз знаний Flexly AI Core. + +Поиск аналогов двухступенчатый: + +1. структурные фильтры: `tenant_id`, домен/возможности, тип задачи, сложность, технология, период, сопоставимость; +2. гибридный текстово-векторный поиск и ранжирование пригодных кандидатов. + +Индексировать не только описание проекта, но и WBS-работы, их предположения, фактические часы, объём и исходную версию оценки. В выдаче хранить `reference_id`, факторы сходства и основания использования. **Не возвращать цены/чувствительные данные чужого tenant.** + +### 8.2. Калибровка + +Идея исходного документа `k = median(actual_hours / estimated_hours)` разумна как простое первое приближение, но её нужно применять осторожно: + +- коэффициент считать по сопоставимым работам/доменам/сложности, а не глобально; +- не подстраивать модель под 1–2 аномальных проекта; +- отмечать число наблюдений и качество данных; +- при малой выборке использовать консервативный prior и постепенное «усиление» собственных данных; +- хранить факт отдельно от прогноза и **не переписывать исторические версии**; +- проверять эффект калибровки на отложенных проектах, а не только на обучающей истории. + +Фактические данные желательно собирать **на уровне work item**, а не только проекта: иначе невозможно понять, что регулярно недооценивается — аналитика, QA, CRM-интеграции или эксплуатация. + +--- + +## 9. API, UI, безопасность и интеграция с Flexly AI Core + +### 9.1. API + +Сохранить существующий контракт `POST /api/estimates`, версии, ответы на вопросы, пересчёт и ручные правки. Расширение вводить совместимо: + +- новые поля `project_type`, `capabilities`, `mode`, `pricing_profile_id` — по возможности опционально для существующих клиентов; +- `domain_pack_refs`, `scope`, `risk_register`, `uncertainty`, `cost_breakdown` — в версии результата; +- версия схемы ответа/конфигурации или отдельный API v2 при несовместимом изменении; +- стабильно сохранять `estimate_id`, версии и идемпотентность; +- старые оценки читать и пересчитывать с **их** снимком тарифов и конфигураций, если запрошен исторический повтор. + +### 9.2. UI + +**HTMX + Jinja2 сохранять** для первого расширенного релиза. Важнее улучшить сценарий работы, чем менять frontend-стек: + +- выбор типа проекта и составных возможностей; +- индикатор полноты требований, список вопросов и допущений; +- WBS с ручным редактированием и отображением причин оценки; +- сценарии `economy / base / conservative` (или согласованные аналоги); +- сравнение версий и ручных исправлений; +- отдельные единовременные и ежемесячные расходы; +- экспорт коммерческого предложения (PDF/XLSX — по отдельной задаче); +- план/факт и показатели качества оценщика. + +Если появится сложный drag-and-drop редактор WBS, можно добавить точечный JS-компонент, не переводя всё приложение на SPA. + +### 9.3. Tenant / user security + +Текущий API уже фильтрует сметы по клиенту из `X-API-Key`. Для полноценного UI этого недостаточно, если пользователи одной компании имеют разные права или один UI работает с несколькими организациями. + +Рекомендуется: + +- идентифицировать **tenant и пользователя** на доверенной стороне; +- управлять ролями `viewer`, `estimator`, `approver`, `admin` (точный перечень — ADR); +- не принимать произвольный `tenant_id` или `X-User-ID` от браузера без проверки доверенного контекста; +- проверять доступ ко **всем** версиям, задачам, рыночным данным и документам; +- ограничить и аудитировать публикацию клиенту/экспорт коммерческого предложения; +- очищать/ограничивать логи и хранилище ТЗ с учётом конфиденциальности. + +XSS/CSRF-защита из текущего документа должна остаться. Prompt injection обрабатывать отдельно от XSS: экранирование HTML защищает рендер, а не инструкции для модели. + +### 9.4. Конфигурация + +Для Flexly AI Core ранее выбран `app_settings` как источник изменяемых настроек моделей, fallback-цепочек и таймаутов. Это **не означает**, что самостоятельный оценщик обязан писать в ту же физическую таблицу. + +Разделение: + +| Источник | Ответственность | +|---|---| +| `default.toml`, env | технические настройки, секреты, ограничения по умолчанию | +| DB / `app_settings` или собственное конфигурационное API | изменяемые эксплуатационные настройки, маршруты моделей и таймауты | +| `DomainPack` + каталог | предметные правила, коды capabilities и версионируемые шаблоны | +| `PricingProfile` | коммерческая политика, ставки, налоги, наценка/маржа | +| `EstimateVersion` snapshot | точный набор применённых настроек и правил конкретной оценки | + +При интеграции с Flexly AI Core возможен поставщик конфигурации через API/адаптер; при отдельном инсталляционном пакете оценщик должен сохранять автономный запуск. + +### 9.5. Фоновая обработка + +Текущий внутрипроцессный `JobRunner` по документации рассчитан на один экземпляр и требует развития при нескольких репликах. + +Рекомендуемый следующий шаг — **PostgreSQL-backed job queue** с отдельным worker, без обязательного RabbitMQ: + +- транзакционный захват работ (`FOR UPDATE SKIP LOCKED` там, где применимо); +- lease/heartbeat, контроль timeout, повторный подбор зависших работ; +- идемпотентность `job_id` / `estimate_version_id`; +- лимиты параллелизма и вызовов LLM по tenant/провайдеру; +- политика повторов с учётом сетевых ошибок и риска повторного платного вызова; +- ручное возобновление, отмена, мониторинг, аудит причин сбоя. + +SQLite оставить для локальных тестов, но не имитировать на ней продукционные гарантии многопроцессной очереди. + +--- + +## 10. Переход от v1 к v2 без переписывания ядра + +### Фаза 0. Зафиксировать базу и устранить несоответствия документации + +- Сверить текущий код со статусами раздела 13 `estimator-architecture.md`. +- Обновить шапки документов, где написано «реализация не начата». +- Зафиксировать текущие OpenAPI snapshots, миграции, golden-тесты и эталонные расчёты. +- Зафиксировать поведение существующих `Segment`, рынка и ценового калькулятора как совместимый baseline. + +**Готово, когда:** можно продемонстрировать, что старый бот-сценарий и история оценок работают до и после миграции. + +### Фаза 1. Универсальное ядро и корректная экономика (**P0**) + +- Ввести `DomainPackRef`, `ProjectType`, `Capability`, `WorkItem` и `PricingProfile`. +- Реализовать реестр пакетов и валидацию их схем. +- Представить текущий бот-справочник как первый `bots_ai` pack. +- Развести маржу и наценку, исключить двойной PM и двойной резерв риска. +- Явно маркировать режим расчёта и метод интервала. + +**Готово, когда:** текущий бот считается новым ядром без изменения бизнес-смысла старых смет, а финансовые формулы проходят эталонные тесты. + +### Фаза 2. Каталог задач и новые домены (**P0/P1**) + +- Создать общие work items для аналитики, UI, backend, QA, DevOps, интеграций. +- Добавить `web`, `software`, `automation` как тонкие каталоги. +- Ввести композицию capabilities и проверку дублей. +- Добавить `Intake & Classify`, расширить `Decompose` и `Critic`. + +**Готово, когда:** один проект корректно включает работы из нескольких пакетов и не получает повторных общих расходов. + +### Фаза 3. Рыночная база, RAG, план/факт (**P1**) + +- Перейти от сегмента к контекстным эталонам. +- Добавить гибридный поиск похожих задач с tenant-scoping. +- Собирать факт по work items, строить отчёт bias/coverage. +- Включать калибровку сначала в теневом режиме, затем после подтверждения качества. + +**Готово, когда:** улучшение метрик на отложенных проектах измеримо и не приводит к ухудшению отдельных доменов. + +### Фаза 4. Эксплуатационная зрелость и интерфейс (**P1/P2**) + +- Вынести фоновые расчёты в PostgreSQL worker. +- Ввести user/tenant роли, жизненный цикл согласования сметы. +- Добавить UI выбора capabilities, подробную WBS, сценарии и сравнение версий. +- Реализовать экспорт КП после согласования формата. +- MCP — как тонкий адаптер к стабильному REST/use cases, когда появится реальный потребитель. + +**Готово, когда:** параллельные расчёты, рестарты и разграничение доступа воспроизводимо проверяются интеграционными тестами. + +--- + +## 11. Кандидаты ADR + +Ниже **предлагаемые** решения, не принятые автоматически: + +| ADR | Тема | Рекомендуемое решение | +|---|---|---| +| `ADR-EST-001` | Расширение предметных областей | Engine + декларативные Domain Packs | +| `ADR-EST-002` | Модель состава проекта | Композиция capabilities и единый WBS, а не комбинации сегментов | +| `ADR-EST-003` | Экономическая модель | Отдельные cost basis, markup, target margin, налоги, recurring costs | +| `ADR-EST-004` | Неопределённость и риск | PERT с явными допущениями; позже Monte Carlo с корреляциями | +| `ADR-EST-005` | Хранилище эталонов | SQL-истина + гибридный retrieval для описаний/аналогов | +| `ADR-EST-006` | Калибровка | Work-item plan/fact, версии, отложенная валидация, приоры при малой выборке | +| `ADR-EST-007` | Фоновые задачи | PostgreSQL-backed worker вместо in-process job runner для multi-instance | +| `ADR-EST-008` | Аутентификация UI | Tenant-scoped actor + RBAC, не общий ключ без пользовательского контекста | +| `ADR-EST-009` | Источники конфигурации | TOML/env + DB runtime settings + immutable estimate snapshot | + +Каждый ADR должен фиксировать контекст, альтернативы, ограничения, последствия и план миграции с указанием затрагиваемых данных/API. + +--- + +## 12. Тестовая стратегия и критерии готовности + +### Контрольные проекты для доказательства универсальности + +1. **Мультиканальный AI-бот:** Telegram + сайт + CRM + RAG. +2. **Интернет-магазин:** каталог + оформление заказа + оплата + CRM + AI-консультант. +3. **SaaS-приложение:** кабинет, роли, подписки/биллинг, backend API, администрирование. + +Для всех трёх должен работать **один** `EstimateService`, единый pricing engine, единая схема версий и один интерфейс сметы. Специализация должна отличаться данными каталога/пакетов, а не крупными ветками кода `if project_type == ...`. + +### Проверки + +- Unit/property-based тесты: монотонность стоимости по часам, правила маржи, налоги, валюты, нулевые/аномальные вводные, исключение дублей. +- Golden-тесты: типовые ТЗ разных доменов, полнота WBS, разумные диапазоны, изменения после критика. +- Contract-тесты: совместимость существующих REST-клиентов; версионирование схем. +- Integration: PostgreSQL, concurrent version writes, очередь, retries, tenant isolation. +- Security: XSS, CSRF, prompt injection, разграничение доступа, изоляция RAG и аудита. +- Calibration: сравнение с историческим baseline, временной holdout, bias, coverage, ручные исправления. +- Эксплуатация: продолжительность оценивания, стоимость токенов, частота ошибок/fallback. + +**Не стоит задавать универсальные численные пороги точности заранее:** они зависят от накопленной выборки и сложности проектов. Сначала нужен baseline, затем целевые SLA/метрики по доменам. + +--- + +## 13. Открытые вопросы перед утверждением v2 + +1. **Границы продукта:** только разработка ПО и автоматизация либо намерение оценивать также не-IT работы? +2. **Коммерческая политика:** кто владеет тарифами и ценовыми профилями, нужны ли разные профили для клиентов/команд/регионов? +3. **Роли UI:** внутренний оценщик для команды, сервис для клиентов или оба режима? +4. **Смета vs коммерческое предложение:** когда и кем утверждаются итоговые значения; допускается ли автоматическая публикация предварительной вилки? +5. **Качество исходных данных:** есть ли завершённые проекты с план/фактом на уровне задач? +6. **Правила использования исторических проектов:** можно ли использовать агрегаты между tenants или данные должны быть строго изолированы? +7. **Интеграция с Flexly AI Core:** общий деплой и config provider или автономный сервис с независимой БД? +8. **Стоимость эксплуатации:** нужен ли в v2 полноценный TCO по нагрузочным сценариям (запросы/мес, токены, hosting, поддержка)? + +Эти вопросы влияют на ADR и API, но **не мешают** уже сейчас разрабатывать универсальные Domain Packs и исправления расчётной модели. + +--- + +## 14. Рекомендуемое решение + +**Принять направление Estimator Engine v2 без переписывания существующих слоёв.** + +Сохранить `domain/pricing/agent/market/services/infra`, REST как первичный контракт, HTMX + Jinja2 на первом этапе и историческую версионность оценок. Перед масштабированием на новые рынки и виды проектов: + +1. формализовать **Domain Packs + capabilities + work-item catalog**; +2. исправить **финансовую модель и трактовку неопределённости**; +3. обеспечить **композицию WBS без двойного учёта**; +4. затем развивать **RAG, рыночные эталоны и обучение на плане/факте**; +5. отдельно усилить очередь заданий, авторизацию и UI. + +**Критерий архитектурного успеха:** новый тип проекта добавляется преимущественно через данные пакета и эталонные тесты, а не через переписывание `pricing.calculator`, `EstimateService`, схемы версий и REST-роутов. + +--- + +## Приложение A. Связь с исходными решениями + +| Из исходных документов | Действие в v2 | +|---|---| +| Детерминированная цена | **Сохранить**, уточнить экономику | +| PERT O/M/P | **Сохранить как базовый режим**, не преувеличивать вероятностную интерпретацию | +| `Segment` для ботов | **Обернуть совместимостью**, заменить как главную абстракцию на capabilities | +| TOML рыночные версии | **Сохранить**, добавить метаданные сопоставимости и snapshots | +| `channel_multiplier` | **Не дублировать** с задачами каналов | +| Immutable `estimate_versions` | **Сохранить и расширить** lineage и domain pack refs | +| API + MCP | **Сохранить REST**, MCP подключать по мере реального спроса | +| HTMX + Jinja2 | **Сохранить**, добавлять точечную интерактивность | +| `JobRunner` в процессе | **Оставить на одном инстансе**, перейти на PostgreSQL worker при масштабировании | +| RAG и план/факт | **Реализовать после унификации work items**, иначе усложнится миграция | + +## Приложение B. Дополнительные ориентиры + +- Исходные локальные документы из раздела 0 — источник описания состояния и принятых решений проекта. +- [GAO Cost Estimating and Assessment Guide (GAO-20-195G)](https://www.gao.gov/products/gao-20-195g) — общие ориентиры по WBS, документированию допущений, анализу неопределённости и актуализации оценок. Руководство рассчитано на крупные программы; принципы следует адаптировать к масштабу Flexly AI. + +--- + +**Статус документа:** рекомендации для архитектурного ревью и постановки ADR. Не подменяет текущую рабочую спецификацию до утверждения решений и миграционного плана. diff --git a/docs/estimator-architecture.md b/docs/estimator-architecture.md new file mode 100644 index 0000000..8c5022a --- /dev/null +++ b/docs/estimator-architecture.md @@ -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/.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/.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 = "" + +[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`. Открыто: режим налогообложения продавца (ОСНО или УСН), НДС в источниках ориентиров, предупреждение о падении наценки при фиксированной сумме с НДС. + diff --git a/docs/estimator-web-ui.md b/docs/estimator-web-ui.md new file mode 100644 index 0000000..440506b --- /dev/null +++ b/docs/estimator-web-ui.md @@ -0,0 +1,410 @@ +# Сервис оценки: веб-интерфейс на HTMX + Jinja + +**Версия:** 1.0 · **Дата:** 30 октября 2026 · **Статус:** реализовано (экраны 1–4, история, справочник), состояние и отклонения в разделе 13 +**Связанные документы:** `estimator-architecture.md` (архитектура и конфигурация), `bot-estimation-market-data.md` (рыночные данные) + +Документ дополняет архитектуру разделом про интерфейс. Он не меняет ядро: `web/` добавляется как ещё один вход рядом с `api/`, `mcp/` и `cli/`. + +--- + +## 1. Принятые решения + +| # | Решение | Обоснование | +|---|---|---| +| 1 | Интерфейс на **HTMX + Jinja2**, без Node в зависимостях | Экраны это формы, таблицы, статусы и справочники; сборка фронтенда не нужна | +| 2 | UI использует **REST API** как любой другой клиент (вариант B) | Один контракт для бота и интерфейса, UI ежедневно проверяет API, возможен отдельный деплой | +| 3 | Вызов API **in-process** через `httpx.ASGITransport`, без сети | Контракт соблюдается, накладных расходов нет | +| 4 | Маршруты `/ui/*` отдают только HTML-фрагменты, `/api/*` только JSON | Контракт API не засоряется `HX-Request`-ветками | +| 5 | Долгие расчёты через **асинхронное создание + опрос статуса** (`hx-trigger="every 2s"`) | Оценка идёт десятки секунд (несколько вызовов LLM) | +| 6 | JS и CSS **лежат в репозитории**, без CDN | Проще CSP и работа в закрытом контуре | +| 7 | Текст от LLM считается **недоверенным**: автоэкранирование Jinja включено, `\|safe` не используется | Защита от XSS и prompt injection через допущения и названия задач | + +--- + +## 2. Сравнение вариантов интеграции UI и API + +| Вариант | Как работает | Плюсы | Минусы | Выбор | +|---|---|---|---|---| +| A. UI вызывает `services/` напрямую | `web/` рядом с `api/` | Проще и быстрее | UI может обойти контракт, расхождения заметны поздно | нет | +| **B. UI ходит в API через клиент** | `web/` вызывает REST | Единый контракт, можно вынести в отдельный сервис | Нужен клиент и решение по аутентификации | **да** | + +Клиент для in-process режима: + +```python +# web/client.py +import httpx + +def make_api_client(api_app, key: str) -> httpx.AsyncClient: + return httpx.AsyncClient( + transport=httpx.ASGITransport(app=api_app), + base_url="http://api", + headers={"X-API-Key": key}, + ) +``` + +Для отдельного деплоя в TOML задаётся `[web] api_base_url`, и клиент создаётся с обычным транспортом. Код маршрутов не меняется. + +Нюанс: `ASGITransport` не запускает lifespan приложения. Зависимости API (БД, LLM-клиент) должны инициализироваться в общем lifespan основного приложения, а не только внутри sub-app, иначе первый вызов упадёт. Это нужно подтвердить тестом на раннем этапе. + +--- + +## 3. Структура модуля + +``` +src/estimator/web/ +├── router.py # подключается как /ui, отдельно от /api +├── client.py # клиент API +├── deps.py # сессия, CSRF, текущий пользователь, get_api +├── routes/ +│ ├── estimates.py # список, форма, результат, статус, ответы на вопросы +│ ├── market.py # справочник рынка, версии +│ ├── feedback.py # ввод план/факт +│ └── calibration.py # коэффициенты k +├── templates/ +│ ├── base.html +│ ├── components/ # макросы: таблица, бейдж, диапазон, пагинация +│ ├── estimates/ +│ │ ├── list.html +│ │ ├── new.html +│ │ ├── detail.html +│ │ ├── _status.html # фрагмент опроса +│ │ ├── _result.html +│ │ ├── _task_row.html # одна строка таблицы задач +│ │ └── _questions.html # открытые вопросы +│ ├── market/ +│ │ └── index.html +│ └── feedback/ +│ └── form.html +└── static/ + ├── htmx.min.js # зафиксированная версия, не из CDN + ├── app.css + ├── VENDOR.md # версии и хэши вендорных файлов + └── alpine.min.js # опционально +``` + +Правило зависимостей прежнее: бизнес-модули ничего не знают об HTML, `web/` зависит только от API-клиента и собственных шаблонов. + +### Секция конфигурации (в `default.toml`) + +```toml +[web] +enabled = true +api_base_url = "" # пусто = in-process через ASGITransport +session_ttl_s = 28800 +page_size = 20 +poll_interval_s = 2 +# из env: EST_WEB__SESSION_SECRET, EST_WEB__INTERNAL_API_KEY +``` + +Секрет сессии и внутренний ключ API приходят только из окружения и в браузер не попадают. + +--- + +## 4. Контракт API, нужный интерфейсу + +Реализован на этапе 5 (см. раздел 13.5 `estimator-architecture.md`). Интерфейс опирается на асинхронную модель с версиями: + +| Метод | Назначение | Ответ | +|---|---|---| +| `POST /api/estimates` | Создать оценку (`Idempotency-Key` необязателен, `engagement` необязателен) | `202` + оценка со статусом `pending` | +| `POST /api/estimates/{id}/engagement` | Показать готовую оценку как фикс или T&M | `200`, новая версия `reprice` без вызова модели | +| `POST /api/estimates/{id}/vat` | Сменить ставку НДС на готовой оценке (`vat_rate`, доля) | `200`, новая версия `reprice` без пересчёта | +| `GET /api/estimates/{id}?version=N` | Статус и результат | `{id, version, latest_version, status, step, open_questions, result, error, ...}` | +| `GET /api/estimates?status=&limit=&cursor=` | Список | `{items, next_cursor}` | +| `POST /api/estimates/{id}/answers` | Ответы на открытые вопросы (`question_id`, `answer`) | `202`, новая версия | +| `POST /api/estimates/{id}/recalculate` | Пересчёт | `202`, новая версия | +| `PATCH /api/estimates/{id}/tasks/{task_id}` | Правка часов задачи | `200`, новая версия с итогом | +| `GET /api/market/versions`, `GET /api/market/{version}` | Справочник рынка | JSON | +| `POST /api/projects/{id}/actuals` | Ввод факта | этап 7, пока нет | +| `GET /api/calibration` | Коэффициенты `k` и число наблюдений | этап 7, пока нет | + +Статусы: `pending`, `running`, `needs_input`, `done`, `failed`. Поле `step` содержит текущий шаг конвейера (`clarify`, `decompose`, `estimate`, `critic`, `pricing`). При `failed` поле `error` содержит `code` и безопасный текст. Идентификаторы задач (`t1`, `t2`, ...) стабильны внутри версии и используются в правках. + +--- + +## 5. Экраны первой версии + +| # | Экран | Содержимое | +|---|---|---| +| 1 | Новая оценка | Форма: описание, регион, валюта → статус → результат | +| 2 | Результат | Таблица задач (O/M/P, часы, роль), итоговый диапазон, допущения и риски, бейдж «сверка с рынком», блок открытых вопросов с формой ответа, кнопка «пересчитать» | +| 3 | История | Список оценок, версии, фильтры по региону и статусу | +| 4 | Справочник рынка | Активная версия, ставки, диапазоны (только просмотр) | +| 5 | План/факт | Форма ввода фактических часов по закрытому проекту | +| 6 | Калибровка | Таблица коэффициентов `k` по типам задач и числу наблюдений | + +Правка отдельной задачи делается построчно: `hx-put`/`hx-patch` на строку, подмена только этой строки, пересчёт итога приходит следующим фрагментом (`hx-swap-oob`). + +--- + +## 6. Рабочий скелет + +### 6.1. Подключение + +```python +# web/router.py +from pathlib import Path +from fastapi import APIRouter +from fastapi.staticfiles import StaticFiles +from fastapi.templating import Jinja2Templates + +BASE = Path(__file__).parent +templates = Jinja2Templates(directory=BASE / "templates") +router = APIRouter(prefix="/ui") + +# в app.py: +# app.include_router(web_router) +# app.mount("/ui/static", StaticFiles(directory=BASE / "static"), name="ui-static") +``` + +### 6.2. Маршрут создания оценки + +```python +# web/routes/estimates.py +from fastapi import Depends, Form, Request +from fastapi.responses import HTMLResponse +from ..router import router, templates +from ..deps import get_api, check_csrf + +@router.post("/estimates", response_class=HTMLResponse, dependencies=[Depends(check_csrf)]) +async def create(request: Request, requirements: str = Form(...), + region: str = Form("ru"), currency: str = Form("RUB"), + api=Depends(get_api)): + r = await api.post("/api/estimates", json={ + "requirements": requirements, "region": region, "currency": currency}) + r.raise_for_status() + return templates.TemplateResponse(request, "estimates/_status.html", {"est": r.json()}) + +@router.get("/estimates/{est_id}/status", response_class=HTMLResponse) +async def status(request: Request, est_id: str, api=Depends(get_api)): + r = await api.get(f"/api/estimates/{est_id}") + r.raise_for_status() + return templates.TemplateResponse(request, "estimates/_status.html", {"est": r.json()}) +``` + +### 6.3. `base.html` + +```html + + + + + + {% block title %}Оценка работ{% endblock %} + + + + + + +
{% block content %}{% endblock %}
+ + +``` + +### 6.4. `estimates/new.html` + +```html +{% extends "base.html" %} +{% block content %} +
+ + + + +
+
+{% endblock %} +``` + +### 6.5. `estimates/_status.html` (опрос останавливается сам) + +```html +
+ {% if est.status == "done" %} + {% include "estimates/_result.html" %} + {% elif est.status == "needs_input" %} + {% include "estimates/_questions.html" %} + {% elif est.status == "failed" %} +

Не удалось выполнить расчёт. Повторите попытку.

+ {% else %} +

Считаю… {{ est.step or "" }}

+ {% endif %} +
+``` + +Когда статус становится `done`, сервер возвращает фрагмент без `hx-get` и `hx-trigger`, и опрос прекращается. Если понадобится живой прогресс по шагам, подключается SSE-расширение HTMX, но на старте опроса достаточно. + +### 6.6. CSRF и сессия (эскиз) + +```python +# web/deps.py +import secrets +from fastapi import HTTPException, Request + +def csrf_token(request: Request) -> str: + token = request.session.get("csrf") + if not token: + token = secrets.token_urlsafe(32) + request.session["csrf"] = token + return token + +async def check_csrf(request: Request): + sent = request.headers.get("X-CSRF-Token") + if not sent or not secrets.compare_digest(sent, request.session.get("csrf", "")): + raise HTTPException(403, "CSRF") +``` + +`SessionMiddleware` подключается с секретом из `EST_WEB__SESSION_SECRET`, cookie с флагами `HttpOnly`, `Secure` (вне dev) и `SameSite=Lax`. + +--- + +## 7. Статика без Node + +| Задача | Решение | +|---|---| +| Стили | Классless-CSS (Pico или Simple.css) одним файлом, либо Tailwind standalone CLI (один бинарник, не Node, запускается только при разработке) | +| Графики | Серверный SVG из Jinja или вендорный Chart.js в `static/`; для калибровки на старте достаточно таблиц | +| Мелкая интерактивность | Нативные `
` и ``, при необходимости Alpine.js одним файлом | +| Вендорные файлы | Версии и контрольные суммы записываются в `static/VENDOR.md`, обновление вручную по решению | + +--- + +## 8. Безопасность + +| Риск | Мера | +|---|---| +| XSS через текст от LLM (допущения, риски, названия задач) | Автоэкранирование Jinja включено (проверить, что оно действует для всех `.html`-шаблонов), `\|safe` на таких полях запрещён, код-ревью и тест на экранирование | +| Утечка внутреннего ключа API | Ключ только на сервере, браузер получает сессионную cookie | +| CSRF | Токен в сессии, заголовок `X-CSRF-Token` через `hx-headers` | +| Кража сессии | `HttpOnly`, `Secure`, `SameSite=Lax`, короткий TTL (`session_ttl_s`) | +| Подмена клиента | UI использует отдельный внутренний ключ с ограниченными правами | +| Утечка чужих смет | Все запросы фильтруются по клиенту/пользователю на стороне API | +| Prompt injection через требования клиента | Текст требований передаётся в LLM как данные, результат шагов валидируется схемой, отображается экранированным | +| Лишние данные в логах | В логи UI не пишется текст требований и персональные поля | + +--- + +## 9. Тестирование + +| Уровень | Что проверяем | +|---|---| +| Контракт API | OpenAPI-схема, коды ответов и статусы, snapshot схемы | +| Фрагменты UI | `TestClient`: ключевые элементы в HTML, остановка опроса после `done`, отсутствие `hx-trigger` в конечных статусах | +| Безопасность | Экранирование: оценка с ` + + + {% if user %} +
+ +
+ + {{ user }} + +
+
+ {% endif %} +
+ + + {% block content %}{% endblock %} +
+ + diff --git a/src/estimator/web/templates/components/macros.html b/src/estimator/web/templates/components/macros.html new file mode 100644 index 0000000..3ed67cb --- /dev/null +++ b/src/estimator/web/templates/components/macros.html @@ -0,0 +1,9 @@ +{% macro badge(text, kind="muted") %}{{ text }}{% endmacro %} + +{# imported macros do not see the page context, so the token is passed in explicitly #} +{% macro csrf(token) %}{% endmacro %} + +{% macro status_badge(status) %} +{% set kinds = {"done": "ok", "failed": "bad", "needs_input": "warn", "running": "info", "pending": "info"} %} +{{ status | status }} +{% endmacro %} diff --git a/src/estimator/web/templates/error.html b/src/estimator/web/templates/error.html new file mode 100644 index 0000000..0994c92 --- /dev/null +++ b/src/estimator/web/templates/error.html @@ -0,0 +1,9 @@ +{% extends "base.html" %} +{% block title %}Ошибка {{ code }}{% endblock %} +{% block content %} +
+

Ошибка {{ code }}

+

{{ message }}

+

На главную

+
+{% endblock %} diff --git a/src/estimator/web/templates/estimates/_panel.html b/src/estimator/web/templates/estimates/_panel.html new file mode 100644 index 0000000..fa3a006 --- /dev/null +++ b/src/estimator/web/templates/estimates/_panel.html @@ -0,0 +1,47 @@ +{% from "components/macros.html" import status_badge %} +{% set active = est.status in ("pending", "running") %} +{% set is_latest = est.version == est.latest_version %} +
+
+ {{ status_badge(est.status) }} + {{ est.region | region }}, {{ est.currency }} + {{ est.engagement | engagement }} + создана {{ est.created_at | dt }} + {% if est.latest_version > 1 %} + + {% for v in range(1, est.latest_version + 1) %} + v{{ v }} + {% endfor %} + + {% endif %} + версия {{ est.version }}: {{ est.source | source }} +
+ + {% if not is_latest %} +

Это версия {{ est.version }} из {{ est.latest_version }}. + Открыть последнюю

+ {% endif %} + + {% if active %} +

{% if est.step %}{{ est.step | step }}{% else %}{{ est.status | status }}{% endif %}…

+
+
Что оцениваем

{{ est.requirements }}

+ {% elif est.status == "needs_input" %} + {% include "estimates/_questions.html" %} + {% elif est.status == "failed" %} +

{{ est.error.message }} ({{ est.error.code }})

+ {% if is_latest %} +
+ + + +
+ {% endif %} + {% else %} + {% include "estimates/_result.html" %} + {% endif %} +
diff --git a/src/estimator/web/templates/estimates/_questions.html b/src/estimator/web/templates/estimates/_questions.html new file mode 100644 index 0000000..d268bbf --- /dev/null +++ b/src/estimator/web/templates/estimates/_questions.html @@ -0,0 +1,22 @@ +

Нужны уточнения

+{% if est.summary %}

{{ est.summary }}

{% endif %} +{% if is_latest %} +
+ + {% for q in est.open_questions %} +
+ +

{{ q.why }}

+ +
+ {% endfor %} + + +
+{% else %} +
    {% for q in est.open_questions %}
  • {{ q.text }}
  • {% endfor %}
+{% endif %} diff --git a/src/estimator/web/templates/estimates/_result.html b/src/estimator/web/templates/estimates/_result.html new file mode 100644 index 0000000..9358a9a --- /dev/null +++ b/src/estimator/web/templates/estimates/_result.html @@ -0,0 +1,133 @@ +{% from "components/macros.html" import badge %} +{% set r = est.result %} +{% set p = r.price %} +{% set mc = r.market_check %} + +{% if est.summary %}

{{ est.summary }}

{% endif %} +

+ {% if r.segment %}{{ badge(r.segment | segment, "info") }}{% endif %} + {% for c in r.channels %}{{ badge(c) }}{% endfor %} + {% if r.has_ai %}{{ badge("ИИ", "info") }}{% endif %} + {% for i in r.integrations %}{{ badge(i) }}{% endfor %} +

+ +{% if r.warnings %} +
Обратите внимание +
    {% for w in r.warnings %}
  • {{ w }}
  • {% endfor %}
+{% endif %} + +{% set qt = r.quote %} +{% set fixed = qt.engagement == "fixed_price" %} +
+
+

{{ qt.engagement | engagement }}

+ {% if fixed %} +

{{ qt.amount | money(est.currency) }}

+

цена для клиента без НДС, резерв внутри

+ {% if qt.vat_rate %}

К оплате с НДС {{ qt.vat_rate | pct(0) }}: {{ qt.amount_gross | money(est.currency) }} (НДС {{ (qt.amount_gross - qt.amount) | money(est.currency) }})

+ {% else %}

НДС не применяется

{% endif %} +
+
Без резерва
{{ p.cost_expected | money(est.currency) }}
+
Резерв
{{ p.reserve_cost | money(est.currency) }} ({{ p.reserve_hours | hours }}, {{ p.reserve_pct | pct }})
+
+ {% else %} +

{{ qt.amount | money(est.currency) }}

+

ожидаемая стоимость по фактическим часам, без НДС

+
+
Потолок бюджета
{{ qt.cap | money(est.currency) }} ({{ qt.hours_cap | hours }})
+
+ {% if qt.vat_rate %}

С НДС {{ qt.vat_rate | pct(0) }}: ожидаемо {{ qt.amount_gross | money(est.currency) }}, потолок {{ qt.cap_gross | money(est.currency) }}

+ {% else %}

НДС не применяется

{% endif %} +

Потолок стоит закрепить в договоре на спринт или месяц, иначе бюджет «растекается».

+ {% endif %} +
+
Трудозатраты
{{ p.hours | hours }}, σ {{ p.sigma | num }} ч
+
Резерв считается
{{ p.reserve_basis | reserve_basis }}: по PERT {{ p.pert_reserve_hours | hours }}, минимум {{ p.floor_reserve_hours | hours }}
+
Наценка
{{ p.inputs.markup_pct | pct }} к себестоимости (маржа {{ p.implied_margin_pct | pct }})
+
Справочник рынка
{{ r.market_version or "—" }}
+
+ {% if is_latest %} +
+ + {% if fixed %} + + {% else %} + + {% endif %} +
+ {% endif %} + {% if is_latest %} +
+ + + +
+ {% endif %} +
+
+

Сверка с рынком

+ {% if mc %} +

{{ badge(mc.message, mc.verdict | verdict_class) }}

+ {% if mc.benchmark %} +
+
Сравнивается с
ценой с резервом без НДС: {{ p.cost_with_reserve | money(mc.currency) }}
+
Ориентир рынка
{{ mc.benchmark.min | money(mc.currency) }} – {{ mc.benchmark.max | money(mc.currency) }}{% if mc.normalized_from_gross %} (указан с НДС {{ mc.benchmark.vat_rate | pct(0) }}, для сравнения приведён к цене без НДС){% else %} (без НДС){% endif %}
+
Допустимый коридор (±{{ (mc.tolerance * 100) | round | int }}%)
{{ mc.lower | money(mc.currency) }} – {{ mc.upper | money(mc.currency) }}
+
+ {% endif %} +

Ориентиры рынка это стартовые допущения из открытых источников. Попадание в них не означает точность оценки.

+ {% endif %} +
+
+ +

Задачи

+
+ + + + {% for t in r.tasks %}{% include "estimates/_task_row.html" %}{% endfor %} + +
#ЗадачаРольОптим.Вероятн.Пессим.Ожид.
+
+ +

По ролям

+

Ставка клиента = себестоимость × (1 + управление {{ p.inputs.pm_pct | pct }}) × (1 + наценка {{ p.inputs.markup_pct | pct }}). По ней считается Time & Materials.

+
+ + + + {% for b in p.by_role %} + + {% endfor %} + +
РольЧасыСебестоимость, в часСтавка клиента, в часСумма работ
{{ b.role | role }}{{ b.hours | hours }}{{ b.rate | money(est.currency) }}{{ b.billing_rate | money(est.currency) }}{{ b.cost | money(est.currency) }}
+
+ +
+ {% if r.assumptions %}

Допущения

    {% for a in r.assumptions %}
  • {{ a }}
  • {% endfor %}
{% endif %} + {% if r.risks %}

Риски

    {% for x in r.risks %}
  • {{ x }}
  • {% endfor %}
{% endif %} + {% if r.critic_notes %}

Замечания проверки

    {% for n in r.critic_notes %}
  • {{ n }}
  • {% endfor %}
{% endif %} +
+ +{% if is_latest %} +
+ Пересчитать +
+ + + {% if est.answers %} + + {% endif %} + +
+
+{% endif %} diff --git a/src/estimator/web/templates/estimates/_rows.html b/src/estimator/web/templates/estimates/_rows.html new file mode 100644 index 0000000..7cf699e --- /dev/null +++ b/src/estimator/web/templates/estimates/_rows.html @@ -0,0 +1,18 @@ +{% from "components/macros.html" import status_badge %} +{% for i in items %} + + {{ i.created_at | dt }} + {{ i.id[:8] }} + {% if i.summary %}{{ i.summary }}{% endif %} + {{ i.region | region }} + {{ status_badge(i.status) }} + v{{ i.version }} + {{ i.cost | money(i.currency) if i.cost is not none else "—" }}
{{ i.engagement | engagement }} + +{% endfor %} +{% if next_cursor %} + + + +{% endif %} diff --git a/src/estimator/web/templates/estimates/_task_edit_row.html b/src/estimator/web/templates/estimates/_task_edit_row.html new file mode 100644 index 0000000..7ed26a1 --- /dev/null +++ b/src/estimator/web/templates/estimates/_task_edit_row.html @@ -0,0 +1,18 @@ + + {{ t.id }} + {{ t.title }} + {{ t.role | role }} + +
+ + + + + + +
+

Правка создаёт новую версию оценки и пересчитывает стоимость.

+ + diff --git a/src/estimator/web/templates/estimates/_task_row.html b/src/estimator/web/templates/estimates/_task_row.html new file mode 100644 index 0000000..da9f2a4 --- /dev/null +++ b/src/estimator/web/templates/estimates/_task_row.html @@ -0,0 +1,22 @@ + + {{ t.id }} + {{ t.title }} + {% if t.assumptions or t.risks %} +
допущения и риски + {% if t.assumptions %}
    {% for a in t.assumptions %}
  • {{ a }}
  • {% endfor %}
{% endif %} + {% if t.risks %}

Риски:

    {% for x in t.risks %}
  • {{ x }}
  • {% endfor %}
{% endif %} +
+ {% endif %} + + {{ t.role | role }} + {{ t.optimistic | num }} + {{ t.likely | num }} + {{ t.pessimistic | num }} + {{ t.expected | num }} + + {% if editable | default(is_latest) %} + + {% endif %} + + diff --git a/src/estimator/web/templates/estimates/detail.html b/src/estimator/web/templates/estimates/detail.html new file mode 100644 index 0000000..f4df85a --- /dev/null +++ b/src/estimator/web/templates/estimates/detail.html @@ -0,0 +1,6 @@ +{% extends "base.html" %} +{% block title %}Оценка {{ est.id[:8] }}{% endblock %} +{% block content %} +

Оценка {{ est.id[:8] }}

+{% include "estimates/_panel.html" %} +{% endblock %} diff --git a/src/estimator/web/templates/estimates/list.html b/src/estimator/web/templates/estimates/list.html new file mode 100644 index 0000000..6fe79ee --- /dev/null +++ b/src/estimator/web/templates/estimates/list.html @@ -0,0 +1,21 @@ +{% extends "base.html" %} +{% from "components/macros.html" import status_badge %} +{% block title %}История оценок{% endblock %} +{% block content %} +

История

+

+ Все + {% for s in ["done", "needs_input", "running", "pending", "failed"] %} + {{ s | status }} + {% endfor %} +

+
+ + + + {% include "estimates/_rows.html" %} + {% if not items %}{% endif %} + +
СозданаОценкаРегионСтатусВерсияСтоимость
Оценок пока нет. Создать
+
+{% endblock %} diff --git a/src/estimator/web/templates/estimates/new.html b/src/estimator/web/templates/estimates/new.html new file mode 100644 index 0000000..86605c9 --- /dev/null +++ b/src/estimator/web/templates/estimates/new.html @@ -0,0 +1,44 @@ +{% extends "base.html" %} +{% from "components/macros.html" import csrf %} +{% block title %}Новая оценка{% endblock %} +{% block content %} +

Новая оценка

+
+ {{ csrf(csrf_token) }} + + {% if error %}

{{ error }}

{% endif %} + + + + + + +
+{% endblock %} diff --git a/src/estimator/web/templates/login.html b/src/estimator/web/templates/login.html new file mode 100644 index 0000000..05186f4 --- /dev/null +++ b/src/estimator/web/templates/login.html @@ -0,0 +1,20 @@ +{% extends "base.html" %} +{% from "components/macros.html" import csrf %} +{% block title %}Вход · Оценка работ{% endblock %} +{% block content %} +
+

Вход

+ {% if error %}

{{ error }}

{% endif %} +
+ {{ csrf(csrf_token) }} + + + + +
+
+{% endblock %} diff --git a/src/estimator/web/templates/market/index.html b/src/estimator/web/templates/market/index.html new file mode 100644 index 0000000..5d1453a --- /dev/null +++ b/src/estimator/web/templates/market/index.html @@ -0,0 +1,41 @@ +{% extends "base.html" %} +{% block title %}Справочник рынка{% endblock %} +{% block content %} +

Справочник рынка

+

Активная версия: {{ data.version }}, опубликована {{ data.published }}. + {% if versions.versions | length > 1 %}Доступны: {{ versions.versions | join(", ") }}.{% endif %}

+{% if data.note %}

{{ data.note }}

{% endif %} + +

Ставки, в час

+
+ + + + {% for region, card in data.rates.items() %} + {% for role_name, rate in card.hourly.items() %} + + + {% endfor %} + {% endfor %} + +
РегионРольСтавкаОснование
{{ region | region }}{{ role_name | role }}{{ rate | money(card.currency) }}{{ card.basis | basis }}
+
+ +

Ориентиры цен проекта

+
+ + + + {% for region, segments in data.benchmarks.items() %} + {% for seg, b in segments.items() %} + + + {% endfor %} + {% endfor %} + +
РегионСегментОтДо
{{ region | region }}{{ seg | segment }}{{ b.min | money(b.currency) }}{{ b.max | money(b.currency) }}
+
+ +

Коэффициент мультиканальности: первый канал ×{{ data.channel_coefficient.first | num }}, + каждый следующий +{{ (data.channel_coefficient.additional * 100) | round | int }}% к базе (для быстрой оценки, в расчёт по задачам не входит).

+{% endblock %} diff --git a/src/estimator/web/templating.py b/src/estimator/web/templating.py new file mode 100644 index 0000000..bec4d51 --- /dev/null +++ b/src/estimator/web/templating.py @@ -0,0 +1,50 @@ +from pathlib import Path + +from fastapi.templating import Jinja2Templates + +from estimator.config import Settings + +from . import format as fmt + +BASE = Path(__file__).parent +TEMPLATES_DIR = BASE / "templates" +STATIC_DIR = BASE / "static" + + +def build_templates(cfg: Settings) -> Jinja2Templates: + templates = Jinja2Templates(directory=str(TEMPLATES_DIR)) + env = templates.env + env.autoescape = True # LLM-written text is untrusted: never mark it safe + env.filters.update( + money=fmt.money, + hours=fmt.hours, + num=fmt.num, + dt=fmt.make_datetime_filter(cfg.web.timezone), + role=fmt.label(fmt.ROLES), + status=fmt.label(fmt.STATUSES), + step=fmt.label(fmt.STEPS), + source=fmt.label(fmt.SOURCES), + segment=fmt.label(fmt.SEGMENTS), + region=fmt.label(fmt.REGIONS), + basis=fmt.label(fmt.BASES), + engagement=fmt.label(fmt.ENGAGEMENTS), + reserve_basis=fmt.label(fmt.RESERVE_BASIS), + pct=fmt.pct, + verdict_class=fmt.label(fmt.VERDICTS), + ) + env.globals["poll_interval"] = cfg.web.poll_interval_s + # htmx hardening: no eval, no ' +EVIL2 = '">' + + +def test_untrusted_text_is_escaped_everywhere(monkeypatch, dsn): + rows = [(f"{EVIL} Аналитика", Role.ANALYST, 8, 12, 20), *DOC_WBS[1:]] + est = estimate_out(rows) + est.tasks[0].assumptions = [EVIL2] + est.tasks[0].risks = ["risk"] + gw = AutoGateway( + clarify=[clarify_out(summary=f"Сводка {EVIL}")], + decompose=[decompose_out(rows)], + estimate=[est], + ) + with make_ui(monkeypatch, dsn, gw) as c: + login(c) + eid = create_via_ui(c, f"Требования {EVIL}") + html = wait_done(c, eid) + page = c.get(f"/ui/estimates/{eid}").text + for doc in (html, page): + assert EVIL not in doc and EVIL2 not in doc and "risk" not in doc + assert "<script>" in doc + assert "</textarea>" in page # the requirements cannot close their own textarea + history = c.get("/ui/estimates").text + assert EVIL not in history and "