chore: finalize backend feature scope

app/services/learning_assistant_service.py

@@ -2,6 +2,7 @@ import json
 import time
 from collections.abc import AsyncIterator
 from dataclasses import dataclass
+from typing import Any
 
 from sqlalchemy.orm import Session
 
@@ -10,8 +11,14 @@ from app.core.config import settings
 from app.core.context import UserContext
 from app.core.exceptions import AppError
 from app.repositories.knowledge_base_repository import KnowledgeBaseRepository
-from app.schemas.learning_assistant import LearningAssistantChatRequest, LearningAssistantChatResponse, LearningAssistantSource
+from app.schemas.learning_assistant import (
+    LearningAssistantChatRequest,
+    LearningAssistantSessionCreateRequest,
+    LearningAssistantSessionResponse,
+    LearningAssistantSource,
+)
 from app.services.knowledge_space_service import KnowledgeSpaceService
+from app.services.learning_assistant_session_store import LearningAssistantSessionStore, learning_assistant_session_store
 from app.services.vector_search_service import RetrievedChunk, VectorSearchService
 
 
@@ -28,7 +35,7 @@ class LearningAssistantRetrieval:
 
 
 class LearningAssistantService:
-    """AI 学习助手服务：优先 RAG 检索，知识库不可用时降级为通用流式问答。"""
+    """AI 学习助手服务：管理短期会话，并优先通过 RAG 检索生成流式学习回答。"""
 
     def __init__(
         self,
@@ -36,78 +43,115 @@ class LearningAssistantService:
         *,
         vector_search_service: VectorSearchService | None = None,
         agent: LearningAssistantAgent | None = None,
+        session_store: LearningAssistantSessionStore | None = None,
     ) -> None:
         self.db = db
         self.repo = KnowledgeBaseRepository(db)
         self.space_service = KnowledgeSpaceService(self.repo)
         self.vector_search = vector_search_service or VectorSearchService(db)
         self.agent = agent or LearningAssistantAgent()
+        self.session_store = session_store or learning_assistant_session_store
 
-    async def chat(self, ctx: UserContext, payload: LearningAssistantChatRequest) -> LearningAssistantChatResponse:
-        """知识问答调试：检索失败不阻断回答，返回完整文本和检索降级信息。"""
-        start = time.perf_counter()
-        retrieval = await self._retrieve_sources(ctx, payload)
-        llm_started = time.perf_counter()
-        response = await self.agent.answer(payload.question, retrieval.sources)
-        total_latency_ms = int((time.perf_counter() - start) * 1000)
-        llm_latency_ms = response.latency_ms or int((time.perf_counter() - llm_started) * 1000)
-        self._write_query_log(
-            ctx=ctx,
-            payload=payload,
-            retrieval=retrieval,
-            answer=response.content,
-            model=response.model,
-            llm_latency_ms=llm_latency_ms,
-            total_latency_ms=total_latency_ms,
-        )
-        return LearningAssistantChatResponse(
-            answer=response.content,
-            retrieval_hit=bool(retrieval.sources),
-            sources=retrieval.sources,
-            retrieval_error=retrieval.retrieval_error,
-            model=response.model,
-            embedding_latency_ms=retrieval.embedding_latency_ms,
-            search_latency_ms=retrieval.search_latency_ms,
-            llm_latency_ms=llm_latency_ms,
-            total_latency_ms=total_latency_ms,
-        )
+    def create_session(self, ctx: UserContext, payload: LearningAssistantSessionCreateRequest) -> LearningAssistantSessionResponse:
+        """学习助手会话创建：进入 AI 学习助手页面时初始化短期上下文容器。"""
+        state = self.session_store.create(ctx, title=payload.title)
+        return self._session_response(state)
 
-    async def stream_chat(self, ctx: UserContext, payload: LearningAssistantChatRequest) -> AsyncIterator[str]:
-        """流式知识问答：先返回检索状态，再流式输出 LLM 回答。"""
+    def validate_session(self, ctx: UserContext, assistant_session_id: str) -> dict[str, Any]:
+        """学习助手会话校验：确保会话存在、未过期且属于当前用户。"""
+        state = self.session_store.get(assistant_session_id, ctx.user_id)
+        if not state:
+            raise AppError("LEARNING_ASSISTANT_SESSION_NOT_FOUND", "learning assistant session not found", 404)
+        if state.get("status") != "active":
+            raise AppError("LEARNING_ASSISTANT_SESSION_INVALID", "learning assistant session is not active", 400)
+        return state
+
+    async def stream_session_chat(
+        self,
+        ctx: UserContext,
+        payload: LearningAssistantChatRequest,
+        assistant_session: dict[str, Any],
+    ) -> AsyncIterator[str]:
+        """会话式流式问答：绑定学习助手会话，记录最近问答并参与后续提示词拼接。"""
+        yield self._sse(
+            "session_ready",
+            {
+                "assistant_session_id": assistant_session["assistant_session_id"],
+                "status": assistant_session["status"],
+                "history_count": len(assistant_session.get("messages") or []),
+            },
+        )
+        async for event in self._stream_answer(ctx, payload, assistant_session=assistant_session):
+            yield event
+
+    async def _stream_answer(
+        self,
+        ctx: UserContext,
+        payload: LearningAssistantChatRequest,
+        *,
+        assistant_session: dict[str, Any] | None,
+    ) -> AsyncIterator[str]:
+        """学习助手流式核心流程：检索知识库、调用 LLM、写入查询日志和短期会话上下文。"""
         start = time.perf_counter()
