# 报告兼容接口测试文档

## 概述
测试 shudao-chat-py 中新增的报告兼容接口，这些接口完全对齐 Go 版本的实现。

## 测试环境
- 基础URL: `http://127.0.0.1:22000`
- AIChat服务: `http://127.0.0.1:28002`

## 1. 完整报告生成流程（SSE）

### 1.1 使用外部 Token（代理到 aichat）

```bash
curl -X POST "http://127.0.0.1:22000/apiv1/report/complete-flow" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_EXTERNAL_TOKEN" \
  -d '{
    "user_question": "请帮我生成一份关于安全生产的报告",
    "window_size": 5,
    "n_results": 5,
    "ai_conversation_id": null,
    "is_network_search_enabled": false,
    "enable_online_model": false
  }'
```

**预期行为**：
- 请求被代理到 `http://127.0.0.1:28002/api/v1/report/complete-flow`
- 返回 SSE 流式响应
- 日志显示 `[报告兼容] 代理到 aichat 服务`

### 1.2 使用本地 Token（降级到本地流式聊天）

```bash
curl -X POST "http://127.0.0.1:22000/apiv1/report/complete-flow" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_LOCAL_TOKEN" \
  -d '{
    "user_question": "请帮我生成一份关于安全生产的报告",
    "window_size": 5,
    "n_results": 5,
    "ai_conversation_id": null,
    "is_network_search_enabled": false,
    "enable_online_model": false
  }'
```

**预期行为**：
- 降级到本地流式聊天接口 `/apiv1/stream/chat-with-db`
- 返回 SSE 流式响应
- 日志显示 `[报告兼容] 降级到本地流式聊天`

### 1.3 空问题验证

```bash
curl -X POST "http://127.0.0.1:22000/apiv1/report/complete-flow" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_TOKEN" \
  -d '{
    "user_question": "",
    "window_size": 5,
    "n_results": 5
  }'
```

**预期响应**：
```
data: {"type": "online_error", "message": "Question cannot be empty"}

data: {"type": "completed"}
```

## 2. 更新 AI 消息

### 2.1 使用外部 Token（代理到 aichat）

```bash
curl -X POST "http://127.0.0.1:22000/apiv1/report/update-ai-message" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_EXTERNAL_TOKEN" \
  -d '{
    "ai_message_id": 123,
    "content": "更新后的消息内容"
  }'
```

**预期响应**：
```json
{
  "success": true,
  "message": "AI message updated"
}
```

### 2.2 使用本地 Token（本地处理）

```bash
curl -X POST "http://127.0.0.1:22000/apiv1/report/update-ai-message" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_LOCAL_TOKEN" \
  -d '{
    "ai_message_id": 123,
    "content": "更新后的消息内容"
  }'
```

**预期行为**：
- 直接更新本地数据库中的 AI 消息
- 返回成功响应

### 2.3 无效 ID 验证

```bash
curl -X POST "http://127.0.0.1:22000/apiv1/report/update-ai-message" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_TOKEN" \
  -d '{
    "ai_message_id": 0,
    "content": "测试内容"
  }'
```

**预期响应**：
```json
{
  "success": false,
  "message": "ai_message_id cannot be empty"
}
```

## 3. 停止 SSE 流

### 3.1 使用外部 Token（代理到 aichat）

```bash
curl -X POST "http://127.0.0.1:22000/apiv1/sse/stop" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_EXTERNAL_TOKEN" \
  -d '{
    "ai_conversation_id": 456
  }'
```

**预期响应**：
```json
{
  "success": true,
  "message": "Stop request received",
  "ai_conversation_id": 456
}
```

### 3.2 使用本地 Token（本地处理）

```bash
curl -X POST "http://127.0.0.1:22000/apiv1/sse/stop" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_LOCAL_TOKEN" \
  -d '{
    "ai_conversation_id": 456
  }'
```

**预期行为**：
- 本地简单返回成功响应
- 不实际执行停止操作（因为本地流式聊天没有停止机制）

## 4. Token 识别测试

### 4.1 本地 Token 特征
本地生成的 Token 应包含以下字段之一：
- `account`
- `username`

### 4.2 外部 Token 特征
外部系统的 Token 不包含上述字段，会被识别为外部 Token

### 4.3 测试 Token 识别

```python
# Python 测试脚本
import jwt

# 本地 Token 示例
local_token_payload = {
    "account": "test_account",
    "username": "test_user",
    "exp": 1234567890
}

# 外部 Token 示例
external_token_payload = {
    "user_id": "external_user",
    "exp": 1234567890
}

# 生成 Token（不验证签名）
local_token = jwt.encode(local_token_payload, "secret", algorithm="HS256")
external_token = jwt.encode(external_token_payload, "secret", algorithm="HS256")

print(f"本地 Token: {local_token}")
print(f"外部 Token: {external_token}")
```

## 5. 完整流程测试

### 5.1 外部用户完整流程

1. 使用外部 Token 发起报告生成请求
2. 请求被代理到 aichat 服务
3. 接收 SSE 流式响应
4. 更新 AI 消息（如需要）
5. 停止 SSE 流（如需要）

### 5.2 本地用户完整流程

1. 使用本地 Token 发起报告生成请求
2. 降级到本地流式聊天
3. 接收 SSE 流式响应
4. 更新本地数据库中的 AI 消息（如需要）

## 6. 错误处理测试

### 6.1 AIChat 服务不可用

```bash
# 停止 aichat 服务后测试
curl -X POST "http://127.0.0.1:22000/apiv1/report/complete-flow" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_EXTERNAL_TOKEN" \
  -d '{
    "user_question": "测试问题"
  }'
```

**预期行为**：
- 代理失败后自动降级到本地流式聊天
- 日志显示 `[报告兼容] 代理到 aichat 失败`
- 日志显示 `[报告兼容] 降级到本地流式聊天`

### 6.2 请求体解析错误

```bash
curl -X POST "http://127.0.0.1:22000/apiv1/report/complete-flow" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_TOKEN" \
  -d 'invalid json'
```

**预期响应**：
```
data: {"type": "online_error", "message": "Request parse error: ..."}

data: {"type": "completed"}
```

## 7. 性能测试

### 7.1 并发请求测试

```bash
# 使用 Apache Bench 进行并发测试
ab -n 100 -c 10 -p request.json -T application/json \
  -H "token: YOUR_TOKEN" \
  http://127.0.0.1:22000/apiv1/report/complete-flow
```

### 7.2 长时间流式响应测试

测试长时间运行的 SSE 流是否稳定，不会中断或超时。

## 8. 日志验证

检查日志文件，确认以下关键日志：

```
[Token验证] 识别为本地 token: test_user
[Token验证] 不是本地 token 格式
[报告兼容] 代理到 aichat 服务
[报告兼容] 降级到本地流式聊天
[AIChat代理] SSE 请求: http://127.0.0.1:28002/api/v1/report/complete-flow
[报告兼容] 代理到 aichat 失败: ...
```

## 9. 接口对齐验证

确认以下接口与 Go 版本完全一致：

- ✅ `/apiv1/report/complete-flow` - POST - SSE 流式响应
- ✅ `/apiv1/report/update-ai-message` - POST - JSON 响应
- ✅ `/apiv1/sse/stop` - POST - JSON 响应

## 10. 注意事项

1. 确保 aichat 服务在 `http://127.0.0.1:28002` 运行
2. 本地 Token 和外部 Token 的识别逻辑需要根据实际 Token 结构调整
3. 降级机制确保即使 aichat 服务不可用，本地用户仍可正常使用
4. SSE 流式响应需要客户端支持 EventSource 或类似机制