# 客运页面 API 接口文档

## 📌 文档说明

本文档用于记录**客运页面（Traffic）** 所有后端 API 接口的详细信息，包括接口地址、请求参数、返回数据格式及测试方法。

---

## 🔧 基础配置

### 接口基础信息

| 项目 | 说明 |
|-----|------|
| **Controller 类名** | `TrafficApiController` |
| **基础路径** | `/api/traffic` |
| **请求方式** | `POST` |
| **Content-Type** | `application/json` |
| **鉴权方式** | Header 中携带 `token` |
| **加密方式** | SM4（根据配置文件决定是否启用） |

### 测试环境配置

**开发环境地址示例：**
```
http://192.168.16.193:8888/juntech-ysdp/api/traffic/{接口路径}
```

**测试工具推荐：**
- Postman
- Apifox
- cURL

---

## 📡 接口列表

### 1. 获取进出站客流排名 TOP10

#### 接口信息

| 项目 | 内容 |
|-----|------|
| **接口名称** | 获取进出站客流排名TOP10 |
| **接口路径** | `/api/traffic/getInOutStationRank/v1` |
| **请求方式** | `POST` |
| **接口说明** | 查询单线路站点（非换乘站）的客流排名TOP10，按今日客流量降序排列 |
| **适用页面** | Traffic1 组件 |

#### 请求示例

**请求地址：**
```
POST http://192.168.16.193:8888/juntech-ysdp/api/traffic/getInOutStationRank/v1
```

**请求 Headers：**
```json
{
  "Content-Type": "application/json",
  "token": "your-token-here"
}
```

**请求 Body：**
```json
{}
```

> 注：该接口无需传参，自动查询当天数据

#### 返回参数

**成功返回示例：**
```json
{
  "success": true,
  "code": 200,
  "msg": "请求成功!",
  "data": [
    {
      "lineId": "03",
      "stationId": "0313",
      "stationName": "上海火车站",
      "total": "8.40",
      "compareTotal": "6.20",
      "sortNo": null
    },
    {
      "lineId": "07",
      "stationId": "0753",
      "stationName": "静安寺",
      "total": "7.80",
      "compareTotal": "6.50",
      "sortNo": null
    }
  ]
}
```

**返回字段说明：**

| 字段名 | 类型 | 说明 |
|-------|------|------|
| `success` | Boolean | 请求是否成功 |
| `code` | Integer | HTTP状态码，200表示成功 |
| `msg` | String | 返回消息 |
| `data` | Array | 站点排名数据列表 |
| `data[].lineId` | String | 线路编号（单线路，如 "03"） |
| `data[].stationId` | String | 站点ID |
| `data[].stationName` | String | 站点名称 |
| `data[].total` | String | 今日客流量（单位：万人次） |
| `data[].compareTotal` | String | 对比日客流量（单位：万人次） |

**业务逻辑说明：**
- 只返回 `lineId` 不含逗号的站点（单线路站点 = 进出站）
- 自动排除指定的不统计站点（如0316-0324等）
- 统计时段：当日 5:00 - 24:00
- 对比日期：优先读取 `ys_operate_manager` 表的 `compareDate` 字段，否则默认为前一天

---

### 2. 获取换乘站客流排名 TOP10

#### 接口信息

| 项目 | 内容 |
|-----|------|
| **接口名称** | 获取换乘站客流排名TOP10 |
| **接口路径** | `/api/traffic/getTransferStationRank/v1` |
| **请求方式** | `POST` |
| **接口说明** | 查询多线路换乘站的客流排名TOP10，按今日客流量降序排列 |
| **适用页面** | Traffic2 组件 |

#### 请求示例

**请求地址：**
```
POST http://192.168.16.193:8888/juntech-ysdp/api/traffic/getTransferStationRank/v1
```

**请求 Headers：**
```json
{
  "Content-Type": "application/json",
  "token": "your-token-here"
}
```

**请求 Body：**
```json
{}
```

#### 返回参数

**成功返回示例：**
```json
{
  "success": true,
  "code": 200,
  "msg": "请求成功!",
  "data": [
    {
      "lineId": "01,03,15",
      "stationId": "0115",
      "stationName": "上海南站",
      "total": "15.80",
      "compareTotal": "12.30",
      "sortNo": null
    },
    {
      "lineId": "01,09,11",
      "stationId": "0118",
      "stationName": "徐家汇",
      "total": "14.20",
      "compareTotal": "11.80",
      "sortNo": null
    }
  ]
}
```

