RAG/client/src/types.ts

/**
 * ChatbotSDK 核心类型定义
 *
 * 关键参数映射（SDK → 后端）：
 *   integrateId → roleId（客服角色 ID，决定 AI 人设和知识库范围）
 *   userId      → accountId（客户账号 ID，账号可绑定角色）
 *   chatId      → 自动管理（从 /conversation/list 获取或自动生成，是对话唯一标识）
 */

/** SDK 初始化配置 */
export interface SDKConfig {
  // === 必传参数 ===
  /** 集成标识 → 后端 roleId 参数（客服角色 ID），决定 AI 人设和知识库检索范围 */
  integrateId: string | number;
  /** 后端 API 域名 */
  requestDomain: string;

  // === 用户标识 ===
  /** 宿主用户标识 → 后端 accountId 参数（客户账号 ID），账号可绑定角色 */
  userId?: string;

  // === 鉴权配置 ===
  /** SDK JWT Token（从 /open-api/auth/token 换取），用于访问 /ai/** 接口 */
  token?: string;
  /** 可用客服角色列表（与 token 配套使用，决定用户可选择哪些角色） */
  roles?: Array<{ id: string | number; key?: string; name?: string }>;

  // === 知识库 ===
  /** 默认知识库分类 ID */
  categoryId?: number;
  /** 是否显示知识库下拉切换 */
  showCategorySwitch?: boolean;

  // === UI 配置 ===
  /** 弹窗标题文字，默认 "AI 智能助手" */
  title?: string;
  /** 弹窗宽度(px)，默认 380 */
  width?: number;
  /** 弹窗高度(px)，默认 520，最小 300 */
  height?: number;
  /** 保密声明 HTML 内容。提供后直接渲染（不走后端拉取），传空串 '' 彻底隐藏，传 undefined 则从后端拉取 */
  disclaimer?: string;
  /** 悬浮按钮位置，默认 "right-bottom" */
  position?: 'left-bottom' | 'right-bottom';
  /** 主色调，默认 "#4F46E5" */
  primaryColor?: string;
  /** 悬浮按钮图标（可传 URL 或 SVG 字符串），默认使用极光粒子动画图标 */
  launcherIcon?: string;
  /** 是否显示新对话按钮，默认 true */
  showClear?: boolean;
  /** 是否显示管理面板，默认 false */
  showAdminPanel?: boolean;
  /** 欢迎态快捷问题列表，点击即自动发送，默认空数组 */
  quickReplies?: string[];
  /** 是否在 AI 回复后展示推荐问题（suggest-message-list），默认 true */
  suggestions?: boolean;
  /** 主题模式，默认 'light' */
  theme?: 'light' | 'dark';
  /** 是否显示首访提示气泡（延迟 1.5s 弹出），默认 true */
  showTeaser?: boolean;
  /** 提示气泡文字，留空则使用 i18n 默认值 */
  teaserText?: string;
  /** 是否允许用户拖拽缩放窗口（右下角手柄），默认 true。移动端(≤480px)强制全屏时忽略 */
  resizable?: boolean;

  // === 水印 ===
  /** 聊天窗口水印文字（浅色背景平铺），不传则不显示。建议传入用户ID、工号等标识信息 */
  watermark?: string;

  // === 行为配置 ===
  /** 是否启用流式输出，默认 true */
  streaming?: boolean;
  /**
   * 是否启用 RAG 知识库检索对话，默认 true。
   * 开启后对话将使用 /chat/rag/sse 接口，后端会根据角色绑定的知识库分类自动检索。
   * 如果角色未绑定知识库，后端自动降级为普通对话，不会报错。
   */
  enableRag?: boolean;
  /** RAG 查询重写策略，默认 "REWRITE"（在 enableRag=true 时生效） */
  rewriteStrategy?: 'NONE' | 'REWRITE' | 'TRANSLATION' | 'COMPRESSION' | 'MULTI_QUERY';
  /** 界面语言，默认 "zh-CN" */
  locale?: string;
  /** 是否输出调试日志，默认 true */
  debug?: boolean;

  // === 通知配置 ===
  /** 弹窗关闭时收到新消息是否播放提示音，默认 false */
  sound?: boolean;
  /** 弹窗关闭时收到新消息是否发送桌面通知，默认 false */
  notification?: boolean;

  // === 生命周期回调 ===
  /** SDK 内部异常回调（网络错误、SSE 解析失败等），宿主可接入监控 */
  onError?: (error: { message: string; code: string; detail?: unknown }) => void;
  /** SDK 初始化完成回调 */
  onReady?: () => void;
  /** 收到新 AI 消息回调 */
  onMessage?: (msg: ChatMessage) => void;
}

