baton/docs/ux_spec.md

# UX Specification: Baton PWA

**Версия:** 1.0
**Дата:** 2026-03-20
**Статус:** Ready for Frontend

---

## Обзор

Baton — PWA экстренного сигнала. Два ключевых экрана:

1. **Registration** — одноразовый экран при первом запуске: пользователь вводит имя для идентификации в Telegram-уведомлениях.
2. **Main** — постоянный рабочий экран: одна большая кнопка вызова.

Интерфейс должен быть интуитивно понятен без знания языка — см. раздел «Методология usability-тестирования».

---

## Wire-frames

### Экран: Registration

```
+--------------------------------------------------+
| [U]                                    [WiFi]   |
|                                                  |
|                                                  |
|                                                  |
|            +---------------------------+         |
|            |   Введите ваше имя        |         |
|            +---------------------------+         |
|                                                  |
|            +---------------------------+         |
|            |      Подтвердить          |         |
|            +---------------------------+         |
|                                                  |
|                                                  |
+--------------------------------------------------+

Элементы:
  [U]    — иконка пользователя, верхний левый угол
  [WiFi] — иконка wi-fi соединения, верхний правый угол
  [ Введите ваше имя ] — однострочное поле ввода, центр экрана
  [ Подтвердить ]      — кнопка подтверждения, под полем ввода
```

---

### Экран: Main

```
+--------------------------------------------------+
| [U]                                    [WiFi]   |
|                                                  |
|                                                  |
|    +----------------------------------------+   |
|    |                                        |   |
|    |                                        |   |
|    |                                        |   |
|    |               ВЫЗОВ                   |   |
|    |                                        |   |
|    |            ( >= 60vmin )               |   |
|    |                                        |   |
|    |                                        |   |
|    +----------------------------------------+   |
|                                                  |
+--------------------------------------------------+

Элементы:
  [U]    — иконка пользователя, верхний левый угол
  [WiFi] — иконка wi-fi соединения, верхний правый угол
  ( ВЫЗОВ ) — кнопка вызова, центр экрана,
              минимальный размер: 60vmin × 60vmin
              (занимает большую часть рабочей области)
```

---

## Поведение элементов

### Иконка [U] (пользователь)

- Отображает инициалы или иконку профиля текущего пользователя
- Tap → открыть информацию о текущем пользователе (v2)
- В v1: не интерактивна, только индикатор

### Иконка [WiFi]

- Показывает статус сети: полный сигнал / нет соединения
- Обновляется по `navigator.onLine` события
- Цвет: зелёный (online) / серый (offline)

### Поле ввода имени (Registration)

- Placeholder: «Введите ваше имя»
- Максимум 100 символов
- Обязательное поле: кнопка «Подтвердить» неактивна при пустом поле
- После подтверждения: имя сохраняется через `POST /api/register`

### Кнопка «Подтвердить» (Registration)

- Неактивна (disabled) при пустом поле ввода
- Активна при наличии хотя бы одного символа
- Tap → `POST /api/register` → переход на экран Main

### Кнопка «ВЫЗОВ» (Main)

- Размер: минимум 60vmin × 60vmin
- Форма: круг или скруглённый прямоугольник
- Tap → `POST /api/signal` с геолокацией (если разрешена)
- Состояния:
  - Default: красный / яркий
  - Pressed: тёмнее, scale(0.96)
  - Sending: spinner или пульсация
  - Success: краткая зелёная анимация (≤1 сек)
  - Error: встроенное сообщение «Нет подключения» (при offline)

---

## Методология usability-тестирования

**Обязательный критерий QA-фазы** (decision #1035).

### Параметры теста

| Параметр | Значение |
|---------|---------|
| Тестировщики | 3 человека |
| Знание языка интерфейса | Отсутствует (не знают язык UI) |
| Попыток | 1 (первая и единственная) |
| Подсказки | Запрещены |

### Ключевой сценарий

1. Открыть приложение (экран Registration)
2. Ввести своё имя в форму
3. Нажать кнопку подтверждения
4. На экране Main — нажать кнопку вызова
5. Дождаться подтверждения отправки

### Критерий прохождения

Все 3 тестировщика завершают сценарий с первой попытки без подсказок.

### Критерий провала (блокирующий дефект)

Хотя бы один тестировщик из трёх:
- Не нашёл поле ввода имени
- Не понял, как подтвердить ввод
- Не нашёл кнопку вызова на главном экране
- Не понял, что сигнал отправлен (нет обратной связи)

При провале: UI-дизайн возвращается на доработку. Выпуск Frontend не разрешён.

### Проведение теста

- Тестировщики тестируют независимо, не наблюдая за другими
- Засекается время прохождения каждого шага
- Фиксируются: колебания, ошибочные нажатия, паузы > 3 сек

---

## Константы дизайна

| Параметр | Значение |
|---------|---------|
| Кнопка вызова min-size | 60vmin × 60vmin |
| Цвет кнопки вызова | #FF0000 (или близкий красный) |
| Фон приложения | #000000 |
| Тема | `theme_color: #ff0000` (из manifest.json) |

---

## Связанные документы

- `docs/tech_report.md` — технический отчёт, PWA-ограничения, auth
- `docs/backend_spec.md` — API контракты `/api/register`, `/api/signal`
- `docs/adr/ADR-003-auth-pattern.md` — UUID stateless auth