**返回字段说明：**

| 字段名 | 类型 | 说明 |
|-------|------|------|
| `data[].lineId` | String | 线路编号（多线路，用逗号分隔，如 "01,03,15"） |
| 其他字段 | - | 同接口1 |

**业务逻辑说明：**
- 只返回 `lineId` 包含逗号的站点（多线路站点 = 换乘站）
- 其他逻辑同接口1

---

### 3. 清理客运页面接口缓存

#### 接口信息

| 项目 | 内容 |
|-----|------|
| **接口名称** | 清理客运页面接口缓存 |
| **接口路径** | `/api/traffic/cleanCache` |
| **请求方式** | `POST` |
| **接口说明** | 清理所有客运页面相关的 Redis 缓存 |
| **适用场景** | 数据更新后需要立即刷新缓存时使用 |

#### 请求示例

**请求地址：**
```
POST http://192.168.16.193:8888/juntech-ysdp/api/traffic/cleanCache
```

**请求 Headers：**
```json
{
  "Content-Type": "application/json",
  "token": "your-token-here"
}
```

**请求 Body：**
```json
{}
```

#### 返回参数

**成功返回示例：**
```json
{
  "success": true,
  "code": 200,
  "msg": "请求成功!",
  "data": "缓存清理成功"
}
```

**业务逻辑说明：**
- 清理所有以 `api_traffic_*` 为前缀的 Redis 缓存键
- 包括：进出站排名缓存、换乘站排名缓存等所有客运页面接口的缓存

---

## 🧪 测试指南

### Postman 测试步骤

#### 1. 导入接口

**方式一：手动创建**

1. 打开 Postman，新建请求
2. 设置请求方式为 `POST`
3. 输入接口地址，例如：
   ```
   http://192.168.16.193:8888/juntech-ysdp/api/traffic/getInOutStationRank/v1
   ```
4. 添加 Headers：
   - Key: `Content-Type`, Value: `application/json`
   - Key: `token`, Value: `your-token-value`
5. Body 选择 `raw` + `JSON`，输入 `{}`
6. 点击 `Send` 发送请求

**方式二：导入 cURL 命令**

```bash
curl --location 'http://192.168.16.193:8888/juntech-ysdp/api/traffic/getInOutStationRank/v1' \
--header 'Content-Type: application/json' \
--header 'token: your-token-here' \
--data '{}'
```

#### 2. 检查返回结果

**成功标志：**
- `success` 字段为 `true`
- `code` 字段为 `200`
- `data` 数组包含站点数据（最多10条）

**失败处理：**
- `code` 为 `500`：服务器异常，查看 `error` 字段（开发环境）
- `code` 为 `400`：请求参数错误或鉴权失败

#### 3. 缓存测试

**测试缓存是否生效：**

1. 第一次请求：观察响应时间（例如：500ms）
2. 第二次请求：响应时间应显著降低（例如：50ms）
3. 调用 `cleanCache` 接口清理缓存
4. 再次请求，响应时间恢复到第一次的水平

**禁用缓存测试：**

在请求中添加 Header：
```
noCache: true
```

---

## 🔑 数据字典

### 线路编号对照表

| 线路编号 | 线路名称 |
|---------|---------|
| 01 | 1号线 |
| 02 | 2号线 |
| 03 | 3号线 |
| 04 | 4号线 |
| 06 | 6号线 |
| 07 | 7号线 |
| 08 | 8号线 |
| 09 | 9号线 |
| 10 | 10号线 |
| 11 | 11号线 |
| 12 | 12号线 |
| 13 | 13号线 |
| 14 | 14号线 |
| 15 | 15号线 |
| 16 | 16号线 |
| 18 | 18号线 |
| 51 | 浦江线 |

### 缓存键规则

| 缓存键前缀 | 说明 |
|-----------|------|
| `api_traffic_inOutStationRankV1_` | 进出站客流排名缓存 |
| `api_traffic_transferStationRankV1_` | 换乘站客流排名缓存 |

**缓存时效：** 由配置文件 `application.yml` 中的 `api-cache-expire` 参数控制（默认单位：分钟）

