feat: stabilize rag chat conversations and auto title sync

docs/RAG/RAG会话自动标题开发任务拆解与接口变更清单.md

@@ -0,0 +1,185 @@
+# RAG 会话自动标题开发任务拆解与接口变更清单
+
+> 最后整理：2026-05-19
+> 对应方案：`docs/RAG/RAG会话自动标题生成与重命名实施方案.md`
+
+## 1. 本期落地范围
+
+本期目标不是做一个“前端点一下自动命名”的伪功能，而是完成第一版可稳定运行的后端自动标题链路：
+
+1. 新会话首轮回答完成后，后端异步生成标题
+2. 手动重命名后，不再被自动标题覆盖
+3. 会话列表排序从“单纯 updated_at”收口到“最后消息时间优先”
+4. 前端移除旧的假自动重命名逻辑
+
+---
+
+## 2. 任务拆解
+
+## 2.1 后端数据层
+
+任务：
+
+1. 为 `rag_conversation` 增加标题状态字段
+2. 增加 `last_message_at`
+3. 增加相关索引
+
+交付物：
+
+1. `scripts/创建sql/schema_rag_chat_auto_title.sql`
+
+验收点：
+
+1. 老数据执行 SQL 不报错
+2. 默认值正确
+3. 索引存在
+
+## 2.2 后端会话查询层
+
+任务：
+
+1. 会话列表返回 `titleSource`
+2. 会话列表返回 `lastMessageAt`
+3. 排序改为 `COALESCE(last_message_at, updated_at) DESC`
+
+验收点：
+
+1. 自动标题更新不会让会话无故跳到顶部
+2. 真正发新消息的会话仍能上浮
+
+## 2.3 后端消息完成链路
+
+任务：
+
+1. assistant 最终落库时同步更新 `last_message_at`
+2. 首轮回答完成后调度自动标题任务
+
+验收点：
+
+1. 标题生成失败不影响主回答
+2. 只在首轮完整回答后触发
+
+## 2.4 后端自动标题生成器
+
+任务：
+
+1. 新增 `_maybe_schedule_auto_title(...)`
+2. 新增 `_run_auto_title_task(...)`
+3. 新增 `_generate_conversation_title(...)`
+4. 新增 `_sanitize_generated_title(...)`
+5. 新增 `_build_fallback_title(...)`
+
+验收点：
+
+1. 同一会话不会重复并发生成标题
+2. 生成失败能记状态
+3. 生成成功后能回写标题
+
+## 2.5 后端手动重命名链路
+
+任务：
+
+1. `RenameConversation()` 改为写入 `title_source = 'manual'`
+2. 清空最近一次标题生成错误
+
+验收点：
+
+1. 用户手动改名后，后续自动任务不再覆盖
+
+## 2.6 前端聊天主链路
+
+任务：
+
+1. 移除 `generateConversationName(...)` 自动调用
+2. 移除 `sidebarRef.autoRename(...)` 自动调用
+3. 回答完成后轻量刷新会话列表，把后端自动标题同步回来
+
+验收点：
+
+1. 首轮问答完成后，会话名称自然更新
+2. 前端不再双写标题
+
+## 2.7 前端会话列表排序与本地更新
+
+任务：
+
+1. 会话排序优先用 `last_message_at`
+2. 仅标题更新时不再强行覆盖 `updated_at`
+
+验收点：
+
+1. 手动重命名不会导致会话跳序
+2. 自动重命名不会导致会话跳序
+
+---
+
+## 3. 接口变更清单
+
+## 3.1 `GET /api/v3/rag/chat/conversations`
+
+新增返回字段：
+
+```json
+{
+  "id": "conversation_id",
+  "name": "烟草专卖法中的烟草定义",
+  "introduction": "",
+  "titleSource": "auto",
+  "createdAt": 1779078161,
+  "updatedAt": 1779078200,
+  "lastMessageAt": 1779078200
+}
+```
+
+兼容性说明：
+
+1. 前端旧代码即使不消费新增字段也不会炸
+2. 新前端会使用 `last_message_at` 改善排序
+
+## 3.2 `PATCH /api/v3/rag/chat/conversations/{ConversationId}`
+
+本期请求体不变：
+
+```json
+{
+  "name": "我手动改的标题"
+}
+```
+
+但服务端语义变化为：
+
+1. 更新标题
+2. 将 `title_source` 切为 `manual`
+3. 保护后续自动任务不覆盖
+
+---
+
+## 4. 数据字段说明
+
+| 字段 | 说明 |
+|---|---|
+| `title_source` | `default / auto / manual` |
+| `title_generation_status` | `idle / pending / running / succeeded / failed` |
+| `title_generated_at` | 自动标题成功时间 |
+| `first_question_message_id` | 预留，本期可暂不写 |
+| `first_answer_message_id` | 记录首轮回答 message_id |
+| `title_generation_error` | 最近一次失败原因 |
+| `last_message_at` | 最后一次消息完成时间 |
+
+---
+
+## 5. 本期已知边界
+
+1. 自动标题目前走与 follow-up 相同的在线 LLM 依赖
+2. 如果 LLM 配置错误，主回答可能正常但标题生成失败
+3. 本期还未增加专门的 `conversation_renamed` SSE 事件
+4. 前端目前通过“回答完成后刷新列表”同步标题，优先保证正确性
+
+---
+
+## 6. 后续增强建议
+
+1. 新增 `conversation_renamed` SSE 事件，减少列表刷新
+2. 增加后台补偿任务，扫描 `failed` 会话再重试
+3. 引入标题生成提示词版本号，便于回溯
+4. 对 `first_question_message_id` 也做持久化，补齐审计链路