# AI助手Web客户端 - 后端集成指南

## 📋 概述

本Web客户端已成功对接im-api后端聊天服务，支持：
- ✅ 应用列表加载（支持搜索、按创建时间倒排）
- ✅ 应用选择
- ✅ SSE流式对话
- ✅ 推荐问题加载
- ✅ 完整的对话交互

## 🔧 配置说明

### 1. 环境变量配置

复制 `.env.example` 为 `.env` 并修改：

```bash
# im-api后端服务地址
IM_API_BASE_URL=http://localhost:8080

# 认证Token（可选，如果后端需要认证）
AUTH_TOKEN=your_jwt_token_here

# 服务端口
PORT=15000
```

### 2. 后端API要求

确保im-api后端服务已启动，并提供以下接口：

#### 2.1 获取应用列表
```
GET /api/ai-assistant/chatapp
```

响应格式：
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "app_id",
      "appName": "应用名称",
      "appDescription": "应用描述",
      "appAvatar": "头像URL",
      "category": "分类",
      "sortNum": 1,
      "enableRecommendation": true,
      "conversationStarter": "欢迎语",
      "reasoningEnable": false
    }
  ]
}
```

#### 2.2 获取推荐问题
```
GET /api/ai-assistant/chatapp/{appId}/getRecommendQuestion?pageSize=3&current=1
```

响应格式：
```json
{
  "code": 200,
  "data": {
    "records": [
      {
        "question": "推荐问题1"
      }
    ]
  }
}
```

#### 2.3 发送消息（SSE流式）
```
POST /api/ai-assistant/chat/completions/message
Content-Type: application/json
```

请求体：
```json
{
  "chatId": "chat_id_or_null",
  "appId": "app_id",
  "equipment": "web",
  "messageTag": "AI_TAG",
  "body": {
    "messages": [
      {
        "role": "user",
        "content": "用户消息"
      }
    ],
    "channel": "web",
    "attachmentIds": [],
    "recommendQuestions": [],
    "variables": {},
    "reasoning": "false"
  }
}
```

SSE响应格式：
```
event: MESSAGE_DETAIL
data: {
  "detailId": "detail_id",
  "chatId": "chat_id",
  "question": {
    "content": "用户问题",
    "role": "user"
  },
  "answer": {
    "content": "AI回答",
    "role": "assistant"
  },
  "status": "PROCESSING|FINISH|ERROR"
}
```

## 🚀 启动步骤

### 1. 安装依赖

```bash
cd web_client
pip3 install -r requirements.txt
```

### 2. 配置环境变量

```bash
# 复制配置文件
cp .env.example .env

# 编辑配置
vim .env
```

### 3. 启动服务

```bash
# 使用启动脚本
./start.sh

# 或直接运行
python3 app.py
```

### 4. 访问应用

打开浏览器访问：http://localhost:15000

## 📝 使用流程

1. **选择应用**
   - 页面加载后自动显示应用列表
   - 可以使用搜索框搜索应用
   - 点击应用卡片进入对话

2. **开始对话**
   - 进入对话界面后显示欢迎消息
   - 如果应用启用了推荐问题，会显示快捷回复按钮
   - 在输入框输入消息，按Enter或点击发送按钮

3. **查看回复**
   - AI回复以流式方式实时显示
   - 支持打字指示器动画
   - 自动滚动到最新消息

4. **返回应用列表**
   - 点击左上角返回按钮
   - 可以切换到其他应用

## 🔍 故障排查

### 问题1：应用列表加载失败

**原因**：后端服务未启动或地址配置错误

**解决**：
1. 检查im-api服务是否启动
2. 检查 `.env` 中的 `IM_API_BASE_URL` 配置
3. 查看浏览器控制台和后端日志

### 问题2：消息发送失败

**原因**：认证失败或SSE连接问题

**解决**：
1. 检查是否需要配置 `AUTH_TOKEN`
2. 检查浏览器是否支持SSE
3. 查看网络请求详情

### 问题3：推荐问题不显示

**原因**：应用未启用推荐或后端接口返回空

**解决**：
1. 检查应用的 `enableRecommendation` 字段
2. 检查后端推荐问题接口是否正常

## 📊 技术架构

```
┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   浏览器    │ ───> │ Flask代理层  │ ───> │  im-api后端 │
│  (前端UI)   │ <─── │  (web_client)│ <─── │  (聊天服务) │
└─────────────┘      └──────────────┘      └─────────────┘
```

### 代理层功能

1. **请求转发**：将前端请求代理到im-api后端
2. **SSE流式转发**：支持Server-Sent Events流式响应
3. **错误处理**：统一的错误处理和日志记录
4. **CORS支持**：解决跨域问题

## 🎯 下一步优化

1. **认证集成**
   - 集成真实的登录系统
   - 从登录获取JWT token
   - 支持token刷新

2. **功能增强**
   - 支持文件上传
   - 支持语音输入
   - 支持多会话管理
   - 支持历史记录

3. **性能优化**
   - 添加请求缓存
   - 优化SSE连接管理
   - 添加重连机制

## 📞 联系方式

如有问题，请联系：huazm@glodon.com