merge: W23 —— 接入契约 v0.63 的 documents[].reason（只在下发时原样显示，不做整句判断）

app/src/main/kotlin/top/yeij/cyrene/data/api/dto/DocumentDto.kt

@@ -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,
 )

app/src/main/kotlin/top/yeij/cyrene/domain/chat/DocumentChip.kt

@@ -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,
     )
 
     /** 扩展名大写；没有扩展名或扩展名不像扩展名时回「文件」（不猜类型）。 */

app/src/main/kotlin/top/yeij/cyrene/domain/chat/DocumentPreview.kt

@@ -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)

app/src/main/kotlin/top/yeij/cyrene/ui/chat/DocumentPreviewDialog.kt

@@ -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`，