✨ 新增小程序司机端运单行驶轨迹接口

按打卡记录/计划时间自动推导起止日期后查询 LBS 轨迹。

Co-authored-by: Cursor <cursoragent@cursor.com>

blade-service/blade-transport/src/main/java/org/springblade/transport/controller/DriverWaybillController.java

@@ -38,6 +38,7 @@ import org.springblade.transport.pojo.vo.DriverNodePunchVO;
 import org.springblade.transport.pojo.vo.DriverWaybillCardVO;
 import org.springblade.transport.pojo.vo.DriverWaybillPreviewVO;
 import org.springblade.transport.pojo.vo.DriverWaybillTabCountsVO;
+import org.springblade.transport.pojo.vo.WaybillTrackVO;
 import org.springblade.transport.service.IDriverWaybillService;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -104,6 +105,13 @@ public class DriverWaybillController extends BladeController {
 		return R.data(driverWaybillService.detail(id));
 	}
 
+	@PostMapping("/track")
+	@ApiOperationSupport(order = 11)
+	@Operation(summary = "司机端行驶轨迹", description = "按当前用户手机号校验归属后，根据打卡记录/计划时间自动推导起止日期并查询 LBS 轨迹（WGS-84）")
+	public R<WaybillTrackVO> track(@Parameter(description = "运单ID", required = true) @RequestParam Long id) {
+		return R.data(driverWaybillService.track(id));
+	}
+
 	@PostMapping("/accept")
 	@ApiOperationSupport(order = 6)
 	@Operation(summary = "司机确认接单", description = "过程配置接单为「是」时，司机确认接单后运单进入进行中")

blade-service/blade-transport/src/main/java/org/springblade/transport/service/IDriverWaybillService.java

@@ -30,6 +30,7 @@ import org.springblade.transport.pojo.vo.DriverNodePunchVO;
 import org.springblade.transport.pojo.vo.DriverWaybillCardVO;
 import org.springblade.transport.pojo.vo.DriverWaybillPreviewVO;
 import org.springblade.transport.pojo.vo.DriverWaybillTabCountsVO;
+import org.springblade.transport.pojo.vo.WaybillTrackVO;
 
 import java.util.Map;
 
@@ -70,6 +71,19 @@ public interface IDriverWaybillService {
 	 */
 	DriverWaybillCardVO detail(Long id);
 
+	/**
+	 * 司机端运单行驶轨迹：按打卡记录 / 计划时间自动推导起止日期后查询 LBS 轨迹。
+	 * <p>
+	 * 起止日期优先级：
+	 * <ol>
+	 *   <li>有打卡且多于 1 条：首条打卡日 → 末条打卡日</li>
+	 *   <li>有打卡且仅 1 条：首条打卡日 → 今天</li>
+	 *   <li>无打卡有计划开始日：计划开始日 → 今天</li>
+	 *   <li>无打卡无计划：3 天前 → 今天</li>
+	 * </ol>
+	 */
+	WaybillTrackVO track(Long id);
+
 	/**
 	 * 按运单ID组装详情打卡数据（punchNodes / enrouteRecords），不校验当前登录人是否为该司机。
 	 * 供调度端 manage/detail 复用。

blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/DriverWaybillServiceImpl.java

@@ -56,6 +56,7 @@ import org.springblade.transport.pojo.vo.DriverPunchPhotoVO;
 import org.springblade.transport.pojo.vo.DriverWaybillCardVO;
 import org.springblade.transport.pojo.vo.DriverWaybillPreviewVO;
 import org.springblade.transport.pojo.vo.DriverWaybillTabCountsVO;
+import org.springblade.transport.pojo.vo.WaybillTrackVO;
 import org.springblade.transport.service.IDriverService;
 import org.springblade.transport.service.IDriverWaybillService;
 import org.springblade.transport.service.IProcessConfigService;
@@ -239,6 +240,69 @@ public class DriverWaybillServiceImpl implements IDriverWaybillService {
 		return toCard(normalizeAcceptStatus(waybill), true);
 	}
 
+	@Override
+	public WaybillTrackVO track(Long id) {
+		requireCurrentDriver();
+		Waybill waybill = loadDriverWaybill(id);
+		LocalDate[] range = resolveTrackDateRange(waybill);
+		return waybillService.trackVehicle(waybill.getId(), range[0].toString(), range[1].toString());
+	}
+
+	/**
+	 * 小程序行驶轨迹查询区间：
+	 * 1/2 有打卡 → 首条打卡日为开始；多于 1 条结束取末条日，仅 1 条结束取今天
+	 * 3 无打卡有计划开始日 → 计划开始日到今天
+	 * 4 无打卡无计划 → 3 天前到今天
+	 */
+	private LocalDate[] resolveTrackDateRange(Waybill waybill) {
+		LocalDate today = LocalDate.now();
+		List<Date> punchTimes = listAllPunchTimes(waybill.getId());
+		if (!punchTimes.isEmpty()) {
+			LocalDate start = toLocalDate(punchTimes.get(0));
+			LocalDate end = punchTimes.size() > 1
+				? toLocalDate(punchTimes.get(punchTimes.size() - 1))
+				: today;
+			return clampTrackRange(start, end, today);
+		}
+		LocalDate planStart = waybill.getEstimatedStartTime();
+		if (planStart != null) {
+			return clampTrackRange(planStart, today, today);
+		}
+		return clampTrackRange(today.minusDays(3), today, today);
+	}
+
+	private LocalDate[] clampTrackRange(LocalDate start, LocalDate end, LocalDate today) {
+		LocalDate safeStart = start == null ? today.minusDays(3) : start;
+		LocalDate safeEnd = end == null ? today : end;
+		if (safeEnd.isBefore(safeStart)) {
+			safeEnd = safeStart;
+		}
+		return new LocalDate[]{safeStart, safeEnd};
+	}
+
+	private List<Date> listAllPunchTimes(Long waybillId) {
+		if (waybillId == null) {
+			return Collections.emptyList();
+		}
+		List<Date> times = new ArrayList<>();
+		nodePunchMapper.selectList(Wrappers.<WaybillNodePunch>lambdaQuery()
+				.eq(WaybillNodePunch::getWaybillId, waybillId)
+				.isNotNull(WaybillNodePunch::getPunchTime)
+				.orderByAsc(WaybillNodePunch::getPunchTime))
+			.forEach(punch -> times.add(punch.getPunchTime()));
+		enroutePunchMapper.selectList(Wrappers.<WaybillEnroutePunch>lambdaQuery()
+				.eq(WaybillEnroutePunch::getWaybillId, waybillId)
+				.isNotNull(WaybillEnroutePunch::getPunchTime)
+				.orderByAsc(WaybillEnroutePunch::getPunchTime))
+			.forEach(punch -> times.add(punch.getPunchTime()));
+		times.sort(Date::compareTo);
+		return times;
+	}
+
+	private LocalDate toLocalDate(Date date) {
+		return date.toInstant().atZone(ZoneId.systemDefault()).toLocalDate();
+	}
+
 	@Override
 	public DriverWaybillCardVO detailPunchSnapshot(Long id) {
 		if (id == null) {