healthlog/openspec/specs/read-api/spec.md

# read-api Specification

## Purpose

Общие правила читающих маршрутов — то, что у каталога, точек, тренировок,
записей, статистики и MCP одинаково и потому не должно решаться каждым заново.
Форма конкретного ответа принадлежит capability самого маршрута; здесь — правила
поверх них.

Первое и главное: **публичный контракт объявляет транспорт.** Форма ответа не
выводится из формы доменных типов, поэтому её смена есть правка транспортного
слоя — действие, а не побочный эффект переименования поля в домене. Цена
названа и она обратная: новое поле домена в ответ само не попадёт.

## Requirements
### Requirement: Публичный контракт читающего маршрута меняется только правкой транспорта

Система SHALL объявлять форму ответа каждого читающего маршрута типами
транспортного слоя и MUST NOT выводить её из формы доменных типов: ни один тип
домена MUST NOT достигать сериализации ответа, а перевод домена в форму провода
MUST быть явным перечислением полей.

**Читающий маршрут** здесь — тот, что отдаёт наружу состояние витрины: каталог,
точки, тренировки, записи, статистика. `/healthz` под правило не подпадает —
его тело есть литеральный признак живости процесса, а не данные.

**MCP собственной формы провода не объявляет.** Адаптер переводит вызовы в те
же обработчики (`docs/architecture.md`, раздел «MCP»), поэтому объявленная форма
у контракта одна на оба транспорта. Второе объявление развело бы их молча.

Правило распространяется и на **тело отказа**: у читающего маршрута оно часть
того же контракта, и клиент видит его чаще успешного ответа. Тело отказа MUST
собираться объявленным типом транспорта, а не картой и не свободной строкой.

**Следствие, ради которого правило и существует:** переименование поля
доменного типа, разъединение встроенной в него структуры и появление в нём
нового поля байты ответа не меняют — до сериализации доменный тип не доезжает.
Смена публичного контракта становится правкой транспортного слоя, то есть
действием, а не побочным эффектом.

**Цена названа и взята сознательно, потому что она обратная.** Новое поле
домена не попадает в ответ само: чтобы клиент его увидел, транспорт обязан его
перечислить. Контракт перестаёт меняться случайно в обе стороны, и это дороже
ровно на объём перевода.

Из правила есть одно исключение, и оно ограничено **содержимым**, а не
конвертом: значение, которое хранилище держит дословно, уезжает клиенту сырым
JSON без разбора и переобъявления — переписывать его в тип провода значило бы
нарушить инвариант «точки хранятся дословно». Конверт вокруг такого значения —
метки времени, офсет, единицы, слой — объявляется типом провода и нормализуется,
как того требует инвариант «форма Apple не транслируется».

#### Scenario: Поле доменного типа переименовано

- **GIVEN** поле доменного типа, из которого собирается ответ, переименовано, а
  транспортный слой не тронут
- **WHEN** маршрут отвечает на прежний запрос при прежнем состоянии витрины
- **THEN** байты ответа те же

#### Scenario: Форма провода изменена намеренно

- **GIVEN** транспорт переименовал поле объявленной формы
- **WHEN** маршрут отвечает на прежний запрос при прежнем состоянии витрины
- **THEN** байты ответа изменились, и изменение целиком лежит в правке
  транспортного слоя

#### Scenario: Читающий маршрут отвечает отказом

- **WHEN** читающий маршрут отвечает кодом отказа
- **THEN** тело отказа собрано объявленным типом транспорта

#### Scenario: Словарь значения виден клиенту строкой

- **GIVEN** доменное перечисление, чьи значения клиент видит строками
- **WHEN** маршрут отвечает
- **THEN** строку в ответ кладёт транспорт, а домен собственной сериализации не
  несёт

#### Scenario: Дословное содержимое проходит насквозь

- **WHEN** в ответ идёт значение, сохранённое хранилищем дословно
- **THEN** оно уезжает сырым JSON, а конверт вокруг него объявлен типом провода

### Requirement: Пустая коллекция чтения — список, а не отсутствие

Система SHALL отдавать пустую коллекцию читающего маршрута как `[]` и MUST NOT
отдавать её как `null`; отсутствующее значение MUST отдаваться как `null` и
MUST NOT подменяться нулевым значением своего типа.

Правило общее для всех читающих маршрутов, потому что цена у него одна:
`nil`-срез сериализуется в `null`, и клиент читает «поля нет» там, где на самом
деле «элементов нет»; правдоподобная нулевая дата в ответе неотличима от
настоящей. Конкретные коллекции и поля каждого маршрута нормирует его
собственная capability — здесь только правило, чтобы следующий маршрут не
принимал его заново.

Ручной перевод домена в форму провода делает это правило не теоретическим:
присваивание поле в поле копирует `nil` и разыменовывает указатель ровно так,
как написано, и обе ошибки молчат.

#### Scenario: Коллекция ответа пуста

- **WHEN** в ответ читающего маршрута идёт коллекция без единого элемента
- **THEN** она уезжает как `[]`

#### Scenario: Значения нет

- **WHEN** поле ответа не имеет значения
- **THEN** оно уезжает как `null`, а не как нулевая метка времени, пустая
  строка или ноль

### Requirement: Сериализация ответа чтения не экранирует содержимое

Система SHALL сериализовать тела ответов читающих маршрутов **без экранирования
HTML-символов**: `&`, `<` и `>` внутри значений MUST уезжать клиенту как есть и
MUST NOT подменяться escape-последовательностями `&`, `<`, `>`.

Правило общее для всех читающих маршрутов, а не частное для точек, потому что
общим является механизм: тело собирает один помощник сериализации, и умолчание
`encoding/json` экранирует эти три символа молча. На маршруте, отдающем
**дословно сохранённое** содержимое, это прямо ломает обещание дословности:
имя источника приходит с телефона пользовательской строкой и законно содержит
`&`. Хранилище этот же капкан уже проходило и обезвредило тем же способом —
кодировщик с выключенным экранированием вместо `json.Marshal`.

Проверка обязана стоять на содержимом, реально несущем эти символы: набор
фикстур, в котором их нет, зелен и будучи сломанным.

#### Scenario: Значение несёт символ, который сериализатор склонен экранировать

- **GIVEN** значение ответа читающего маршрута, содержащее `&`, `<` или `>`
- **WHEN** маршрут отвечает
- **THEN** эти символы присутствуют в теле ответа как есть

### Requirement: Ответ чтения непригоден для разделяемого кеша

Система SHALL помечать ответы читающих маршрутов заголовком
`Cache-Control: private, no-cache`.

Правило общее, потому что цена у него одна на все маршруты чтения: с появлением
валидатора ответ становится штатно кешируемым, а при выключенной проверке
токенов — законной конфигурации для доверенной локальной сети — в запросе нет и
`Authorization`. Тогда выгрузку истории здоровья вправе сохранить любой прокси
на пути. Маршрут, решающий это заново, однажды решит иначе.

#### Scenario: Читающий маршрут ответил

- **WHEN** читающий маршрут отдаёт тело
- **THEN** ответ несёт `Cache-Control: private, no-cache`