feat(data,domain): 文档进对话数据层（v0.59 待发布形状 + 该不该走文件判定）
契约 v0.59 尚未发布（api-client.md 最新仍是 v0.58），形状依据
devdocs/02 回执五「契约形状修正」，并用后端已落库切片逐字段核对：
407c934（S1 存储端点）、a4789ec（S3-B 网关入口）、5b2b385（S3.5 多值化）。
新增：
- data/api/DocumentsApi.kt：POST /api/v1/documents（multipart 字段 file）、
GET /api/v1/documents/{name}（Bearer owner|admin；@Streaming 取字节）
- data/api/dto/DocumentDto.kt：文档形状的唯一落点（v0.59 若不同只改这里）
- data/repository/DocumentRepository.kt：200 + deduped:true 当成功；url 是相对
路径故不做图片那套绝对化校验；不做本地白名单/大小上限（服务端才是裁决者）
- domain/chat/DocumentDelivery.kt：该不该走文件的判定 + chat.documents 载荷构造
- domain/chat/DocumentStatus.kt / DocumentFailure.kt：状态与四个错误码的可分支映射
改动：
- ChatDto.ChatRequest 增 documents（默认空列表 ⇒ 旧请求逐字节不变，有字面量钉子）
- MessageDto.HistoryMessageDto 增 documents（缺键与空数组都解成空列表，覆盖
后端「0 个」尚未定死的两种形状；WS message_persisted / history 回放共用该 DTO）
- ChatSendRouting.channelFor 增 hasDocuments（默认 false）：带附件强制 REST，
因为 WS 帧 4096 字节硬上限超限是直接断连，且文档一律走 REST
为什么不做 UI/VM：UI 与 ViewModel 文件由并行的分享入口模块占用，接线由主代理统一做。
测试：353 → 413（+60：DTO 12 / Repository 17 / Delivery 21 / Failure 10），
assembleDebug 与 testDebugUnitTest 均通过。
This commit is contained in:
AskaEth committed
1 parent
664fd8dcef
commit
095d6e781e
13 files changed
+1498
-1
No files matched your search
@@ -0,0 +1,68 @@
|
||||
package top.yeij.cyrene.data.api
|
||||
|
||||
import okhttp3.MultipartBody
|
||||
import okhttp3.ResponseBody
|
||||
import retrofit2.Response
|
||||
import retrofit2.http.GET
|
||||
import retrofit2.http.Multipart
|
||||
import retrofit2.http.POST
|
||||
import retrofit2.http.Part
|
||||
import retrofit2.http.Path
|
||||
import retrofit2.http.Streaming
|
||||
import top.yeij.cyrene.data.api.dto.DocumentUploadResponse
|
||||
|
||||
/**
|
||||
* 文档存储端点（契约 **v0.59 待发布**，形状依据见 `02-前后端协同事项.md` 回执五 §一 S1）。
|
||||
* 权限 `owner|admin`。与图片链路（[UploadApi] + `/api/v1/files/{name}`）**刻意分离**：
|
||||
*
|
||||
* | | 图片 | 文档 |
|
||||
* |---|---|---|
|
||||
* | 上传字段名 | `file` | `file`（同） |
|
||||
* | 上限 | 5 MiB | 20 MiB（`CHAT_DOCUMENT_MAX_BYTES` 默认，**与图片上限解耦**） |
|
||||
* | 读侧鉴权 | **不需要**（名字即凭据，供 `<img>`/provider 直接取） | **要 Bearer `owner|admin`** |
|
||||
* | 读侧响应 | 可内联渲染 | `Content-Disposition: attachment` + `nosniff`（**永不渲染**） |
|
||||
* | 成功载荷的 url | **绝对**同源地址，可直接当 `chat.image` | **相对**路径，客户端要的是 `name` |
|
||||
*
|
||||
* 为什么文档读侧要鉴权而图片不要：文档的摄取在**服务端**完成（正文进上下文），
|
||||
* 客户端不需要把一个「名字即凭据」的读侧打开；图片则必须被 `<img>` 与 provider 直接消费。
|
||||
*
|
||||
* ## 鉴权拦截器这一侧没问题的依据
|
||||
* Bearer 不是按接口挂的，而是**按 OkHttpClient** 挂的：[ApiClientFactory.create] 给每个
|
||||
* 客户端都装了 `AuthInterceptor`（`Authorization: Bearer <token>` + 401 单飞续期），
|
||||
* 因此只要 [DocumentRepository] 拿到的 `DocumentsApi` 是从 `ApiClientFactory.create` 建的
|
||||
* （`AppContainer` 里照 [UploadApi] 的写法），**两个端点都自带 Bearer**，不需要额外加头。
|
||||
*/
|
||||
interface DocumentsApi {
|
||||
|
||||
/**
|
||||
* 上传一份文档。
|
||||
*
|
||||
* @param file **部件名必须是 `file`**（服务端 `r.FormFile("file")`）；**文件名必须带扩展名**，
|
||||
* 且该扩展名要落在服务端的 deny-by-default 白名单里——与图片不同，这里的名字
|
||||
* **真的参与裁决**（白名单扩展名 + 字节嗅探**合取**，两者都过才放行）。
|
||||
* 服务端随后丢弃该名字，按内容寻址重命名为 `<sha256[:32]><ext>`，所以名字里
|
||||
* 除了扩展名以外的内容不会被采用（也不会进路径）。
|
||||
*
|
||||
* 返回原始 [Response]：**`200` 不是错误**——同一份字节重复上传回 `200` + 同一个 `name` +
|
||||
* `deduped:true`，客户端必须当成功。状态码本身不承载额外语义（`413`/`415` 的区分在
|
||||
* `error.code` 里），所以仓库层可以直接走 [apiCall]。
|
||||
*/
|
||||
@Multipart
|
||||
@POST("api/v1/documents")
|
||||
suspend fun upload(@Part file: MultipartBody.Part): Response<ApiEnvelope<DocumentUploadResponse>>
|
||||
|
||||
/**
|
||||
* 取回一份文档的原始字节。
|
||||
*
|
||||
* 它**不是信封**（响应体就是文件本身），所以返回 [ResponseBody]：解码器只处理
|
||||
* `application/json`，这里必须自己读字节并在仓库层负责关闭。
|
||||
* [Streaming] 让 Retrofit 不把响应体一次性读进内存（单份最大 20 MiB，边界情况不小）。
|
||||
*
|
||||
* @param name 服务端存储名（`<32hex>.<ext>`）。形态非法 / 不存在服务端都回
|
||||
* `404 document_not_found`（不区分「非法」与「没有」），因此这里不做本地形态校验、
|
||||
* 也不拿它拼任何本地路径。
|
||||
*/
|
||||
@Streaming
|
||||
@GET("api/v1/documents/{name}")
|
||||
suspend fun download(@Path("name") name: String): Response<ResponseBody>
|
||||
}
|
||||
@@ -20,6 +20,10 @@ import kotlinx.serialization.Serializable
|
||||
* ⚠️ 本项目 `ApiClientFactory.json` 用 kotlinx 默认的 `encodeDefaults = false`：
|
||||
* 取值等于默认值的字段**整键省略**。因此**纯图片消息**（`text == ""`）线上不会带 `text` 键——
|
||||
* 服务端 Go 侧零值同为空串，语义完全等价（已按此实现，见 [ChatDtoRealPayloadTest]）。
|
||||
*
|
||||
* [documents] 同理：默认空列表 ⇒ **不带附件的请求线上与加入该字段之前逐字节相同**
|
||||
* （服务端 `Documents []chatDocumentRef \`json:"documents,omitempty"\`` 零值也省略，
|
||||
* 见 `DocumentDtoTest` 里拿字面量 JSON 对比的那条钉子）。
|
||||
*/
|
||||
@Serializable
|
||||
data class ChatRequest(
|
||||
@@ -30,6 +34,18 @@ data class ChatRequest(
|
||||
val mode: String? = null,
|
||||
val stream: Boolean? = null,
|
||||
val clientMsgId: String? = null,
|
||||
/**
|
||||
* 本回合附带的文档引用（契约 v0.59 待发布，形状见 [DocumentRefDto]）：**≤5 条**，
|
||||
* 每条**只给服务端存储名**（`{"name":"<32hex>.<ext>"}`），**不收 URL**。
|
||||
*
|
||||
* 上行只发 `name`：其它字段服务端一律不采信并覆盖（字节嗅探是唯一的类型裁决）。
|
||||
* 空列表 → 整键省略（`encodeDefaults = false`），旧请求逐字节不变。
|
||||
*
|
||||
* ⚠️ **带附件一律走 REST**：文档本体经 `POST /api/v1/documents` 上传，引用随
|
||||
* `POST /api/v1/chat` 发出（[top.yeij.cyrene.domain.chat.DocumentDelivery] 的判定）；
|
||||
* WS `chat` 帧的 4096 字节读上限仍在，且上行帧里没有承载附件的余地。
|
||||
*/
|
||||
val documents: List<DocumentRefDto> = emptyList(),
|
||||
)
|
||||
|
||||
/**
|
||||
|
||||
@@ -0,0 +1,83 @@
|
||||
package top.yeij.cyrene.data.api.dto
|
||||
|
||||
import kotlinx.serialization.Serializable
|
||||
|
||||
/**
|
||||
* 文档 DTO —— 「文件进对话」的**唯一形状落点**（契约 **v0.59 尚未发布**）。
|
||||
*
|
||||
* ## 形状从哪来
|
||||
* 写这份代码时 `Cyrene_v2/Docs/api-client.md` 的最新契约版本仍是 **v0.58**（里面**没有**
|
||||
* `documents` 任何形状）。因此形状依据是
|
||||
* `Cyrene-For-Android/devdocs/02-前后端协同事项.md` 的 **回执五**（2026-10-04 深夜，
|
||||
* 标题即「一条契约形状修正」），并用后端仓库已落库的三个切片逐字段核对过：
|
||||
* `407c934`（S1 存储端点）/ `a4789ec`（S3-B 网关入口）/ `5b2b385`（S3.5 文档多值化）。
|
||||
*
|
||||
* **形状要变只改本文件。** 上行（`documents:[{name}]`）与下行/历史（`documents:[{…}]`）
|
||||
* 是**同一个元素类型**（[DocumentRefDto]）：服务端两条入口共用一处解析，这里也共用一个类。
|
||||
*
|
||||
* ## 回执五 §二「请以此为准」的三条
|
||||
* 1. **单对象 `document` 已作废**，一律**数组** `documents`（≤5）——修的是「一回合 5 个附件，
|
||||
* 历史与后续上下文里只留第一个」这个实测确认的缺陷；
|
||||
* 2. 上行元素**只给服务端存储名 `name`，绝不收 URL**（不收 URL 是为了不重开 `F3` 那种
|
||||
* 「服务端代取 URL」的 SSRF 面）；谎报的 `mime`/`url`/`size` 会被服务端覆盖，
|
||||
* **类型裁决只有字节嗅探一条**（客户端声明的 `Content-Type` 与文件名只作参考、可被否决，
|
||||
* 所以一个 `data.json` 可能被回成 `text/plain`）；
|
||||
* 3. 下行/历史元素只回**引用与统计，绝不回正文**（吸取 `G3`「base64 原样落库、每页历史重传」
|
||||
* 的教训）。`status:"unreadable"` 才是「读不到这个文件」的可观测信号，**不是** `truncated`
|
||||
* （`truncated` 只说明注入正文被预算截断，正文照样进得了上下文）。
|
||||
*
|
||||
* ## 客户端必须两种都吃的一件事
|
||||
* 「0 个附件」这一形状在后端**尚未定死**（回执五原文：期望「不出现或空数组」，S3.5 回报里定死）。
|
||||
* 因此本包的解析一律按**缺失键 → 空列表**、**空数组 → 空列表**两条都收：
|
||||
* 详见 [HistoryMessageDto.documents] 与 [ChatRequest.documents] 的默认值。
|
||||
*/
|
||||
@Serializable
|
||||
data class DocumentUploadResponse(
|
||||
/** 服务端存储名：32 位小写十六进制 + 白名单扩展名。**上行引用时唯一能用的字段**。 */
|
||||
val name: String = "",
|
||||
/**
|
||||
* **相对**同源路径（`/api/v1/documents/<name>`），与图片上传的**绝对** URL 不同：
|
||||
* 读侧要 Bearer `owner|admin`，所以它不是「贴进 `<img>` 就能取」的能力 URL，绝对化没有意义。
|
||||
* 客户端真正要用的是 [name]。
|
||||
*/
|
||||
val url: String = "",
|
||||
/** 服务端**字节嗅探**所得的基类型（不是客户端声明的），如 `text/plain`。 */
|
||||
val mime: String = "",
|
||||
val size: Long = 0,
|
||||
/** 内容寻址的哈希（64 位小写十六进制）：落盘名就是它的前 32 位 + 扩展名。 */
|
||||
val sha256: String = "",
|
||||
/**
|
||||
* `true` = 同一份字节（同扩展名）之前已经上传过：服务端回 `200` + **同一个** `name`，
|
||||
* **必须当成功处理，不是错误**。`false` = 首次上传（`201`）。
|
||||
*/
|
||||
val deduped: Boolean = false,
|
||||
)
|
||||
|
||||
/**
|
||||
* 一条文档引用。**上行只发 [name]**（其余字段服务端不采信、会覆盖），
|
||||
* 下行/历史则带上全部统计字段。
|
||||
*
|
||||
* 字段可出现性（后端 `history.DocumentRef` 的 `omitempty` 口径，逐字段核对过）：
|
||||
* `name` / `mime` / `size` **恒在**；`chars` / `truncated` / `status` 为 Go 的 `omitempty`
|
||||
* —— 零值（0 / false / ""）时**整键省略**，所以取值一律给默认值，解码不会因缺键失败。
|
||||
*/
|
||||
@Serializable
|
||||
data class DocumentRefDto(
|
||||
/** 服务端存储名（`<32hex>.<ext>`）。客户端**本地**的原始文件名不在这里，也不该在这里。 */
|
||||
val name: String = "",
|
||||
val mime: String = "",
|
||||
val size: Long = 0,
|
||||
/** 本次**注入上下文**的字符数（被预算截断者填截断后的值）；`null` = 服务端未报告。 */
|
||||
val chars: Int? = null,
|
||||
/**
|
||||
* 注入正文是否被预算截断：`true` 只说明进上下文的那段被截短了，**不是**「读不到」——
|
||||
* 读不到看 [status]（`unreadable`）。两个信号刻意分开，别互相顶替。
|
||||
*/
|
||||
val truncated: Boolean = false,
|
||||
/**
|
||||
* 抽取状态：`extracted` / `listed` / `unreadable`（见
|
||||
* [top.yeij.cyrene.domain.chat.DocumentStatus]）。**开放集合，不用 enum**：
|
||||
* 未知值**原样保留**（不丢弃、不报错、不占位符），由客户端决定如何显示。
|
||||
*/
|
||||
val status: String = "",
|
||||
)
|
||||
@@ -5,6 +5,9 @@ import kotlinx.serialization.Serializable
|
||||
/**
|
||||
* `GET /api/v1/sessions/{id}/messages` 单条消息（api-reference §3.4）。
|
||||
* 服务端按 `createdAt` 倒序返回，渲染前需 reverse / merge。
|
||||
*
|
||||
* 它同时是 WS 握手 `history` 回放与 `message_persisted` 的载荷消息类型
|
||||
* （服务端三处共用同一个 `historyMessage`），所以 [documents] 的解析一处覆盖三条路。
|
||||
*/
|
||||
@Serializable
|
||||
data class HistoryMessageDto(
|
||||
@@ -27,5 +30,17 @@ data class HistoryMessageDto(
|
||||
* 空 = 这条消息没有键（老客户端发的、IM 镜像进来的、v0.56 之前的历史行）。
|
||||
*/
|
||||
val clientMsgId: String? = null,
|
||||
/**
|
||||
* 这条消息携带的文档引用与抽取统计（契约 v0.59 待发布；形状见 [DocumentRefDto]）。
|
||||
*
|
||||
* 默认 [emptyList] 同时吃掉后端**尚未定死**的两种「0 个附件」形状：
|
||||
* **键缺失 → 空列表**（后端 `historyMessage.Documents` 带 `omitempty`，空/缺失即整键省略——
|
||||
* 这一点已对着 `5b2b385` 的实现与 `history_document_test.go` 的断言核对过）、
|
||||
* **空数组 → 空列表**（S3.5 之前写下的行、以及将来若改回恒下发 `[]`）。
|
||||
*
|
||||
* 只回引用与统计、**绝不回正文**；未知 `status` **原样保留**（开放集合，见 [DocumentRefDto]）。
|
||||
* WS `message_persisted` 与握手 `history` 回放用的是同一个 DTO，因此这一处解析两条路都覆盖。
|
||||
*/
|
||||
val documents: List<DocumentRefDto> = emptyList(),
|
||||
val createdAt: Long,
|
||||
)
|
||||
@@ -0,0 +1,142 @@
|
||||
package top.yeij.cyrene.data.repository
|
||||
|
||||
import kotlinx.coroutines.CancellationException
|
||||
import kotlinx.coroutines.CoroutineDispatcher
|
||||
import kotlinx.coroutines.Dispatchers
|
||||
import kotlinx.coroutines.withContext
|
||||
import okhttp3.MediaType.Companion.toMediaTypeOrNull
|
||||
import okhttp3.MultipartBody
|
||||
import okhttp3.RequestBody.Companion.toRequestBody
|
||||
import top.yeij.cyrene.core.error.CyreneError
|
||||
import top.yeij.cyrene.data.api.ApiErrorMapper
|
||||
import top.yeij.cyrene.data.api.CyreneException
|
||||
import top.yeij.cyrene.data.api.DocumentsApi
|
||||
import top.yeij.cyrene.data.api.apiCall
|
||||
|
||||
/**
|
||||
* 一次成功上传的文档。
|
||||
*
|
||||
* **首次上传（`201`）与去重命中（`200`）返回的是同一个结果**——区别只在 [deduped]：
|
||||
* 服务端对「同一份字节 + 同一扩展名」回同一个 [name]，调用方**必须当成功处理**，
|
||||
* 唯一的差别是可以据此少显示一次「已上传」的进度。
|
||||
*
|
||||
* [url] 是**相对**同源路径（`/api/v1/documents/<name>`），与图片上传的绝对 URL 不同：
|
||||
* 读侧要 Bearer，客户端真正要用的是 [name]。它留着只为排查与展示，**不要**当 `chat.image`
|
||||
* 那样的可直接取用地址。
|
||||
*/
|
||||
data class UploadedDocument(
|
||||
val name: String,
|
||||
val url: String,
|
||||
val mime: String,
|
||||
val size: Long,
|
||||
val sha256: String,
|
||||
val deduped: Boolean,
|
||||
)
|
||||
|
||||
/**
|
||||
* 文档取数层（`POST /api/v1/documents` 上传、`GET /api/v1/documents/{name}` 取字节）。
|
||||
*
|
||||
* ## 与图片上传（[UploadRepository]）的三处刻意的不同
|
||||
* 1. **文件名参与裁决**：服务端把**白名单扩展名**与**字节嗅探**合取，两者都过才放行
|
||||
* （图片只看嗅探）。所以 [fileName] 必须原样带上真实扩展名，不能像图片那样自己编一个；
|
||||
* 2. **`200` 是成功**：同一份字节重复上传回 `200` + 同一个 name + `deduped:true`，
|
||||
* **不是错误**。这条由 [apiCall] 天然成立（它只看「2xx 且信封里有 data」）；
|
||||
* 3. **`url` 不做绝对化校验**：文档的 url 本来就是相对路径（读侧要 Bearer），
|
||||
* 照搬图片那条「不是 http(s) 就判失败」的规则会把每一次成功上传都判成解析失败。
|
||||
*
|
||||
* ## 错误语义
|
||||
* 用 [apiCall]：状态码**不承载额外语义**（`413` / `415` / `400` / `404` 的机器可读区分
|
||||
* 全在 `error.code` 里），仓库只把它折进 `Result.failure`；调用方用
|
||||
* [top.yeij.cyrene.domain.chat.toDocumentFailure] 收敛成可分支的失败类型。
|
||||
*
|
||||
* ## 客户端不做的事（服务端才是裁决者）
|
||||
* **不做本地扩展名白名单、不做本地 20 MiB 上限**：白名单与上限都是服务端配置（上限是
|
||||
* `CHAT_DOCUMENT_MAX_BYTES`，可部署改），客户端复制一份必然漂移——把「本地觉得不行」当成
|
||||
* 拒绝，就会出现「服务端其实收得下、客户端却拦了」的静默更严。这里宁可让服务端回一个
|
||||
* 带真实上限的 `413` / `415`，让用户看到准确的理由。
|
||||
*/
|
||||
class DocumentRepository(
|
||||
private val api: DocumentsApi,
|
||||
private val dispatcher: CoroutineDispatcher = Dispatchers.IO,
|
||||
) {
|
||||
|
||||
/** 上传一份文档（[bytes] 与 [fileName] 必须来自同一个文件）。 */
|
||||
suspend fun upload(bytes: ByteArray, fileName: String): Result<UploadedDocument> =
|
||||
withContext(dispatcher) {
|
||||
apiCall { api.upload(partOf(bytes, fileName)) }.fold(
|
||||
onSuccess = { data ->
|
||||
if (data.name.isBlank()) {
|
||||
// 201/200 却没有可用存储名 = 上传了但引用不上，判解析失败。
|
||||
// **绝不**退回「用本地文件名」——服务端已经把它丢掉了，引用一个不存在的名字
|
||||
// 只会让这一轮在服务端回 404。
|
||||
Result.failure(CyreneException(CyreneError.Local(CyreneError.LocalKind.Parse)))
|
||||
} else {
|
||||
Result.success(
|
||||
UploadedDocument(
|
||||
name = data.name,
|
||||
url = data.url,
|
||||
mime = data.mime,
|
||||
size = data.size,
|
||||
sha256 = data.sha256,
|
||||
deduped = data.deduped,
|
||||
),
|
||||
)
|
||||
}
|
||||
},
|
||||
onFailure = { Result.failure(it) },
|
||||
)
|
||||
}
|
||||
|
||||
/**
|
||||
* 取回一份文档的原始字节。
|
||||
*
|
||||
* 响应体**不是信封**（就是文件本身），所以这里不用 [apiCall]：成功即读字节，
|
||||
* 失败才走 [ApiErrorMapper]（`404 document_not_found` / `401`）。
|
||||
* `@Streaming` 的响应体必须由调用方关闭，[okhttp3.ResponseBody.use] 在这里收口。
|
||||
*/
|
||||
suspend fun download(name: String): Result<ByteArray> = withContext(dispatcher) {
|
||||
try {
|
||||
val response = api.download(name)
|
||||
val body = response.body()
|
||||
when {
|
||||
response.isSuccessful && body != null -> Result.success(body.use { it.bytes() })
|
||||
// 2xx 却没有响应体：与 apiCall 同一口径，判解析失败而不是「拿到了空文件」。
|
||||
response.isSuccessful -> Result.failure(CyreneException(CyreneError.Local(CyreneError.LocalKind.Parse)))
|
||||
else -> Result.failure(
|
||||
CyreneException(
|
||||
ApiErrorMapper.fromHttp(response.code(), response.errorBody()?.string()),
|
||||
),
|
||||
)
|
||||
}
|
||||
} catch (e: CancellationException) {
|
||||
throw e
|
||||
} catch (e: Exception) {
|
||||
Result.failure(CyreneException(ApiErrorMapper.fromThrowable(e)))
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* multipart 部件。
|
||||
*
|
||||
* **部件名固定 `file`**（服务端 `r.FormFile("file")`），**文件名必须给且要带扩展名**：
|
||||
* Go 只把带非空 `filename` 参数的部件当**文件**（不带的落进普通表单值，`FormFile` 就找不到它），
|
||||
* 而扩展名要参与服务端的白名单判定。[fileName] 为空时回落到
|
||||
* [FALLBACK_FILE_NAME]——只是为了不让一个「没有名字的部件」变成 `400 需要 multipart 字段 file`；
|
||||
* 真正的原因（用户到底送的是什么）只有调用方知道，**不要**靠这个兜底掩盖调用方的空名字。
|
||||
*
|
||||
* `Content-Type` 固定 `text/plain`：服务端**不采信**客户端声明（字节嗅探是唯一裁决），
|
||||
* 这里给一个诚实的默认值即可——文档白名单里放行的都是文本类。
|
||||
*/
|
||||
private fun partOf(bytes: ByteArray, fileName: String): MultipartBody.Part =
|
||||
MultipartBody.Part.createFormData(
|
||||
name = UPLOAD_FIELD_NAME,
|
||||
filename = fileName.takeIf { it.isNotBlank() } ?: FALLBACK_FILE_NAME,
|
||||
body = bytes.toRequestBody(MIME_TEXT.toMediaTypeOrNull()),
|
||||
)
|
||||
}
|
||||
|
||||
private const val UPLOAD_FIELD_NAME = "file"
|
||||
|
||||
private const val FALLBACK_FILE_NAME = "document.txt"
|
||||
|
||||
private const val MIME_TEXT = "text/plain"
|
||||
@@ -19,6 +19,7 @@ enum class SendChannel {
|
||||
* 且 `stream:true` 的回合同样在**已连接的 WS** 上流式回来 ⇒ 「REST 发、WS 收」不牺牲流式体验。
|
||||
*
|
||||
* 图片一律走 REST：真实图片的 base64 远超 4096 字节，在 WS 上**必然**断连。
|
||||
* 文档附件同理一律走 REST（上传换引用这件事整个压在同一条通道上，见 [DocumentDelivery]）。
|
||||
*
|
||||
* ## 阈值
|
||||
* 判据是**文本的 UTF-8 字节数**（不是字符数——中文一个字 3 字节，按字符数算会在
|
||||
@@ -46,9 +47,17 @@ object ChatSendRouting {
|
||||
/**
|
||||
* 这一条该走哪条通道。
|
||||
* @param hasImage 本次是否带图片（带图**永远**走 REST）
|
||||
* @param hasDocuments 本次是否带**文档附件**（带附件**永远**走 REST）：文档本体要先经
|
||||
* `POST /api/v1/documents` 上传，引用只随 `POST /api/v1/chat` 发出——
|
||||
* 「文档一律走 REST」见 [DocumentDelivery] 第 2 条。默认 false ⇒ 既有调用与旧行为逐字不变。
|
||||
*/
|
||||
fun channelFor(text: String, hasImage: Boolean): SendChannel = when {
|
||||
fun channelFor(
|
||||
text: String,
|
||||
hasImage: Boolean,
|
||||
hasDocuments: Boolean = false,
|
||||
): SendChannel = when {
|
||||
hasImage -> SendChannel.Rest
|
||||
hasDocuments -> SendChannel.Rest
|
||||
utf8Length(text) <= WS_TEXT_LIMIT_BYTES -> SendChannel.Ws
|
||||
else -> SendChannel.Rest
|
||||
}
|
||||
|
||||
@@ -0,0 +1,161 @@
|
||||
package top.yeij.cyrene.domain.chat
|
||||
|
||||
import top.yeij.cyrene.data.api.dto.DocumentRefDto
|
||||
|
||||
/**
|
||||
* 一份待上传的本地附件。
|
||||
*
|
||||
* 只带「服务端裁决需要的两样」：[fileName]（**扩展名真的参与裁决**——服务端把白名单扩展名与
|
||||
* 字节嗅探**合取**，两者都过才放行；其余部分会被丢进内容寻址的存储名里）与 [bytes]。
|
||||
*
|
||||
* 不用 `data class`：`ByteArray` 的 `equals` 是引用比较，写成 `data class` 会给出一个
|
||||
* 「看着像值语义、其实永远不等」的陷阱（测试里第一眼就会撞上）。
|
||||
*/
|
||||
class DocumentFile(
|
||||
val fileName: String,
|
||||
val bytes: ByteArray,
|
||||
) {
|
||||
val sizeBytes: Long get() = bytes.size.toLong()
|
||||
}
|
||||
|
||||
/** 正文该内联发出，还是该先落成文档。 */
|
||||
sealed interface DocumentPlan {
|
||||
|
||||
/** 照既有路由（[ChatSendRouting]）内联发出：没有附件，正文也没到「文件级」。 */
|
||||
data object Inline : DocumentPlan
|
||||
|
||||
/**
|
||||
* 先 `POST /api/v1/documents` 换成存储名，再用 `chat.documents` 引用发出。
|
||||
* 调用方应把这一路整个交给 REST（见类型 KDoc 第 2 条的策略说明），不要在 WS 上重开一条。
|
||||
*
|
||||
* @param files 本地附件（≤ [DocumentDelivery.MAX_ATTACHMENTS_PER_TURN] 份）。
|
||||
* @param textAsDocument 正文是否也要落成一份 `.txt` 一起当附件发。
|
||||
*/
|
||||
data class AsDocuments(
|
||||
val files: List<DocumentFile> = emptyList(),
|
||||
val textAsDocument: Boolean = false,
|
||||
) : DocumentPlan
|
||||
|
||||
/**
|
||||
* 明确拒绝：调用方**必须**给用户一个说法，**绝不静默丢**。
|
||||
* 「静默丢」正是本模块要消灭的东西——一方以为附件发上去了、另一方一无所知。
|
||||
*/
|
||||
data class Rejected(val reason: DocumentRejection) : DocumentPlan
|
||||
}
|
||||
|
||||
/** 本地就能判定的拒绝理由（服务端的同类拒绝见 [DocumentFailure]）。 */
|
||||
enum class DocumentRejection {
|
||||
/** 一个回合的附件数超过上限：不做「只发前 5 个」这种裁剪，多出来的必须让用户看见。 */
|
||||
TooManyAttachments,
|
||||
}
|
||||
|
||||
/**
|
||||
* 「该不该走文件」的判定与 `chat.documents` 载荷构造（纯函数，VM 与测试共用）。
|
||||
*
|
||||
* ## 为什么这条规则值得单独存在
|
||||
* 三条互不相同的约束在客户端汇成一个决定，任何一条被忘掉都会出线上事故：
|
||||
*
|
||||
* 1. **WS 帧 4096 字节硬上限，且超限是直接断连**（不是回错误）⇒ 正文超过它必须走 REST
|
||||
* —— 这一步**已经在** [ChatSendRouting] 里，本对象**不另立阈值**，只用 [textNeedsRest]
|
||||
* 把它显式暴露出来，免得接线时把「超帧限」误当成「该转文件」；
|
||||
* 2. **文档一律走 REST**（回执五 §一 S3-B 的明文规则）：文档本体经
|
||||
* `POST /api/v1/documents` 上传、引用随 `POST /api/v1/chat` 发出。实测后端 WS `chat` 帧
|
||||
* **确实**能收 `documents`（`ws_hub_turn.go` 的入站结构与 REST 同形），所以这一条是
|
||||
* **客户端策略**而非后端限制——理由是把「上传 → 引用 → 起回合」压在**一条**通道上，
|
||||
* 不让两条入口在错误面（413 / 415 / 404 / too_many）上分叉。所以
|
||||
* [DocumentPlan.AsDocuments] 的调用方不该再把这条消息交给 WS；
|
||||
* 3. **长正文按文件送，比内联更划算**：内联的正文会进**每一页历史**、每一次 `history` 回放、
|
||||
* 以及这一轮的完整上下文；落成文档后历史里只留一条引用（名 / MIME / 大小 / 字符数 /
|
||||
* 状态），正文按预算注入、还能被 `document-read` 按游标**继续读**。
|
||||
*
|
||||
* ## 阈值与它们各自的分量（**别把三个数混成一个**）
|
||||
* | 界线 | 值 | 谁定的 | 越过的后果 |
|
||||
* |---|---|---|---|
|
||||
* | WS 帧上限 | 4096 字节 | 服务端 `wsReadLimit` | **直接断连**（不是报错）⇒ 走 REST |
|
||||
* | 走 REST 的正文上限 | 3584 字节 | 本端预留 512 字节 JSON 外壳 | 就是「换条通道」，无惩罚 |
|
||||
* | **转文件的正文界线** | 4000 **rune** | **本端自定**（见下） | 换形态：正文变附件 |
|
||||
*
|
||||
* ⚠️ **第三行是客户端的产品判断，不是服务端拒绝线。** 契约里唯一的 4000 rune 上限是
|
||||
* `PATCH /api/v1/messages/{id}` 的**编辑正文**上限（服务端 `maxMessageContentRunes`），
|
||||
* **`POST /api/v1/chat` 根本没有正文长度上限**（已核 `api-client.md` §1 行 3 与后端
|
||||
* `rest.go` / `ws_hub_turn.go` 的请求结构）。这里借它当「正文量级已经不像一条消息」的
|
||||
* 参照——按 Unicode 码点计，与服务端 Go 的 rune 口径一致（代理对算一个）。
|
||||
* 于是 [textNeedsFile] 只是**建议**：[plan] 会据此给出 [DocumentPlan.AsDocuments]，
|
||||
* 而**接线时要不要真的自动转换，是产品取舍**（建议先问用户：「这段内容较长，
|
||||
* 作为文件发送？」），纯函数不替产品做决定、也不静默改变既有行为。
|
||||
*
|
||||
* 反过来，**正文只是超过 4096 字节（走 REST 就够）不该被当成文件**：那会平白改变一条
|
||||
* 已经验证过的路径（长文本 → REST 内联）的语义，而 REST 本来装得下。
|
||||
*/
|
||||
object DocumentDelivery {
|
||||
|
||||
/** 一个回合的附件数上限：服务端 `maxChatDocuments = 5`（回执五 §一 S3-B），含等于。 */
|
||||
const val MAX_ATTACHMENTS_PER_TURN: Int = 5
|
||||
|
||||
/**
|
||||
* 正文「已经不像一条消息」的**客户端**界线（rune，含等于 → 仍算一条消息）。
|
||||
*
|
||||
* 取值参照契约里唯一的 rune 计数上限——`PATCH /api/v1/messages/{id}` 的 4000 rune
|
||||
* （见类型 KDoc 的诚实说明：`/chat` 没有这条上限）。
|
||||
*/
|
||||
const val TEXT_AS_DOCUMENT_RUNE_LIMIT: Int = 4000
|
||||
|
||||
/** 长正文落成附件时的扩展名：服务端白名单内的 `.txt`（名字其余部分会被内容寻址丢弃）。 */
|
||||
const val TEXT_DOCUMENT_FILE_NAME: String = "message.txt"
|
||||
|
||||
/** 按 Unicode 码点计数，与服务端 Go 的 rune 口径一致（代理对算一个）。 */
|
||||
fun runeCount(text: String): Int = text.codePointCount(0, text.length)
|
||||
|
||||
/** 正文是否已经超过「一条消息的正文量级」⇒ 建议按文件发送。见类型 KDoc 的界线说明。 */
|
||||
fun textNeedsFile(text: String): Boolean = runeCount(text) > TEXT_AS_DOCUMENT_RUNE_LIMIT
|
||||
|
||||
/**
|
||||
* 正文是否连既有的 WS 通道都放不下 ⇒ 必须走 REST。
|
||||
*
|
||||
* 直接复用 [ChatSendRouting] 的判据（**不另立阈值**）：这里只是把
|
||||
* 「超帧限 = 换通道」与「超 rune 界线 = 换形态」两件事在名字上分开。
|
||||
*/
|
||||
fun textNeedsRest(text: String): Boolean =
|
||||
ChatSendRouting.channelFor(text, hasImage = false) == SendChannel.Rest
|
||||
|
||||
/**
|
||||
* 这一轮该怎么发。
|
||||
*
|
||||
* 判定顺序（先拒绝、再看附件、最后看正文）：
|
||||
* 1. 附件 > [MAX_ATTACHMENTS_PER_TURN] → [DocumentPlan.Rejected]（**不裁剪**）；
|
||||
* 2. 有附件 → [DocumentPlan.AsDocuments]（附件一律先上传换存储名）；
|
||||
* 3. 没附件、正文超 [TEXT_AS_DOCUMENT_RUNE_LIMIT] → [DocumentPlan.AsDocuments]（正文落成 `.txt`）；
|
||||
* 4. 其余 → [DocumentPlan.Inline]。
|
||||
*
|
||||
* @param text 本轮的正文（调用方已 trim；空串 = 纯附件回合，服务端**支持**纯附件回合）。
|
||||
* @param files 本轮要挂的本地附件。
|
||||
*/
|
||||
fun plan(text: String, files: List<DocumentFile>): DocumentPlan = when {
|
||||
files.size > MAX_ATTACHMENTS_PER_TURN -> DocumentPlan.Rejected(DocumentRejection.TooManyAttachments)
|
||||
files.isNotEmpty() -> DocumentPlan.AsDocuments(files = files, textAsDocument = textNeedsFile(text))
|
||||
textNeedsFile(text) -> DocumentPlan.AsDocuments(textAsDocument = true)
|
||||
else -> DocumentPlan.Inline
|
||||
}
|
||||
|
||||
/**
|
||||
* 把长正文落成一份待上传的 `.txt`（服务端只看扩展名，名字其余部分会被丢弃）。
|
||||
* 字节就是 UTF-8 编码——服务端嗅探得到的基类型因此是 `text/plain`。
|
||||
*/
|
||||
fun textAsFile(text: String, fileName: String = TEXT_DOCUMENT_FILE_NAME): DocumentFile =
|
||||
DocumentFile(fileName = fileName, bytes = text.toByteArray(Charsets.UTF_8))
|
||||
|
||||
/**
|
||||
* 由**已上传**的服务端存储名构造 `chat.documents` 载荷。
|
||||
*
|
||||
* 只带 `name`（见 [DocumentRefDto]：服务端不采信其它字段并会覆盖），且**≤5 条**。
|
||||
*
|
||||
* @return `null` = 这份载荷**不合法**（超过 5 条，或有空名字），调用方**必须**给用户提示，
|
||||
* **不得**截断到 5 条、也**不得**丢掉空名字那条——服务端对>5 回 `400 too_many_documents`、
|
||||
* 对非法/不存在的名字回 `404 document_not_found`，两边都不做静默裁剪。
|
||||
*/
|
||||
fun payload(storageNames: List<String>): List<DocumentRefDto>? = when {
|
||||
storageNames.size > MAX_ATTACHMENTS_PER_TURN -> null
|
||||
storageNames.any { it.isBlank() } -> null
|
||||
else -> storageNames.map { DocumentRefDto(name = it) }
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,72 @@
|
||||
package top.yeij.cyrene.domain.chat
|
||||
|
||||
import top.yeij.cyrene.core.error.CyreneError
|
||||
import top.yeij.cyrene.data.api.CyreneException
|
||||
|
||||
/**
|
||||
* 文档操作失败（上传 / 取值）。契约 **v0.59 待发布**，错误码依据见
|
||||
* `02-前后端协同事项.md` 回执五 §一 S1 与 §五「v0.59 会登记什么」。
|
||||
*
|
||||
* ## 为什么要把错误码收成类型
|
||||
* 四个码在**用户能做的事**上各不相同，折进一个「操作失败」会让 UI 只能靠字符串猜：
|
||||
*
|
||||
* | 码 | HTTP | 用户能做什么 |
|
||||
* |---|---|---|
|
||||
* | [UnsupportedType] `unsupported_media_type` | 415 | **换文件**：这个格式不在白名单里（deny-by-default 的文本/代码扩展名，含 `.js` / `.py` / `.sh` 一律拒），改名 / 改声明都没有用——**字节嗅探是唯一裁决** |
|
||||
* | [TooLarge] `document_too_large` | 413 | **换文件**：超过单文件上限（默认 20 MiB，可部署配置） |
|
||||
* | [TooMany] `too_many_documents` | 400 | **少选几个**：一个回合最多 5 个附件 |
|
||||
* | [NotFound] `document_not_found` | 404 | 重传：存储名形态非法或文件已不在（非法与不存在**刻意同码**，不给探测面） |
|
||||
* | [Unreadable] `document_unreadable` | 400 | **只有显式索取正文时才会出现**（如 `document-read`），不是「上传失败」 |
|
||||
*
|
||||
* 每个分支都带 [message]：四种拒绝的文案由**服务端产出**（含真实上限），客户端原样展示、
|
||||
* 不自己编数字（与 `image_too_large` 同一口径）。未知码与本地网络错误一律落 [Other]，
|
||||
* **原样带上服务端消息**，绝不因为「不认识这个码」就把失败吞掉。
|
||||
*/
|
||||
sealed interface DocumentFailure {
|
||||
|
||||
/** 可直接展示给用户的文案（服务端有话说时就是它说的那句）。 */
|
||||
val message: String
|
||||
|
||||
/** `415 unsupported_media_type`：扩展名白名单外，或字节嗅探判出非文本。 */
|
||||
data class UnsupportedType(override val message: String) : DocumentFailure
|
||||
|
||||
/** `413 document_too_large`：超过单文件字节上限（`CHAT_DOCUMENT_MAX_BYTES`，默认 20 MiB）。 */
|
||||
data class TooLarge(override val message: String) : DocumentFailure
|
||||
|
||||
/** `400 too_many_documents`：一个回合挂的附件数超过 5。 */
|
||||
data class TooMany(override val message: String) : DocumentFailure
|
||||
|
||||
/** `404 document_not_found`：存储名非法或文件不存在（两者同码）。 */
|
||||
data class NotFound(override val message: String) : DocumentFailure
|
||||
|
||||
/** `400 document_unreadable`：正文取不回来（**仅显式索取正文时**）。 */
|
||||
data class Unreadable(override val message: String) : DocumentFailure
|
||||
|
||||
/** 401 / 403：会话失效或角色不够（文档端点要求 `owner|admin`）。 */
|
||||
data object Forbidden : DocumentFailure {
|
||||
override val message: String get() = "登录状态已失效，请重新登录"
|
||||
}
|
||||
|
||||
/** 其它失败：网络 / 超时 / 未知码 / 服务端 5xx——消息照原样带出来。 */
|
||||
data class Other(override val message: String) : DocumentFailure
|
||||
}
|
||||
|
||||
/** 把仓库层的 `Result` 失败收敛成 [DocumentFailure]。 */
|
||||
fun Throwable.toDocumentFailure(): DocumentFailure {
|
||||
val error = (this as? CyreneException)?.error
|
||||
return when {
|
||||
error is CyreneError.Unauthorized -> DocumentFailure.Forbidden
|
||||
error is CyreneError.Server && error.httpStatus == 403 -> DocumentFailure.Forbidden
|
||||
error is CyreneError.Server -> when (error.code) {
|
||||
"unsupported_media_type" -> DocumentFailure.UnsupportedType(error.userMessage)
|
||||
"document_too_large" -> DocumentFailure.TooLarge(error.userMessage)
|
||||
"too_many_documents" -> DocumentFailure.TooMany(error.userMessage)
|
||||
"document_not_found" -> DocumentFailure.NotFound(error.userMessage)
|
||||
"document_unreadable" -> DocumentFailure.Unreadable(error.userMessage)
|
||||
else -> DocumentFailure.Other(error.userMessage)
|
||||
}
|
||||
|
||||
error != null -> DocumentFailure.Other(error.userMessage)
|
||||
else -> DocumentFailure.Other("文档操作失败，请稍后重试")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,31 @@
|
||||
package top.yeij.cyrene.domain.chat
|
||||
|
||||
/**
|
||||
* 文档抽取状态（契约 **v0.59 待发布**，形状依据见 `02-前后端协同事项.md` 回执五 §一 S3-A/S3-B）。
|
||||
*
|
||||
* **开放集合，不用 enum**：后端的 `status` 是自由字符串，客户端映射只认这三个已知值，
|
||||
* **未知值原样保留**（不丢弃、不报错、不占位符）——与 `mode` / `platform` / `mood` 同一口径。
|
||||
*
|
||||
* 三个值的语义（**别互相顶替**）：
|
||||
* - [EXTRACTED]：正文已抽取并进了这一轮的上下文；
|
||||
* - [LISTED]：只给了模型一份附件清单（名 / MIME / 大小 / 结论），**正文没进上下文**；
|
||||
* 它不是错误态——大文件、超预算、或本期不支持的格式都可能停在这里；
|
||||
* - [UNREADABLE]：**读不到这个文件**。这是唯一一个「昔涟看不到内容」的可观测信号，
|
||||
* 与「内容被截断」（`truncated`）是两件事：截断者正文照样进了上下文，只是尾巴被预算切掉。
|
||||
*/
|
||||
object DocumentStatus {
|
||||
|
||||
const val EXTRACTED: String = "extracted"
|
||||
|
||||
const val LISTED: String = "listed"
|
||||
|
||||
const val UNREADABLE: String = "unreadable"
|
||||
|
||||
/**
|
||||
* 这条引用是否报告「读不到」。
|
||||
*
|
||||
* 只比 [UNREADABLE]，**不猜**：服务端是本信号的唯一生产者（回合结束后回写该用户消息的
|
||||
* document 列——用户消息是回合前落的、结论是回合中才知道的），客户端不做二次推断。
|
||||
*/
|
||||
fun isUnreadable(status: String): Boolean = status == UNREADABLE
|
||||
}
|
||||
Reference in new issue
Block a user