Simon
293 lines
10 KiB
Python
293 lines
10 KiB
Python
# =============================================================================
|
||
# 企微IT智能服务台 — 会话模型
|
||
# =============================================================================
|
||
# 说明：对应数据库 conversations 表，存储所有会话信息
|
||
# 核心概念：每个员工的每次咨询对应一个会话（Conversation）
|
||
# 会话状态流转：ai_handling → queued → serving → resolved
|
||
# =============================================================================
|
||
|
||
import uuid
|
||
from datetime import datetime
|
||
from typing import Any, Dict, Optional
|
||
|
||
from sqlalchemy import Boolean, DateTime, Index, Integer, JSON, String
|
||
from sqlalchemy.orm import Mapped, mapped_column
|
||
|
||
from app.database import Base
|
||
|
||
|
||
class Conversation(Base):
|
||
"""会话模型 — 对应 conversations 表。
|
||
|
||
每个员工的一次完整咨询过程对应一个会话记录。
|
||
包含员工信息、会话状态、紧急度评分、标签等核心数据。
|
||
|
||
Attributes:
|
||
id: 会话唯一标识（UUID，数据库自动生成）
|
||
employee_id: 企微员工UserID（关联企微通讯录）
|
||
employee_name: 员工姓名（冗余存储，减少关联查询）
|
||
department: 员工部门
|
||
position: 员工岗位
|
||
level: 员工等级（用于 VIP 判断）
|
||
status: 会话状态（ai_handling/queued/serving/resolved）
|
||
is_vip: VIP标记（基于企微通讯录规则自动匹配）
|
||
is_pinned: 置顶标记（坐席手动操作）
|
||
is_todo: 代办标记（坐席手动操作）
|
||
urgency_score: 紧急度评分（1-5，数值越大越紧急）
|
||
tags: 标签集合（JSONB，存储举手/需介入/情绪等标记）
|
||
assigned_agent_id: 分配的坐席ID
|
||
last_message_at: 最后消息时间（用于会话排序）
|
||
last_message_summary: 最后消息摘要（会话列表预览用）
|
||
created_at: 创建时间
|
||
updated_at: 更新时间
|
||
"""
|
||
|
||
# 表名（必须和架构文档 DDL 一致）
|
||
__tablename__ = "conversations"
|
||
|
||
# --------------------------------------------------------------------------
|
||
# 字段定义
|
||
# --------------------------------------------------------------------------
|
||
|
||
# 主键：UUID，Python端生成（兼容PostgreSQL和SQLite）
|
||
id: Mapped[str] = mapped_column(
|
||
String(36),
|
||
primary_key=True,
|
||
default=lambda: str(uuid.uuid4()),
|
||
)
|
||
|
||
# 企业微信企业ID（US-7: 区分主企业和下游企业员工）
|
||
# 默认值为主企业 corp_id，下游企业员工使用下游企业 corp_id
|
||
corp_id: Mapped[str] = mapped_column(
|
||
String(64),
|
||
nullable=False,
|
||
default="",
|
||
comment="企业微信企业ID（主企业或下游企业）",
|
||
)
|
||
|
||
# 企微员工UserID（NOT NULL，配合 corp_id 唯一标识员工）
|
||
employee_id: Mapped[str] = mapped_column(
|
||
String(64),
|
||
nullable=False,
|
||
comment="企微员工UserID",
|
||
)
|
||
|
||
# 员工姓名（冗余存储，避免每次查询都要关联企微API）
|
||
employee_name: Mapped[str] = mapped_column(
|
||
String(128),
|
||
nullable=False,
|
||
default="",
|
||
comment="员工姓名",
|
||
)
|
||
|
||
# 部门
|
||
department: Mapped[str] = mapped_column(
|
||
String(256),
|
||
nullable=False,
|
||
default="",
|
||
comment="部门",
|
||
)
|
||
|
||
# 岗位
|
||
position: Mapped[str] = mapped_column(
|
||
String(128),
|
||
nullable=False,
|
||
default="",
|
||
comment="岗位",
|
||
)
|
||
|
||
# 等级（用于 VIP 判断：总监及以上为 VIP）
|
||
level: Mapped[str] = mapped_column(
|
||
String(64),
|
||
nullable=False,
|
||
default="",
|
||
comment="等级",
|
||
)
|
||
|
||
# 会话状态（CHECK 约束：只能取四种值）
|
||
# ai_handling: AI处理中（第二步启用）
|
||
# queued: 排队中，等待坐席接入
|
||
# serving: 服务中，坐席正在处理
|
||
# resolved: 已结单
|
||
status: Mapped[str] = mapped_column(
|
||
String(20),
|
||
nullable=False,
|
||
default="queued",
|
||
comment="会话状态: ai_handling/queued/serving/resolved",
|
||
)
|
||
|
||
# VIP标记（基于企微通讯录API规则自动匹配）
|
||
is_vip: Mapped[bool] = mapped_column(
|
||
Boolean,
|
||
nullable=False,
|
||
default=False,
|
||
comment="VIP标记",
|
||
)
|
||
|
||
# 置顶标记（坐席手动操作，置顶的会话在列表中优先显示）
|
||
is_pinned: Mapped[bool] = mapped_column(
|
||
Boolean,
|
||
nullable=False,
|
||
default=False,
|
||
comment="置顶标记",
|
||
)
|
||
|
||
# 代办标记（坐席手动操作，标记需要后续跟进的会话）
|
||
is_todo: Mapped[bool] = mapped_column(
|
||
Boolean,
|
||
nullable=False,
|
||
default=False,
|
||
comment="代办标记",
|
||
)
|
||
|
||
# 紧急度评分（1-5，数值越大越紧急）
|
||
# 计算公式：基础分 + 情绪加成 + VIP加成 + 重复追问加成
|
||
urgency_score: Mapped[int] = mapped_column(
|
||
Integer,
|
||
nullable=False,
|
||
default=1,
|
||
comment="紧急度1-5",
|
||
)
|
||
|
||
# 标签集合（JSON 格式，存储结构化标记数据，兼容所有数据库）
|
||
# 示例：{"hand_raise": true, "emotion": "angry", "need_intervene": true}
|
||
tags: Mapped[Dict[str, Any]] = mapped_column(
|
||
JSON,
|
||
nullable=False,
|
||
default=dict,
|
||
comment="标签集合",
|
||
)
|
||
|
||
# 分配的坐席ID（可为空，表示尚未分配坐席）
|
||
assigned_agent_id: Mapped[Optional[str]] = mapped_column(
|
||
String(64),
|
||
nullable=True,
|
||
comment="分配的坐席ID",
|
||
)
|
||
|
||
# 协作坐席ID列表（JSON 数组，存储所有被邀请来协作的坐席ID）
|
||
# 和 assigned_agent_id 的区别：
|
||
# - assigned_agent_id：会话的「主责」坐席（接单人），只有他才能结单/转接
|
||
# - collaborating_agent_ids：被邀请来协助的坐席，可以查看和回复，但不能结单
|
||
# 设计决策：用 JSON 而非关联表，因为协作人数少（1-3人），JSON 查询足够
|
||
collaborating_agent_ids: Mapped[list] = mapped_column(
|
||
JSON,
|
||
nullable=False,
|
||
default=list,
|
||
comment="协作坐席ID列表",
|
||
)
|
||
|
||
# 被邀请参与会话的非坐席人员列表（JSON 数组，存储员工ID或部门ID）
|
||
# 和 collaborating_agent_ids 的区别：
|
||
# - collaborating_agent_ids：坐席 → 坐席协作（摇人）
|
||
# - participants：坐席 → 任意员工/部门（邀请功能 P0-09~P0-11）
|
||
# 格式：[ {"id": "employee_id", "name": "姓名", "department": "部门", "type": "employee"},
|
||
# {"id": "dept_id", "name": "部门名", "type": "department"} ]
|
||
# 设计决策：存储完整信息，减少企微API调用
|
||
participants: Mapped[list] = mapped_column(
|
||
JSON,
|
||
nullable=False,
|
||
default=list,
|
||
comment="被邀请参与会话的人员列表（邀请功能）",
|
||
)
|
||
|
||
# AI 实质性回复计数（排除打招呼/呼叫人工的引导回复）
|
||
# 当计数 >= 3 时，前端显示「呼叫坐席」按钮
|
||
ai_substantive_reply_count: Mapped[int] = mapped_column(
|
||
Integer,
|
||
nullable=False,
|
||
default=0,
|
||
comment="AI实质性回复计数（满3次可呼叫坐席）",
|
||
)
|
||
|
||
# 影响范围（受影响人数，0=未评估，数值越大影响范围越广）
|
||
impact_scope: Mapped[int] = mapped_column(
|
||
Integer,
|
||
nullable=False,
|
||
default=0,
|
||
comment="影响范围",
|
||
)
|
||
|
||
# 阻断性标记（问题是否阻断员工正常工作流程）
|
||
is_blocking: Mapped[bool] = mapped_column(
|
||
Boolean,
|
||
nullable=False,
|
||
default=False,
|
||
comment="阻断性标记",
|
||
)
|
||
|
||
# 情绪状态（normal: 正常, worried: 担忧, angry: 愤怒, urgent: 紧急）
|
||
emotion_state: Mapped[str] = mapped_column(
|
||
String(20),
|
||
nullable=False,
|
||
default="normal",
|
||
comment="情绪状态",
|
||
)
|
||
|
||
# Dify 会话ID（用于多轮对话上下文保持）
|
||
# Dify 侧通过此 ID 关联同一员工的多轮对话
|
||
dify_conversation_id: Mapped[Optional[str]] = mapped_column(
|
||
String(128),
|
||
nullable=True,
|
||
default=None,
|
||
comment="Dify会话ID（多轮对话上下文）",
|
||
)
|
||
|
||
# 最后消息时间（用于会话列表按最新消息排序）
|
||
last_message_at: Mapped[Optional[datetime]] = mapped_column(
|
||
DateTime(timezone=True),
|
||
nullable=True,
|
||
comment="最后消息时间",
|
||
)
|
||
|
||
# 最后消息摘要（会话列表预览用，截取消息前256字符）
|
||
last_message_summary: Mapped[str] = mapped_column(
|
||
String(256),
|
||
nullable=False,
|
||
default="",
|
||
comment="最后消息摘要",
|
||
)
|
||
|
||
# 创建时间
|
||
created_at: Mapped[datetime] = mapped_column(
|
||
DateTime(timezone=True),
|
||
nullable=False,
|
||
default=datetime.now,
|
||
comment="创建时间",
|
||
)
|
||
|
||
# 更新时间
|
||
updated_at: Mapped[datetime] = mapped_column(
|
||
DateTime(timezone=True),
|
||
nullable=False,
|
||
default=datetime.now,
|
||
onupdate=datetime.now,
|
||
comment="更新时间",
|
||
)
|
||
|
||
# --------------------------------------------------------------------------
|
||
# 索引定义（和架构文档 DDL 严格一致）
|
||
# --------------------------------------------------------------------------
|
||
__table_args__ = (
|
||
# 按状态查询（如查询所有排队中的会话）
|
||
Index("idx_conversations_status", "status"),
|
||
# 按员工ID查询（如查询某个员工的所有会话）
|
||
Index("idx_conversations_employee_id", "employee_id"),
|
||
# US-7: 按企业ID查询（如查询某企业所有会话）
|
||
Index("idx_conversations_corp_id", "corp_id"),
|
||
# 按坐席ID查询（如查询某个坐席正在服务的所有会话）
|
||
Index("idx_conversations_assigned_agent", "assigned_agent_id"),
|
||
# 按紧急度倒序查询（紧急度高的排前面）
|
||
Index("idx_conversations_urgency_score", "urgency_score"),
|
||
# 按最后消息时间倒序查询（最新消息的排前面）
|
||
Index("idx_conversations_last_message_at", "last_message_at"),
|
||
)
|
||
|
||
def __repr__(self) -> str:
|
||
"""会话对象的字符串表示，方便调试。"""
|
||
return (
|
||
f"<Conversation(id={self.id}, employee={self.employee_name}, "
|
||
f"status={self.status}, urgency={self.urgency_score})>"
|
||
)
|
||
|