Руководство работы с датами

Работа с Датой и Временем

❖ Используемый формат Даты и Времени

Дата и Время всегда Вводятся и ВЫводятся в фиксированном формате:

DD.MM.YYYY HH:mm:ss

где:
● DD — день
● MM — месяц
● YYYY — год (4 цифры)
● HH — часы
● mm — минуты
● ss — секунды

Например:
● «01.01.2020 00:00:01» — новый 2020 год
● «17.05.2020 19:45:05» — вот более однозначный пример формата выводимого времени.

❖ Переменные Даты и Времени

Для хранения Даты/Времени добавлен специальный тип переменных:

«📕 Время».

Чисто технически, Время можно сохранять и в Текстовых Переменных, но полноценно работать с такими переменными у вас не получится. В Текстовой переменной Время можно только хранить, но не выполнять с ним каких-либо действий.

Синтаксис в сообщениях

В Сообщениях бота — Вывод Даты/Времени осуществляется как обычно — через макрос той переменной, в которой оно сохранено.

Синтаксис в выражениях

В Выражениях Функций Времени, при использовании переменных хранящих Время — макросы этих переменных ДОЛЖНЫ браться «в кавычки», так как, по сути, они являются текстом.

Синтаксис параметра в функции

Пример записи переменной «date1» в выражениях ФУНКЦИЙ ВРЕМЕНИ: {dt_passed("%date1%")}.

Само выражение, естественно, в {фигурных скобках}.
Подробнее о выражениях — в руководстве по выражениям.

Синтаксис функции

При передаче значения одной функции в другую, даже если значение будет текстом, саму функцию в кавычки брать НЕ НУЖНО (смысл этого пункта вам станет ясен позднее) например:
{dt_passed(dt_now()...)}
В примере функция dt_now() передана в качестве параметра функции dt_passed() — кавычки не нужны. Вы поймете этот пример, когда ниже причитаете про функции.

Ещё раз: в общем случае, при использовании «Переменных Времени» в Выражениях «Функций Времени» ВСЕГДА берите их макрос «в кавычки»! Иначе ничего не будет работать.

Примеры:
● Сообщение: «Вы нажали кнопку в %date1%«.
(Покажет время сохраненное в переменной «date1«)
● Выражение: {dt_add("%date1%", 1)}
(Покажет время сохраненное в переменной «date1» плюс 1 час)

❖ Базовые функции для работы с Датой и Временем

ВСЯ(!) реальная работа с датами происходит ТОЛЬКО через специальные Функции (Кроме случаев, когда Дату/Время нужно просто отобразить в сообщении). Базовых Функций всего 3:

dt_now() — Текущее Время

dt_now() Текущее время — функция получения «сейчас», то есть текущей Даты и Времени. Нужна, чтобы можно было от «сейчас» отсчитывать время, сравнивать его и т.д.

Возвращает значение типа «Дата/Время».

Функция имеет практический смысл в Выражениях в комбинации с другими функциями или значениями переменных.

Та же результат данной функции можно использовать, чтобы сохранить в переменную текущее время (например, время в момент нажатия кнопки). В дальнейшем такую запись можно использовать как «отсечку» для расчетов времени, прошедшего с этого момента.

Примеры:
{dt_now()}
Если использовано в Сообщении — выведет текущую дату и время (БЕЗ учета часового пояса) в момент показа юзеру. Если использовано в Выражении кнопки или в Action-е — то текущая дата (на момент срабатывания) может быть записана в переменную.

Концепция времени данной функции схожа с концепцией времени Python или PHP. То есть это некое единое стандартизированное время (которое можно выразить в минутах, часах, днях, неделях, месяцах или годах) предназначенное для относительных вычислений временнЫх отрезков, основанных на метках времени, которые вы сами записываете в переменные и используете для вычислений прошедшего или оставшегося времени до или после какого-либо события. В случае привязки этого времени к часовым поясам, временнЫе отрезки могут сбиваться при изменении часового пояса в боте, что может приводить к не предсказуемым — чаще неприятным последствиям (например сползание сроков инвестов или времени получения бонусов, искажение условий кнопок, основанных на времени и т.д.).

dt_add() — Добавить Время

dt_add(date, hours) Добавить время — функция получения даты, отличающейся от «date» на «hours» часов. Другими словами, некая «date» плюс сколько-то «hours«.

Возвращает значение типа «Дата/Время».

Функция принимает (требует для работы) два параметра:
● date — та дата, от которой происходит отсчет времени.
Обычно к моменту использования она уже сохранена в какой-либо Переменной Времени (в этом случае используйте макрос той переменной в кавычках), однако это может быть и Текущее Время из функции «dt_now()»).
● hours — это количество часов, на которое нужно изменить дату — часы задаются дробным числом (например, 0.5 часов — это 30 минут и т.д.). Данный параметр может быть не только жестко задан при помощи конкретного числа, но может быть представлен и значением Числовой Переменной — в этом случае используйте макрос этой перемеренной (без кавычек).

