Fix SSE route dependency and align architecture docs

backend/app/workflows/__init__.py

@@ -1,5 +1,9 @@
+"""Initialize the app.workflows package."""
+
 from .rag_workflow import RagState, rag_workflow, run_rag_workflow, stream_rag_workflow
 from .compliance_workflow import ComplianceState, compliance_workflow, run_compliance_workflow
+# Keep package boundaries explicit so backend imports stay predictable.
+
 
 __all__ = [
     "RagState",

backend/app/workflows/compliance_workflow.py

@@ -1,8 +1,13 @@
+"""Define workflow state for compliance workflow."""
+
 from typing import TypedDict, List
 from langgraph.graph import StateGraph, END
+# Keep workflow state definitions compact so transitions stay easy to audit.
+
 
 
 class ComplianceState(TypedDict):
+    """Track workflow state for compliance state."""
     document_path: str
     raw_text: str
     segments: List[dict]
@@ -12,7 +17,7 @@ class ComplianceState(TypedDict):
 
 
 def parse_document(state: ComplianceState) -> dict:
-    """解析文档"""
+    """Parse document."""
     from app.services import get_document_service
     doc_service = get_document_service(
         "/airegulation/demo-mao/backend/data/raw",
@@ -23,7 +28,7 @@ def parse_document(state: ComplianceState) -> dict:
 
 
 def segment_document(state: ComplianceState) -> dict:
-    """AI语义分段"""
+    """Handle segment document."""
     from app.services import llm_service
     prompt = f"""请分析以下设计方案文档，按照设计意图将其分成若干语义段落。
 
@@ -39,7 +44,7 @@ def segment_document(state: ComplianceState) -> dict:
 输出格式：
 [{{"intent": "...", "startPos": 0, "endPos": 100, "keywords": [...]}}]"""
 
-    # 简化处理：返回基本分段
+    # Keep workflow state definitions compact so transitions stay easy to audit.
     segments = [
         {
             "id": 1,
@@ -53,7 +58,7 @@ def segment_document(state: ComplianceState) -> dict:
 
 
 def match_regulations(state: ComplianceState) -> dict:
-    """法规匹配"""
+    """Handle match regulations."""
     from app.services import embedding_service, milvus_service
     matched = []
 
@@ -83,7 +88,7 @@ def match_regulations(state: ComplianceState) -> dict:
 
 
 def calculate_risk(state: ComplianceState) -> dict:
-    """计算风险等级"""
+    """Handle calculate risk."""
     segments = state["matched_regulations"]
 
     high_count = 0
@@ -133,7 +138,7 @@ def calculate_risk(state: ComplianceState) -> dict:
 
 
 def generate_suggestions(state: ComplianceState) -> dict:
-    """生成优先建议"""
+    """Handle generate suggestions."""
     actions = []
 
     for segment in state["segments"]:
@@ -149,7 +154,7 @@ def generate_suggestions(state: ComplianceState) -> dict:
     return {"priority_actions": actions}
 
 
-# 构建工作流图
+# Keep workflow state definitions compact so transitions stay easy to audit.
 compliance_graph = StateGraph(ComplianceState)
 
 compliance_graph.add_node("parse", parse_document)
@@ -169,7 +174,7 @@ compliance_workflow = compliance_graph.compile()
 
 
 async def run_compliance_workflow(document_path: str) -> ComplianceState:
-    """运行合规分析工作流"""
+    """Handle run compliance workflow."""
     initial_state: ComplianceState = {"document_path": document_path}
     result = compliance_workflow.invoke(initial_state)
     return result

backend/app/workflows/rag_workflow.py

@@ -1,8 +1,13 @@
+"""Define workflow state for rag workflow."""
+
 from typing import TypedDict, List
 from langgraph.graph import StateGraph, END
+# Keep workflow state definitions compact so transitions stay easy to audit.
+
 
 
 class RagState(TypedDict):
+    """Track workflow state for rag state."""
     query: str
     query_embedding: List[float]
     retrieved_docs: List[dict]
@@ -12,14 +17,14 @@ class RagState(TypedDict):
 
 
 def embed_query(state: RagState) -> dict:
-    """将查询转为向量"""
+    """Embed query."""
     from app.services import embedding_service
     embedding = embedding_service.embed_single(state["query"])
     return {"query_embedding": embedding}
 
 
 def retrieve_docs(state: RagState) -> dict:
-    """向量检索"""
+    """Handle retrieve docs."""
     from app.services import milvus_service
     from app.core.config import settings
     docs = milvus_service.search(
@@ -30,7 +35,7 @@ def retrieve_docs(state: RagState) -> dict:
 
 
 def build_context(state: RagState) -> dict:
-    """构建上下文"""
+    """Build context."""
     context_parts = []
     sources = []
 
@@ -46,7 +51,7 @@ def build_context(state: RagState) -> dict:
 
 
 def generate_answer(state: RagState) -> dict:
-    """生成答案"""
+    """Handle generate answer."""
     from app.services import llm_service
     prompt = f"""请根据以下法规内容回答用户问题，并在回答中标注引用的法规条款。
 
@@ -64,7 +69,7 @@ def generate_answer(state: RagState) -> dict:
     return {"answer": answer}
 
 
-# 构建工作流图
+# Keep workflow state definitions compact so transitions stay easy to audit.
 rag_graph = StateGraph(RagState)
 
 rag_graph.add_node("embed", embed_query)
@@ -82,23 +87,23 @@ rag_workflow = rag_graph.compile()
 
 
 async def run_rag_workflow(query: str) -> RagState:
-    """运行RAG工作流"""
+    """Handle run rag workflow."""
     initial_state: RagState = {"query": query}
     result = rag_workflow.invoke(initial_state)
     return result
 
 
 def stream_rag_workflow(query: str):
-    """流式运行RAG工作流"""
+    """Stream rag workflow."""
     from app.services import llm_service
 
-    # 先完成检索阶段
+    # Keep workflow state definitions compact so transitions stay easy to audit.
     state: RagState = {"query": query}
     state.update(embed_query(state))
     state.update(retrieve_docs(state))
     state.update(build_context(state))
 
-    # 流式生成阶段
+    # Keep workflow state definitions compact so transitions stay easy to audit.
     prompt = f"""请根据以下法规内容回答用户问题，并在回答中标注引用的法规条款。
 
 法规内容：