dc-observatio/docs/tasks/TASK_datetime-utc-consistency.md

Задача: единообразие времени (UTC) по всей группе сервисов pcp

Документ-ТЗ для кодинг-агента. Раздел 0 — промпт для запуска (скопировать в агента). Разделы 1–9 — инструкция, которую агент читает в репозитории и которой следует. Стиль работы, границы слоёв и формат финального ответа — по корневому AGENTS.md.

---

0. Промпт для запуска агента (copy-paste)

Ты работаешь в монорепозитории observatio-terrae (pcp).

Задача: провести аудит и привести к единообразию работу со временем (датами) по всей
группе сервисов pcp. Целевое соглашение: ВСЁ ВРЕМЯ — UTC, представление на API не зависит
от часового пояса машины-клиента или сервера.

Перед началом обязательно прочитай:
1. /AGENTS.md — правила работы, стиль, формат финального ответа.
2. /docs/tasks/TASK_datetime-utc-consistency.md — это ТЗ (данный файл).
3. Эталонную реализацию на фронте: services/pcp-tgu-ops-ui/src/utils/utcTime.ts
   и историю правок в pcp-tgu-ops-ui (вкладки «Планы», «Редактор», «Заявки», «Карта 2D»).

Это в первую очередь АУДИТ + точечные правки, а не массовый рефактор. Сначала инвентаризация
(раздел 4), затем фиксы по чек-листу (раздел 5) с приоритетом на места, где сдвиг времени
виден пользователю или уходит на бэкенд при записи. Backend (Kotlin) трогать только там, где
сериализация реально неоднозначна (раздел 6) — сериализационные правки сопровождать тестом.

Не ломай чужие контракты: если меняешь формат на проводе — обнови потребителей и тесты.
После каждого модуля прогоняй его тесты/сборку. В конце дай отчёт по формату из AGENTS.md
плюс заполненную таблицу инвентаризации (раздел 4) и список расхождений.

---

1. Контекст и зачем это

Время в системе хранится и передаётся как UTC, но представление на границах API неоднородно: часть сервисов отдаёт naive LocalDateTime (ISO без зоны, напр. "2026-05-29T01:00:00", по соглашению — UTC), часть — OffsetDateTime/Instant (ISO с зоной, напр. "2026-05-29T01:00:00Z"). Эта разница уже привела к багу во фронте:

• pcp-tgu-service отдаёт планы как naive LocalDateTime.
• Фронт парсил такие строки через new Date(s) / Date.parse(s), а JS трактует строку без зоны как локальное время браузера → сдвиг на офсет (для МСК — +3 ч).
• Одни вкладки показывали через toLocaleString (пояс браузера), другие — в UTC → одно и то же время выглядело по-разному на разных экранах и у разных операторов.
• В пути записи заявки оператор, вводя 01:00, отправлял на бэк 22:00.

Корень — не «UTC против местного», а несогласованность парсинга/форматирования и неоднородность формата на проводе между сервисами. Эта задача делает всё единообразным.

2. Целевое соглашение (canonical)

1. Всё время — UTC. На любом API времена представляют момент в UTC.
2. Формат на проводе — ISO-8601 с явной зоной Z (предпочтительно). Где сервис исторически отдаёт naive LocalDateTime, это допустимо только при железном правиле «naive = UTC», но такой эндпоинт — кандидат на миграцию к Z (раздел 6).
3. Фронт:
   • парсинг строк бэка — только через src/utils/utcTime.ts (parseUtc); никаких «голых» new Date(string) / Date.parse(string);
   • отображение — только UTC (formatUtcDateTime/Date/Time, либо toLocale* с timeZone: "UTC"); никакого toLocaleString без timeZone;
   • <input type="datetime-local"> — значение через toUtcInputValue, чтение обратно через parseUtc; отправка на offset-бэк — через toUtcIso.
4. Никакой неявной локализации под пояс машины ни на фронте, ни в логах/ответах бэка.

3. Эталон (уже сделано — переиспользовать, не переделывать)

В pcp-tgu-ops-ui это соглашение уже внедрено и может служить образцом:

• src/utils/utcTime.ts — parseUtc, formatUtcDateTime/Date/Time, toUtcInputValue, toUtcIso. Единая точка парсинга/форматирования.
• Переведены вкладки «Планы», «Редактор», «Заявки», «Карта 2D» (источник startMs/endMs в tguTimelineMapper, пикеры диапазона, детали заявок, путь создания заявки).
• Нюанс: pcp-request-service отдаёт OffsetDateTime (строки с Z) — parseUtc их тоже корректно обрабатывает (зона есть → не добавляет Z), а запись идёт через toUtcIso.

Любой новый код во фронте обязан следовать этому слою.

4. Инвентаризация (заполнить в отчёте)

Стартовый срез (тип LocalDateTime vs OffsetDateTime/ZonedDateTime/Instant в файлах dto|controller|api|response|model); агент должен уточнить и довести до пер-эндпоинтной картины «что именно отдаётся наружу»:

Сервис	Преобладает на границе API	Действие
pcp-tgu-service	naive LocalDateTime	задокументировать «=UTC», кандидат на Z
pcp-request-service	OffsetDateTime (Z)	эталон, проверить полноту
pcp-dynamic-plan-service	naive LocalDateTime (+1 offset-файл)	проверить смешение
pcp-complex-mission-service	naive LocalDateTime (+2 offset)	проверить смешение
pcp-ui-service	naive LocalDateTime (+1 offset)	проверить (агрегатор/BFF?)
slots-service	naive LocalDateTime	задокументировать «=UTC»
pcp-coverage-scheme-service	naive LocalDateTime	задокументировать «=UTC»
pcp-ballistics-service	naive LocalDateTime	задокументировать «=UTC»
pcp-mission-planing-service	naive LocalDateTime	задокументировать «=UTC»
pcp-route-processing-service	нет времени на границе (проверить)	—
pcp-satellite-catalog-service	нет (проверить)	—
pcp-stations-service	нет (проверить)	—
tle-monitoring-service	нет (проверить)	—