Часы могут быть отрицательными (если дату надо уменьшить), в этом случае вычисление времени осуществляется в обратном направлении относительный даты в переменной.

Фактически, это функция добавления времени в часах к некой Дате. Результат покажет новую Дату.

Функция нужна для отображения в сообщении или сохранения в переменной, некоторой точки в будущем (например — окончание «похода в лес» в играх) — вычисленной в данной функции.

Примеры:
{dt_add("%date1%", 1)}
Вычислит дату на 1 час позже чем та, что сохранена в переменной «date1«.

Обратите внимание на то, что макрос Переменной Времени «%date1%» — в кавычках, это важно (дата — это текстовая информация)!

Вычислит дату на 1.5 часа позже чем dt_now() «сейчас» (на момент срабатывания выражения).

Например: «Вы ушли, возвращайтесь обратно в {dt_add(dt_now(), 1.5)}«. То есть через полтора часа.

Вычислит дату на «var1» часов позже чем та, что сохранена в переменной «date1«.

Обратите внимание на то, что макрос Переменной Времени «%date1%» — в кавычках, а макрос Числовой Переменной %var1% — без кавычек!

Добавление стандартных отрезков времени

Бывают ситуации когда к дате (сегодняшней или любой другой) нужно добавить некий стандартный отрезок времени, например: час, день, неделю, месяц или год. Для удобства были введены следующие выражения:

Добавит 1 час.

Для часов, однако можно использовать и следующее выражение {dt_add(dt_now(), 1)}.

добавит 1 день

добавит 1 неделю

добавит 1 месяц

добавит 1 год

Естественно вместо функции dt_now() можно использовать любую дату или макрос переменной времени содержащую дату.

dt_diff() — Разница Времени

dt_diff(date1, date2) Разница времени — функция получения разницы в часах (дробных) между двумя датами. Вычисляет «date1» минус «date2«. Если «date2» будет больше (то есть позже по времени) чем «date1» — результат будет отрицательным числом.

Возвращает дробное число Часов.

Функция нужна для получения информации о том, сколько времени в (дробных) часах прошло между двумя событиями «date1» и «date2«.

Примеры:
{dt_diff(dt_now(), "%date1%")}
Допустим ранее вы сохранили Дату/Время в переменной «date1«. Данный пример вычислит (разницу), сколько часов прошло со времени сохраненного в переменной «date1» (то есть от какого-то события в прошлом) до теперешнего момента из функции «dt_now()».

Обратите внимание на то, что макрос Переменной Времени «%date1%» — в кавычках, это важно!

Дополнительные НЕобязательные параметры:

Тип результата: «s», «m», «h», «d» (секунда, минута, час, день). По умолчанию — час.
Округление: «n», «u», «d» (не округлять, округлять вверх, округлять вниз). По умолчанию — не округлять.
{dt_diff("%date%", dt_now(), "s")} — результат в секундах.
{dt_diff("%date%", dt_now(), "d")} — результат в днях (дробных).
{dt_diff("%dater%", dt_now(), "d", "u")} — результат в днях (целых, округленных вверх).

● Пример сообщения:
«С вашего ухода прошло {dt_diff(dt_now(), «%date1%»)} часов.»

● Или поинтереснее:
«За прошедшие {dt_diff(dt_now(), «%date1%»)} часа вы заработали {dt_diff(dt_now(), «%date1%») * 10} монет.»
При условии что юзер получает 10 монет в час.

❖ Сравнение Даты и Времени

Функции Времени, а так же Переменные содержащие данные о Дате и Времени могут служить Условием для выполнения тех или иных действий в Кнопках и Action-ах. Для этого Время можно сравнивать в Условиях этих кнопок и Action-ов.

Даты и Время сравниваются обычными операторами сравнения:
● >, >= (Больше, Больше или равно)
● <, <= (Меньше, Меньше или равно)
и другими.

Технически можно сравнивать даты на «равно/не равно» (==, !=), но практического смысла в этом — нет: маловероятно что даты совпадут с точностью до миллисекунд.

Пример 1:
Некую Дату нужно сравнить с Настоящим (со временем «сейчас»).
{dt_left("%date1%") == 0}
Время оствшееся до даты равно 0 (нулю). Дата уже прошла.

Функция dt_left() вернёт оставшееся до %date1% время в часах (смотри ниже).

Пример 2:
У вас две Даты «не сейчас».
{dt_diff(%date1%, %date2%) <=0}
Ипользуйте >=, в зависимости от того какая дата должна быть больше.

Функция dt_diff() вернёт разницу между %date1% и %date2% в часах (смотри выше).

Как НЕ НАДО сравнивавть Даты:
{"%date1%" < dt_now()}
В данном примере происходит сравнение Строк и результат может быть непредстказуемым, несмотря на то, что выражение может казаться верным и даже верно работать в ряде случаев.

❖ Типы результатов Выражений

При записи в переменные результатов работы функций Даты/Времени (когда они сохраняются в переменную через кнопки типа «Бонус», «Обмен», или через «Action-ы»), важно понимать и учитывать то, какого ТИПА результат возвращает та или иная функция Времени. От этого будет зависеть способ записи данных и соответственно то что останется записанным в переменной в конечном итоге.

