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

418 lines
30 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Сервис оценки: веб-интерфейс на 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
<!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`
```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` (опрос останавливается сам)
```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 и сессия (эскиз)
```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/`; для калибровки на старте достаточно таблиц |
| Мелкая интерактивность | Нативные `<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](adr/0001-reserve-policy-and-engagement.md).
- В форме новой оценки поле «Как продаём» (значение по умолчанию из `[pricing] default_engagement`).
- На странице оценки карточка показывает цену по выбранной модели. Фикс: цена с резервом, отдельно без резерва и сам резерв. T&M: ожидаемая стоимость, потолок бюджета и совет закрепить его в договоре.
- Переключатель «Показать как Time & Materials» и обратно создаёт новую версию без нового расчёта.
- В таблице по ролям добавлена ставка клиента (себестоимость × (1 + управление) × (1 + наценка)), по ней считается T&M.
- Карточка показывает основание резерва (по PERT или минимум), наценку и маржу.
- В истории рядом с суммой указана модель.
### 13.5. НДС в интерфейсе (31.10.2026)
Подробности в [ADR-0002](adr/0002-vat-layer.md).
- В форме новой оценки поле «НДС»: по региону клиента (РФ 22%, ЕС без НДС), «Без НДС» или ставка из списка конфигурации.
- Все цены на странице без НДС. Под ценой строка «К оплате с НДС X%» с суммой и размером НДС; для T&M отдельно ожидаемая стоимость и потолок.
- На карточке цены селектор ставки: смена создаёт новую версию без нового расчёта.
- Карточка сверки с рынком пишет, что сравнивается цена с резервом без НДС, и помечает ориентиры, приведённые из цен с НДС.
### 13.6. Автор, предварительная оценка, аналоги (2.11.2026)
- В строке состояния оценки указаны автор оценки и автор каждой версии; в истории колонка «Автор» (кто начал оценку).
- Оценка, построенная на допущениях по неуточнённым вопросам, получает жёлтую плашку «Предварительная оценка» с перечнем допущений, а в истории пометку «предварительная».
- Под задачей в раскрывающемся блоке «Аналоги из истории»: похожие прошлые задачи с часами, видом (факт или оценка), проектом и сходством. Блок виден только при включённом RAG ([ADR-0003](adr/0003-rag-reference-tasks.md)). Тексты аналогов экранируются.
- Токены, которыми интерфейс обращается к API внутри процесса, теперь выдаются на каждого пользователя, чтобы в журнале версий был виден человек.