Init Project Flexly Estimator

This commit is contained in:
Alexey Dudin
2026-11-03 09:37:44 +03:00
commit 447464c16c
160 changed files with 12779 additions and 0 deletions
+410
View File
@@ -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
<!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 отдельно ожидаемая стоимость и потолок.
- На карточке цены селектор ставки: смена создаёт новую версию без нового расчёта.
- Карточка сверки с рынком пишет, что сравнивается цена с резервом без НДС, и помечает ориентиры, приведённые из цен с НДС.