483 lines
11 KiB
Markdown
483 lines
11 KiB
Markdown
# 客运页面 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. 联系方式
|
||
|
||
**后端开发：** [您的团队名称]
|
||
**技术支持：** [联系方式]
|
||
**文档维护：** 请在新增接口后及时更新本文档
|
||
|
||
---
|
||
|
||
**文档结束**
|