Files
estimator/docs/estimator-web-ui.md
2026-11-09 08:43:30 +03:00

30 KiB
Raw Permalink Blame History

Сервис оценки: веб-интерфейс на 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 отдельно ожидаемая стоимость и потолок.
  • На карточке цены селектор ставки: смена создаёт новую версию без нового расчёта.
  • Карточка сверки с рынком пишет, что сравнивается цена с резервом без НДС, и помечает ориентиры, приведённые из цен с НДС.

13.6. Автор, предварительная оценка, аналоги (2.11.2026)

  • В строке состояния оценки указаны автор оценки и автор каждой версии; в истории колонка «Автор» (кто начал оценку).
  • Оценка, построенная на допущениях по неуточнённым вопросам, получает жёлтую плашку «Предварительная оценка» с перечнем допущений, а в истории пометку «предварительная».
  • Под задачей в раскрывающемся блоке «Аналоги из истории»: похожие прошлые задачи с часами, видом (факт или оценка), проектом и сходством. Блок виден только при включённом RAG (ADR-0003). Тексты аналогов экранируются.
  • Токены, которыми интерфейс обращается к API внутри процесса, теперь выдаются на каждого пользователя, чтобы в журнале версий был виден человек.