/** 解析后的完整配置（所有可选字段已填充默认值） */
export interface ResolvedConfig {
  /** 集成标识（同时也是 roleId，客服角色 ID） */
  integrateId: string;
  /** 后端 API 域名 */
  requestDomain: string;
  /** 客户账号 ID → 后端 accountId */
  userId?: string;
  /** SDK JWT Token → 访问 /ai/** 接口的认证头 */
  token?: string;
  /** 可用客服角色列表 */
  roles?: Array<{ id: string | number; key?: string; name?: string }>;
  /** 知识库分类 ID */
  categoryId?: number;
  /** 是否显示知识库切换 */
  showCategorySwitch: boolean;
  /** 弹窗标题 */
  title: string;
  /** 弹窗宽度 */
  width: number;
  /** 弹窗高度 */
  height: number;
  /** 保密声明 HTML 内容（来自 SDKConfig 或后端动态拉取） */
  disclaimer?: string;
  /** 位置 */
  position: 'left-bottom' | 'right-bottom';
  /** 主色调 */
  primaryColor: string;
  /** 悬浮按钮图标 */
  launcherIcon: string;
  /** 显示新对话按钮 */
  showClear: boolean;
  /** 显示管理面板 */
  showAdminPanel: boolean;
  /** 欢迎态快捷问题列表 */
  quickReplies: string[];
  /** 是否在 AI 回复后展示推荐问题 */
  suggestions: boolean;
  /** 主题模式 */
  theme: 'light' | 'dark';
  /** 是否显示首访提示气泡 */
  showTeaser: boolean;
  /** 提示气泡文字 */
  teaserText: string;
  /** 是否允许用户拖拽缩放窗口 */
  resizable: boolean;
  /** 水印文字，不传则不显示 */
  watermark?: string;
  /** 流式输出 */
  streaming: boolean;
  /** 是否启用 RAG 知识库检索 */
  enableRag: boolean;
  /** RAG 查询重写策略 */
  rewriteStrategy: string;
  /** 界面语言 */
  locale: string;
  /** 调试日志 */
  debug: boolean;
  /** 提示音 */
  sound: boolean;
  /** 桌面通知 */
  notification: boolean;
  /** 异常回调 */
  onError?: (error: { message: string; code: string; detail?: unknown }) => void;
  /** 初始化完成回调 */
  onReady?: () => void;
  /** 新消息回调 */
  onMessage?: (msg: ChatMessage) => void;
  /** 当前对话 ID（自动管理，从 /conversation/list 获取或自动生成） */
  chatId: string;
}

/** 聊天消息 */
export interface ChatMessage {
  /** 消息唯一 ID */
  id: string;
  /** 角色：user 或 ai */
  role: 'user' | 'ai';
  /** 消息文本内容 */
  content: string;
  /** 时间戳（毫秒） */
  timestamp: number;
  /** 可选：RAG 引用来源 */
  sources?: RagSource[];
  /** 可选：用户反馈 'up' | 'down'，预留后端对接位 */
  feedback?: 'up' | 'down';
  /** 可选：点踩原因分类（仅 feedback='down' 时有效） */
  feedbackReason?: 'inaccurate' | 'irrelevant' | 'incomplete' | 'other';
  /** 可选：点踩补充说明 */
  feedbackComment?: string;
}

/** RAG 引用来源 */
export interface RagSource {
  documentId: string;
  title: string;
  sourceName: string;
  chunkIndex: number;
  score: number;
  snippet: string;
}

/** 知识库分类节点（树形结构） */
export interface CategoryNode {
  id: string;
  name: string;
  parentId?: string;
  children?: CategoryNode[];
}

/** 知识库分类平铺项 */
export interface CategoryItem {
  id: string;
  name: string;
  parentId?: string;
}

/** 会话摘要 */
export interface ConversationSummary {
  id: string;
  chatId: string;
  accountId?: string;
  roleId?: number;
  roleName?: string;
  messageCount?: number;
  lastMessageTime?: number;
  createdAt?: number;
}

/** 会话详情 */
export interface ConversationDetail {
  id: string;
  chatId: string;
  accountId?: string;
  messages: ChatMessage[];
}

/** 本地缓存数据结构 */
export interface CacheData {
  messages: ChatMessage[];
  updatedAt: number;
  chatId?: string;
}

/** SDK 公开 API 接口 */
export interface ChatbotSDKInstance {
  /** 初始化 SDK */
  init(config: SDKConfig): void;
  /** 销毁 SDK 实例 */
  destroy(): void;
  /** 打开聊天窗口 */
  open(): void;
  /** 关闭聊天窗口 */
  close(): void;
  /** 切换窗口显示/隐藏 */
  toggle(): void;
  /** 开启新对话（生成新的 chatId） */
  clearHistory(): void;
}

/** 后端 API 响应通用结构 */
export interface ApiResponse<T = unknown> {
  success: boolean;
  message?: string;
  data?: T;
  total?: number;
  page?: number;
  size?: number;
  pages?: number;
}