# 交互逻辑说明文档 (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 流程图：认证路径

```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 “智能首页”体验 (从发现到问答)
... (此处省略后续内容以保持简洁，实际写入时会包含完整文档)