feat(appointments): add four-type calendar sources and align release contracts

2026-10-19 12:15:43 +08:00
parent fe1b2a6a46
commit aa195cef66
21 changed files with 599 additions and 65 deletions
@@ -0,0 +1,56 @@
+openapi: 3.0.3
+info: {title: 四类日历整柜到仓来源, version: 1.0.0}
+security: [{bearerAuth: []}]
+paths:
+  /api/platform/v1/last-leg/appointment-calendar/warehouse-arrivals/query:
+    post:
+      summary: 查询日历整柜人工到仓计划与冻结事实
+      description: >-
+        仅平台，同时要求platform:appointment:list与platform:overseas-warehouse:last-mile-order:list。
+        返回所选来源柜，以及查询区间内已人工维护或已有入库计划的到仓记录，支持跨月人工改期。
+        同柜多个客户合并一条。plannedAt只有整柜时间一致且人工维护版本大于0或已经建计划时才有值。
+        未人工维护、未建计划的日历默认日期由到港来源加2个自然日；此只读接口不写入库计划、不补造时刻。
+        actualAt只读PDA首次收货时间，不替换计划日期。
+        具备原尾程订单编辑权限、版本一致、无入库计划且未实际到仓时canEdit=true。
+        保存复用overseas-business-v1的整柜expected-arrival入口和原版本、幂等键、冻结门禁。
+        无法核平的整柜版本为-1，不能用默认日期覆盖。最多2000条，超出返回400。
+      x-permissions: [platform:appointment:list, 'platform:overseas-warehouse:last-mile-order:list']
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [from, to, sourceContainerBookingIds]
+              properties:
+                from: {type: string, format: date}
+                to: {type: string, format: date, description: 左闭右开，最多42天}
+                sourceContainerBookingIds: {type: array, maxItems: 2000, uniqueItems: true, items: {type: string, pattern: '^[1-9][0-9]*$'}}
+      responses:
+        '200':
+          description: 成功业务响应，code为字符串200
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  data:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        sourceContainerBookingId: {type: string}
+                        containerNo: {type: string, nullable: true}
+                        warehouseName: {type: string, nullable: true}
+                        warehouseCode: {type: string, nullable: true}
+                        plannedAt: {type: string, format: date-time, nullable: true}
+                        actualAt: {type: string, format: date-time, nullable: true}
+                        version: {type: integer, minimum: -1}
+                        planCount: {type: integer, minimum: 0}
+                        canEdit: {type: boolean}
+        '400': {description: 日期、来源柜或数量不符合约束}
+        '403': {description: 非平台或缺少任一读取权限}
+components:
+  securitySchemes:
+    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}