+        assistant_session_id = assistant_session.get("assistant_session_id") if assistant_session else None
+        history = (
+            self.session_store.get_messages(assistant_session_id, ctx.user_id, settings.learning_assistant_history_limit)
+            if assistant_session_id
+            else []
+        )
+        if assistant_session_id:
+            self.session_store.append_message(assistant_session_id, ctx.user_id, "user", payload.question)
+
         retrieval = await self._retrieve_sources(ctx, payload)
         yield self._sse(
             "retrieval_done",
-            {
-                "retrieval_hit": bool(retrieval.sources),
-                "sources": [source.model_dump() for source in retrieval.sources],
-                "retrieval_error": retrieval.retrieval_error,
-                "embedding_latency_ms": retrieval.embedding_latency_ms,
-                "search_latency_ms": retrieval.search_latency_ms,
-            },
+            self._with_session(
+                assistant_session_id,
+                {
+                    "retrieval_hit": bool(retrieval.sources),
+                    "sources": [source.model_dump() for source in retrieval.sources],
+                    "retrieval_error": retrieval.retrieval_error,
+                    "embedding_latency_ms": retrieval.embedding_latency_ms,
+                    "search_latency_ms": retrieval.search_latency_ms,
+                },
+            ),
         )
 
         answer_parts: list[str] = []
         llm_latency_ms: int | None = None
         model: str | None = None
         try:
-            async for chunk in self.agent.stream_answer(payload.question, retrieval.sources):
+            async for chunk in self.agent.stream_answer(payload.question, retrieval.sources, history=history):
                 if chunk.done:
                     llm_latency_ms = chunk.total_latency_ms
                     model = chunk.model
                     break
                 if chunk.delta:
                     answer_parts.append(chunk.delta)
-                    yield self._sse("answer_delta", {"delta": chunk.delta})
+                    yield self._sse("answer_delta", self._with_session(assistant_session_id, {"delta": chunk.delta}))
         except AppError as exc:
-            yield self._sse("error", {"code": exc.code, "message": exc.message})
+            yield self._sse("error", self._with_session(assistant_session_id, {"code": exc.code, "message": exc.message}))
             return
         except Exception:
-            yield self._sse("error", {"code": "LEARNING_ASSISTANT_LLM_FAILED", "message": "AI 学习助手回答生成失败，请稍后重试"})
+            yield self._sse(
+                "error",
+                self._with_session(
+                    assistant_session_id,
+                    {"code": "LEARNING_ASSISTANT_LLM_FAILED", "message": "AI 学习助手回答生成失败，请稍后重试"},
+                ),
+            )
             return
 
         answer = "".join(answer_parts)
         total_latency_ms = int((time.perf_counter() - start) * 1000)
+        if assistant_session_id:
+            self.session_store.append_message(
+                assistant_session_id,
+                ctx.user_id,
+                "assistant",
+                answer,
+                metadata={"retrieval_hit": bool(retrieval.sources), "source_count": len(retrieval.sources), "model": model},
+            )
         self._write_query_log(
             ctx=ctx,
             payload=payload,
@@ -118,7 +162,17 @@ class LearningAssistantService:
             total_latency_ms=total_latency_ms,
             commit=True,
         )
-        yield self._sse("answer_done", {"model": model, "total_latency_ms": total_latency_ms})
+        yield self._sse(
+            "answer_done",
+            self._with_session(
+                assistant_session_id,
+                {
+                    "model": model,
+                    "total_latency_ms": total_latency_ms,
+                    "llm_latency_ms": llm_latency_ms,
+                },
+            ),
+        )
 
     async def _retrieve_sources(self, ctx: UserContext, payload: LearningAssistantChatRequest) -> LearningAssistantRetrieval:
         """知识检索：按机构读取知识空间；无空间、Milvus 或 embedding 异常时降级为空来源。"""
@@ -204,7 +258,6 @@ class LearningAssistantService:
         sources: list[LearningAssistantSource] = []
         for item in chunks:
             document = self.repo.get_document(item.chunk.document_id, item.chunk.institution_id)
-            quote = item.chunk.chunk_text[:500]
             sources.append(
                 LearningAssistantSource(
                     document_id=item.chunk.document_id,
@@ -214,11 +267,31 @@ class LearningAssistantService:
                     page_end=item.chunk.page_end,
                     chunk_uid=item.chunk.chunk_uid,
                     score=round(item.score, 4),
-                    quote=quote,
+                    quote=item.chunk.chunk_text[:500],
                 )
             )
         return sources
 
+    def _session_response(self, state: dict[str, Any]) -> LearningAssistantSessionResponse:
+        """会话响应转换：只返回前端需要展示和后续调用的字段。"""
+        return LearningAssistantSessionResponse(
+            assistant_session_id=state["assistant_session_id"],
+            user_id=state["user_id"],
+            institution_id=state.get("institution_id"),
+            institution_name=state.get("institution_name"),
+            title=state["title"],
+            status=state["status"],
+            created_at=state["created_at"],
+            updated_at=state["updated_at"],
+            expires_in_seconds=state["expires_in_seconds"],
+        )
+
     def _sse(self, event: str, data: dict) -> str:
         """SSE 封装：统一输出 event + data 格式。"""
         return f"event: {event}\ndata: {json.dumps(data, ensure_ascii=False)}\n\n"
+
+    def _with_session(self, assistant_session_id: str | None, data: dict) -> dict:
+        """SSE 数据增强：会话式接口返回 assistant_session_id，旧接口保持兼容。"""
+        if assistant_session_id:
+            return {"assistant_session_id": assistant_session_id, **data}
+        return data