📈 作业历史数据 API 文档

基础路径 (Base Path)

所有接口的基础路径为：/ysuwx/job-history

---

1. 获取所有历史数据 (周/月/年)

此接口用于获取所有作业类型（卸船、疏港、装车、精混）的周、月、年三个维度的完整历史统计数据，用于页面的默认展示。

• 接口： GET /all
• 别名： GET /test
• 请求参数： 无

响应 (Success 200)

返回 R.ok() 包装的 data 对象，data 字段的结构为 JobHistoryDto。

JSON

{
    "msg": "success",
    "code": 0,
    "data": { ... }
}

data 对象详解

data 对象包含四大模块，每个模块都有周、月、年数据：

1. 卸船数据 (xc)

字段	类型	说明	示例值
xcTotal	BigDecimal	卸船: 周总作业量 (单位: 万吨)	104.98
xcWeekXAxis	List<String>	卸船: 近7天X轴 (日期 "MM-dd")	["10-28", ...]
xcWeekData	List<BigDecimal>	卸船: 近7天Y轴 (作业量, 吨)	[174147, ...]
xcMonthXAxis	List<String>	卸船: 近5月X轴 (日期 "yyyy-MM")	["2025-07", ...]
xcMonthData	List<BigDecimal>	卸船: 近5月Y轴 (作业量, 吨)	[196243, ...]
xcMonthTotal	BigDecimal	卸船: 月总作业量 (单位: 万吨)	10182987
xcYearXAxis	List<String>	卸船: 近5年X轴 (年份 "yyyy")	["2021", ...]
xcYearData	List<BigDecimal>	卸船: 近5年Y轴 (作业量, 吨)	[0, ...]
xcYearTotal	BigDecimal	卸船: 年总作业量 (单位: 万吨)	10182987

2. 疏港数据 (sg)

字段	类型	说明	示例值
sgTotal	BigDecimal	疏港: 周总作业量 (单位: 万吨)	34.8
sgWeekXAxis	List<String>	疏港: 近7天X轴 (日期 "MM-dd")	["10-28", ...]
sgWeekData	List<BigDecimal>	疏港: 近7天Y轴 (作业量, 吨)	[44599.9, ...]
sgMonthXAxis	List<String>	疏港: 近5月X轴 (日期 "yyyy-MM")	["2025-07", ...]
sgMonthData	List<BigDecimal>	疏港: 近5月Y轴 (作业量, 吨)	[1365099.85, ...]
sgMonthTotal	BigDecimal	疏港: 月总作业量 (单位: 万吨)	7274917.55
sgYearXAxis	List<String>	疏港: 近5年X轴 (年份 "yyyy")	["2021", ...]
sgYearData	List<BigDecimal>	疏港: 近5年Y轴 (作业量, 吨)	[0, ...]
sgYearTotal	BigDecimal	疏港: 年总作业量 (单位: 万吨)	15564728.9

3. 装车数据 (zc)

字段	类型	说明	示例值
zcTotal	BigDecimal	装车: 周总作业量 (单位: 万吨)	0
zcWeekXAxis	List<String>	装车: 近7天X轴 (日期 "MM-dd")	["10-28", ...]
zcWeekData	List<BigDecimal>	装车: 近7天Y轴 (作业量, 吨)	[0, ...]
zcMonthXAxis	List<String>	装车: 近5月X轴 (日期 "yyyy-MM")	["2025-07", ...]
zcMonthData	List<BigDecimal>	装车: 近5月Y轴 (作业量, 吨)	[13749.62, ...]
zcMonthTotal	BigDecimal	装车: 月总作业量 (单位: 万吨)	58934.54
zcYearXAxis	List<String>	装车: 近5年X轴 (年份 "yyyy")	["2021", ...]
zcYearData	List<BigDecimal>	装车: 近5年Y轴 (作业量, 吨)	[0, ...]
zcYearTotal	BigDecimal	装车: 年总作业量 (单位: 万吨)	58934.54

4. 精混数据 (jh)

字段	类型	说明	示例值
jhTotal	BigDecimal	精混: 周总作业量 (单位: 万吨)	0
jhWeekXAxis	List<String>	精混: 近7天X轴 (日期 "MM-dd")	["10-28", ...]
jhWeekData	List<BigDecimal>	精混: 近7天Y轴 (作业量, 吨)	[0, ...]
jhMonthXAxis	List<String>	精混: 近5月X轴 (日期 "yyyy-MM")	["2025-07", ...]
jhMonthData	List<BigDecimal>	精混: 近5月Y轴 (作业量, 吨)	[0, ...]
jhMonthTotal	BigDecimal	精混: 月总作业量 (单位: 万吨)	1537266.19
jhYearXAxis	List<String>	精混: 近5年X轴 (年份 "yyyy")	["2021", ...]
jhYearData	List<BigDecimal>	精混: 近5年Y轴 (作业量, 吨)	[0, ...]
jhYearTotal	BigDecimal	精混: 年总作业量 (单位: 万吨)	1537266.19

---

2. 按自定义时间范围查询数据

此接口用于按自定义时间范围（例如 "2025-10-15" 到 "2025-11-03"）查询所有作业类型的日度统计数据。

• 接口： GET /by-time
• 请求参数： (Query)

参数	类型	是否必填	说明
startTime	String	是	开始时间, 格式: "yyyy-MM-dd"
endTime	String	是	结束时间, 格式: "yyyy-MM-dd"

响应 (Success 200)

返回 R.ok() 包装的 data 对象。

重要提示： 此接口的 data 对象是一个部分填充的 JobHistoryDto。

• 它只会填充 ...Total、...WeekXAxis 和 ...WeekData 字段。
• ...Week... 字段在此处被复用，用于存储自定义时间范围的日度数据。
• 所有 ...Month... 和 ...Year... 相关的字段将始终为 null。

JSON

{
    "msg": "success",
    "code": 0,
    "data": { ... }
}

data 对象详解 (by-time 模式)

字段	类型	说明	示例值
xcTotal	BigDecimal	卸船: 范围内总作业量	2707719
xcWeekXAxis	List<String>	卸船: 范围内X轴 (日期 "yyyy-MM-dd")	["2025-10-16", ...]
xcWeekData	List<BigDecimal>	卸船: 范围内Y轴 (作业量, 吨)	[192716, ...]
sgTotal	BigDecimal	疏港: 范围内总作业量	900906.90
sgWeekXAxis	List<String>	疏港: 范围内X轴 (日期 "yyyy-MM-dd")	["2025-10-15", ...]
sgWeekData	List<BigDecimal>	疏港: 范围内Y轴 (作业量, 吨)	[46315.7, ...]
zcTotal	BigDecimal	装车: 范围内总作业量	0
zcWeekXAxis	List<String>	装车: 范围内X轴 (日期 "yyyy-MM-dd")	[]
zcWeekData	List<BigDecimal>	装车: 范围内Y轴 (作业量, 吨)	[]
jhTotal	BigDecimal	精混: 范围内总作业量	54071
jhWeekXAxis	List<String>	精混: 范围内X轴 (日期 "yyyy-MM-dd")	["2025-10-15", ...]
jhWeekData	List<BigDecimal>	精混: 范围内Y轴 (作业量, 吨)	[9271, ...]
...Month...	-	(所有月度字段)	null
...Year...	-	(所有年度字段)	null

响应 (Error 500)

如果请求的时间范围不合法（例如超过30天限制，该限制在 JobHistoryServiceImpl.java 中定义），将返回错误信息。

JSON

{
    "msg": "查询时间范围不能超过30天，当前查询范围：35天（...）",
    "code": 500
}