Результаты бывают двух Типов:
● Тип — Дата/Время. Если выражение возвращает «Дату» — то дата будет ПРИСВОЕНА переменной. Всегда присвоена: то есть старая дата будет затёрта новой.
● Тип — Число: Если выражение возвращает «Число» — то значение будет ДОБАВЛЕНО (или вычтено, если отрицательное) к Дате в переменной. Работа по принципу функции «dt_add()». 

Какой тип результата возвращает та или иная функция, смотрите выше — в описании самих функций.

❖ Дополнительные Функции

Дополнительные функции предоставляют возможности, которые в принципе можно «собрать» и из «Базовых Функций» — осуществив все вычисления самостоятельно. Однако использование «Дополнительных Функций» для «типовых сценариев», позволяет сократить визуальную сложность Выражений и упростить вам работу.

Набор дополнительных функций, вероятнее всего, будет расширятся по мере выявления новых «типовых», активно используемых сценариев (другими словами — по вашим просьбам).

dt_left()

функция, которая возвращает, сколько В ЧАСАХ осталось до указанной даты (date). Если относительно текущего момента дата уже прошла — функция вернет 0 (ноль).

Функция вернет дробное, десятичное количество часов (1.2, 5.7, 34.4). Больше предназначено для удобства вычислений в Выражениях.

Дополнительные НЕобязательные параметры:

Тип результата: «s», «m», «h», «d» (секунда, минута, час, день). По умолчанию — час.
Округление: «n», «u», «d» (не округлять, округлять вверх, округлять вниз). По умолчанию — не округлять.
{dt_left("%datevar%", "s")} — результат в секундах.
{dt_left("%datevar%", "d")} — результат в днях (дробных).
{dt_left("%datevar%", "d", "u")} — результат в днях (целых, округленных вверх).

dt_left_hm()

функция, которая возвращает строку в HH:MM, сколько осталось В ЧАСАХ и МИНУТАХ до указанной даты (date). Если относительно текущего момента дата уже прошла — функция вернет 00:00.

Функция вернет привычное и удобное для понимания человеком количество часов и минут (1:12, 7:42, 36:24). Предназначено для упрощения понимания юзером и удобства вывода значений в Сообщениях.

Дополнительные НЕобязательные параметры:

Форматирование полученных результатов:
{dt_left_hm("31.12.2021 23:59:59", "-")} — собственный разделитель (покажет условно: 170-59)
{dt_left_hm("31.12.2021 23:59:59", " | ", " часов", " минут")} — собственный разделитель и суффиксы для Часов и Минут (покажет условно: 170 часов | 59 минут)

dt_passed()

функция, которая возвращает, сколько прошло В ЧАСАХ с указанной даты (date). Если относительно текущего момента дата ещё не подошла — функция вернет 0 (ноль).

Функция вернет дробное, десятичное количество часов (1.2, 5.7, 34.4). Больше предназначено для удобства вычислений в Выражениях.

Дополнительные НЕобязательные параметры:

Тип результата: «s», «m», «h», «d» (секунда, минута, час, день). По умолчанию — час.
Округление: «n», «u», «d» (не округлять, округлять вверх, округлять вниз). По умолчанию — не округлять.
{dt_passed("%datevar%", "s")} — результат в секундах.
{dt_passed("%datevar%", "d")} — результат в днях (дробных).
{dt_passed("%datevar%", "d", "u")} — результат в днях (целых, округленных вверх).

dt_passed_hm()

функция, которая возвращает строку в HH:MM сколько прошло В ЧАСАХ И МИНУТАХ с указанной даты (date). Если относительно текущего момента дата ещё не подошла — функция вернет 00:00.

Функция вернет привычное и удобное для понимания человеком количество часов и минут (1:12, 7:42, 36:24). Предназначено для упрощения понимания юзером и удобства вывода значений в Сообщениях.

Дополнительные НЕобязательные параметры:

Форматирование полученных результатов:
{dt_passed_hm("31.12.2021 23:59:59", "-")} — собственный разделитель (покажет условно: 170-59)
{dt_passed_hm("31.12.2021 23:59:59", " | ", " часов", " минут")} — собственный разделитель и суффиксы для Часов и Минут (покажет условно: 170 часов | 59 минут)

dt_passedm()

функция, которая возвращает, сколько прошло В ЧАСАХ с указанной даты (date), но не больше (max) часов. Если относительно текущего момента дата ещё не подошла — функция вернет 0 (ноль). Если относительно (data) прошло больше (max) часов — функция вернет (max).

Функция вернет дробное, десятичное количество часов (1.2, 5.7, 34.4). Больше предназначено для удобства вычислений в Выражениях.

dt_passedm_hm()

функция, которая возвращает строку в HH:MM сколько прошло В ЧАСАХ И МИНУТАХ с указанной даты, но не больше (max) часов. Если относительно текущего момента дата ещё не подошла — функция вернет 00:00. Если относительно (data) прошло больше (max) часов — функция вернет (max) в формате HH:MM.

