# Сервис оценки: веб-интерфейс на 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` в конечных статусах | | Безопасность | Экранирование: оценка с `