wyh
/
ysdp-juntechysdp
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ysdp-juntechysdp/客运页面API接口文档.md

11 KiB
Raw Blame History

客运页面 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：

{
  "Content-Type": "application/json",
  "token": "your-token-here"
}

请求 Body：

{}

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

返回参数

成功返回示例：

{
  "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：

{
  "Content-Type": "application/json",
  "token": "your-token-here"
}

请求 Body：

{}

返回参数

成功返回示例：

{
  "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：

{
  "Content-Type": "application/json",
  "token": "your-token-here"
}

请求 Body：

{}

返回参数

成功返回示例：

{
  "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 命令

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. 联系方式

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

文档结束