# Как правильно читать и записывать DateTime в кастомные таблицы

## 📅 Работа с датой и временем в Metabot  

В Metabot работа с датой и временем имеет **важную особенность**, о которой легко не узнать — в документации она описана фрагментарно.  
Этот урок объясняет **как правильно работать с DateTime**, чтобы данные **гарантированно сохранялись в базе данных** и корректно отображались.

---

## 🔹 Как хранятся дата и время в базе данных

В кастомных таблицах Metabot используется база данных **PostgreSQL**.

Поля типа даты и времени имеют тип:

```
DATETIME
```

Это означает:

- дата и время **хранятся без временной зоны**
- формат хранения:  

```
YYYY-MM-DD HH:mm:ss
```

Пример корректного значения в базе:
```
2026-01-17 11:48:06
```

---

## ❌ Частая ошибка: запись `new Date()` напрямую

В JavaScript на платформе Metabot **нельзя** напрямую записывать объект `Date` в кастомную таблицу.

❌ **Неправильно:**
```js
table.createItem('nav_actor_missions', {
  completed_at: new Date()
});
```

Такое значение **не будет сохранено**, даже если остальные поля записались успешно.

Причина:  
`new Date()` — это **JS-объект**, а база данных ожидает **строку**.

---

## ❌ Почему не работает `toISOString()`

Многие пробуют использовать ISO-строку:

```js
new Date().toISOString()
// "2026-01-17T08:48:06.921Z"
```

❌ **Это тоже не работает** для `DATETIME`.

Почему:

- символ `T` между датой и временем
- суффикс `Z` (UTC)
- миллисекунды `.921`

Все эти элементы **не совместимы с DATETIME без таймзоны**.

---

## ✅ Правильный способ: `getDateFormattedString`

В Metabot есть **встроенный безопасный метод**, который решает проблему полностью:

### ✔ `bot.getDateFormattedString()`

```js
let now = new Date();
let nowStr = bot.getDateFormattedString(now);
// "2026-01-17 11:48:06"
```

Это **канонический формат**, который:
- корректно сохраняется в `DATETIME`
- не ломает апдейты
- не зависит от БД-драйвера

---

## 🧠 Важно понимать про временные зоны

### Как это работает в Metabot:

- `new Date()` возвращает время **в таймзоне сервера**
- в базу данных дата пишется **без таймзоны**
- при чтении из БД вы получаете **время сервера**

👉 **Это нормально и правильно.**

### Когда учитывать таймзону пользователя?

- при выводе в интерфейс
- в отчётах
- в аналитике

Но **не при записи в БД**.

---

## 🔁 Преобразование дат (FAQ)

### 📌 Преобразовать строку даты в нужный формат

```js
item.getDateFormattedString(
  '2022-02-01 12',
  'd-m-Y H:i:s',
  'Y-m-d H',
  'UTC',
  '+3'
);
// → "01-02-2022 09:00:00"
```

Здесь **`item` — это не абстрактный объект**, а **строка кастомной таблицы** (элемент Custom Table), полученная, например, через:

* `table.find(...)`
* `table.createItem(...)`
* `row` в результате `update()`

Каждый такой `item` (строка кастомной таблицы) **имеет тот же метод `getDateFormattedString`**, что и объект `bot`.

#### Это означает:

* ✅ `bot.getDateFormattedString(...)` — используется для форматирования текущего времени, логов, дат из внешних источников
* ✅ `item.getDateFormattedString(...)` — используется для форматирования дат, связанных с конкретной строкой таблицы

Метод работает **одинаково в обоих случаях** и возвращает строку в формате, совместимом с `DATETIME`.

---

📖 **Подробнее о методе `item.getDateFormattedString` и его использовании** см. в отдельной документации:
👉 [https://docs.metabot24.ru/books/05-low-code-full-code/page/itemgetdateformattedstring](https://docs.metabot24.ru/books/05-low-code-full-code/page/itemgetdateformattedstring)

---

### 📌 Использовать дату из логов или БД

```js
data.msg_at = bot.getDateFormattedString(
  new Date(lastLog.updated_at)
);
```

---

### 📌 Генерация идентификаторов с датой

```js
let sessionId = leadId + '_' + bot.getDateFormattedString(
  new Date(),
  'YmdHis'
);
```

Результат:
```
12345_20260117114806
```

---

## 🧩 Пример: корректная запись DateTime в кастомную таблицу

```js
let now = new Date();
let nowStr = bot.getDateFormattedString(now);

table.createItem('nav_actor_missions', {
  actor_id: leadId,
  status: 'completed',
  completed_at: nowStr
});
```

✔ Дата сохранится  
✔ Ошибок не будет  
✔ Поле не останется `NULL`

---

## 🚨 Итоговые правила (коротко)

❌ Нельзя:
- писать `new Date()` напрямую
- писать `toISOString()`
- писать ISO-строки с `T` и `Z`

✅ Нужно:
- **всегда** использовать `getDateFormattedString`
- писать дату в формате `Y-m-d H:i:s`
- хранить дату **во времени сервера**

---

## 🧭 Рекомендация

Если вы работаете с кастомными таблицами и DateTime:

> **Считайте `getDateFormattedString` обязательным инструментом.**  
> Это часть контракта между JavaScript и базой данных Metabot.