hado/docs/design/2026-09-04-inbox-functional.md

# Hado · веб-инбокс — функциональное описание для дизайна

Что есть на экранах и что делает каждый элемент. Без визуальных требований:
размеры, цвета, сетка, стиль — на стороне дизайна.

## Контекст

Hado — сервис напоминаний. Другие сервисы (документы, люди, оплаты) присылают ему
события со сроком, Hado сам решает, когда и куда напомнить: сюда в инбокс, в Telegram,
в умный дом. Веб-инбокс — единственный экран Hado. Пользователь попадает в него уже
залогиненным через общий вход экосистемы, своей формы логина здесь нет.

Два действия над событием, они принципиально разные и должны читаться по-разному:

- **«Помню»** — «я в курсе, отстань до следующей контрольной точки». Событие остаётся,
  счётчик не меняется. Напоминание вернётся само: в день события через час, до события
  на следующей контрольной точке, после события через день.
- **«Сделано»** — «закрыл вопрос». Событие уходит с экрана навсегда, счётчик падает.
  Подпись кнопки может задавать сервис-источник: «Поздравил», «Оплатил», «Продлил».
  По умолчанию «Сделано».

## Понятия

| термин | что это |
|---|---|
| Событие | одна штука со сроком: ДР Васи, седула протухает 30 сен, вылет 10 сен 08:15 |
| Срок | день события, иногда с конкретным временем |
| Источник | сервис, который прислал событие (`docs`, `people`). Показывается как подпись |
| Счётчик | число событий в группах «Сегодня» и «Просрочено». Это же число потом будет бейджем на иконке iOS |
| Ссылка в источник | у события может быть ссылка на объект в сервисе-источнике (карточка человека, документ) |

## Экран 1. Инбокс (главная и единственная страница)

### Шапка
- Название «Hado».
- Счётчик: число событий «Сегодня» + «Просрочено». Если ноль — не показывается.
- Заголовок вкладки браузера дублирует счётчик: «(3) Hado», чтобы видеть его в списке вкладок.

### Группы событий
Четыре группы, всегда в этом порядке. Пустая группа показывает подпись «Пусто»
(или скрывается — решение дизайна, но порядок остальных не меняется).

1. **Сегодня** — срок сегодня, время ещё не наступило. Самое важное, наверху.
2. **Просрочено** — срок прошёл, но событие всё ещё надо сделать (седула истекла,
   аренда не оплачена). Висит, пока не нажмёшь «Сделано».
3. **Грядёт** — идёт подготовка, срок через дни или недели. В счётчик не входит.
4. **Запланировано** — Hado про событие знает, но ещё молчит. В счётчик не входит.

Внутри группы события отсортированы по сроку, ближайший первым.

### Карточка события
- **Заголовок** — текст от источника («Сегодня ДР — Вася»). Если у события есть ссылка
  в источник, заголовок — ссылка, открывает объект в сервисе-источнике (в той же вкладке
  или новой — решение дизайна).
- **Подзаголовок** — вторая строка от источника, опциональная («исполняется 34»,
  «осталось 30 дней»).
- **Служебная строка** — имя источника и срок: «docs · срок 2026-09-30». Если срок с
  временем — «2026-09-10 08:15».
- **Кнопка «Помню»** — есть во всех группах, кроме «Запланировано» (там напоминаний
  ещё нет, «помнить» нечего). После нажатия карточка остаётся на месте, ничего
  визуально не должно намекать, что событие закрыто.
- **Кнопка «Сделано»** — есть везде, включая «Запланировано» (закрыть можно заранее,
  хоть за два месяца). Подпись берётся у источника, если он её задал. После нажатия
  карточка исчезает, счётчик уменьшается, если событие было в «Сегодня» или «Просрочено».

Нажатие любой кнопки: кнопка блокируется до ответа сервера, затем список обновляется.
При ошибке кнопка разблокируется, карточка остаётся.

### Блок «Настройки»
Свёрнут по умолчанию, раскрывается на той же странице. В заголовке блока — логин
пользователя.

