# Merchant AI HTTP API 调用说明

本文档用于喂给外部“解读 AI”或其他服务平台，让 AI 在对话中正确调用本项目的 HTTP JSON API 进行订单统计、线下订单分析和商户排行分析。

## 1. 服务定位

本项目是一个中间层 HTTP JSON API 服务。AI 不直接请求后台订单系统，也不直接拼接后台订单接口参数。

本项目负责：

- 接收 AI 的结构化分析请求
- 解析时间意图
- 调用后台订单接口
- 复用本项目内部统计逻辑
- 返回适合 AI 解读的 JSON 结果

## 2. 启动方式

本地开发启动：

```bash
php -S 127.0.0.1:8080 -t public public/index.php
```

健康检查：

```http
GET http://127.0.0.1:8080/health
```

正常返回：

```json
{
  "success": true,
  "data": {
    "status": "ok",
    "service": "merchant-ai-api"
  }
}
```

## 3. 接口列表

### 3.1 订单汇总

```http
POST /api/order-summary
```

对应工具：`get_order_summary`

用途：订单总数、活跃商户数、成功订单数、订单金额合计、实付金额合计。

### 3.2 线下订单分析

```http
POST /api/offline-stats
```

对应工具：`get_offline_stats`

用途：订单状态分布、支付方式分布、订单类型分布、平均订单金额、平均实付金额、最大订单金额。

### 3.3 商户排行榜

```http
POST /api/merchant-ranking
```

对应工具：`get_merchant_ranking`

用途：按订单数、成功订单数、订单金额或实付金额生成商户排行。

## 4. 请求格式

所有统计接口都使用：

```http
Content-Type: application/json
```

统一请求示例：

```json
{
  "timePreset": "today",
  "status": -1,
  "keyword": "",
  "fieldKey": "all",
  "payType": "",
  "type": "",
  "btcId": null
}
```

## 5. 时间参数规则

AI 应优先传 `timePreset`，不要直接传自然语言时间。

推荐：

```json
{
  "timePreset": "today"
}
```

支持的 `timePreset`：

| 值 | 含义 |
| --- | --- |
| `today` | 今天 |
| `yesterday` | 昨天 |
| `last_7_days` | 最近 7 天，包含今天 |
| `last_30_days` | 最近 30 天，包含今天 |
| `this_week` | 本周，周一到今天 |
| `last_week` | 上周，周一到周日 |
| `this_month` | 本月，1 号到今天 |
| `last_month` | 上月，1 号到月末 |
| `custom` | 自定义时间范围 |

自定义时间：

```json
{
  "timePreset": "custom",
  "startDate": "2026-06-01",
  "endDate": "2026-06-23"
}
```

自定义时间约束：

- `startDate` 格式必须是 `YYYY-MM-DD`
- `endDate` 格式必须是 `YYYY-MM-DD`
- `startDate` 不能晚于 `endDate`
- 不要传 `2026/06/01`，自定义日期统一使用 `2026-06-01`

兼容旧字段：

```json
{
  "date": "2026/06/01-2026/06/23"
}
```

AI 默认不要使用 `date`，除非调用平台只能传固定后台日期格式。

## 6. AI 对话到接口参数映射

用户说“今天订单怎么样？”时调用：

```json
{
  "timePreset": "today"
}
```

推荐接口：`POST /api/order-summary`

用户说“分析一下昨天线下订单”时调用：

```json
{
  "timePreset": "yesterday"
}
```

推荐接口：`POST /api/offline-stats`

用户说“看本月商户排行”时调用：

```json
{
  "timePreset": "this_month",
  "sortBy": "totalRealPay",
  "limit": 10
}
```

推荐接口：`POST /api/merchant-ranking`

用户说“查 6 月 1 日到 6 月 23 日订单统计”时调用：

```json
{
  "timePreset": "custom",
  "startDate": "2026-06-01",
  "endDate": "2026-06-23"
}
```

推荐接口：`POST /api/order-summary`

## 7. 常用筛选参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `status` | integer | 订单状态，默认 `-1` 表示全部 |
| `keyword` | string | 搜索关键词，当前会传给后台接口的 `real_name` |
| `fieldKey` | string | 搜索字段，默认 `all` |
| `payType` | string | 支付方式，对应后台 `pay_type` |
| `type` | string | 订单类型，对应后台 `type` |
| `btcId` | integer | 商户分类 ID，对应后台 `btc_id` |

## 8. 商户排行参数

`/api/merchant-ranking` 额外支持：

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `sortBy` | string | 排序字段 |
| `limit` | integer | 返回商户数量，默认 `10`，最大 `100` |

`sortBy` 可选值：

| 值 | 含义 |
| --- | --- |
| `orderCount` | 按订单数排序 |
| `successOrderCount` | 按成功订单数排序 |
| `totalOrderAmount` | 按订单金额排序 |
| `totalRealPay` | 按实付金额排序，默认值 |

## 9. 响应格式

成功响应：

```json
{
  "success": true,
  "data": {}
}
```

失败响应：

```json
{
  "success": false,
  "error": {
    "code": "server_error",
    "message": "错误信息"
  }
}
```

常见错误：

| code | 含义 | 处理方式 |
| --- | --- | --- |
| `not_found` | 路由不存在 | 检查 URL |
| `method_not_allowed` | 请求方法错误 | 统计接口必须使用 POST |
| `server_error` | 服务端或后台接口异常 | 根据 message 排查 |

## 10. AI 调用约束

AI 必须遵守以下规则：

1. 统计接口必须使用 `POST`。
2. 不要用浏览器 `GET` 方式访问统计接口。
3. 时间优先使用 `timePreset`。
4. 只有用户明确给出起止日期时，才使用 `timePreset=custom`。
5. 自定义日期必须使用 `YYYY-MM-DD`。
6. 不要传 `今天`、`昨天`、`本月` 这类中文自然语言给接口。
7. 不要伪造不存在的筛选字段。
8. 不要把后台系统 token 暴露给用户。
9. 不要直接调用后台订单接口，只调用本项目 HTTP API。
10. 如果用户问题不包含时间，默认使用 `timePreset=today`。

## 11. PowerShell 调用示例

订单汇总：

```powershell
Invoke-RestMethod `
  -Uri "http://127.0.0.1:8080/api/order-summary" `
  -Method POST `
  -ContentType "application/json" `
  -Body '{"timePreset":"today"}'
```

线下订单分析：

```powershell
Invoke-RestMethod `
  -Uri "http://127.0.0.1:8080/api/offline-stats" `
  -Method POST `
  -ContentType "application/json" `
  -Body '{"timePreset":"yesterday"}'
```

商户排行：

```powershell
Invoke-RestMethod `
  -Uri "http://127.0.0.1:8080/api/merchant-ranking" `
  -Method POST `
  -ContentType "application/json" `
  -Body '{"timePreset":"this_month","sortBy":"totalRealPay","limit":10}'
```

## 12. 推荐给 AI 的简短系统提示词

```text
你需要通过 Merchant AI HTTP API 分析订单数据。统计接口只能使用 POST。不要直接请求后台订单接口，不要暴露 token。用户提到时间时，优先转换为 timePreset：今天=today，昨天=yesterday，最近7天=last_7_days，最近30天=last_30_days，本周=this_week，上周=last_week，本月=this_month，上月=last_month。只有明确起止日期时使用 custom，并传 startDate/endDate，格式 YYYY-MM-DD。不要把“今天”“昨天”“本月”等自然语言直接作为参数传给接口。如果用户没说时间，默认 timePreset=today。
```