pcp-tgu-service: толерантность времени на Jackson-3 пути (REST-кодеки WebFlux)

2026-06-02 22:57:49 +03:00
parent 84e70350b9
commit cde4ffa9b6
5 changed files with 192 additions and 10 deletions
@@ -26,7 +26,7 @@ class CamundaJacksonConfig {
            .addModule(JavaTimeModule())
            // Слой толерантности времени (читать naive=UTC и Z) — см. docs/standards/DATETIME_UTC.md.
            // Покрывает Jackson-2 путь (Camunda/внутренний парсинг). REST-codec на Jackson 3
-            // (WebFlux auto-config) — отдельный tgu-follow-up в DATETIME_UTC.md.
+            // (WebFlux auto-config) покрыт близнецом PcpTimeModuleV3 (см. WebFluxJacksonConfig).
            .addModule(PcpTimeModule())
            .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
            .build()
@@ -0,0 +1,93 @@
+package space.nstart.pcp_tgu_service.config
+
+import tools.jackson.core.JsonParser
+import tools.jackson.core.JsonToken
+import tools.jackson.databind.DeserializationContext
+import tools.jackson.databind.ValueDeserializer
+import tools.jackson.databind.ext.javatime.deser.InstantDeserializer
+import tools.jackson.databind.ext.javatime.deser.LocalDateTimeDeserializer
+import tools.jackson.databind.module.SimpleModule
+import java.time.Instant
+import java.time.LocalDateTime
+import java.time.OffsetDateTime
+import java.time.ZoneOffset
+import java.time.format.DateTimeParseException
+
+/**
+ * Слой толерантности времени для **Jackson 3** (`tools.jackson.*`).
+ *
+ * Близнец [PcpTimeModule] (Jackson 2): то же поведение — читать время в обоих форматах на проводе
+ * (naive=UTC и `Z`/офсет), нормализуя к UTC; трогает только десериализацию. Нужен отдельно, потому
+ * что Boot 4 авто-конфигурирует Jackson 3 `JsonMapper` для REST-кодеков WebFlux, а он не видит
+ * Jackson-2 модули. Регистрируется как бин `tools.jackson.databind.JacksonModule`
+ * ([WebFluxJacksonConfig]) — `JacksonAutoConfiguration` собирает такие бины в общий `JsonMapper`.
+ *
+ * Канонический источник поведения — `space.nstart.pcp.pcp_types_lib.utils.json.PcpTimeModule`;
+ * правки синхронизировать. См. docs/standards/DATETIME_UTC.md.
+ */
+class PcpTimeModuleV3 : SimpleModule(NAME) {
+
+    init {
+        addDeserializer(LocalDateTime::class.java, TolerantLocalDateTimeDeserializerV3())
+        addDeserializer(OffsetDateTime::class.java, TolerantOffsetDateTimeDeserializerV3())
+        addDeserializer(Instant::class.java, TolerantInstantDeserializerV3())
+    }
+
+    companion object {
+        const val NAME = "PcpTimeModuleV3"
+    }
+}
+
+private class TolerantLocalDateTimeDeserializerV3 : ValueDeserializer<LocalDateTime>() {
+
+    private val default: ValueDeserializer<LocalDateTime> = LocalDateTimeDeserializer.INSTANCE
+
+    override fun deserialize(p: JsonParser, ctxt: DeserializationContext): LocalDateTime? {
+        if (p.currentToken() == JsonToken.VALUE_STRING) {
+            val text = p.string.trim()
+            if (text.isEmpty()) return null
+            try {
+                return OffsetDateTime.parse(text).withOffsetSameInstant(ZoneOffset.UTC).toLocalDateTime()
+            } catch (_: DateTimeParseException) {
+                // naive-строка без зоны — трактуем как UTC
+            }
+        }
+        return default.deserialize(p, ctxt)
+    }
+}
+
+private class TolerantOffsetDateTimeDeserializerV3 : ValueDeserializer<OffsetDateTime>() {
+
+    private val default: ValueDeserializer<OffsetDateTime> = InstantDeserializer.OFFSET_DATE_TIME
+
+    override fun deserialize(p: JsonParser, ctxt: DeserializationContext): OffsetDateTime? {
+        if (p.currentToken() == JsonToken.VALUE_STRING) {
+            val text = p.string.trim()
+            if (text.isEmpty()) return null
+            try {
+                return OffsetDateTime.parse(text).withOffsetSameInstant(ZoneOffset.UTC)
+            } catch (_: DateTimeParseException) {
+                return LocalDateTime.parse(text).atOffset(ZoneOffset.UTC)
+            }
+        }
+        return default.deserialize(p, ctxt)
+    }
+}
+
+private class TolerantInstantDeserializerV3 : ValueDeserializer<Instant>() {
+
+    private val default: ValueDeserializer<Instant> = InstantDeserializer.INSTANT
+
+    override fun deserialize(p: JsonParser, ctxt: DeserializationContext): Instant? {
+        if (p.currentToken() == JsonToken.VALUE_STRING) {
+            val text = p.string.trim()
+            if (text.isEmpty()) return null
+            try {
+                return OffsetDateTime.parse(text).toInstant()
+            } catch (_: DateTimeParseException) {
+                return LocalDateTime.parse(text).toInstant(ZoneOffset.UTC)
+            }
+        }
+        return default.deserialize(p, ctxt)
+    }
+}
@@ -0,0 +1,22 @@
+package space.nstart.pcp_tgu_service.config
+
+import org.springframework.context.annotation.Bean
+import org.springframework.context.annotation.Configuration
+import tools.jackson.databind.JacksonModule
+
+/**
+ * Регистрирует слой толерантности времени ([PcpTimeModuleV3]) в авто-конфигурируемом Jackson 3
+ * `JsonMapper`, который Boot 4 использует для REST-кодеков WebFlux.
+ *
+ * `JacksonAutoConfiguration` собирает все бины `tools.jackson.databind.JacksonModule` из контекста
+ * и добавляет их в общий `JsonMapper` (`builder.addModules(...)`), поэтому достаточно объявить бин
+ * этого типа. Закрывает tgu-follow-up из docs/standards/DATETIME_UTC.md: входящий REST-JSON теперь
+ * читается толерантно к обоим форматам времени (naive=UTC и `Z`), как и Jackson-2 путь
+ * ([CamundaJacksonConfig]).
+ */
+@Configuration
+class WebFluxJacksonConfig {
+
+    @Bean
+    fun pcpTimeModuleV3(): JacksonModule = PcpTimeModuleV3()
+}
@@ -0,0 +1,55 @@
+package space.nstart.pcp_tgu_service.config
+
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Test
+import tools.jackson.databind.json.JsonMapper
+import java.time.Instant
+import java.time.LocalDateTime
+import java.time.OffsetDateTime
+import java.time.ZoneOffset
+
+/**
+ * Слой толерантности времени на Jackson-3 пути (REST-кодеки WebFlux): [PcpTimeModuleV3] читает
+ * время в обоих форматах на проводе (naive=UTC и `Z`/офсет), нормализуя к UTC. Близнец
+ * библиотечного PcpTimeModuleTest на Jackson 2. См. docs/standards/DATETIME_UTC.md.
+ */
+class PcpTimeModuleV3Test {
+
+    private val mapper = JsonMapper.builder().addModule(PcpTimeModuleV3()).build()
+
+    @Test
+    fun `LocalDateTime reads naive and Z as the same UTC wall-clock`() {
+        val fromNaive = mapper.readValue("\"2026-05-29T01:00:00\"", LocalDateTime::class.java)
+        val fromZ = mapper.readValue("\"2026-05-29T01:00:00Z\"", LocalDateTime::class.java)
+
+        assertEquals(LocalDateTime.of(2026, 5, 29, 1, 0, 0), fromNaive)
+        assertEquals(LocalDateTime.of(2026, 5, 29, 1, 0, 0), fromZ)
+    }
+
+    @Test
+    fun `LocalDateTime normalizes an explicit offset to UTC`() {
+        // 01:00+03:00 == 28-го 22:00 UTC
+        val fromOffset = mapper.readValue("\"2026-05-29T01:00:00+03:00\"", LocalDateTime::class.java)
+
+        assertEquals(LocalDateTime.of(2026, 5, 28, 22, 0, 0), fromOffset)
+    }
+
+    @Test
+    fun `OffsetDateTime reads naive as UTC and normalizes offset to UTC`() {
+        val fromNaive = mapper.readValue("\"2026-05-29T01:00:00\"", OffsetDateTime::class.java)
+        val fromOffset = mapper.readValue("\"2026-05-29T01:00:00+03:00\"", OffsetDateTime::class.java)
+
+        assertEquals(OffsetDateTime.of(2026, 5, 29, 1, 0, 0, 0, ZoneOffset.UTC), fromNaive)
+        assertEquals(OffsetDateTime.of(2026, 5, 28, 22, 0, 0, 0, ZoneOffset.UTC), fromOffset)
+    }
+
+    @Test
+    fun `Instant reads naive(=UTC) and Z to the same moment`() {
+        val fromNaive = mapper.readValue("\"2026-05-29T01:00:00\"", Instant::class.java)
+        val fromZ = mapper.readValue("\"2026-05-29T01:00:00Z\"", Instant::class.java)
+
+        val expected = OffsetDateTime.of(2026, 5, 29, 1, 0, 0, 0, ZoneOffset.UTC).toInstant()
+        assertEquals(expected, fromNaive)
+        assertEquals(expected, fromZ)
+    }
+}