接入契约 v0.63 的 documents[].reason：把「读不到的原因」原样送到附件预览弹层

后端 902b6ee / 契约 v0.63 给 historyMessage.documents[] 的元素加了可选字段 reason：只在 status == "unreadable" 时下发（Go omitempty，extracted 时整个键缺席），内容与后端注入模型清单里的那 10 条是同一份字符串，最长的一条 40+ 字。改了什么 - DocumentRefDto 加 reason: String? = null。documents[] 在 WS 握手 history、 message_persisted、GET /messages 三处共用这一个 DTO，所以一处解析三条路全覆盖。 KDoc 写明三条口径：可选、只在 unreadable 时下发、是后端原话所以客户端原样显示，且绝不做整句相等判断（需要分支只允许用稳定子串）。 - DocumentChipModel 加 reason，由 DocumentChips.of(ref) 取 ref.reason 去掉首尾空白后非空才留，否则归一成 null——一句空话会顶掉弹层里的通用说明，比没有更坏。芯片外观一个字没改：detail / statusLabel 保持现状（unreadable 仍显示「读不到」）。理由：那句话太长，塞进一行芯片只会被 Ellipsis 切掉半句，比不显示更糟。 - DocumentPreviewGate.plan 增加 reason 参数：非空白时直接作为正文区那句说明原样返回（NotText(reason)），压过本端按 mime / 扩展名的裁决；DocumentTarget.previewPlan 顺着 chips.reason 把它带进裁决。预览弹层本身一行代码都没改——它渲染的就是 plan.message 那句话，所以 reason 从 DTO 到用户看见的那句话整条链路上没有任何改写或截断。 - 配套单测 17 条。为什么这么改 - 服务端那句原因已经断言「无法抽取正文」，它比本端按类型编的通用说明（只知道类型、不知道到底为什么）准确；替它改写、归纳或截断就是丢掉服务端唯一一次说清原因的机会。 - 它也不该与正文并存：服务端说正文抽不出来，本端再把字节当 UTF-8 渲染，产出的正是正文闸要消灭的「看着像文件坏了」。 - reason 缺席时（契约 v0.63 之前的历史消息）产出与改之前逐字相同：兜底那句话、判据、文案全都不动。测试（新增 17 条） - DocumentDtoTest +5：unreadable 带 reason 逐字解出；extracted 元素没有该键 -> null； v0.62 风格的缺键载荷 -> null（不解码失败、不替服务端编一句话）；清单外的未知分类原样保留；显式 null -> null。 - DocumentChipTest +5：reason 带进模型；句中标点与换行原样、只去首尾空白；空白串 -> null；绝不进芯片副行（detail 逐字不变）；待发附件恒为 null。 - DocumentPreviewTest +7：reason 逐字成为正文区那句话（含未知分类，不丢不改不换兜底）；只 trim 一次再原样显示；缺席时与改前逐字相同（拿 refusalMessage 对比）；空白 reason 不改任何行为；text mime + reason 不再假装有正文。 - assembleDebug 通过；testDebugUnitTest 848 个测试 0 失败 0 错误 0 跳过。已知代价（已写进 KDoc，供人拍板）服务端判为读不到、但字节其实下得动的附件（例如超限的纯文本）会失去 App 内预览，「用其它应用打开」与「保存到下载目录」两条出口照旧完整可用——与「未知 mime 判为非文本」是同一笔不对称账。
2026-10-04 21:57:14 +08:00
1 parent a84d473e2f
commit e5fa1b871f
@@ -25,6 +25,8 @@ import kotlinx.serialization.Serializable
 * 3. 下行/历史元素只回**引用与统计，绝不回正文**（吸取 `G3`「base64 原样落库、每页历史重传」
 *    的教训）。`status:"unreadable"` 才是「读不到这个文件」的可观测信号，**不是** `truncated`
 *    （`truncated` 只说明注入正文被预算截断，正文照样进得了上下文）。