**Пояс и тихие часы**
- Выбор часового пояса из полного списка (IANA: `America/Montevideo`, `Asia/Shanghai`).
  Пользователь много переезжает и меняет пояс руками; все напоминания сдвигаются под него.
- Тихие часы: «с» и «до». По умолчанию с 22:00 до 09:00. В тихие часы Hado молчит во
  всех каналах. Ограничение: интервал обязан переходить через полночь («с 22:00 до
  09:00» верно, «с 08:00 до 22:00» — ошибка, показать сообщение).
- Кнопка «Сохранить». После сохранения страница обновляется.

**Каналы** — куда Hado доставляет напоминания. Список:
- **Веб** — этот инбокс. Есть всегда, удалить нельзя, кнопки удаления нет. Подпись
  «этот инбокс».
- **Telegram** — подпись с идентификатором чата. Появляется после привязки (ниже).
  Кнопка «Удалить».
- **Webhook** — адрес, куда Hado шлёт напоминание (в жизни это умный дом). Подпись —
  сам адрес. Кнопка «Удалить». Таких может быть несколько.

**Добавить webhook** — форма из двух полей и кнопки:
- «Адрес доставки» — куда Hado отправит напоминание.
- «Адрес присутствия» — откуда Hado спросит «пользователь сейчас дома/рядом?».
- Кнопка «Добавить webhook». Оба поля обязательны, должны быть URL. Ошибки валидации
  показываются у формы.

**Подключить Telegram** — кнопка. По нажатию появляется одноразовый код и ссылка на
бота: «Отправь боту `/start ABC123` или открой». Код живёт 15 минут. После того как
пользователь отправит код боту, канал Telegram появится в списке (при следующем
открытии страницы).

### Поведение страницы, невидимое пользователю
- Пока вкладка открыта, видима и пользователь что-то делал за последние 3 минуты,
  страница сообщает серверу «я тут». Hado тогда не дёргает Telegram и умный дом:
  напоминание считается доставленным в инбокс. Забытая фоновая вкладка «я тут» не
  сообщает.
- Никаких всплывающих уведомлений и звуков в самом инбоксе нет: он пассивный экран.
  Активные каналы — Telegram и умный дом, потом iOS.

## Экран 0. Нет доступа
Если пользователь пришёл не через общий вход экосистемы, страница не открывается
(ответ 401). Своей заглушки у Hado нет: общий вход сам перебросит на форму логина.
Дизайнить здесь нечего, упомянуто для полноты.

## Вне веба, но для консистентности

**Сообщение в Telegram** — текст: заголовок и подзаголовок события. Под ним две кнопки:
«Помню» и «Сделано» (или подпись источника). После «Сделано» кнопки под сообщением
убираются. Каждое новое напоминание — новое сообщение, старые не редактируются.
Ответы бота на нажатия: «Ок, напомню позже», «Закрыто», «Уже неактуально».

**Умный дом (webhook)** получает те же поля: заголовок, подзаголовок, источник, срок,
подпись кнопки «Сделано» и две ссылки-действия. Как это озвучивается или показывается —
на стороне умного дома.

## Добавлено по дизайну (хендофф 2026-09-04, `handoff/`)

**Кнопка «+ Добавить»** в шапке раскрывает форму «Новое событие» над группами:
заголовок (обязателен), подзаголовок, срок (обязателен), время. «Создать» кладёт
событие в группу по дате: прошла → Просрочено, сегодня → Сегодня, в пределах
30 дней → Грядёт, дальше → Запланировано. Источник подписывается «вручную», кнопка
закрытия — «Сделано». «Отмена» сворачивает форму. Ошибки валидации под формой.

**Архив** — сворачиваемый блок над настройками, в заголовке «N закрыто». Строки:
заголовок, источник и срок, ярлык закрытия (подпись кнопки, которой закрыли, или
«Истекло», если срок прошёл сам). Только чтение, действий нет. Глубина — 90 дней.

## Чего здесь нет намеренно
- Откладывания «на дату»: этим занимается правило «Помню».
- Настройки частоты напоминаний: она общая и не настраивается.
- Мобильного приложения: iOS с бейджем, виджетом «Грядёт» и Live Activity — отдельный
  проект, его описание будет отдельно.