fix(http): make response.json() encode what the type declares

Two defects in the same expression. The bare Json drops every field whose
value happens to equal its declared default, so fee=0 and status=0 vanish
and the client cannot tell them from a missing field - a withdrawal
rendered as NaN and a status of 'unknown' in production on 2026-07-26.
Kotlin clients never see it because they restore defaults on decode, so
this only ever breaks the JS side.

The second one hid behind the first: the parameter is Any, so the reified
serializer() resolves for Any and the branch threw SerializationException
for every object. The only non-String caller is the rate limiter, which
means hitting a rate limit returned a serialization error instead of the
429 body.

Encode Map/List/primitives through JsonElement, and reject anything else
with a message that says what to do instead.

Author: zoujiaqing

neton-core/src/commonMain/kotlin/neton/core/http/HttpResponse.kt

@@ -1,6 +1,59 @@
 package neton.core.http
 
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonNull
 import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+
+/**
+ * 响应体序列化 Json。
+ *
+ * `encodeDefaults = true` 是**契约要求**，不是可选项：kotlinx 的裸 `Json` 默认
+ * `encodeDefaults = false`，会把任何「当前值恰好等于声明默认值」的字段**从响应
+ * JSON 里整个删掉**。对客户端而言这与「这个字段不存在」无法区分——提现单
+ * `fee = 0`、`status = 0(待审核)` 被丢掉后，H5 拿到 `undefined`，渲染出
+ * `¥NaN.NaN` 和状态「未知」（2026-07-26 生产实测，一个根因炸三处）。
+ *
+ * **响应字段集必须由类型决定，不能由运行时取值决定。**
+ *
+ * 这一条 KSP 生成的路由（`ControllerProcessor.responseJson`）与两个适配器的
+ * envelope 序列化都已遵守；本文件是同一条路径上最后一个还在用裸 `Json` 的出口。
+ *
+ * Kotlin 客户端感知不到这个 bug——它反序列化时会把缺失字段补回声明的默认值。
+ * 只有 JS/TS 端才炸，所以它极容易在联调里被漏掉。
+ */
+private val responseJson = Json { encodeDefaults = true }
+
+/**
+ * 把 Map / List / 原始类型转成 [JsonElement]。
+ *
+ * 这里**不能**用 `Json.encodeToString(serializer(), data)`：`json()` 的形参声明成 `Any`，
+ * reified 的 `serializer()` 就只能解析出 `Any` 的序列化器，运行期直接
+ * `SerializationException`。也就是说这个分支此前对**任何**对象都是抛异常——
+ * 包括限流拦截器传进来的那个 `mapOf("code" to 429, ...)`：触发限流时返回给客户端的
+ * 不是 429 JSON，而是一个序列化异常。
+ *
+ * `@Serializable` 业务对象不走这条路：它们由 KSP 生成的路由预序列化成 `JsonContent`
+ * （那条路径自带 `encodeDefaults = true`）。这里只兜底 Map / List / 原始类型，
+ * 遇到别的类型显式报错，说清该怎么办——而不是留一个看不懂的序列化异常。
+ */
+private fun Any?.toResponseJsonElement(): JsonElement = when (this) {
+    null -> JsonNull
+    is JsonElement -> this
+    is String -> JsonPrimitive(this)
+    is Boolean -> JsonPrimitive(this)
+    is Number -> JsonPrimitive(this)
+    is Map<*, *> -> JsonObject(entries.associate { (k, v) -> k.toString() to v.toResponseJsonElement() })
+    is Iterable<*> -> JsonArray(map { it.toResponseJsonElement() })
+    is Array<*> -> JsonArray(map { it.toResponseJsonElement() })
+    else -> throw IllegalArgumentException(
+        "HttpResponse.json() only accepts a pre-encoded String, a JsonElement, or Map/List/primitives. " +
+            "Got ${this::class.simpleName}. Serialize @Serializable types with a Json configured " +
+            "with encodeDefaults = true (or return them from a controller and let KSP do it).",
+    )
+}
 
 /**
  * 流式响应体写出器。由 [HttpResponse.stream] 提供，逐块写出响应体。
@@ -150,9 +203,7 @@ interface HttpResponse {
         val jsonString = when (data) {
             is String -> data
             is JsonObject -> data.toString()
-            else -> kotlinx.serialization.json.Json.encodeToString(
-                kotlinx.serialization.serializer(), data
-            )
+            else -> responseJson.encodeToString(JsonElement.serializer(), data.toResponseJsonElement())
         }
         write(jsonString.encodeToByteArray())
     }

neton-core/src/commonTest/kotlin/neton/core/http/ResponseEncodeDefaultsContractTest.kt

@@ -0,0 +1,108 @@
+package neton.core.http
+
+import kotlinx.coroutines.runBlocking
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+import kotlin.test.Test
+import kotlin.test.assertContains
+import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
+
+/**
+ * 契约：**响应字段集由类型决定，不由运行时取值决定。**
+ *
+ * kotlinx 的裸 `Json` 默认 `encodeDefaults = false`，会把任何「当前值恰好等于声明默认值」
+ * 的字段整个从响应 JSON 里删掉。客户端拿到的是「字段不存在」，与「字段值是 0」无从区分。
+ *
+ * 2026-07-26 生产实测：提现单 `fee = 0`、`status = 0(待审核)` 被丢掉，H5 渲染出
+ * `¥NaN.NaN` 和状态「未知」；同一个根因还让后台的审批按钮永远不显示。
+ *
+ * 特别阴险的是 **Kotlin 客户端感知不到**——反序列化时缺失字段会被补回声明的默认值，
+ * 于是 Kotlin↔Kotlin 的联调全绿，只有 JS/TS 端炸。所以这条必须由测试守着，
+ * 不能指望联调发现。
+ */
+class ResponseEncodeDefaultsContractTest {
+
+    @Serializable
+    private data class WithdrawalVO(
+        val id: Long = 0,
+        /** 手续费为 0 是最常见的正常值，不是「没有值」。 */
+        val fee: Long = 0,
+        /** 0 = 待审核，恰好是默认值，也恰好是后台最需要看到的那个状态。 */
+        val status: Int = 0,
+        val remark: String = "",
+    )
+
+    private class RecordingResponse : HttpResponse {
+        override var status: HttpStatus = HttpStatus.OK
+        override val headers: MutableHeaders = TestHeaders()
+        override val isCommitted: Boolean get() = body != null
+        var body: String? = null
+        override fun cookie(cookie: Cookie) {}
+        override suspend fun write(data: ByteArray) { body = data.decodeToString() }
+    }
+
+    /**
+     * 业务 VO 走的是 KSP 生成的路由：预序列化成字符串再交给 `json()`。
+     * 这条断言的是那份预序列化必须带 `encodeDefaults = true`——裸 `Json` 会把
+     * 整个对象编成 `{}`。
+     */
+    @Test
+    fun fieldsEqualToTheirDefaultsSurviveSerialization() {
+        val responseJson = Json { encodeDefaults = true }
+        val body = responseJson.encodeToString(WithdrawalVO.serializer(), WithdrawalVO())
+
+        assertContains(body, "\"fee\"", message = "fee dropped -> client renders NaN: $body")
+        assertContains(body, "\"status\"", message = "status dropped -> client shows 'unknown': $body")
+
+        // 反过来确认这条测试确实在测东西：裸 Json 会把它整个编空。
+        assertEquals("{}", Json.encodeToString(WithdrawalVO.serializer(), WithdrawalVO()))
+    }
+
+    /**
+     * 限流拦截器传的就是这个形状。
+     *
+     * 修复前这里会抛 `SerializationException`——`json()` 的形参是 `Any`，reified 的
+     * `serializer()` 只能解析出 `Any` 的序列化器。也就是说**触发限流时客户端拿到的
+     * 不是 429 JSON，而是一个序列化异常**。
+     */
+    @Test
+    fun mapPayloadsAreEncodedInsteadOfThrowing() = runBlocking {
+        val response = RecordingResponse()
+        response.json(mapOf("code" to 429, "message" to "too many requests"))
+
+        val body = response.body ?: error("nothing was written")
+        assertContains(body, "\"code\":429")
+        assertContains(body, "\"message\":\"too many requests\"")
+    }
+
+    @Test
+    fun nestedListsAndNullsSurvive() = runBlocking {
+        val response = RecordingResponse()
+        response.json(mapOf("items" to listOf(1, 2), "next" to null))
+        assertEquals("""{"items":[1,2],"next":null}""", response.body)
+    }
+
+    /** 传字符串时按原样写出，不重新序列化（KSP 预序列化就走这条）。 */
+    @Test
+    fun preEncodedStringsPassThroughUnchanged() = runBlocking {
+        val response = RecordingResponse()
+        response.json("""{"already":"encoded"}""")
+        assertEquals("""{"already":"encoded"}""", response.body)
+    }
+
+    /**
+     * 不认识的类型必须显式报错，说清该怎么办。
+     *
+     * 留一个看不懂的 `SerializationException` 才是最坏的：调用方会以为是数据问题，
+     * 而真正的原因是这个入口本来就不接受任意对象。
+     */
+    @Test
+    fun unsupportedTypesFailLoudlyWithAnActionableMessage() = runBlocking {
+        val response = RecordingResponse()
+        val error = assertFailsWith<IllegalArgumentException> {
+            response.json(WithdrawalVO())
+        }
+        assertContains(error.message ?: "", "encodeDefaults")
+    }
+}