docs: 更新协议文档，删除废弃计划文档

- 更新 http-error-codes, user-points-chat-data-protocol - 更新 divination-run-protocol, profile-protocol - 删除废弃的后端和前端设计计划文档
2026-04-08 17:23:02 +08:00
parent 49fc9a116f
commit e80a82bef4
57 changed files with 4117 additions and 2269 deletions
@@ -0,0 +1,90 @@
+# Bug: 首页历史 Session 只显示4条，"更多"按钮缺失
+
+日期：2026-04-08
+状态：功能缺失（未完成）
+
+## 问题描述
+
+前端主页接收后端传来的历史 session，永远只显示四个，"more"按钮不见了。
+
+## 根因分析
+
+### 1. 前端硬编码 `take(4)`
+
+`apps/lib/features/home/presentation/screens/home_screen.dart:287`：
+```dart
+children: historyItems.take(4).map((item) {
+```
+
+这是在 commit `6e82053`（重构首页为底部导航栏布局）时**有意添加**的设计选择，用于限制首页展示的历史记录数量。
+
+### 2. 前端未实现"更多"按钮
+
+- `l10n.more` 本地化字符串存在（`'更多'`/`'More'`），定义于 `apps/lib/l10n/app_localizations_zh.dart:115` 和 `app_localizations_en.dart:116`
+- 但搜索整个 Dart 代码库，`l10n.more` **没有任何地方使用它**
+- "更多"功能从未被实现
+
+### 3. 后端 `hasMore` 硬编码为 `False`
+
+`backend/src/v1/agent/service.py:655-659`：
+```python
+return HistorySnapshotResponse(
+    scope="history_sessions_latest_assistant",
+    threadId=None,
+    day=None,
+    hasMore=False,  # 硬编码，未实际计算
+    messages=messages,
+)
+```
+
+后端 schema 定义了 `hasMore` 字段（`schemas.py:238`），但 service 层返回时**硬编码为 `False`**，从未实际计算是否还有更多数据。
+
+### 4. 后端 API 行为正确
+
+`backend/src/v1/agent/service.py:641-646`：
+```python
+raw_messages = await self._repository.get_latest_assistant_messages_by_user_sessions(
+    user_id=str(current_user.id),
+    visibility_mask=bit_mask(bit=int(SystemVisibilityBit.UI_HISTORY)),
+    session_limit=50,  # 后端返回最多50条
+)
+```
+
+后端正确返回最多 50 条历史 session，前端只是没有利用这些数据。
+
+## 问题性质
+
+| 层级 | 现象 | 性质 |
+|------|------|------|
+| 后端 | `hasMore=False` 硬编码 | 缺陷：响应语义不正确 |
+| 前端 | `take(4)` 只显示4条 | 设计选择：有意的 UI 限制 |
+| 前端 | 无"更多"按钮 | 功能缺失：有 `l10n.more` 但未实现 |
+
+## 证据
+
+- 前端代码：`apps/lib/features/home/presentation/screens/home_screen.dart:287`
+- 后端代码：`backend/src/v1/agent/service.py:655`
+- 本地化字符串：`apps/lib/l10n/app_localizations_zh.dart:115`
+- 提交记录：`6e82053`（feat(home): 重构首页为底部导航栏布局）
+
+## 修复方向
+
+### 方案 A：实现完整分页（推荐）
+
+1. **后端**：实现真正的 `hasMore` 计算逻辑
+   - 添加 `offset` 参数支持分页
+   - 实际计算 `hasMore = total_count > offset + limit`
+
+2. **前端**：实现"更多"按钮或无限滚动
+   - 监听滚动位置，滚动到底部时加载更多
+   - 或添加"更多"按钮手动触发加载
+
+### 方案 B：移除不存在的字符串
+
+如果业务确定只需要显示4条，则：
+- 移除 `l10n.more` 本地化字符串，避免误导
+
+## 相关文档
+
+- 工程计划：`docs/plans/2026-04-05-divination-history-profile-eng-plan.md`
+- 随访计划：`docs/plans/2026-04-08-followup-session-history-eng-plan.md`