+ *    **契约 v0.63（后端 `902b6ee`）在此之上加了可选 [DocumentRefDto.reason]**：读不到时随
+ *    `status:"unreadable"` 一起下发的**服务端原话**，客户端原样显示（详见该字段的 KDoc）。
 *
 * ## 客户端必须两种都吃的一件事
 * 「0 个附件」这一形状在后端**尚未定死**（回执五原文：期望「不出现或空数组」，S3.5 回报里定死）。
@@ -58,8 +60,8 @@ data class DocumentUploadResponse(
 * 下行/历史则带上全部统计字段。
 *
 * 字段可出现性（后端 `history.DocumentRef` 的 `omitempty` 口径，逐字段核对过）：
- * `name` / `mime` / `size` **恒在**；`chars` / `truncated` / `status` 为 Go 的 `omitempty`
- * —— 零值（0 / false / ""）时**整键省略**，所以取值一律给默认值，解码不会因缺键失败。
+ * `name` / `mime` / `size` **恒在**；`chars` / `truncated` / `status` / `reason` 为 Go 的 `omitempty`
+ * —— 零值（0 / false / "" / nil）时**整键省略**，所以取值一律给默认值，解码不会因缺键失败。
 */
@Serializable
 data class DocumentRefDto(
@@ -80,4 +82,18 @@ data class DocumentRefDto(
     * 未知值**原样保留**（不丢弃、不报错、不占位符），由客户端决定如何显示。
     */
    val status: String = "",
+    /**
+     * **读不到的原因**（契约 v0.63 新增，后端 `902b6ee`）：`status == "unreadable"` 时下发的
+     * 那句**服务端原话**；`status == "extracted"` 时**整键缺席**，因此是可选字段。
+     *
+     * 两句纪律：
+     * 1. **原样显示**。[reason] 与后端**注入模型清单里的那 10 条是同一份字符串**（逐字相同，
+     *    最长的一条 40+ 字），客户端**不替服务端改写、不截断、不归纳**成自己的话——
+     *    本端能编的只有像 [top.yeij.cyrene.domain.chat.DocumentPreviewGate.refusalMessage]
+     *    那样「按类型泛泛说一句」，比这里的原因粗得多；
+     * 2. **绝不做整句相等判断**。分类若真的需要分支，只允许用**稳定子串**（如「需要 OCR」）——
+     *    整句比对会在后端改一个字时静默失效，且失败的样子是「显示成兜底那句话」，
+     *    看起来完全正常。
+     */
+    val reason: String? = null,
 )
@@ -27,6 +27,15 @@ data class DocumentChipModel(
    val truncatedLabel: String?,
    /** `status == "unreadable"`：这是唯一一个「昔涟读不到」的信号，UI 据此给灰态。 */
    val unreadable: Boolean,
+    /**
+     * 服务端「读不到」的**原话**（`documents[].reason`，契约 v0.63；只在 `unreadable` 时下发）。
+     * 已去掉首尾空白，空白串与缺席一律归一成 `null`。
+     *
+     * ⚠️ **刻意不进 [detail]**：这句话有 40+ 字，塞进芯片那一行只会被 `Ellipsis` 切掉半句，
+     * 比不显示更糟。它要出现的地方是**用户点开附件后的预览弹层**，见
+     * [DocumentTarget.previewPlan]。
+     */
+    val reason: String? = null,
 ) {
    /** 芯片副行：`MD · 12 KB · 8,000 字 · 已读入`（缺哪项少哪项，全缺就是空串）。 */
    val detail: String
@@ -54,6 +63,9 @@ object DocumentChips {
        statusLabel = statusLabel(ref.status),
        truncatedLabel = if (ref.truncated) TRUNCATED else null,
        unreadable = DocumentStatus.isUnreadable(ref.status),
+        // 首尾空白去掉；只剩空白（或本就缺席）时归一成 null——「有一句空话」比没有更坏：
+        // 弹层会拿它顶掉那句通用说明，于是用户看到一块什么都没有的正文区。
+        reason = ref.reason?.trim()?.takeIf { it.isNotEmpty() },
    )

    /** 一份**待发**附件 → 芯片模型：还没有服务端结论，所以状态与字数为空。 */
@@ -65,6 +77,8 @@ object DocumentChips {
        statusLabel = null,
        truncatedLabel = null,
        unreadable = false,
+        // 待发附件还没有任何服务端结论，也就没有「读不到的原因」可言。
+        reason = null,
    )

    /** 扩展名大写；没有扩展名或扩展名不像扩展名时回「文件」（不猜类型）。 */
@@ -60,10 +60,13 @@ data class DocumentTarget(
     * `mime`，本地待发附件**没有**服务端 `mime`（那时还没上传过），只能按显示名兜底。
     * 本地那条**刻意不问** `ContentResolver.getType`——平台给 `.rs` 这类文件常报
     * `application/octet-stream` 或空，拿它当判据会把一批纯文本文件挡在预览之外。
+     *
+     * 服务端下发的「读不到的原因」（[DocumentChipModel.reason]，契约 v0.63）在这里**顺路带进
+     * 裁决**：它是这句话唯一的去处（芯片那一行放不下 40+ 字），详见 [DocumentPreviewGate.plan]。
     */
    fun previewPlan(): DocumentPreviewPlan = when (val origin = source) {
-        is DocumentSource.Server -> DocumentPreviewGate.plan(origin.mime, origin.name)
-        is DocumentSource.Local -> DocumentPreviewGate.plan("", origin.displayName)
+        is DocumentSource.Server -> DocumentPreviewGate.plan(origin.mime, origin.name, chips.reason)
+        is DocumentSource.Local -> DocumentPreviewGate.plan("", origin.displayName, chips.reason)
    }

    /**
@@ -161,6 +164,9 @@ sealed interface DocumentPreviewPlan {
    /**
     * 非文本类（PDF 这类二进制内容）：**绝不把字节当 UTF-8 渲染**（那会是一整屏乱码），
     * 也**不假装加载失败**（这不是失败，字节取回来了，只是本端不预览它）。
+     *
+     * [message] 有两种来源，都是**原样显示**：本端按类型写的那句（[DocumentPreviewGate.refusalMessage]），
+     * 或服务端下发的「读不到的原因」原话（契约 v0.63 的 `documents[].reason`）。
     */
    data class NotText(val message: String) : DocumentPreviewPlan
 }
@@ -175,6 +181,8 @@ sealed interface DocumentPreviewPlan {
 * 实际是本端拿错了渲染方式。
 *
 * ## 判据（优先服务端，退而扩展名）
+ * 0. `reason` 非空白 ⇒ **直接就是正文区那句说明，原样显示**（契约 v0.63：服务端说读不到时
+ *    下发的原话，比本端按类型编的那句准确）。它压过下面三条，代价见 [plan] 的 KDoc；
 * 1. `mime` 非空 ⇒ **只看服务端那一次字节嗅探**（契约 §1.2：嗅探是唯一裁决权）：
 *    以 `text/` 开头的判为文本，其余（`application/pdf` / `application/octet-stream` / 图片型 …）
 *    一律判为**非文本**；
@@ -194,8 +202,23 @@ object DocumentPreviewGate {
    /**
     * @param mime 服务端 DTO 里的 `mime`（嗅探所得基类型）；待发附件传空串。
     * @param name 服务端存储名或待发附件的显示名——**只在 [mime] 为空时才看它**。
+     * @param reason 服务端下发的「读不到的原因」原话（`documents[].reason`，契约 v0.63；
+     *   已由 [top.yeij.cyrene.domain.chat.DocumentChips] 去掉首尾空白并在空白时归一成 `null`），
+     *   缺席 = 服务端没给，或这条引用本来就不是 `unreadable`。
+     *
+     * [reason] 非空白时**它直接就是正文区那句说明，原样显示**，不再走本端按 [mime] / 扩展名的
+     * 裁决——理由是这句话已经断言了「无法抽取正文」：
+     * - 它比本端那句通用说明（[refusalMessage]：只知道类型，不知道到底为什么）**准确**，
+     *   替它改写或归纳就是丢掉服务端唯一一次说清原因的机会；
+     * - 它也不该与正文并存：服务端说正文抽不出来，本端再把字节当 UTF-8 渲染，产出的正是这道
+     *   闸要消灭的「看着像文件坏了」。
+     *
+     * 代价说清楚：这条会让**服务端判为读不到、但字节其实下得动**的附件失去 App 内预览
+     * （例如超限的纯文本）。两条出口（用其它应用打开 / 保存到下载目录）照旧完整可用，
+     * 与下面「未知 mime 判为非文本」是同一笔不对称账。
     */
-    fun plan(mime: String, name: String): DocumentPreviewPlan {
+    fun plan(mime: String, name: String, reason: String? = null): DocumentPreviewPlan {
+        if (!reason.isNullOrBlank()) return DocumentPreviewPlan.NotText(reason)
        val base = baseType(mime)
        if (base.isEmpty()) return extensionPlan(name)
        return if (base.startsWith(TEXT_PREFIX)) DocumentPreviewPlan.Text else refuse(base)
@@ -70,6 +70,11 @@ data class DocumentPreviewNotice(val message: String, val error: Boolean = false
 * 只留 [DocumentPreviewPlan.NotText.message] 那句人话：**这既不是加载失败**（字节是取回来的，
 * 两条出口照旧可用），也不是「文件是空的」。
 *
+ * 那句话有两种来源，本弹层**一视同仁地原样渲染**：本端按类型写的那句，以及服务端说「读不到」
+ * 时下发的**原因原话**（契约 v0.63 的 `documents[].reason`，判定见
+ * [top.yeij.cyrene.domain.chat.DocumentPreviewGate.plan]）——本层不做任何改写或截断，
+ * 它拿到的 `message` 就是要显示的那句话。
+ *
 * ## 正文为什么是 `LazyColumn` + 分块
 * 上限是 5000 行 / 256 KB，整段塞进一个 `Text` 会让打开弹层的那一刻卡在排版上。切成
 * [top.yeij.cyrene.domain.chat.DocumentPreviewLimits.LINES_PER_CHUNK] 行一块交给 `LazyColumn`，
@@ -22,6 +22,8 @@ import top.yeij.cyrene.domain.chat.DocumentStatus
 * `5b2b385`（S3.5 文档多值化：`history.go` 的 `historyMessage.Documents` 带 `omitempty`、
 * `history.DocumentRef` 的 `omitempty` 口径、`history_document_test.go` 钉住的元素字段集
 * `chars,mime,name,size,status,truncated` 与它用的真实取值）。
+ * **契约 v0.63（后端 `902b6ee`）在此之上加了 `reason`**（只在 `status == "unreadable"` 时下发的
+ * 服务端原话）：那几条用例同样按「缺键 → `null`、有值 → 逐字原样」钉住，**不做整句相等判断**。
 * **没有 v0.59 的真实抓包（形状按 api-client §1.2 与后端实现逐条核对）**：这里的 JSON 是按上述实现形状逐字节手写的（唯一确认过的真实取值
 * 来自后端自己的测试夹具）。
 *
@@ -172,6 +174,69 @@ class DocumentDtoTest {
        assertEquals("", doc.status)
    }

+    // —— 契约 v0.63（后端 `902b6ee`）：`documents[].reason` ——
+
+    /**
+     * 后端注入模型清单里那 10 条中的一条，**真实串就是这么长**：逐字照抄，不做任何简化。
+     * 这里的用例一律拿它整串比对，就是为了钉住「客户端不改写、不截断」。
+     */
+    private val ocrReason = "无法抽取正文：这是图片型/无文本层 PDF，需要 OCR 才能读（当前未做）"
+
+    @Test
+    fun `an unreadable reference carries the server reason verbatim`() {
+        val doc = message(
+            withDocuments(
+                """[{"name":"$name","mime":"application/pdf","size":12345,"status":"unreadable",""" +
+                    """"reason":"$ocrReason"}]""",
+            ),
+        ).documents.single()
+
+        assertEquals(DocumentStatus.UNREADABLE, doc.status)
+        assertEquals(ocrReason, doc.reason)
+    }
+
+    @Test
+    fun `an extracted reference has no reason key at all`() {
+        // 服务端只在 status == "unreadable" 时填 `reason`（Go omitempty）：extracted 的元素里
+        // 整个键不存在 ⇒ 解出来必须是 `null`，**不是空串**——空串会顶掉弹层里那句通用说明。
+        val doc = message(
+            withDocuments(
+                """[{"name":"$name","mime":"text/plain","size":7,"chars":7,"status":"extracted"}]""",
+            ),
+        ).documents.single()
+
+        assertNull(doc.reason)
+    }
+
+    @Test
+    fun `a v0_62 style payload without the reason key still decodes`() {
+        // 契约 v0.63 之前的历史消息里没有这个键：解码不许失败，也不许替服务端编一句话。
+        val doc = message(withDocuments("""[{"name":"$name","status":"unreadable"}]""")).documents.single()
+
+        assertNull(doc.reason)
+    }
+
+    @Test
+    fun `a reason outside the ten known ones is preserved verbatim`() {
+        // 分类可以开放，客户端**不做整句相等判断**：没见过的那句照样原样留着。
+        val reason = "无法抽取正文：这条分类客户端从没见过"
+
+        val doc = message(
+            withDocuments("""[{"name":"$name","status":"unreadable","reason":"$reason"}]"""),
+        ).documents.single()
+
+        assertEquals(reason, doc.reason)
+    }
+
+    @Test
+    fun `an explicit null reason decodes as null`() {
+        val doc = message(
+            withDocuments("""[{"name":"$name","status":"unreadable","reason":null}]"""),
+        ).documents.single()
+
+        assertNull(doc.reason)
+    }
+
    // —— chat 请求：带附件与不带附件 ——

    @Test
@@ -14,7 +14,10 @@ import top.yeij.cyrene.data.api.dto.DocumentRefDto
 * 1. **状态与截断不许互相顶替**——`unreadable` 才是「读不到」，`truncated` 只说明注入被预算
 *    截断（正文照样进了上下文），两句文案必须分开；
 * 2. **未知 `status` 原样显示**（开放集合：不丢弃、不报错、不占位符）；
- * 3. 服务端**没报**的字段（`chars` 缺席、体积为 0/未知）不要编出一个数字来。
+ * 3. 服务端**没报**的字段（`chars` 缺席、体积为 0/未知）不要编出一个数字来；
+ * 4. 服务端下发的「读不到的原因」（契约 v0.63 的 `documents[].reason`）**原样**带进模型
+ *    （只去首尾空白；空白串归一成 `null`，因为一句空话会顶掉弹层里的通用说明），
+ *    且**绝不进芯片副行**——40+ 字在那里只会被切掉半句。
 */
 class DocumentChipTest {

@@ -25,6 +28,7 @@ class DocumentChipTest {
        chars: Int? = 8_000,
        truncated: Boolean = false,
        status: String = DocumentStatus.EXTRACTED,
+        reason: String? = null,
    ) = DocumentRefDto(
        name = name,
        mime = mime,
@@ -32,6 +36,7 @@ class DocumentChipTest {
        chars = chars,
        truncated = truncated,
        status = status,
+        reason = reason,
    )

    // —— 类型 ——
@@ -122,6 +127,56 @@ class DocumentChipTest {
        assertEquals("MD · 12.1 KB", chip.detail)
    }

+    // —— 服务端下发的「读不到的原因」（契约 v0.63）——
+
+    @Test
+    fun `the server reason rides along in the model`() {
+        val reason = "无法抽取正文：这是图片型/无文本层 PDF，需要 OCR 才能读（当前未做）"
+
+        assertEquals(reason, DocumentChips.of(ref(status = DocumentStatus.UNREADABLE, reason = reason)).reason)
+    }
+
+    @Test
+    fun `the reason keeps its own punctuation and newlines`() {
+        // 「原样」就是原样：只去首尾空白，句中标点与换行一个字都不动（这条串不是给本端归纳的）。
+        val reason = "无法抽取正文：第一行（括注）；第二行\n　带全角空格的细节"
+
+        assertEquals(
+            reason,
+            DocumentChips.of(ref(status = DocumentStatus.UNREADABLE, reason = "\n  $reason  \n")).reason,
+        )
+    }
+
+    @Test
+    fun `a blank reason is nothing, not an empty sentence`() {
+        // 空串会顶掉弹层里那句通用说明，用户看到的正文区就成了空的——比没有原因更坏。
+        assertNull(DocumentChips.of(ref(reason = null)).reason)
+        assertNull(DocumentChips.of(ref(reason = "")).reason)
+        assertNull(DocumentChips.of(ref(reason = "   ")).reason)
+        assertNull(DocumentChips.of(ref(reason = "\n\t\n")).reason)
+    }
+
+    @Test
+    fun `the reason never leaks into the chip line`() {
+        // 40+ 字塞进芯片那一行只会被 Ellipsis 切掉半句，比不显示更糟：`detail` 逐字不变。
+        val chip = DocumentChips.of(
+            ref(
+                chars = null,
+                status = DocumentStatus.UNREADABLE,
+                reason = "无法抽取正文：PDF 已加密（当前不支持）",
+            ),
+        )
+
+        assertEquals("MD · 12.1 KB · 读不到", chip.detail)
+        assertTrue(chip.unreadable)
+    }
+
+    @Test
+    fun `a draft attachment has no reason at all`() {
+        // 待发附件还没有任何服务端结论，也就没有「读不到的原因」可言。
+        assertNull(DocumentChips.of(DraftDocument(uri = "content://doc/1", displayName = "报告.md")).reason)
+    }
+
    // —— 副行拼接 ——

    @Test
@@ -21,14 +21,19 @@ import top.yeij.cyrene.data.repository.LocalDocumentUnavailableException
 * 3. 没有任何 App 能开时**如实告知**并指路保存，**不静默失败**；
 * 4. 来源判定只有一处（[DocumentTarget.of]），服务端来源**只能用存储名**当文件名；
 * 5. App 内**正文**只预览文本类（v0.61 的 `.pdf` 因此不会被当 UTF-8 渲染成一屏乱码），
- *    且非文本那句人话**不许读起来像失败**。
+ *    且非文本那句人话**不许读起来像失败**；
+ * 6. 服务端说「读不到」时下发的**原因原话**（契约 v0.63 的 `documents[].reason`）优先于本端
+ *    按类型编的那句，且**逐字**显示（没见过的原因也照原样，不做整句相等判断）；它缺席时
+ *    产出与加入该字段之前逐字相同。
 */
 class DocumentPreviewTest {

    private fun ref(
        name: String = "0123456789abcdef0123456789abcdef.md",
        mime: String = "text/plain",
-    ) = DocumentRefDto(name = name, mime = mime)
+        status: String = "",
+        reason: String? = null,
+    ) = DocumentRefDto(name = name, mime = mime, status = status, reason = reason)

    private fun filler(size: Int) = ByteArray(size) { 'a'.code.toByte() }

@@ -293,6 +298,84 @@ class DocumentPreviewTest {
        assertTrue(messages.toString(), messages.none { it.contains("失败") || it.contains("空文件") || it.contains("是空的") })
    }

+    // —— 服务端下发的「读不到的原因」（契约 v0.63：`documents[].reason`）——
+
+    /**
+     * 后端那 10 条里的一条，**逐字照抄**（真实串就是这么长）。
+     * 用整串相等断言是为了钉住「不改写、不截断、不归纳」——**不是**拿它当实现里的判据。
+     */
+    private val ocrReason = "无法抽取正文：这是图片型/无文本层 PDF，需要 OCR 才能读（当前未做）"
+
+    @Test
+    fun `the server reason becomes the sentence in the body area, verbatim`() {
+        val plan = DocumentTarget.of(
+            ref(
+                name = "0123456789abcdef0123456789abcdef.pdf",
+                mime = "application/pdf",
+                status = DocumentStatus.UNREADABLE,
+                reason = ocrReason,
+            ),
+        ).previewPlan()
+
+        assertEquals(DocumentPreviewPlan.NotText(ocrReason), plan)
+    }
+
+    @Test
+    fun `a reason outside the ten known ones is shown as it came`() {
+        // 客户端**不做整句相等判断**：没见过的原因照样原样进正文区，不丢、不改、不换兜底。
+        val reason = "无法抽取正文：这条分类客户端从没见过（契约同版的第 11 种）"
+
+        val plan = DocumentTarget.of(ref(status = DocumentStatus.UNREADABLE, reason = reason)).previewPlan()
+
+        assertEquals(DocumentPreviewPlan.NotText(reason), plan)
+    }
+
+    @Test
+    fun `the reason is trimmed once and then shown as it is`() {
+        // 首尾空白由 DocumentChips 去掉（免得弹层里那句话顶着一截空行），句中标点原样。
+        val reason = "无法抽取正文：PDF 损坏或无法解析；请重传（原文如此）"
+
+        val plan = DocumentTarget.of(
+            ref(status = DocumentStatus.UNREADABLE, reason = "  $reason  "),
+        ).previewPlan()
+
+        assertEquals(DocumentPreviewPlan.NotText(reason), plan)
+    }
+
+    @Test
+    fun `without a reason the body area keeps the very same sentence as before`() {
+        // 契约 v0.63 之前的历史消息不发 reason：这条路的产出必须与加入该字段之前逐字相同。
+        val plan = DocumentPreviewGate.plan("application/pdf", "0123456789abcdef0123456789abcdef.pdf")
+
+        assertEquals(DocumentPreviewPlan.NotText(DocumentPreviewGate.refusalMessage("PDF")), plan)
+    }
+
+    @Test
+    fun `a blank reason changes nothing at all`() {
+        val blank = DocumentPreviewGate.plan("application/pdf", "a.pdf", "   ")
+
+        assertEquals(DocumentPreviewGate.plan("application/pdf", "a.pdf"), blank)
+        // 尤为重要的是别把它当成一句话显示出来：那会得到一块什么都没有的正文区。
+        assertTrue((blank as DocumentPreviewPlan.NotText).message.isNotBlank())
+        assertEquals(DocumentPreviewPlan.Text, DocumentPreviewGate.plan("text/plain", "a.md", "\n"))
+    }
+
+    @Test
+    fun `a text mime with a reason no longer pretends to be a body`() {
+        // 服务端已经说了「无法抽取正文」，本端再把字节当 UTF-8 渲染就是同一类「看着像文件坏了」。
+        val reason = "无法抽取正文：读取或解析失败"
+
+        assertEquals(DocumentPreviewPlan.NotText(reason), DocumentPreviewGate.plan("text/plain", "a.md", reason))
+    }
+
+    @Test
+    fun `the reason takes precedence over the extension fallback used by drafts`() {
+        val reason = "无法抽取正文：本期不解析 Office 文档"
+
+        assertEquals(DocumentPreviewPlan.NotText(reason), DocumentPreviewGate.plan("", "报告.pdf", reason))
+        assertEquals(DocumentPreviewPlan.NotText(reason), DocumentPreviewGate.plan("", "笔记.md", reason))
+    }
+
    // —— 没有 App 能开 ——

    @Test