29 KiB
Сервис оценки: веб-интерфейс на 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 режима:
# 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)
[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. Подключение
# 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. Маршрут создания оценки
# 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
<!doctype html>
<html lang="ru">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{% block title %}Оценка работ{% endblock %}</title>
<link rel="stylesheet" href="/ui/static/app.css">
<script src="/ui/static/htmx.min.js" defer></script>
<meta name="csrf-token" content="{{ csrf_token }}">
</head>
<body hx-headers='{"X-CSRF-Token": "{{ csrf_token }}"}'>
<nav>
<a href="/ui/estimates/new">Новая оценка</a>
<a href="/ui/estimates">История</a>
<a href="/ui/market">Рынок</a>
<a href="/ui/calibration">Калибровка</a>
</nav>
<main>{% block content %}{% endblock %}</main>
</body>
</html>
6.4. estimates/new.html
{% extends "base.html" %}
{% block content %}
<form hx-post="/ui/estimates" hx-target="#result" hx-swap="innerHTML">
<label>Описание задачи
<textarea name="requirements" rows="8" required></textarea>
</label>
<label>Регион
<select name="region">
<option value="ru">РФ</option>
<option value="eu">ЕС</option>
</select>
</label>
<label>Валюта
<select name="currency">
<option>RUB</option>
<option>EUR</option>
</select>
</label>
<button type="submit">Рассчитать</button>
</form>
<section id="result"></section>
{% endblock %}
6.5. estimates/_status.html (опрос останавливается сам)
<div id="est-{{ est.id }}"
{% if est.status in ("pending", "running") %}
hx-get="/ui/estimates/{{ est.id }}/status"
hx-trigger="every 2s"
hx-swap="outerHTML"
{% endif %}>
{% if est.status == "done" %}
{% include "estimates/_result.html" %}
{% elif est.status == "needs_input" %}
{% include "estimates/_questions.html" %}
{% elif est.status == "failed" %}
<p class="error">Не удалось выполнить расчёт. Повторите попытку.</p>
{% else %}
<p>Считаю… {{ est.step or "" }}</p>
{% endif %}
</div>
Когда статус становится done, сервер возвращает фрагмент без hx-get и hx-trigger, и опрос прекращается. Если понадобится живой прогресс по шагам, подключается SSE-расширение HTMX, но на старте опроса достаточно.
6.6. CSRF и сессия (эскиз)
# 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/; для калибровки на старте достаточно таблиц |
| Мелкая интерактивность | Нативные <details> и <dialog>, при необходимости 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 в конечных статусах |
| Безопасность | Экранирование: оценка с <script> в допущениях не исполняется и выводится как текст; запрос без CSRF-токена получает 403 |
| In-process клиент | Запуск API через ASGITransport с инициализированными зависимостями |
| Доступ | Один пользователь не видит чужие оценки |
Браузерные тесты (Playwright) добавляются, только если экранов станет много.
10. Ограничения подхода
HTMX хорошо подходит для форм, таблиц, статусов и построчного редактирования. Если понадобится визуальный редактор декомпозиции (WBS) с перетаскиванием и зависимостями, лучше выделить для него точечную Alpine-компоненту или небольшой остров на ванильном JS, по-прежнему без Node. Для текущего набора экранов этого не требуется.
11. План реализации
| Этап | Содержимое | Зависит от |
|---|---|---|
| 1 | Каркас web/: router, статика, base.html, сессия, CSRF, get_api через ASGITransport |
Каркас API и конфига (этап 1 архитектуры) |
| 2 | Справочник рынка (просмотр) | market/repository |
| 3 | Новая оценка + опрос статуса + результат | Асинхронный POST /api/estimates и конвейер агента |
| 4 | Открытые вопросы и пересчёт, правка задач построчно | Эндпоинты answers, tasks, recalculate |
| 5 | История и фильтры | Хранилище оценок |
| 6 | Ввод план/факт и экран калибровки | Модуль calibration |
Этапы 1 и 2 можно делать сразу после каркаса API, ещё без LLM: так проверяются сессия, CSRF и in-process клиент на простых экранах.
12. Открытые вопросы
| Вопрос | Влияет на |
|---|---|
| Кто пользователи UI: только вы, команда или клиенты | Модель аутентификации (сессия, вход через reverse proxy, роли) |
| Нужна ли привязка оценки к пользователю UI, а не только к клиенту API | Схема БД, заголовок «от имени» при вызове API |
| Нужен ли экспорт сметы (PDF, XLSX) из интерфейса | Дополнительные эндпоинты и шаблоны, вывод в КП |
| Нужен ли русско-английский интерфейс | i18n в Jinja (gettext) с первого дня или позже |
| Единый деплой или UI отдельным контейнером | [web] api_base_url, транспорт клиента |
13. Статус реализации и отклонения от проекта
Обновлено: 31 октября 2026.
Реализованы экраны 1–4 из раздела 5 и история: вход, новая оценка, результат со статусом и опросом, открытые вопросы, пересчёт, правка задачи в строке, список с пагинацией и справочник рынка. Не реализованы ввод план/факт и калибровка: их API появится на этапе 7. Экспорт сметы (PDF, XLSX) и двуязычность не делались.
13.1. Что сделано иначе, чем в проекте
| Что | В проекте | Реализовано | Причина |
|---|---|---|---|
| Создание оценки | hx-post и подмена фрагмента |
Обычная форма POST с редиректом 303 на страницу оценки, опрос идёт уже на ней |
Работает и без JavaScript, один путь для всех |
| Вызов API из UI | Один внутренний ключ EST_WEB__INTERNAL_API_KEY |
Случайные токены на процесс, по одному на рабочее пространство, живут только в памяти. Ключ из env нужен только в режиме внешнего API (api_base_url) |
Нечему утекать в конфиг и логи, токен недоступен браузеру |
| Аутентификация | Открытый вопрос | Пользователи в EST_WEB__USERS (имя:хэш), пароли PBKDF2-HMAC-SHA256 (600 000 итераций), хэш создаёт python -m estimator hash-password, подписанная cookie-сессия |
Нет БД пользователей, пароли в открытом виде не хранятся |
| Рабочее пространство | Не описано | workspace = "shared" (все видят общие оценки) или "per_user" |
Команда или изолированные пользователи, переключается конфигом |
| Отзыв сессии | Не описано | Подписанная cookie не отзывается, поэтому пользователь перепроверяется по конфигу на каждом запросе: удалили из EST_WEB__USERS, доступ пропал сразу |
Cookie без серверного хранилища |
| Защита входа | Не описано | Не более login_max_attempts неудач за login_window_s на пару (адрес, пользователь), на адрес в четыре раза больше; одинаковый ответ и одинаковое время для неизвестного пользователя |
Подбор паролей |
| Заголовки | CSP упомянут | default-src 'none'; script-src 'self'; style-src 'self'; frame-ancestors 'none', nosniff, no-store; в шаблонах нет инлайн-скриптов и стилей |
Тест это проверяет |
| htmx | Вендорный файл | 2.0.11 из npm, целостность сверена с реестром, хэш в static/VENDOR.md; в конфиге allowEval=false, allowScriptTags=false, selfRequestsOnly=true; ответы 4xx подставляются в #flash, 5xx нет |
Ужесточение и показ ошибок валидации |
| Сообщения об ошибках | Не описано | Сообщения API переводятся на русский, ошибки 5xx не показываются (общий текст), 404 всегда «Не найдено» | Внутренности не уходят в браузер |
| Время | UTC | [web] timezone, по умолчанию UTC |
Часовой пояс пользователя |
13.2. Найдено при тестировании
- Макрос Jinja, импортированный без контекста, не видел переменную
csrf_token: форма входа отправляла пустой токен. Теперь токен передаётся макросу параметром, тест на CSRF это ловит. - Проверка поведения htmx выполнена в jsdom с настоящим
htmx.min.jsна живом сервере: опрос обновляет панель и останавливается после готовности, строка правки подменяется формой, ошибка валидации попадает в#flash, успешная правка доходит с CSRF-токеном иHX-Redirect. Для jsdom пришлось подменить XPath-выражение, которым htmx ищет атрибутыhx-on:*(в проекте они не используются, в браузерах это работает).
13.3. Не проверено и ограничения
- В настоящем браузере интерфейс не открывался. jsdom не применяет CSP и не умеет переходить по
HX-Redirect, вёрстка и тёмная тема не проверялись глазами. - Ограничитель входа живёт в памяти процесса и сбрасывается при перезапуске. За обратным прокси нужен
uvicorn --proxy-headers, иначе все запросы приходят с адреса прокси. - Сессии нельзя отозвать по одной, только удалением пользователя или сменой
EST_WEB__SESSION_SECRET(разлогинит всех). - Правка строки поддерживается только для последней версии, старые версии показываются без действий.
- В режиме
per_userоценки, созданные через API ботами, в интерфейсе не видны (отдельное пространство клиента).
13.4. Модель оплаты в интерфейсе (31.10.2026)
Подробности в ADR-0001.
- В форме новой оценки поле «Как продаём» (значение по умолчанию из
[pricing] default_engagement). - На странице оценки карточка показывает цену по выбранной модели. Фикс: цена с резервом, отдельно без резерва и сам резерв. T&M: ожидаемая стоимость, потолок бюджета и совет закрепить его в договоре.
- Переключатель «Показать как Time & Materials» и обратно создаёт новую версию без нового расчёта.
- В таблице по ролям добавлена ставка клиента (себестоимость × (1 + управление) × (1 + наценка)), по ней считается T&M.
- Карточка показывает основание резерва (по PERT или минимум), наценку и маржу.
- В истории рядом с суммой указана модель.
13.5. НДС в интерфейсе (31.10.2026)
Подробности в ADR-0002.
- В форме новой оценки поле «НДС»: по региону клиента (РФ 22%, ЕС без НДС), «Без НДС» или ставка из списка конфигурации.
- Все цены на странице без НДС. Под ценой строка «К оплате с НДС X%» с суммой и размером НДС; для T&M отдельно ожидаемая стоимость и потолок.
- На карточке цены селектор ставки: смена создаёт новую версию без нового расчёта.
- Карточка сверки с рынком пишет, что сравнивается цена с резервом без НДС, и помечает ориентиры, приведённые из цен с НДС.