内容
# 智能AI订单支持策略助理
一款Spring Boot助理，具备以下功能：
- 从MongoDB（`orderdb`）查找订单数据
- 将策略文件摄入到基于MongoDB的策略块存储中
- 使用OpenAI聊天模型，结合订单上下文和策略上下文，回答支持问题
## 本项目提供的内容
- 订单支持查询API：`POST /api/support/query`
- 策略摄入API：`POST /api/support/policies/ingest`
- 内部MCP服务器API：`POST /api/mcp`
- `policies/`文件夹中的本地策略示例
- 首次启动时自动插入种子订单记录
## 技术栈
- Java 21
- Spring Boot 3.3.x
- Spring Data MongoDB
- Spring AI OpenAI聊天
## 前提条件
- 已安装Java 21
- 已安装Maven
- 本地运行的MongoDB，端口为27017
- OpenAI API密钥
## 配置
应用程序读取以下环境变量：
- `MONGODB_URI`（默认值：`mongodb://localhost:27017/orderdb`）
- `OPENAI_API_KEY`（聊天响应所需）
- `OPENAI_MODEL`（默认值：`gpt-4o-mini`）
- `SERVER_PORT`（默认值：`8080`）
- `POLICY_PDF_DIRECTORY`（默认值：`./policies`）
- `MCP_API_KEY`（调用`/api/mcp`所需）
## 运行应用程序
PowerShell：
```powershell
$env:MONGODB_URI="mongodb://localhost:27017/orderdb"
$env:OPENAI_API_KEY="your-openai-api-key"
$env:MCP_API_KEY="your-internal-mcp-key"
mvn spring-boot:run
```
API将在以下地址可用：
- `http://localhost:8080`
Web UI：
- `http://localhost:8080/`
## 加载策略文件（RAG摄入）
此端点扫描目录并摄入支持的策略文件：
- `.pdf`
- `.txt`
- `.md`
### 选项1：使用默认文件夹（`./policies`）
```powershell
Invoke-RestMethod -Method Post -Uri "http://localhost:8080/api/support/policies/ingest"
```
### 选项2：传递自定义目录
```powershell
Invoke-RestMethod -Method Post -Uri "http://localhost:8080/api/support/policies/ingest?directory=./policies"
```
示例响应：
```json
{
"filesIngested": 3,
"chunksIngested": 18
}
```
## 提出订单支持问题
端点：
- `POST /api/support/query`
请求负载：
```json
{
"customerId": "C-991",
"orderId": "O-1001",
"question": "我的订单延迟了。可以退款或赔偿运费吗？",
"confirmCancellation": false
}
```
PowerShell调用：
```powershell
$body = @{
customerId = "C-991"
orderId = "O-1001"
question = "我的订单延迟了。可以退款或赔偿运费吗？"
confirmCancellation = $false
} | ConvertTo-Json
Invoke-RestMethod -Method Post `
-Uri "http://localhost:8080/api/support/query" `
-ContentType "application/json" `
-Body $body
```
示例响应形状：
```json
{
"answer": "...assistant response..."
}
```
取消安全性行为：
- 助理不会自动执行取消操作。
- 它会首先检查订单状态和策略上下文。
- 只有在提供明确确认时，才会执行`cancelOrder`。
要明确确认取消，请发送：
```json
{
"customerId": "C-991",
"orderId": "O-1001",
"question": "请取消此订单。我确认取消。",
"confirmCancellation": true
}
```
## 内部MCP工具用于事务操作
应用程序包含一个内部MCP服务器，为聊天机器人使用提供实时的订单工具：
- `getOrderStatus(id)`
- `cancelOrder(id)`
端点：
- `POST /api/mcp`
- 必要的头部：`X-MCP-API-KEY: <your MCP_API_KEY>`
PowerShell示例，带有头部：
```powershell
$mcpHeaders = @{ "X-MCP-API-KEY" = $env:MCP_API_KEY }
```
### 列表工具
```json
{
"jsonrpc": "2.0",
"id": "1",
"method": "tools/list",
"params": {}
}
```
PowerShell调用：
```powershell
$listBody = @{
jsonrpc = "2.0"
id = "1"
method = "tools/list"
params = @{}
} | ConvertTo-Json -Depth 5
Invoke-RestMethod -Method Post `
-Uri "http://localhost:8080/api/mcp" `
-Headers $mcpHeaders `
-ContentType "application/json" `
-Body $listBody
```
### 调用getOrderStatus
```json
{
"jsonrpc": "2.0",
"id": "2",
"method": "tools/call",
"params": {
"name": "getOrderStatus",
"arguments": {
"id": "O-1001"
}
}
}
```
PowerShell调用：
```powershell
$statusBody = @{
jsonrpc = "2.0"
id = "2"
method = "tools/call"
params = @{
name = "getOrderStatus"
arguments = @{ id = "O-1001" }
}
} | ConvertTo-Json -Depth 8
Invoke-RestMethod -Method Post `
-Uri "http://localhost:8080/api/mcp" `
-Headers $mcpHeaders `
-ContentType "application/json" `
-Body $statusBody
```
### 调用cancelOrder
```json
{
"jsonrpc": "2.0",
"id": "3",
"method": "tools/call",
"params": {
"name": "cancelOrder",
"arguments": {
"id": "O-1001"
}
}
}
```
PowerShell调用：
```powershell
$cancelBody = @{
jsonrpc = "2.0"
id = "3"
method = "tools/call"
params = @{
name = "cancelOrder"
arguments = @{ id = "O-1001" }
}
} | ConvertTo-Json -Depth 8
Invoke-RestMethod -Method Post `
-Uri "http://localhost:8080/api/mcp" `
-Headers $mcpHeaders `
-ContentType "application/json" `
-Body $cancelBody
```
注意：
- 聊天机器人会自动为每个支持问题调用`getOrderStatus`。
- 如果问题中包含“取消”或“取消订单”等字样，聊天机器人还会调用`cancelOrder`。
## 包含的种子数据
启动时，应用程序会插入两条默认记录。您也可以按需触发相同的插入：
```powershell
Invoke-RestMethod -Method Post -Uri "http://localhost:8080/api/support/orders/seed"
```
示例响应：
```json
{
"ordersSeeded": 2
}
```
默认记录：
- `customerId: C-991`, `orderId: O-1001`, 状态 `IN_TRANSIT`
- `customerId: C-992`, `orderId: O-1002`, 状态 `DELIVERED`
## 包含的本地策略
项目包含以下启动策略文档：
- `policies/returns-and-refunds-policy.md`
- `policies/shipping-and-delivery-policy.md`
- `policies/cancellations-and-modifications-policy.md`
## 故障排除
- 如果查询答案提到缺少策略上下文，请先运行摄入。
- 如果订单未找到，请验证`customerId` + `orderId`值或在`orderdb.orders`中检查MongoDB数据。
- 如果OpenAI调用失败，请验证`OPENAI_API_KEY`和外部网络访问。