Колонки итоговой таблицы: сервис · эндпоинт/поле · тип · формат на проводе (пример) · naive? · потребители · вердикт (ok / задокументировать / мигрировать на Z).

Полезно: во всех проверенных сервисах Jackson настроен с JavaTimeModule и disable(WRITE_DATES_AS_TIMESTAMPS) → времена сериализуются как ISO-строки (не числа), поэтому LocalDateTime уходит без зоны, OffsetDateTime/Instant — с Z/офсетом.

5. Фронт: инвариант и фиксы (pcp-tgu-ops-ui)

Эталон внедрён, но нужно закрепить как инвариант и проверить, что ничего не утекло:

1. Найти нарушителей (раздел 7, паттерн A). Любой «голый» разбор/формат строки времени бэка чинить через utils/utcTime.
2. Добавить защиту от регрессий — на выбор:
   • юнит-тест-«страж», который грепает src/ и падает на запрещённых паттернах (new Date(<string>), Date.parse(, toLocaleString( без timeZone, formatDateTimeLocal); или
   • ESLint-правило (no-restricted-syntax) с тем же смыслом.
3. Прогнать npm run test и npm run build в модуле.

6. Backend: когда и что править

По умолчанию — не менять формат на проводе (это контракт). Действия:

1. Документировать инвариант. Для сервисов с naive LocalDateTime: явно зафиксировать «все времена на API — UTC» (KDoc у DTO + запись в docs/standards, раздел 8). Это дёшево и безопасно, и снимает неоднозначность для будущих клиентов.
2. Чинить реальные баги. Если найдётся место, где сервис:
   • кладёт в naive-поле локальное время сервера (LocalDateTime.now() вместо LocalDateTime.now(ZoneOffset.UTC) / Instant.now()), или
   • конвертирует под зону JVM при чтении/записи — это баг: исправить на UTC, добавить тест.
3. Миграция к явному Z (опционально, по согласованию). Перевод naive LocalDateTime на OffsetDateTime/Instant (UTC) на границе — самый чистый итог, но это смена контракта: делать только с обновлением потребителей (на фронте parseUtc уже совместим с обоими) и сериализационным тестом. Оформить как отдельные under-задачи per-service, не «большим взрывом».
4. Тест формата. Для каждого сервиса, отдающего время, иметь тест, фиксирующий формат на проводе (есть Z / нет зоны) — чтобы контракт не «уехал» молча.

7. Как искать нарушителей (детект-паттерны)

A. Фронт (services/pcp-tgu-ops-ui/src), запрещено вне utils/utcTime.ts:

# разбор строки как локального времени
grep -rn "new Date([a-zA-Z].*)\.getTime\|Date\.parse(" src --include=*.ts --include=*.tsx | grep -v utcTime
# показ в поясе браузера
grep -rn "toLocaleString\|toLocaleDateString\|toLocaleTimeString" src --include=*.ts --include=*.tsx | grep -v 'timeZone: "UTC"'
# локальные хелперы пикеров
grep -rn "formatDateTimeLocal" src
# локальные компоненты даты
grep -rn "getFullYear()\|getMonth()\|getDate()\|getHours()\|getMinutes()" src --include=*.ts --include=*.tsx | grep -v getUTC

B. Backend (Kotlin) — потенциально локальное «сейчас» в UTC-полях:

# now() без UTC-зоны
grep -rn "LocalDateTime\.now()\|LocalDate\.now()\|LocalTime\.now()" services/*/src/main
# конвертации под зону системы
grep -rn "atZone(\|ZoneId\.systemDefault\|toLocalDateTime()\|systemDefault()" services/*/src/main
# типы времени на границе (для инвентаризации)
grep -rn "LocalDateTime\|OffsetDateTime\|ZonedDateTime\|Instant" services/*/src/main | grep -iE "dto|controller|response"

Каждое попадание классифицировать: ок / задокументировать / починить / мигрировать.

8. Зафиксировать стандарт

Создать docs/standards/DATETIME_UTC.md (на него ссылаться из KDoc/комментариев):

• соглашение из раздела 2 (всё UTC; формат на проводе; правила фронта);
• таблица состояния сервисов (итог раздела 4);
• правило для нового кода: фронт — только utils/utcTime; бэк — UTC-now, предпочтительно Z на новых API.

При наличии общего чек-листа в docs/standards/CHECKLIST.md — добавить пункт «Время на API — UTC; фронт парсит/форматирует через utcTime».

9. Definition of Done

• Заполнена пер-эндпоинтная таблица инвентаризации (раздел 4) по всем 13 сервисам.
• Фронт: нарушителей по паттернам раздела 7A не осталось; добавлена защита от регрессий (тест-страж или ESLint-правило); npm run test и npm run build зелёные.
• Backend: задокументирован инвариант «API = UTC» у сервисов с naive LocalDateTime; найденные реальные баги локального now/конвертаций исправлены с тестами.
• Создан docs/standards/DATETIME_UTC.md; обновлён CHECKLIST.md (если есть).
• Список расхождений и предложенные under-задачи на миграцию к Z (если такие нужны) приведены в финальном отчёте (формат — AGENTS.md).

Не делать

• Массовую смену формата на проводе без обновления потребителей и тестов.
• Изменение семантики хранения в БД (там уже UTC) — только представление/парсинг.
• Локализацию под пояс машины «чтобы было привычнее» — это и есть источник проблемы.