docs(documents): 契约 v0.59 已发布 —— 更正 W6 那批「未发布/待发布」的过时注释

Cyrene_v2/Docs/api-client.md 已发布 v0.59(§1.2「文档存储与摄取契约」+ 端点表 16/17),
而 W6 那批文件的 KDoc 仍写着「契约尚未发布 / 待发布」,会误导后来人以为形状没有契约背书。

已逐条核对:我们实现的形状与已发布契约**完全一致** —— multipart 部件名 `file`、
201 首次 / 200 + `deduped:true` 去重、单文件 20 MiB、单回合 ≤5 条、上行只收 `name`、
`url` 是相对路径、`mime` 是嗅探基类型、`documents` 数组含 `chars`/`truncated`/`status`、
0 个附件时该键省略、4 个错误码。白名单在契约里也已更正为 22 项(与代码一致)。

纯注释更正,零行为变更。
This commit is contained in:
AskaEth committed 2026-10-04 18:53:10 +08:00
1 parent ab76798bff
commit 29733914a4
10 files changed
+12 -12

No files matched your search

@@ -15,14 +15,14 @@ import top.yeij.cyrene.domain.chat.DocumentStatus
/**
* 文档 DTO 的形状钉子。
*
* **形状来源:`Cyrene-For-Android/devdocs/02-前后端协同事项.md` 回执五,契约 v0.59 尚未发布**
* **形状来源:`Cyrene-For-Android/devdocs/02-前后端协同事项.md` 回执五,契约 v0.59 已发布(api-client.md §1.2「文档存储与摄取契约」)**
* (写这些用例时 `Cyrene_v2/Docs/api-client.md` 最新仍是 v0.58,没有 documents 条目)。
* 字段集与取值另对齐后端已落库实现与它的测试:
* `407c934`(S1 存储端点 `documents.go` 的 `documentResponse`)、
* `5b2b385`(S3.5 文档多值化:`history.go` 的 `historyMessage.Documents` 带 `omitempty`、
* `history.DocumentRef` 的 `omitempty` 口径、`history_document_test.go` 钉住的元素字段集
* `chars,mime,name,size,status,truncated` 与它用的真实取值)。
* **没有 v0.59 抓包**:这里的 JSON 是按上述实现形状逐字节手写的(唯一确认过的真实取值
* **没有 v0.59 的真实抓包(形状按 api-client §1.2 与后端实现逐条核对)**:这里的 JSON 是按上述实现形状逐字节手写的(唯一确认过的真实取值
* 来自后端自己的测试夹具)。
*
* 解码器用 [ApiClientFactory.json](与生产同一份配置),所以这里过不了的形状线上也过不了。
@@ -22,12 +22,12 @@ import java.util.concurrent.Executors
* 文档端点的**线级**行为:真 OkHttp + 真 Retrofit + JDK 自带 HTTP 服务端(与
* [UploadRepositoryTest] / [ChatRepositoryTest] 同一手法,不引新依赖)。
*
* **形状来源:`02-前后端协同事项.md` 回执五,契约 v0.59 尚未发布**
* **形状来源:`02-前后端协同事项.md` 回执五,契约 v0.59 已发布(api-client.md §1.2「文档存储与摄取契约」)**
* (`api-client.md` 最新仍是 v0.58,没有 documents 条目)。夹具逐字段对齐后端实现:
* `documents.go` 的 `documentResponse`(`{name,url,mime,size,sha256,deduped}`,`url` 是
* **相对**路径、`201` 首次 / `200` 去重)与它的错误码常量、
* `chat_documents.go` 的 `too_many_documents`、`maxChatDocuments = 5`。
* **没有 v0.59 抓包**:响应体是按实现形状手写的。
* **没有 v0.59 的真实抓包(形状按 api-client §1.2 与后端实现逐条核对)**:响应体是按实现形状手写的。
*
* 要证明的四件事:
* 1. 请求**真的是 multipart**、部件名真的是 `file`、**文件名(含扩展名)原样发出**、
@@ -10,7 +10,7 @@ import top.yeij.cyrene.data.api.dto.DocumentRefDto
/**
* 「该不该走文件」的判定矩阵与 `chat.documents` 载荷构造(纯函数)。
*
* **形状来源**:`02-前后端协同事项.md` **回执五**(契约 v0.59 尚未发布)——
* **形状来源**:`02-前后端协同事项.md` **回执五**(契约 v0.59 已发布(api-client.md §1.2「文档存储与摄取契约」))——
* 「≤5 条」「只收服务端存储名」「文档一律走 REST」「WS 上行帧 4096 字节硬上限仍在」;
* 数值另对齐后端实现与测试:`chat_documents.go` 的 `maxChatDocuments = 5`、
* `wsReadLimit = 4096`(契约 v0.56 明确记载)。
@@ -9,7 +9,7 @@ import top.yeij.cyrene.data.api.CyreneException
/**
* 文档错误码 → 可分支失败类型的映射(纯函数)。
*
* **来源**:`02-前后端协同事项.md` **回执五**(契约 v0.59 尚未发布)§一 S1 的四个错误码表,
* **来源**:`02-前后端协同事项.md` **回执五**(契约 v0.59 已发布(api-client.md §1.2「文档存储与摄取契约」))§一 S1 的四个错误码表,
* 另核过后端实现里的常量(`documents.go` 的 `documentUnsupportedCode` /
* `documentTooLargeCode` / `documentNotFoundCode`、`chat_documents.go` 的
* `tooManyDocumentsCode` / `documentsUnavailableCode`)。文案一律用**服务端产出的原文**,