wecom_it_smart_desk/backend/app/models/knowledge_base.py

# =============================================================================
# 企微IT智能服务台 — 知识库模型
# =============================================================================
# 说明：对应数据库 knowledge_base 表，存储IT知识库FAQ
# 分类：按问题类型（硬件/软件/网络/安全/账号/其他）
# 支持标签、命中统计
# =============================================================================

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 KnowledgeBase(Base):
    """知识库FAQ模型 — 对应 knowledge_base 表。

    存储IT知识库的问答对，支持分类、标签、命中统计。

    Attributes:
        id: 知识ID（UUID）
        category: 分类（硬件/软件/网络/安全/账号/其他）
        title: 问题标题
        content: 答案内容（支持富文本）
        tags: 标签列表（JSON数组）
        view_count: 查看次数
        use_count: 使用次数（坐席引用次数）
        created_at: 创建时间
        updated_at: 更新时间
    """

    # 表名
    __tablename__ = "knowledge_base"

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

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

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

    # 问题标题
    title: Mapped[str] = mapped_column(
        String(256),
        nullable=False,
        comment="问题标题",
    )

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

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

    # 查看次数
    view_count: Mapped[int] = mapped_column(
        Integer,
        nullable=False,
        default=0,
        comment="查看次数",
    )

    # 使用次数（坐席引用次数）
    use_count: Mapped[int] = mapped_column(
        Integer,
        nullable=False,
        default=0,
        comment="使用次数",
    )

    # --------------------------------------------------------------------------
    # Tier0 扩展字段 — 图同步状态（D1 解读2 合一）
    # --------------------------------------------------------------------------

    # 图同步状态（pending / synced / failed）
    graph_sync_status: Mapped[str] = mapped_column(
        String(20),
        nullable=False,
        default="pending",
        comment="图同步状态：pending / synced / failed",
    )

    # 关联 Neo4j Issue 节点的 uuid（写入图后回填）
    graph_node_uuid: Mapped[Optional[str]] = mapped_column(
        String(36),
        nullable=True,
        comment="关联 Neo4j Issue 节点的 uuid",
    )

    # 创建时间
    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_kb_category", "category"),
        # Index("idx_kb_tags", "tags"),  # JSON 字段不能用 btree，需要 GIN 索引或注释
    )

    def __repr__(self) -> str:
        """知识库对象的字符串表示。"""
        return f"<KnowledgeBase(id={self.id}, category={self.category}, title={self.title})>"