feat(fleet): expose bounded origin-aware trip calendar

lastleg-service/src/main/resources/openapi/fleet-trips-v1.yaml

@@ -27,6 +27,37 @@ info:
 security:
   - bearerAuth: []
 paths:
+  /api/platform/v1/last-leg/fleet/trips/calendar:
+    get:
+      summary: 读取美国车次计划日历来源
+      description: >-
+        仅PLATFORM且平台公共主体（tenantId=0），权限 platform:fleet:trip:list。from/to 是明确UTC时间点，按计划发车时间读取半开区间，最多44天；
+        该保护性窗口供界面最多42个当地日历日加时区边界使用，不扩大界面范围。
+        最多2000条候选，超限明确拒绝并要求缩小日期范围，不分页扫描、不静默截断。
+        一车一条，保留取消及完成状态；记录只表示用车计划，不表示收货预约已确认。
+        已知非美国仓排除；未知仓库/国家/地理IANA时区进入unresolvedRecords，不落入美国当地日槽。
+        一次车次查询加一次仓库批量资料请求，包含停用仓历史资料，资料服务失败返回错误而非空日历。
+      parameters:
+        - {name: from, in: query, required: true, schema: {type: string, format: date-time}}
+        - {name: to, in: query, required: true, schema: {type: string, format: date-time}}
+      responses:
+        '200':
+          description: 统一业务响应；UTC事实保持原值，司机预计结束不是收货预约时间
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - {$ref: '#/components/schemas/Envelope'}
+                  - properties:
+                      data:
+                        type: object
+                        required: [records, unresolvedRecords]
+                        properties:
+                          records: {type: array, items: {$ref: '#/components/schemas/TripCalendarEntry'}}
+                          unresolvedRecords: {type: array, items: {$ref: '#/components/schemas/TripCalendarEntry'}}
+        '400': {description: 时间范围无效或候选车次超过2000条}
+        '403': {description: 缺少车次查看权限}
+        '503': {description: 仓库元数据无法可靠读取}
   /api/platform/v1/last-leg/fleet/trips:
     get:
       summary: 分页查询车次
@@ -338,6 +369,27 @@ components:
                           reason: {type: string}
                           licenseExpiresOn: {type: string, format: date, nullable: true}
   schemas:
+    TripCalendarEntry:
+      type: object
+      required: [sourceType, tripNo, status, plannedDepartureAt, expectedDriverEndAt, stops, incompleteReasons]
+      properties:
+        sourceType: {type: string, enum: [TRIP_PLAN]}
+        tripNo: {type: string}
+        status: {type: string, enum: [PLANNED, IN_TRANSIT, COMPLETED, CANCELLED]}
+        originWarehouseId: {type: string, nullable: true}
+        originWarehouseCode: {type: string, nullable: true}
+        originWarehouseName: {type: string, nullable: true}
+        originCountryCode: {type: string, nullable: true}
+        originTimezone: {type: string, nullable: true, description: 地理IANA时区；未知、固定偏移、Etc及SystemV标记为空，不猜UTC}
+        originWarehouseStatus: {type: string, nullable: true}
+        plannedDepartureAt: {type: string, format: date-time}
+        expectedDriverEndAt: {type: string, format: date-time, description: 司机任务预计结束，不是收货预约时间}
+        departedAt: {type: string, format: date-time, nullable: true}
+        completedAt: {type: string, format: date-time, nullable: true}
+        stops: {type: array, items: {$ref: '#/components/schemas/Stop'}}
+        incompleteReasons:
+          type: array
+          items: {type: string, enum: [ORIGIN_WAREHOUSE_UNKNOWN, ORIGIN_COUNTRY_UNKNOWN, ORIGIN_TIMEZONE_UNKNOWN, ROUTE_INCOMPLETE]}
     BookingCargo:
       type: object
       required: [destinationKey]