xiaozhi/jk-rag-platform/INTERACTION_LOGIC.md

交互逻辑说明文档 (INTERACTION_LOGIC.md)

本文档描述了 jk-rag-platform（管理平台）与 jk-rag-chat-client（用户界面/通用问答客户端）之间的交互逻辑。

1. 系统概述

系统采用双层架构设计：

• 管理平台 (jk-rag-platform)：作为集中的管理枢纽。提供知识库管理、RAG 应用监控以及用户/租户配置等功能。
• 问答客户端 (jk-rag-chat-client)：作为高性能、统一的对话交互界面。

---

2. 详细交互流程

2.1 登录流程

系统根据入口点和用户上下文支持多种身份验证路径，分为“智能问答端”与“开放平台端”。

端口定义与职责划分

端点	端口	角色描述	核心逻辑
智能问答端	3900	面向终端用户的极简交互入口	无登录界面。自动识别 SSO 或外部 Token；Token 失效时重定向至 3200。
开放平台端	3200	系统统一认证中心与管理入口	提供标准凭据及 SSO 选择界面；承接所有显式登录请求。

Mermaid 流程图：认证路径

graph TD
    %% 定义端点
    subgraph "智能问答端 (Port 3900)"
        QA_Entry[用户访问问答链接] --> QA_Check{Token 是否有效?}
        QA_Check -- "是" --> QA_Direct[直接进入问答界面]
        QA_Check -- "否/无" --> Redirect_3200[重定向至 3200 登录页]

        QA_Entry -- "来自外部系统/SSO" --> QA_AutoAuth{自动识别来源}
        QA_AutoAuth -- "OA SSO" --> SSO_Flow[执行 SSO 流程]
        QA_AutoAuth -- "外部系统 Token" --> Ext_Flow[验证并进入]
    end

    subgraph "开放平台端 (Port 3200)"
        Login_Page[统一登录界面] --> Choice{选择方式}
        Choice -- "标准凭据" --> Local_Login[账号密码登录]
        Choice -- "OA 系统 SSO" --> SSO_Flow

        Local_Login --> Success[登录成功并跳转回原请求地址]
        SSO_Flow --> Success
    end

    %% 关系连接
    Redirect_3200 --> Login_Page
    Success -.-> QA_Direct

    %% 原有路径逻辑映射
    subgraph "认证细节"
        direction TB
        SSO_Flow --> S1[重定向至集团 OAuth URL]
        S1 --> S2[用户在 OA 平台完成认证]
        S2 --> S3[回调 Code/State 至平台]
        S3 --> S4[平台通过 apis.jklogin 用 Code 换取 Token]
        S4 --> Success

        Ext_Flow --> E1[从 慧监理/掌监 等系统重定向进入]
        E1 --> E2[URL 参数中携带 Token 回调]
        E2 --> E3[平台通过 apis.checkToken 验证 Token]
        E3 --> QA_Direct

        Local_Login --> L1[输入账号密码 + 验证码]
        L1 --> L2[通过 apis.login 验证]
        L2 --> Success
    end

路径详情：

路径	端点	描述	关键组件 / API
智能问答自动认证	3900	根据来源自动识别 SSO 或外部 Token，实现无感登录。	src/router.tsx, apis.checkToken
标准凭据登录	3200	在开放平台端进行显式的账号密码验证。	src/pages/login/index.tsx, apis.login
OA SSO 认证	3200/3900	通过集团 OAuth 进行重定向认证，支持两端触发。	apis.jklogin
外部系统集成	3900	外部系统携带 Token 直接进入，无需经过 3200 登录页。	apis.checkToken

---

2.2 “智能首页”体验 (从发现到问答)

... (此处省略后续内容以保持简洁，实际写入时会包含完整文档)