docs(docs): 完善设计文档

docs/api.md

@@ -25,6 +25,8 @@
 - 创建成功返回 `201` + 创建后的完整对象；
 - 更新成功返回 `200` + 更新后的完整对象；
 - 删除成功返回 `204`，无响应体。
+- 返回笔记对象的列表接口，item 中一律包含 `content_preview` 字段。正文截断规则见 6.1 备注。
+
 
 ### 1.4 错误响应
 
@@ -410,6 +412,7 @@
     {
       "id": "...",
       "title": "...",
+      "content_preview": "笔记正文前 200 字...",
       "visibility": "private",
       "published_at": null,
       "created_at": "...",
@@ -421,7 +424,8 @@
 }
 ```
 
-**备注**：列表不返回 `content`（正文），正文只在详情接口返回。按 `updated_at DESC` 排序。
+**备注**：列表不返回 `content`（正文），正文只在详情接口返回。按 `updated_at DESC` 排序。列表返回 `content_preview`：正文按 rune 截断至 200 字符，超出部分以 `…` 结尾；正文为空时返回空串。截断由后端完成，前端直接展示。
+
 
 ### 6.2 GET `/api/notes/:id`
 
@@ -548,6 +552,7 @@
     {
       "id": "...",
       "title": "...",
+      "content_preview": "...",
       "published_at": "...",
       "updated_at": "...",
       "tags": [{ "id": "...", "name": "编程" }]
@@ -640,7 +645,8 @@
 
 **查询参数**：`limit`、`offset`
 
-**响应** `200`：结构同 6.1（含私有和公开）。
+**响应** `200`：结构同 6.1，含 `content_preview`。
+
 
 **错误**：
 
@@ -668,6 +674,7 @@
       {
         "id": "...",
         "title": "...",
+        "content_preview": "...",
         "visibility": "private",
         "published_at": null,
         "updated_at": "...",
@@ -703,6 +710,7 @@
     {
       "id": "...",
       "title": "...",
+      "content_preview": "...",
       "published_at": "...",
       "updated_at": "...",
       "tags": [{ "id": "...", "name": "编程" }]

docs/backend/audit.md

@@ -105,9 +105,3 @@ CREATE INDEX idx_audit_events_actor ON audit_events (actor_user_id, created_at D
 `audit_events` 表结构本身就是查询入口，索引已覆盖常见查询（按时间倒序、按事件类型、按用户）。
 
 如果后期需要界面，另开文档，不在本期范围。
-
-## 七、对 data-model.md 的回写
-
-贴完本文件后，回头修改 `docs/backend/data-model.md` 第九节，将 `audit_events` 那一行改为指向本文件：
-
-> - `audit_events` — 审计事件（见 audit.md）

docs/backend/auth.md

@@ -111,6 +111,7 @@ Haven 的鉴权分三个独立维度，共同决定一次请求能否通过：
 4. **不做设备指纹**：不用 UA + IP 做绑定校验，避免网吧环境不稳定导致误判。安全性靠“token 随机 + HttpOnly + 可撤销”，不靠指纹。
 5. **用户可在设置页列出所有授信设备并单独撤销**，撤销即删除记录。
 6. **密码修改时，所有授信设备与所有会话一并撤销**（强制重新登录 + 重新授信）。这是安全底线：密码变了的含义是“我怀疑旧凭证泄露”。
+7. **公共机器不建议授信**。授信设备有效期 30 天，登出不清除。在网吧、酒店等公共机器上登录时，不应勾选 `trust_device`；若误勾选，应通过设置页或另一台已登录设备手动撤销该授信设备。
 
 ## 五、API Token（tokens）
 
@@ -203,7 +204,8 @@ Haven 的鉴权分三个独立维度，共同决定一次请求能否通过：
 | 创建 / 撤销 Token | ❌ | ❌ 403 | ❌ 403 | ✅（需 TOTP） |
 | 查看 / 撤销授信设备 | ❌ | ❌ 403 | ❌ 403 | ✅ |
 | 查看 / 撤销会话 | ❌ | ❌ 403 | ❌ 403 | ✅ |
-| 绑定 / 关闭 TOTP | ❌ | ❌ 403 | ❌ 403 | ✅（需原 TOTP） |
+| 绑定 TOTP（setup / verify） | ❌ | ❌ 403 | ❌ 403 | ✅ |
+| 关闭 TOTP（disable） | ❌ | ❌ 403 | ❌ 403 | ✅（需当前 TOTP） |
 | 修改密码 | ❌ | ❌ 403 | ❌ 403 | ✅（需原密码 + TOTP） |
 
 **说明**：Token（包括 read_write）**不能管理凭证类资源**（Token / 授信设备 / 会话 / TOTP / 密码）。理由：Token 本身是凭证，如果它又能创建新 Token，泄露一次就等于永久后门。凭证管理只允许通过 Web 会话操作。

docs/backend/data-model.md

@@ -27,7 +27,8 @@
 |---|---|---|
 | `note_visibility` | `private` / `public` | 笔记可见性 |
 | `repo_platform` | `gogs` / `github` | 作品集仓库托管平台 |
-| `token_scope` | `read` / `read_write` | API Token 权限档位（用于 tokens 表，待补） |
+| `token_scope` | `read` / `read_write` | API Token 权限档位 |
+
 
 ## 三、notes — 笔记
 
@@ -187,6 +188,8 @@ CREATE UNIQUE INDEX idx_portfolio_repos_primary ON portfolio_repos (portfolio_it
 - 标签名：对 `tags.name` 建 `pg_trgm` GIN 索引，查询 `WHERE user_id = ? AND name ILIKE '%关键词%'`。
 - 不安装中文分词扩展。1–2 个字的查询会退化为全表扫描，接受这一代价（数据量小，且实际使用中很少只搜一两个字）。
 
+**已知限制**：本期搜索为子串匹配，只处理“包含”语义。不处理同义词（如“知识中台”搜不到“知识管理平台”）、不处理繁体与简体互通、不纠正错别字。这是刻意的取舍：自用场景、数据量小，子串匹配足够日常检索；语义检索与分词留到第二版评估。
+
 **返回**：
 
 - 笔记搜索结果返回笔记列表，同时返回每篇笔记的标签（联查 `note_tags` + `tags`）。