WIP-CHECKPOINT[auth-refactor]: 固化工程师崩溃前部分成果 + 同树其他未提交WIP（仅源码，不含密钥/二进制）-- 待重激活工程师续作

2026-07-07 21:52:11 +08:00
parent 242c1967ff
commit fab75760e0
203 changed files with 21504 additions and 3345 deletions
@@ -0,0 +1,140 @@
+# =============================================================================
+# 企微IT智能服务台 — 满意度评价 Pydantic Schema
+# =============================================================================
+# 说明：定义满意度评价的请求/响应数据结构
+# 包含：评价提交、评价查询、评价统计等
+# =============================================================================
+
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+# --------------------------------------------------------------------------
+# 评价提交请求 Schema
+# --------------------------------------------------------------------------
+class EvaluationSubmitRequest(BaseModel):
+    """满意度评价提交请求 Schema。
+
+    员工提交服务评价时发送的请求。
+
+    Attributes:
+        star_rating: 星级评分（1-5，必选）
+        emoji: 表情评价（satisfied/neutral/dissatisfied，必选）
+        feedback_text: 文字反馈（可选，最大200字）
+    """
+
+    star_rating: int = Field(
+        ...,
+        ge=1,
+        le=5,
+        description="星级评分（1-5）",
+    )
+    emoji: str = Field(
+        ...,
+        description="表情评价（satisfied/neutral/dissatisfied）",
+    )
+    feedback_text: Optional[str] = Field(
+        None,
+        max_length=200,
+        description="文字反馈（可选，限200字）",
+    )
+
+
+# --------------------------------------------------------------------------
+# 评价记录响应 Schema
+# --------------------------------------------------------------------------
+class EvaluationResponse(BaseModel):
+    """满意度评价响应 Schema。
+
+    返回评价记录详情。
+
+    Attributes:
+        id: 评价记录ID
+        conversation_id: 关联的会话ID
+        employee_id: 评价员工UserID
+        employee_name: 评价员工姓名
+        star_rating: 星级评分
+        emoji: 表情评价
+        feedback_text: 文字反馈
+        created_at: 评价时间
+    """
+
+    id: str = Field(..., description="评价记录ID")
+    conversation_id: str = Field(..., description="关联的会话ID")
+    employee_id: str = Field(..., description="评价员工UserID")
+    employee_name: str = Field(default="", description="评价员工姓名")
+    star_rating: int = Field(..., description="星级评分（1-5）")
+    emoji: str = Field(..., description="表情评价")
+    feedback_text: Optional[str] = Field(None, description="文字反馈")
+    created_at: datetime = Field(..., description="评价时间")
+
+    model_config = {"from_attributes": True}
+
+
+# --------------------------------------------------------------------------
+# 评价统计项 Schema
+# --------------------------------------------------------------------------
+class EvaluationStatsItem(BaseModel):
+    """评价统计项 Schema。
+
+    某个具体的统计维度。
+
+    Attributes:
+        label: 统计标签（如"5星"、"满意"等）
+        count: 数量
+        percentage: 占比（百分比）
+    """
+
+    label: str = Field(..., description="统计标签")
+    count: int = Field(..., description="数量")
+    percentage: float = Field(..., description="占比（百分比）")
+
+
+# --------------------------------------------------------------------------
+# 评价统计响应 Schema
+# --------------------------------------------------------------------------
+class EvaluationStatsResponse(BaseModel):
+    """满意度评价统计响应 Schema。
+
+    返回评价数据的统计分析结果，供管理后台使用。
+
+    Attributes:
+        total_count: 总评价数
+        avg_star_rating: 平均星级
+        star_distribution: 星级分布统计
+        emoji_distribution: 表情分布统计
+        recent_evaluations: 最近评价记录（可选）
+    """
+
+    total_count: int = Field(..., description="总评价数")
+    avg_star_rating: float = Field(..., description="平均星级")
+    star_distribution: List[EvaluationStatsItem] = Field(
+        ..., description="星级分布统计"
+    )
+    emoji_distribution: List[EvaluationStatsItem] = Field(
+        ..., description="表情分布统计"
+    )
+    recent_evaluations: Optional[List[EvaluationResponse]] = Field(
+        None, description="最近评价记录"
+    )
+
+
+# --------------------------------------------------------------------------
+# 评价邀请推送 Schema
+# --------------------------------------------------------------------------
+class EvaluationInviteRequest(BaseModel):
+    """评价邀请推送请求 Schema。
+
+    坐席结单后，系统向员工推送评价邀请。
+
+    Attributes:
+        conversation_id: 会话ID
+        employee_id: 员工UserID
+    """
+
+    conversation_id: str = Field(..., description="会话ID")
+    employee_id: str = Field(..., description="员工UserID")
+    employee_name: str = Field(default="", description="员工姓名")
+    agent_name: str = Field(default="IT服务台", description="坐席姓名")