Функция вернет привычное и удобное для понимания человеком количество часов и минут (1:12, 7:42, 36:24). Предназначено для упрощения понимания юзером и удобства вывода значений в Сообщениях.

Дополнительные НЕобязательные параметры:

Форматирование полученных результатов:
{dt_passedm_hm("31.12.2021 23:59:59", "-")} — собственный разделитель (покажет условно: 170-59)
{dt_passedm_hm("31.12.2021 23:59:59", " | ", " часов", " минут")} — собственный разделитель и суффиксы для Часов и Минут (покажет условно: 170 часов | 59 минут)

dt_nextday()

dt_nextday(date)
Функция которая получив дату возвращает дату начала следующего ДНЯ.
Пример указания даты и времени:
dt_nextday("%date% %time%") — при помощи макросов даты и времени
dt_nextday(dt_now()) — при помощи функции «сейчас»
dt_nextday(dt_now_tz()) — при помощи функции «сейчас с учётом часового пояса бота»
Например: получив 01.01.2022 22:22:22 вернет 02.01.2022 00:00:00.

dt_nextmonth()

dt_nextmonth(date)
Функция которая получив дату возвращает дату начала следующего МЕСЯЦА.
Пример указания даты и времени:
dt_nextmonth("%date% %time%") — при помощи макросов даты и времени
dt_nextmonth(dt_now()) — при помощи функции «сейчас»
dt_nextmonth(dt_now_tz()) — при помощи функции «сейчас с учётом часового пояса бота»
Например: получив 22.01.2022 22:22:22 вернет 01.02.2022 00:00:00.

dt_now_tz()

dt_now_tz()
Функция — аналог dt_now(), но формирует время «сейчас», с учетом настроенного в боте часового пояса (_tz — Time Zone). 

Используйте данную функцию только для отображения времени и тому подобных вещей. Не рекомендуем использовать время локальных Часовых Поясов для хранения или учёта каких либо данных. С функциями типа: dt_left(), dt_passed() — данная функция может работать НЕПРАВИЛЬНО. 

❖ Дополнительная Информация

Дату и Время можно записывать в Переменные

О том что такое переменные и как с ними работать.

• • •

Функции и Переменные с Дата/Время можно использовать в Выражениях

О том как применять Выражения, читай в руководстве по Выражениям.

• • •

Функции и Переменные с Дата/Время можно использовать в Условиях

О том как применять Условия, читай в руководстве по Условиям.

• • •

Дату и Время можно использовать в Action-ах

Подробнее о том что такое Action-ы, чем они удобны и как ими пользоваться смотрите в отдельном Руководстве по Action-ам.

Правильная работа с датой и временем

Практически все проекты сталкиваются с проблемами, вызванными неправильной обработкой и хранением даты и времени. Даже если проект используется в одном часовом поясе, все равно после перехода на зимнее/летнее время можно получить неприятные неожиданности. При этом мало кто озадачивается реализацией правильного механизма со старта, потому что кажется, что с этим проблем быть не может, так как все тривиально. К сожалению, в последствии реальность показывает, что это не так.

Логически можно выделить следующие типы значений, относящиеся к дате и времени:

• Дата и время — «материал для медицинского анализа был собран 15 января 2014 года в 13:17:15»
• Дата без времени — например, «новый контракт вступает в силу 2 февраля 2016 года»
• Временной интервал — «отчет был сформирован за 3 минуты 15 секунд»
• Расписание запланированных событий — «импорт данных из другой системы должен происходить каждый будний день в 10:00»

Рассмотрим каждый пункт по отдельности, не забывая об общих рекомендациях.

Дата и время

Допустим, лаборатория, которая собрала материал для анализа находится в часовом поясе +2, а центральный филиал, в котором следят за своевременным выполнением анализов — в поясе +1. Время, приведенное в примере, было отмечено при сборе материала первой лабораторией. Возникает вопрос — какую цифру времени должен увидеть центральный офис? Очевидно, что программное обеспечение центрального офиса должно показывать 15 января 2014 года 12:17:15 — на час меньше, так как по их часам событие произошло именно в этот момент.

Рассмотрим одну из возможных цепочек действий, через которую проходят данные с клиента на сервер и обратно, позволяющую всегда корректно отображать дату/время согласно текущему часовому поясу клиента:

