foodie-server/specs/024-flash-delivery/research.md

技术调研：闪送配送服务

Google 路线距离

采用 Google Routes API v2 的 POST https://routes.googleapis.com/directions/v2:computeRoutes。请求头使用 X-Goog-Api-Key 和 X-Goog-FieldMask: routes.distanceMeters,routes.duration，请求体使用取件、收件经纬度、DRIVE、TRAFFIC_AWARE。参考 Google 官方 Compute Routes、计算路线 和 字段掩码。

服务端只从字典 sys_google_routes_key 读取独立密钥，不复用可能由现有匿名接口返回的浏览器密钥 sys_googlemap_key，也不在响应或日志中输出服务端密钥。该密钥需启用 Routes API 并限制服务端来源。连接/读取超时、HTTP 非成功、JSON 无路线或距离不大于 0 均降级。

降级与精度

外部路线不可用时使用 Haversine 公式计算球面直线距离，四舍五入为整数米并标记 STRAIGHT_LINE；路线成功标记 ROUTE。价格使用 BigDecimal 和 decimal(10,2)；超距里程以整数米转换为实际小数公里，预计时长以秒转换为实际小数分钟，分别计算里程费和时长费后再应用不小于 1 的尖峰倍率与最低价，避免浮点边界误差。

并发与安全

• 创建由 (user_id, client_request_id) 唯一键最终保证幂等。
• 抢单和状态变更使用条件 UPDATE，不先查后改。
• App 身份只来自 JwtUtil.getusid(token)，骑手额外校验 userType=2。
• 平台接口使用 @PreAuthorize；凭证仅接受 HTTP(S) URL。
• 待抢订单通过专用视图脱敏，不直接序列化数据库实体。