From ff37b0b476bd9f3cd4a5df14df963841bcca8160 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=BF=E4=BA=91=E7=A7=8B=E6=9C=88?= <15273589815@163.com>
Date: Sun, 13 Sep 2026 20:26:56 +0800
Subject: [PATCH] =?UTF-8?q?=EF=BB=BFdocs(40):=20=E8=AE=B0=E5=BD=95?=
 =?UTF-8?q?=E7=9F=A5=E8=AF=86=E6=B2=BB=E7=90=86=E7=AB=AF=E7=82=B9=E7=9A=84?=
 =?UTF-8?q?=E4=B8=A4=E5=A4=84=E6=8E=A5=E5=8F=A3=E5=B7=AE=E5=BC=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

联调时踩到并查明（更正前一版判断：不是接口故障，是调用方解包方式不对）：

1) GET /api/v1/knowledge/list **不套 data 信封**，直接返回 {"items": [...], "count": N}，
   而多数端点返回 {"code":…, "data": {…}}。按 data.items 解包会拿到 0 条，
   看着像"库里没数据"——我据此误判过一次，也因此在重灌时没能用列表接口批量删除，
   改为按 id 逐个 DELETE。
2) 上传是 POST /api/v1/knowledge/upload（/documents 会 405）；
   DELETE /api/v1/knowledge/{id} 的语义是标记 expired + 投向量删除事件，不是物理删除。

两条都写进验收清单的"通用预期"，避免下一个人重复踩。
---
 docs/40-前端验收清单.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/40-前端验收清单.md b/docs/40-前端验收清单.md
index 10090b1..9799483 100644
--- a/docs/40-前端验收清单.md
+++ b/docs/40-前端验收清单.md
@@ -230,6 +230,8 @@ python -m app.worker
 | 8-5 | 多标签 | 各页面独立。**注意**：`auth.js` 现在以 cookie 为权威（跨标签同步），所以**同一浏览器两个账号不能并存** ✅实测代码逻辑 |
 | 8-6 | 排版 | 文字不重叠、内容不溢出、表格行高稳定 ⚠️待点验 |
 | 8-7 | 缓存 | 产品列表/详情页的 CSS/JS 已带 `?v=20260913-4`；若改了资源仍看不到效果，请硬刷新 ⚠️待点验 |
+| 8-8 | **`GET /api/v1/knowledge/list` 不套 `data` 信封** | 它直接返回 `{"items": [...], "count": N}`，而多数端点返回 `{"code":…, "data": {…}}`。按 `data.items` 解包会得到 0 条、看着像"库里没数据" ✅实测（联调时踩过一次，误判成接口故障） |
+| 8-9 | 知识治理端点 | 上传是 `POST /api/v1/knowledge/upload`（**不是** `/documents`，用后者会 405）；删除是 `DELETE /api/v1/knowledge/{id}`，语义是标记 `expired` + 投向量删除事件，**不是**物理删除 |
 
 ---