wecom_it_smart_desk/backend/app/models/knowledge_suggestion.py

# =============================================================================
# 企微IT智能服务台 — 知识库优化建议模型
# =============================================================================
# 说明：对应数据库 knowledge_suggestions 表
# 存储AI分析生成的优化建议，用于知识库迭代
# 分析维度：错误标注高频问题、未命中知识库的会话、AI不确定回复
# =============================================================================

import uuid
from datetime import datetime
from typing import List, Optional

from sqlalchemy import DateTime, Index, Integer, JSON, String, Text
from sqlalchemy.orm import Mapped, mapped_column

from app.database import Base


class KnowledgeSuggestion(Base):
    """知识库优化建议模型 — 对应 knowledge_suggestions 表。

    存储AI自动分析生成的优化建议，用于知识库持续迭代。

    Attributes:
        id: 建议ID（UUID）
        suggestion_type: 建议类型（new_faq=新增FAQ/update=更新/outdated=标记过时）
        status: 状态（pending=待审核/approved=已通过/rejected=已拒绝/applied=已应用）
        title: 建议标题（新增/更新的FAQ标题）
        content: 建议内容（答案内容）
        category: 分类
        tags: 标签列表（JSON数组）
        source_type: 分析来源（annotation=标注数据/conversation=会话数据/ai_uncertain=AI不确定）
        source_data: 来源数据（JSON，存储相关会话ID或标注ID列表）
        reason: 生成理由（AI分析的理由）
        reject_reason: 拒绝理由（审核拒绝时填写）
        reviewer_id: 审核人ID
        reviewed_at: 审核时间
        created_at: 创建时间
        updated_at: 更新时间
    """

    # 表名
    __tablename__ = "knowledge_suggestions"

    # --------------------------------------------------------------------------
    # 字段定义
    # --------------------------------------------------------------------------

    # 主键
    id: Mapped[str] = mapped_column(
        String(36),
        primary_key=True,
        default=lambda: str(uuid.uuid4()),
    )

    # 建议类型
    suggestion_type: Mapped[str] = mapped_column(
        String(20),
        nullable=False,
        default="new_faq",
        comment="new_faq=新增FAQ/update=更新/outdated=标记过时",
    )

    # 状态
    status: Mapped[str] = mapped_column(
        String(20),
        nullable=False,
        default="pending",
        index=True,
        comment="pending=待审核/approved=已通过/rejected=已拒绝/applied=已应用",
    )

    # 建议标题
    title: Mapped[str] = mapped_column(
        String(256),
        nullable=False,
        comment="新增/更新的FAQ标题",
    )

    # 建议内容
    content: Mapped[str] = mapped_column(
        Text,
        nullable=False,
        comment="答案内容",
    )

    # 分类
    category: Mapped[str] = mapped_column(
        String(64),
        nullable=False,
        default="其他",
        comment="分类：硬件/软件/网络/安全/账号/其他",
    )

    # 标签列表
    tags: Mapped[List[str]] = mapped_column(
        JSON,
        nullable=False,
        default=list,
        comment="标签列表",
    )

    # 分析来源
    source_type: Mapped[str] = mapped_column(
        String(30),
        nullable=False,
        comment="annotation=标注数据/conversation=会话数据/ai_uncertain=AI不确定",
    )

    # 来源数据（JSON）
    source_data: Mapped[Optional[List[str]]] = mapped_column(
        JSON,
        nullable=True,
        comment="相关会话ID或标注ID列表",
    )

    # 生成理由
    reason: Mapped[Optional[str]] = mapped_column(
        Text,
        nullable=True,
        comment="AI分析的理由",
    )

    # 拒绝理由
    reject_reason: Mapped[Optional[str]] = mapped_column(
        Text,
        nullable=True,
        comment="审核拒绝时填写",
    )

    # 审核人ID
    reviewer_id: Mapped[Optional[str]] = mapped_column(
        String(36),
        nullable=True,
        comment="审核人ID",
    )

    # 审核时间
    reviewed_at: Mapped[Optional[datetime]] = mapped_column(
        DateTime(timezone=True),
        nullable=True,
        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="更新时间",
    )

    # --------------------------------------------------------------------------
    # 索引定义
    # --------------------------------------------------------------------------
    __table_args__ = (
        Index("idx_suggestion_status", "status"),
        Index("idx_suggestion_type", "suggestion_type"),
        Index("idx_suggestion_created", "created_at"),
    )

    def __repr__(self) -> str:
        """建议对象的字符串表示。"""
        return f"<KnowledgeSuggestion(id={self.id}, type={self.suggestion_type}, status={self.status})>"