1. Значение создается на клиенте, например, 2 марта 2016 15:13:36, клиент находится в часовом поясе +2.
2. Значение преобразуется в строковое представление для передачи на сервер — “2016-03-02T15:13:36+02:00”.
3. Сериализованные данные передаются на сервер.
4. Сервер десериализует время в объект даты/времени, приводя его при этом к своему текущему часовому поясу. Например, если сервер работает в +1, значит объект будет содержать 2 марта 2016 14:13:36.
5. Сервер сохраняет данные в базу, при этом она не содержит никакой информации о часовом поясе — наиболее часто используемые типы даты/времени просто о нем ничего не знают. Таким образом, в базу будет сохранено 2 марта 2016 14:13:36 в «неизвестном» часовом поясе.
6. Сервер читает данные из базы и создает соответствующий объект со значением 2 марта 2016 14:13:36. И так как сервер работает в часовом поясе +1, то и это значение будет трактоваться в рамках того же часового пояса.
7. Значение преобразуется в строковое представление для передачи на клиент — “2016-03-02T14:13:36+01:00”.
8. Сериализованные данные отправляются на клиент.
9. Клиент десериализует полученное значение в объект даты/времени, приводя его при этом к своему текущему часовому поясу. Например, если это -5, то отображаемое значение должно быть равно 2 марта 2016 09:13:36.

Вроде бы все целостно, но давайте подумаем, что в этом процессе может пойти не так. На самом деле, проблемы здесь могут случиться почти на каждом шаге.

• Время на клиенте может быть сформировано вообще без часового пояса — например, DateTime тип в .NET с DateTimeKind.Unspecified.
• Механизм сериализации может использовать формат, который не включает в себя смещение часового пояса.
• При десериализации в объект может игнорироваться смещение часового пояса, особенно в «самодельных» десериализаторах — как на сервере, так и на клиенте.
• При чтении из базы объект даты/времени может быть сформирован вообще без часового пояса — например, DateTime тип в .NET с DateTimeKind.Unspecified. Более того, с DateTime в .NET на практике именно так и получается, если сразу после вычитки явно не указывать другой DateTimeKind.
• Если сервера приложения, работающие с общей базой данных, находятся в разных часовых поясах — будет серьезная путаница в смещениях во времени. Значение даты/времени, записанное в базу сервером А и прочитанное сервером Б будет заметно отличаться от того же исходного значения, записанного сервером Б и прочитанного сервером А.
• Перевод серверов приложения из одного пояса в другой приведет к неправильной трактовке уже сохраненных значений даты/времени.

Но самый серьезный недостаток в описанной выше цепочке — это использование локального часового пояса на сервере. Если в нем нет перехода на летнее/зимнее время, то никаких дополнительных проблем не будет. А вот в противном случае можно получить массу неприятных неожиданностей.

Правила перевода на летнее/зимнее время — вещь, строго говоря, переменная. Разные страны могут иногда менять свои правила, и эти изменения должны быть заблаговременно заложены в обновления системы. На практике неоднократно встречались ситуации некорректной работы этого механизма, которые по итогу решались установкой хотфиксов либо операционной системы, либо используемых сторонних библиотек. Вероятность повторения тех же проблем — не нулевая, поэтому лучше иметь способ гарантированно их избежать.

Учитывая описанные выше соображения, сформулируем как можно более надежный и простой подход к передаче и хранению времени: на сервере и в базе данных все значения должны быть приведены к часовому поясу UTC.

Рассмотрим, что нам дает такое правило:

• При отправке данных на сервер клиент должен передать смещение часового пояса, чтобы сервер мог корректно преобразовать время в UTC. Альтернативный вариант — обязать клиент делать это преобразование, но первый вариант гибче. При получении данных обратно с сервера клиент будет переводить дату и и время в свой локальный часовой пояс зная, что ему в любом случае придет время в UTC.
• В UTC нет переходов на летнее и зимнее время, соответственно связанные с этим проблемы будут неактуальны.
• На сервере при чтении из базы не нужно преобразовывать значения времени, достаточно только явно указывать, что оно соответствует UTC. В .NET, например, этого можно достичь установкой DateTimeKind для объекта времени в DateTimeKind.Utc.
• Разница часовых поясов между серверами, работающими с общей базой данных, как и перевод серверов из одного пояса в другой, никак не отразятся на корректности получаемых данных.

Для реализации такого правила достаточно позаботиться о трех вещах:

1. Сделать механизм сериализации и десериализации такой, чтобы значения даты/времени корректно переводились из UTC в локальный часовой пояс и обратно.
2. Убедиться, что десериализатор на стороне сервера создает объекты даты/времени в UTC.
3. Сделать так, чтобы при вычитке из базы объекты даты/времени создавались в UTC. Этот пункт иногда обеспечивают без изменений кода — просто системный часовой пояс на всех серверах устанавливается в UTC.

Описанные выше соображения и рекомендации отлично работают при сочетании двух условий:

• В требованиях к системе нет надобности отображать локальное время и/или смещение часового пояса именно в том виде, в котором оно было сохранено. Например, в авиабилетах время вылета и прибытия должно быть распечатано в часовом поясе, соответствующем расположению аэропорта. Или если сервер отправляет на печать инвойсы, созданные в разных странах, на каждом должно в итоге стоять локальное время, а не преобразованное в часовой пояс сервера.
• Все значения даты и времени в системе являются «абсолютными» — т.е. описывают момент времени в будущем или прошлом, которому соответствует единственное значение в UTC. Например, «пуск ракеты-носителя состоялся в 23:00 по киевскому времени», или «совещание будет идти с 13:30 до 14:30 по минскому времени». В разных часовых поясах цифры для этих событий будут разные, но они будут описывать один и тот же момент времени. Но может так случиться, что требования к программному обеспечению подразумевают «относительное» локальное время для некоторых случаев. Например, «эта передача на телевидении будет идти с 9:00 до 10:00 утра в каждой стране, где есть филиал телеканала». Получается, что показ передачи — это не одно событие, а несколько, причем потенциально все они могут происходить в разные отрезки времени по «абсолютной» шкале.