---

## 🚨 常见问题

### Q1: 接口返回 `{"success": false, "code": 500}`？

**可能原因：**
1. 数据库连接失败
2. `ys_yunying` 表无数据或表结构不匹配
3. SQL 语法错误（检查 MyBatis XML）

**排查步骤：**
1. 检查后端日志中的异常堆栈
2. 确认数据库中 `ys_yunying` 表有当天数据
3. 检查 `ys_station` 表是否存在

---

### Q2: 返回数据少于 10 条？

**可能原因：**
1. 当天实际符合条件的站点少于 10 个
2. 进出站/换乘站的分布不均匀

**解决方案：**
- 检查数据库中 `ys_yunying` 表的 `line_id` 字段分布
- 确认是否有足够的单线路/多线路站点数据

---

### Q3: `compareTotal` 字段为空？

**可能原因：**
1. `ys_operate_manager` 表中 `compareDate` 字段未配置
2. 对比日期的数据不存在

**排查步骤：**
1. 查询 `ys_operate_manager` 表，确认 `compareDate` 字段值
2. 检查对比日期在 `ys_yunying` 表中是否有数据

---

## 📝 后续接口规划

### 待开发接口（占位）

#### 4. 获取单站客流详情

**接口路径：** `/api/traffic/getStationDetail/v1`  
**接口说明：** 根据线路ID和站点ID查询该站的详细客流数据（进出站/换乘站时段分布）  
**适用页面：** Traffic4 组件  
**状态：** 📋 待开发

---

#### 5. 获取客诉排名统计

**接口路径：** `/api/traffic/getComplaintRank/v1`  
**接口说明：** 查询客诉类型排名TOP7 + 年度客诉总数/A类投诉统计  
**适用页面：** Traffic5 组件  
**状态：** 📋 待开发

---

#### 6. 获取站点活动列表

**接口路径：** `/api/traffic/getStationActivityList/v1`  
**接口说明：** 根据线路、站点、月份筛选活动列表（按时间排序）  
**适用页面：** Traffic7 组件  
**状态：** 📋 待开发

---

#### 7. 获取线路舆情排名

**接口路径：** `/api/traffic/getLinePublicOpinionRank/v1`  
**接口说明：** 查询各线路的舆情评论数量排名TOP5  
**适用页面：** Traffic8 组件  
**状态：** 📋 待开发

---

#### 8. 获取舆情评论列表

**接口路径：** `/api/traffic/getPublicOpinionComments/v1`  
**接口说明：** 查询舆情评论列表（支持关键词搜索）  
**适用页面：** Traffic8 组件  
**状态：** 📋 待开发

---

## 📚 附录

### A. 数据表结构参考

#### ys_yunying（客流信息表）

| 字段名 | 类型 | 说明 |
|-------|------|------|
| id | VARCHAR | 主键 |
| line_id | VARCHAR | 线路编号（如 "03"） |
| station_id | VARCHAR | 站点ID（如 "0313"） |
| beg_time | DATETIME | 数据开始时间 |
| end_time | DATETIME | 数据结束时间 |
| pull_num | BIGINT | 进站客流数 |
| departure_num | BIGINT | 出站客流数 |
| file_name | VARCHAR | 文件名 |
| del_flag | CHAR | 删除标记（0=正常，1=删除） |
| create_time | DATETIME | 创建时间 |
| update_time | DATETIME | 更新时间 |

#### ys_station（站点信息表）

| 字段名 | 类型 | 说明 |
|-------|------|------|
| station_id | VARCHAR | 站点ID |
| name | VARCHAR | 站点名称 |

#### ys_operate_manager（运营管理表）

| 字段名 | 类型 | 说明 |
|-------|------|------|
| id | VARCHAR | 主键 |
| compare_date | DATETIME | 对比日期配置 |
| del_flag | CHAR | 删除标记 |

---

### B. 更新日志

| 日期 | 版本 | 更新内容 | 作者 |
|-----|------|---------|------|
| 2026-08-26 | v1.0 | 初始版本，完成进出站/换乘站排名接口 | Claude |

---

### C. 联系方式

**后端开发：** [您的团队名称]  
**技术支持：** [联系方式]  
**文档维护：** 请在新增接口后及时更新本文档

---

**文档结束**