From de208a039d102212873e476492c760f904de373b 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:40:16 +0800
Subject: [PATCH] =?UTF-8?q?=EF=BB=BFdocs(40):=20=E8=A1=A5=E5=85=A8?=
 =?UTF-8?q?=E6=B5=81=E7=A8=8B=E9=AA=8C=E6=94=B6=E5=AE=9E=E6=B5=8B=E5=88=B0?=
 =?UTF-8?q?=E7=9A=84=E6=8E=A5=E5=8F=A3=E5=BD=A2=E7=8A=B6=E5=B7=AE=E5=BC=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

跑全流程 E2E 时连续踩到（都是调用方视角的真实摩擦点）：

- 各端点的 data 形状不统一：账户看板 data.account + data.summary、持仓 data.holdings、
  成交明细 data.transactions、资金流水 **data.entries**、角色列表 data（裸数组）、
  知识列表 items（不套 data）。我写脚本时连续猜错三个字段名，一度误判"资金流水没记录"。
- 创建类接口返回 201 而非 200：下单 T002、创建会话 C001、访客令牌 V001 都是 201。

两条都写进"通用预期"，并说明是实测结论。
---
 docs/40-前端验收清单.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/40-前端验收清单.md b/docs/40-前端验收清单.md
index 9799483..d00c7d9 100644
--- a/docs/40-前端验收清单.md
+++ b/docs/40-前端验收清单.md
@@ -232,6 +232,8 @@ python -m app.worker
 | 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` + 投向量删除事件，**不是**物理删除 |
+| 8-10 | **各端点的 `data` 形状不统一**（写联调脚本时别猜） | 实测：账户看板 `data.account` + `data.summary`、持仓 `data.holdings`、成交明细 `data.transactions`、资金流水 **`data.entries`**、角色列表 `data`（裸数组）、知识列表 `items`（**不套 `data`**）。我写全流程脚本时连续猜错三个字段名 ✅实测 |
+| 8-11 | 创建类接口返回 **201** 而非 200 | 下单 `T002`、创建会话 `C001`、访客令牌 `V001` 都是 201。判"成功"要用 `status in (200,201)` ✅实测 |
 
 ---