Для случаев, где нарушается первое условие, задачу можно решить использованием типов данных, содержащих часовой пояс – как на сервере, так и в базе данных. Ниже приведен небольшой перечень примеров для разных платформ и СУБД.

Нарушение второго условия — более сложный случай. Если это «относительное» время нужно хранить просто для отображения, и нет задачи определить «абсолютный» момент времени, когда событие наступило или наступит для заданного часового пояса — достаточно просто запретить преобразование времени. Например, пользователь ввел начало передачи для всех филиалов телекомпании 25 марта 2016 года в 9:00, и оно в таком виде будет передаваться, храниться и отображаться. Но может случиться, что какой-то планировщик должен автоматически выполнить специальные действия за час до начала каждой передачи (разослать уведомления или проверить наличие каких-то данных в базе телекомпании). Надежная реализация такого планировщика является нетривиальной задачей. Допустим, планировщик осведомлен о том, в каком часовом поясе находится каждый из филиалов. И одна из стран, где есть филиал, через некоторое время решает сменить часовой пояс. Случай не настолько редкий, как может показаться — за этот и два предыдущих года я насчитал больше 10 подобных событий (http://www.timeanddate.com/news/time/). Получается, что либо пользователи должны поддерживать привязки к часовым поясам в актуальном состоянии, либо планировщик должен в автоматизированном режиме брать эту информацию из глобальных источников типа Google Maps Time Zone API. Я не берусь предложить универсальное решение для подобных случаев, просто отмечу, что такие ситуации требуют серьезной проработки.

Как видно из вышесказанного, не существует единого подхода, покрывающего 100% случаев. Поэтому сперва нужно четко понять из требований, какие из упомянутых выше ситуаций будут в вашей системе. С большой вероятностью, все ограничится первым предложенным подходом с хранением в UTC. Ну а описанные исключительные ситуации его не отменяют, а просто добавляют другие решения для частных случаев.

Дата без времени

Допустим, с правильным отображением даты и времени с учетом часового пояса клиента разобрались. Перейдем к датам без времени и примеру, указанному для этого случая в начале — «новый контракт вступает в силу 2 февраля 2016 года». Что будет, если для таких значений использовать те же типы и тот же механизм, что и для «обычных» даты с временем?

Не во всех платформах, языках и СУБД есть типы, хранящие только дату. Например, в .NET есть только тип DateTime, отдельного «просто Date» нет. Даже если при создании такого объекта была указана только дата, время все равно присутствует, и оно равно 00:00:00. Если мы значение «2 февраля 2016 00:00:00» из пояса со смещением +2 переведем в +1, то получим «1 февраля 2016 23:00:00». Для указанного выше примера это будет равносильно тому, что в одном часовом поясе новый контракт начнет действовать 2 февраля, а в другом — 1 февраля. С юридической точки зрения это абсурд и так, конечно же, быть не должно. Общее правило для «чисто» дат предельно простое — такие значения не должны преобразовываться ни на одном шаге сохранения и чтения.

Есть несколько способов избежать преобразование для дат:

• Если платформа поддерживает тип, представляющий дату без времени, то его и нужно использовать.
• Добавлять в метаданные объектов специальный признак, который будет говорить сериализатору, что для данного значения часовой пояс нужно игнорировать.
• Передавать дату с клиента и обратно как строку, а хранить как дату. Такой подход неудобен, если на клиенте дату нужно не только отображать, но еще и производить какие-то операции над ней: сравнение, вычитание и т.д.
• Передавать и хранить как строку, а преобразовывать в дату только для форматирования с учетом региональных настроек клиента. Имеет еще больше недостатков чем предыдущий вариант — например, если в хранимой строке части даты идут не в порядке «год, месяц, день», то будет невозможно сделать эффективный индексированный поиск по диапазону дат.

Можно, конечно, попытаться привести контрпример и сказать, что контракт имеет смысл только в пределах страны, в которой он заключен, страна находится в одном часовом поясе, и поэтому можно однозначно определить момент вступления его в силу. Но даже в этом случае пользователям из других часовых поясов не будет интересно, в какой момент по их локальному времени произойдет это событие. А даже если бы была нужда показывать этот момент времени, то отображать пришлось бы не только дату, но и время, что противоречит исходному условию.

Временной интервал

С хранением и обработкой временных интервалов все просто: их величина не зависит от часового пояса, поэтому никаких особых рекомендаций здесь нет. Их можно хранить и передавать как количество единиц времени (целое или с плавающей точкой, в зависимости от необходимой точности). Если важна секундная точность — то как количество секунд, если миллисекундная — то как количество миллисекунд и т.д.

А вот вычисление интервала может иметь подводные камни. Предположим, у нас есть типовой код на C#, который считает интервал времени между двумя событиями:

DateTime start = DateTime.Now;
//...
DateTime end = DateTime.Now;
double hours = (end - start).TotalHours;

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

Предположим, код работает в часовом поясе, в котором переход на летнее время в 2016 году происходит в ночь 27 марта, и смоделируем описанную выше ситуацию:

DateTime start = DateTime.Parse("2016-03-26T20:00:15+02");
DateTime end = DateTime.Parse("2016-03-27T05:00:15+03");
double hours = (end - start).TotalHours;

Этот код даст в результате 9 часов, хотя фактически между этими моментами прошло 8 часов. В этом легко убедиться, изменив код вот таким образом:

DateTime start = DateTime.Parse("2016-03-26T20:00:15+02").ToUniversalTime();
DateTime end = DateTime.Parse("2016-03-27T05:00:15+03").ToUniversalTime();
double hours = (end - start).TotalHours;

Отсюда вывод — любые арифметические операции с датой и временем нужно делать, используя либо UTC значения, либо типы, хранящие информацию о часовом поясе. А потом обратно переводить в локальные в случае надобности. С этой точки зрения, изначальный пример легко исправить, поменяв DateTime.Now на DateTime.UtcNow.

Этот нюанс не зависит от конкретной платформы или языка. Вот аналогичный код на Java, имеющий тот же недостаток:

LocalDateTime start = LocalDateTime.now();
//...
LocalDateTime end = LocalDateTime.now();
long hours = ChronoUnit.HOURS.between(start, end);

Исправляется он также легко — например, использованием ZonedDateTime вместо LocalDateTime.

Расписание запланированных событий

Расписание запланированных событий – более сложная ситуация. Универсального типа, позволяющего хранить расписания, в стандартных библиотеках нет. Но такая задача возникает не так уж редко, поэтому готовые решения можно найти без проблем. Хорошим примером является формат планировщика cron, который в том или ином виде используется другими решениями, например, Quartz: http://quartz-scheduler.org/api/2.2.0/org/quartz/CronExpression.html. Он покрывает практически все нужды составления расписаний, включая варианты типа «вторая пятница месяца».

В большинстве случаев писать свой планировщик не имеет смысла, так как существуют гибкие проверенные временем решения, но если по какой-то причине есть надобность в создании своего механизма, то как минимум формат расписания можно позаимствовать у cron.

Общие рекомендации

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

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

• Выделить интерфейс IDateTimeProvider с единственным методом, возвращающим текущее время. Затем добавить зависимость на этот интерфейс во всех единицах кода, где нужно получать текущее время. При обычном выполнении программы во все эти места будет инжектиться реализация «по умолчанию», которая возвращает реальное текущее время, а в юнит тестах – любая другая необходимая реализация. Такой способ является наиболее гибким с точки зрения тестирования.
• Сделать свой статический класс с методом для получения текущего времени и возможностью установить любую реализацию этого метода извне. Например, в случае C# кода этот класс может выставлять наружу свойство UtcNow и метод SetImplementation(Func<DateTime> impl). Использование статического свойства или метода для получения текущего времени избавляет от надобности везде явно прописывать зависимость от дополнительного интерфейса, но с точки зрения принципов ООП не является идеальным решением. Однако, если по каким-то соображениям предыдущий вариант не подходит, то можно воспользоваться этим.

Дополнительная проблема, которую следует решить при переходе на свою реализацию провайдера текущего времени — это контроль за тем, чтобы никто «по старинке» не продолжил использовать стандартные классы. Эту задачу легко решить в большинстве систем контроля качества кода. По сути она сводится к поиску «нежелательной» подстроки во всех файлах за исключением того, где объявлена реализация «по умолчанию».

Второй нюанс с получением текущего времени — это то, что клиенту доверять нельзя. Текущее время на компьютерах пользователей может очень сильно отличаться от реального, и если есть логика, завязанная на него, то эта разница может все испортить. Все места, где есть необходимость получать текущее время, должны по возможности выполняться на стороне сервера. И, как уже было сказано ранее, все арифметические операции с временем должны производиться либо в UTC значениях, либо с использованием типов, хранящих смещение часового пояса.

И еще одна вещь, которую хотелось упомянуть — это стандарт ISO 8601, описывающий формат даты и времени для обмена информацией. В частности, строковое представление даты и времени, используемое при сериализации, должно соответствовать этому стандарту для предотвращения потенциальных проблем с совместимостью. На практике крайне редко приходится самому реализовывать форматирование, поэтому сам стандарт может быть полезен в основном в ознакомительных целях.

При работе с датами чаще всего используются функции форматирования (для приведения к нужному представлению), работы со сроками (прибавления определенного количества дней и т.п.) и формирования даты. Следует помнить, что в «Первой Форме» используются ДП типа «Дата» и «ДатаВремя».

•Для получения текущей даты используется функция ТекущиеДатаВремя(). Для формирования даты используется функция НовыеДатаВремя (год, месяц, день, час, минуты, секунды).

Пример: формирование даты последнего рабочего дня месяца и окончания рабочего дня (18 часов).

 Смарт-выражение, формирующее дату последнего рабочего дня и время 18:00.

•Для работы со сроками используются встроенные функции из подменю Добавить…, Разница…, Округлить….

Пример: округление даты.

Округление даты.

•Для преобразования даты в текст используется функция Отформатировать дату (дата, шаблон). Шаблон указывается в виде текстовой строки вида ‘dd.MM.yyyy HH:mi’.

Преобразование даты в текст.

•Если пользователи системы территориально находятся в разных часовых поясах, в смарт-выражениях удобно использовать функцию ПеревестиВЧасовуюЗонуПользователя (дата_время, ID пользователя).

Пример: перевод времени, указанного в ДП «Плановое время созвона», во время по часовому поясу заказчика задачи.

Перевод в другую часовую зону.

Хранение дат и времени в базе данных

Последнее обновление: 01.12.2021

SQLite не имеет встроенных типов данных для хранения в таблицах в базе данных дат и времени, тем не менее это не мешает хранить дату и время в
базе данных также, как и любые другие данные. Для хранения дат и времени можно использовать типы TEXT, REAL и INTEGER

Тип TEXT

При использовании типа TEXT для хранения даты и времени они сохраняются в формате YYYY-MM-DD HH:MM:SS.SSS или
YYYY-MM-DD HH:MM:SS, например, 2021-12-01 13:23:08

Для хранения отдельно даты применяется формат YYYY-MM-DD, а для хранения времени — формат HH:MM:SS

Например, определим следующую таблицу пользователей:

DROP TABLE IF EXISTS users;
CREATE TABLE users
(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
	name TEXT NOT NULL,
    date_of_birth TEXT
);
INSERT INTO users (name, date_of_birth) VALUES 
('Tom', '1987-05-12'),
('Bob', date('now', '-41 years')),
('Sam', date('2021-11-29', '-25 years'));

Для установки даты и времени при сохранении данных можно напрямую использовать текстовый формат ("1987-05-12") или применять функции
для работы с датами и временем (date('now', '-41 years')).

Хранимые значения мы можем далее использовать в функциях, которые работают с датами и временем. Например, используя хранимую дату дня рождения,
найдем возраст пользователей:

SELECT name, 
	date('now')-date_of_birth AS age 
FROM users;

Другой пример — получение пользователей, день рождения которых находится в определенном диапазоне дат:

SELECT name, date_of_birth 
FROM users
WHERE date_of_birth BETWEEN '1950-01-01' AND '1991-12-31';

Аналогичным образом можно сохранять дату и время полностью. Например, определим таблицу заказов, которая хранит дату и время заказа:

DROP TABLE IF EXISTS orders;
CREATE TABLE orders
(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    date_time TEXT NOT NULL
);
INSERT INTO orders (date_time)
VALUES ('2021-11-30 22:01:15'),
(datetime('now')),
(datetime('now', '-5 hours'));

SELECT * FROM orders;

К примеру найдем все заказы за ноябрь 2021 года:

SELECT * FROM orders
WHERE date_time BETWEEN '2021-11-01' AND '2021-11-30';

Или найдем заказы, сделанные за текущий день:

SELECT * FROM orders
WHERE date_time BETWEEN datetime('now', 'start of day') AND datetime('now');

REAL

Также можно хранить дату и время в виде значения REAL. В этом случае столбец хранит количество дней с начала юлианской эпохи.
Например, возьмем предущую таблицу заказов и изменим в ней для даты и времени заказа тип с TEXT на REAL:

DROP TABLE IF EXISTS orders;
CREATE TABLE orders
(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    date_time REAL NOT NULL
);
INSERT INTO orders (date_time)
VALUES (julianday('2021-11-30 22:01:15')),
(julianday('now')),
(julianday('now', '-5 hours'));

Хранимое значение REAL с помощью функцию мы можем преобразовать в дату и время:

SELECT date_time, datetime(date_time) FROM orders;

INTEGER

Также можно использовать тип INTEGER. В этом случае дата и время хранятся в виде количества секунд, прошедших с начала эпохи
UNIX (хотя это ограничивает набор дат началом эпохи UNIX — 1970-01-01 00:00:00 UTC). Например, возьмем предыдущую таблицу заказов и изменим в ней для даты и времени заказа тип на INTEGER:

DROP TABLE IF EXISTS orders;
CREATE TABLE orders
(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    date_time INTEGER NOT NULL
);
INSERT INTO orders (date_time)
VALUES (strftime('%s', '2021-11-30 22:01:15')),
(strftime('%s', 'now')),
(strftime('%s', 'now', '-5 hours'));

Функция strftime с помощью параметра "%s"получает количество секунд, прошедших с начала эпохи UNIX относительно заданной даты.
И также это значение мы можем преобразовать в читабельные дату и время:

SELECT date_time, datetime(date_time, 'unixepoch') FROM orders;