Fix SSE route dependency and align architecture docs

backend/app/api/models/__init__.py

@@ -1,5 +1,14 @@
-"""API数据模型"""
+"""Initialize the app.api.models package."""
 
+from .agent import (
+    AskRequest,
+    AskResponse,
+    ChatRequest,
+    ChatResponse,
+    FeedbackRequest,
+    SessionInfo,
+    TemplateListResponse,
+)
 from .document import (
     DocumentUploadRequest,
     DocumentUploadResponse,
@@ -9,8 +18,17 @@ from .document import (
     DocumentStatusResponse,
     ErrorResponse
 )
+# Keep package boundaries explicit so backend imports stay predictable.
+
 
 __all__ = [
+    "AskRequest",
+    "AskResponse",
+    "ChatRequest",
+    "ChatResponse",
+    "FeedbackRequest",
+    "SessionInfo",
+    "TemplateListResponse",
     "DocumentUploadRequest",
     "DocumentUploadResponse",
     "SearchRequest",

backend/app/api/models/agent.py

@@ -0,0 +1,79 @@
+"""Define API models for agent endpoints."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+# Group agent transport schemas together so route modules stay focused on HTTP flow.
+
+
+class AskRequest(BaseModel):
+    """Define the Ask Request API model."""
+
+    query: str = Field(..., min_length=1, max_length=2000)
+    filters: Optional[str] = None
+    provider: Optional[str] = None
+    model: Optional[str] = None
+    top_k: Optional[int] = Field(default=None, ge=1, le=20)
+    prompt_template: Optional[str] = None
+
+
+class AskResponse(BaseModel):
+    """Define the Ask Response API model."""
+
+    answer: str
+    sources: List[Dict] = Field(default_factory=list)
+    model: str = ""
+    latency_ms: int = 0
+    retrieved_count: int = 0
+    context_tokens: int = 0
+    truncated: bool = False
+    error: Optional[str] = None
+
+
+class ChatRequest(BaseModel):
+    """Define the Chat Request API model."""
+
+    query: str = Field(..., min_length=1, max_length=2000)
+    session_id: Optional[str] = None
+    filters: Optional[str] = None
+    provider: Optional[str] = None
+    model: Optional[str] = None
+    top_k: Optional[int] = Field(default=None, ge=1, le=20)
+
+
+class ChatResponse(BaseModel):
+    """Define the Chat Response API model."""
+
+    session_id: str
+    answer: str
+    sources: List[Dict] = Field(default_factory=list)
+    model: str = ""
+    latency_ms: int = 0
+    message_count: int = 0
+
+
+class SessionInfo(BaseModel):
+    """Define the Session Info API model."""
+
+    session_id: str
+    message_count: int
+    created_at: int
+    updated_at: int
+
+
+class FeedbackRequest(BaseModel):
+    """Define the Feedback Request API model."""
+
+    session_id: str
+    message_index: int
+    rating: int = Field(..., ge=1, le=5)
+    comment: Optional[str] = None
+
+
+class TemplateListResponse(BaseModel):
+    """Define the Template List Response API model."""
+
+    templates: Dict[str, str]

backend/app/api/models/document.py

@@ -1,19 +1,21 @@
-"""文档相关Pydantic数据模型"""
+"""Define API models for document."""
 
 from pydantic import BaseModel, Field
 from typing import List, Optional, Dict, Any
 from datetime import datetime
+# Group related schema definitions so validation rules stay consistent.
+
 
 
 class DocumentUploadRequest(BaseModel):
-    """文档上传请求"""
+    """Define the Document Upload Request API model."""
     doc_name: Optional[str] = Field(None, description="文档名称")
     regulation_type: Optional[str] = Field(None, description="法规类型")
     version: Optional[str] = Field(None, description="文档版本")
 
 
 class DocumentUploadResponse(BaseModel):
-    """文档上传响应"""
+    """Define the Document Upload Response API model."""
     doc_id: str = Field(..., description="文档ID")
     doc_name: str = Field(..., description="文档名称")
     status: str = Field(..., description="处理状态")
@@ -25,14 +27,14 @@ class DocumentUploadResponse(BaseModel):
 
 
 class SearchRequest(BaseModel):
-    """检索请求"""
+    """Define the Search Request API model."""
     query: str = Field(..., description="查询文本")
     top_k: int = Field(default=10, description="返回结果数量")
     filters: Optional[str] = Field(None, description="过滤条件")
 
 
 class SearchResultItem(BaseModel):
-    """单个检索结果"""
+    """Define the Search Result Item API model."""
     id: int = Field(..., description="记录ID")
     content: str = Field(..., description="内容")
     score: float = Field(..., description="相似度分数")
@@ -40,7 +42,7 @@ class SearchResultItem(BaseModel):
 
 
 class SearchResponse(BaseModel):
-    """检索响应"""
+    """Define the Search Response API model."""
     query: str = Field(..., description="查询文本")
     total: int = Field(..., description="结果总数")
     results: List[SearchResultItem] = Field(default_factory=list, description="结果列表")
@@ -48,7 +50,7 @@ class SearchResponse(BaseModel):
 
 
 class DocumentStatusResponse(BaseModel):
-    """文档状态响应"""
+    """Define the Document Status Response API model."""
     doc_id: str = Field(..., description="文档ID")
     status: str = Field(..., description="状态")
     num_chunks: Optional[int] = Field(None, description="分块数量")
@@ -56,7 +58,7 @@ class DocumentStatusResponse(BaseModel):
 
 
 class ErrorResponse(BaseModel):
-    """错误响应"""
+    """Define the Error Response API model."""
     error: str = Field(..., description="错误类型")
     message: str = Field(..., description="错误消息")
     timestamp: datetime = Field(default_factory=datetime.now, description="时间戳")